From 9fa1c3182ea866efca0647146f0871d0276e2af3 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sun, 26 Jan 2020 14:30:33 +0100 Subject: Fix documentation of Fl_Shortcut Unfortunately this typedef for shortcuts in Fl_Menu_Items etc. can currently not be used with the full (21-bit) range of Unicode. These restrictions are now documented but should be removed in a future version, if possible. --- FL/fl_types.h | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/FL/fl_types.h b/FL/fl_types.h index 51caf1a0b..631c7250b 100644 --- a/FL/fl_types.h +++ b/FL/fl_types.h @@ -3,17 +3,17 @@ * * Simple "C"-style types for the Fast Light Tool Kit (FLTK). * - * Copyright 1998-2015 by Bill Spitzak and others. + * Copyright 1998-2020 by Bill Spitzak and others. * * This library is free software. Distribution and use rights are outlined in * the file "COPYING" which should have been included with this file. If this * file is missing or damaged, see the license at: * - * http://www.fltk.org/COPYING.php + * https://www.fltk.org/COPYING.php * * Please report all bugs and problems on the following page: * - * http://www.fltk.org/str.php + * https://www.fltk.org/str.php */ /** \file @@ -42,7 +42,27 @@ typedef char *Fl_String; */ typedef const char *Fl_CString; -/** 24-bit Unicode character + 8-bit indicator for keyboard flags */ +/** 16-bit Unicode character + 8-bit indicator for keyboard flags. + + \note This \b should be 24-bit Unicode character + 8-bit indicator for + keyboard flags. The upper 8 bits are currently unused but reserved. + + Due to compatibility issues this type and all FLTK \b shortcuts can only + be used with 16-bit Unicode characters (U+0000 .. U+FFFF) and + not with the full range of unicode characters (U+0000 .. U+10FFFF). + + This is caused by the bit flags \c FL_SHIFT, \c FL_CTRL, \c FL_ALT, and + \c FL_META being all in the range 0x010000 .. 0x400000. + + \todo Discuss and decide whether we can "shift" these special keyboard + flags to the upper byte to enable full 21-bit Unicode characters + (U+0000 .. U+10FFFF) plus the keyboard indicator bits as this + was originally intended. This would be possible if we could rely on \b all + programs being coded with symbolic names and not hard coded bit values. + + \internal Can we do the move for 1.4 or, if not, for any later version + that is allowed to break the ABI? +*/ typedef unsigned int Fl_Shortcut; /** 24-bit Unicode character - upper 8 bits are unused */ -- cgit v1.2.3