From 3b768484358c6ce7cc8e769ac2bc0cd5da0b1924 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sun, 24 Apr 2011 17:09:41 +0000 Subject: [PATCH] Documentation updates, also fixing STR #2574, trying to make clear which events invisible and inactive widgets can get. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8623 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Enumerations.H | 449 ++++++++++++++++++----------------- FL/Fl_Browser.H | 4 +- FL/Fl_Widget.H | 27 ++- FL/dirent.h | 4 +- FL/forms.H | 4 +- FL/gl.h | 4 +- FL/glut.H | 4 +- documentation/src/events.dox | 93 ++++---- src/Fl_PostScript.cxx | 4 +- src/Fl_win32.cxx | 2 +- src/Fl_x.cxx | 4 +- 11 files changed, 296 insertions(+), 303 deletions(-) diff --git a/FL/Enumerations.H b/FL/Enumerations.H index 78f1a709f..3d26ba746 100644 --- a/FL/Enumerations.H +++ b/FL/Enumerations.H @@ -3,7 +3,7 @@ // // Enumerations for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2011 by Bill Spitzak and others. // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Library General Public @@ -26,7 +26,7 @@ // /** \file - * This file contains type definitions and general enumerations. + This file contains type definitions and general enumerations. */ #ifndef Fl_Enumerations_H @@ -45,39 +45,35 @@ /*@{*/ /** - * The major release version of this FLTK library. + The major release version of this FLTK library. \sa FL_VERSION */ #define FL_MAJOR_VERSION 1 /** - * The minor release version for this library. - * - * FLTK remains mostly source-code compatible between minor version changes. + The minor release version for this library. + + FLTK remains mostly source-code compatible between minor version changes. */ #define FL_MINOR_VERSION 3 /** - * The patch version for this library. - * - * FLTK remains binary compatible between patches. + The patch version for this library. + + FLTK remains binary compatible between patches. */ #define FL_PATCH_VERSION 0 /** - * The FLTK version number as a \em double. - * - * This is changed slightly from the beta versions - * because the old "const double" definition would not allow for conditional - * compilation... - * - * FL_VERSION is a double that describes the major and minor version numbers. - * Version 1.1 is actually stored as 1.01 to allow for more than 9 minor - * releases. - * - * The FL_MAJOR_VERSION, FL_MINOR_VERSION, and FL_PATCH_VERSION constants - * give the integral values for the major, minor, and patch releases - * respectively. + The FLTK version number as a \em double. + + FL_VERSION is a double that describes the major and minor version numbers. + Version 1.1 is actually stored as 1.01 to allow for more than 9 minor + releases. + + The FL_MAJOR_VERSION, FL_MINOR_VERSION, and FL_PATCH_VERSION constants + give the integral values for the major, minor, and patch releases + respectively. */ #define FL_VERSION ((double)FL_MAJOR_VERSION + \ (double)FL_MINOR_VERSION * 0.01 + \ @@ -86,203 +82,205 @@ /*@}*/ // group: Version Numbers /** - * Every time a user moves the mouse pointer, clicks a button, - * or presses a key, an event is generated and sent to your - * application. Events can also come from other programs like the - * window manager. - * - * Events are identified by the integer argument passed to the - * Fl_Widget::handle() virtual method. Other information about the - * most recent event is stored in static locations and acquired by - * calling the Fl::event_*() methods. This static information remains - * valid until the next event is read from the window system, so it - * is ok to look at it outside of the handle() method. - * - * \sa Fl::event_text(), Fl::event_key(), class Fl:: + Every time a user moves the mouse pointer, clicks a button, + or presses a key, an event is generated and sent to your + application. Events can also come from other programs like the + window manager. + + Events are identified by the integer argument passed to the + Fl_Widget::handle() virtual method. Other information about the + most recent event is stored in static locations and acquired by + calling the Fl::event_*() methods. This static information remains + valid until the next event is read from the window system, so it + is ok to look at it outside of the handle() method. + + \sa Fl::event_text(), Fl::event_key(), class Fl:: */ enum Fl_Event { // events /** No event. */ FL_NO_EVENT = 0, /** A mouse button has gone down with the mouse pointing at this - * widget. You can find out what button by calling Fl::event_button(). - * You find out the mouse position by calling Fl::event_x() and - * Fl::event_y(). - * - * A widget indicates that it "wants" the mouse click by returning non-zero - * from its Fl_Widget::handle() method. It will then become the - * Fl::pushed() widget and will get FL_DRAG and the matching FL_RELEASE events. - * If Fl_Widget::handle() returns zero then FLTK will try sending the FL_PUSH - * to another widget. + widget. You can find out what button by calling Fl::event_button(). + You find out the mouse position by calling Fl::event_x() and + Fl::event_y(). + + A widget indicates that it "wants" the mouse click by returning non-zero + from its Fl_Widget::handle() method. It will then become the + Fl::pushed() widget and will get FL_DRAG and the matching FL_RELEASE events. + If Fl_Widget::handle() returns zero then FLTK will try sending the FL_PUSH + to another widget. */ FL_PUSH = 1, /** A mouse button has been released. You can find out what button by - * calling Fl::event_button(). - * - * In order to receive the FL_RELEASE event, the widget must return - * non-zero when handling FL_PUSH. + calling Fl::event_button(). + + In order to receive the FL_RELEASE event, the widget must return + non-zero when handling FL_PUSH. */ FL_RELEASE = 2, /** The mouse has been moved to point at this widget. This can - * be used for highlighting feedback. If a widget wants to - * highlight or otherwise track the mouse, it indicates this by - * returning non-zero from its handle() method. It then - * becomes the Fl::belowmouse() widget and will receive - * FL_MOVE and FL_LEAVE events. + be used for highlighting feedback. If a widget wants to + highlight or otherwise track the mouse, it indicates this by + returning non-zero from its handle() method. It then + becomes the Fl::belowmouse() widget and will receive + FL_MOVE and FL_LEAVE events. */ FL_ENTER = 3, /** The mouse has moved out of the widget. - * In order to receive the FL_LEAVE event, the widget must - * return non-zero when handling FL_ENTER. + In order to receive the FL_LEAVE event, the widget must + return non-zero when handling FL_ENTER. */ FL_LEAVE = 4, /** The mouse has moved with a button held down. The current button state - * is in Fl::event_state(). The mouse position is in Fl::event_x() and - * Fl::event_y(). - * - * In order to receive FL_DRAG events, the widget must return non-zero - * when handling FL_PUSH. + is in Fl::event_state(). The mouse position is in Fl::event_x() and + Fl::event_y(). + + In order to receive FL_DRAG events, the widget must return non-zero + when handling FL_PUSH. */ FL_DRAG = 5, /** This indicates an attempt to give a widget the keyboard focus. - * - * If a widget wants the focus, it should change itself to display the - * fact that it has the focus, and return non-zero from its handle() method. - * It then becomes the Fl::focus() widget and gets FL_KEYDOWN, FL_KEYUP, - * and FL_UNFOCUS events. - * - * The focus will change either because the window manager changed which - * window gets the focus, or because the user tried to navigate using tab, - * arrows, or other keys. You can check Fl::event_key() to figure out why - * it moved. For navigation it will be the key pressed and interaction - * with the window manager it will be zero. + + If a widget wants the focus, it should change itself to display the + fact that it has the focus, and return non-zero from its handle() method. + It then becomes the Fl::focus() widget and gets FL_KEYDOWN, FL_KEYUP, + and FL_UNFOCUS events. + + The focus will change either because the window manager changed which + window gets the focus, or because the user tried to navigate using tab, + arrows, or other keys. You can check Fl::event_key() to figure out why + it moved. For navigation it will be the key pressed and for interaction + with the window manager it will be zero. */ FL_FOCUS = 6, /** This event is sent to the previous Fl::focus() widget when another - * widget gets the focus or the window loses focus. + widget gets the focus or the window loses focus. */ FL_UNFOCUS = 7, - /** A key was pressed or released. The key can be found in Fl::event_key(). - * The text that the key should insert can be found with Fl::event_text() - * and its length is in Fl::event_length(). If you use the key handle() - * should return 1. If you return zero then FLTK assumes you ignored the - * key and will then attempt to send it to a parent widget. If none of - * them want it, it will change the event into a FL_SHORTCUT event. - * - * To receive FL_KEYBOARD events you must also respond to the FL_FOCUS - * and FL_UNFOCUS events. - * - * If you are writing a text-editing widget you may also want to call - * the Fl::compose() function to translate individual keystrokes into - * non-ASCII characters. - * - * FL_KEYUP events are sent to the widget that currently has focus. This - * is not necessarily the same widget that received the corresponding - * FL_KEYDOWN event because focus may have changed between events. + /** A key was pressed (FL_KEYDOWN) or released (FL_KEYUP). + Fl_KEYBOARD is a synonym for FL_KEYDOWN. + The key can be found in Fl::event_key(). + The text that the key should insert can be found with Fl::event_text() + and its length is in Fl::event_length(). If you use the key handle() + should return 1. If you return zero then FLTK assumes you ignored the + key and will then attempt to send it to a parent widget. If none of + them want it, it will change the event into a FL_SHORTCUT event. + + To receive FL_KEYBOARD events you must also respond to the FL_FOCUS + and FL_UNFOCUS events. + + If you are writing a text-editing widget you may also want to call + the Fl::compose() function to translate individual keystrokes into + non-ASCII characters. + + FL_KEYUP events are sent to the widget that currently has focus. This + is not necessarily the same widget that received the corresponding + FL_KEYDOWN event because focus may have changed between events. */ FL_KEYDOWN = 8, - /** Equvalent to FL_KEYDOWN. - * \see FL_KEYDOWN + /** Equivalent to FL_KEYDOWN. + \see FL_KEYDOWN */ FL_KEYBOARD = 8, /** Key release event. - * \see FL_KEYDOWN + \see FL_KEYDOWN */ FL_KEYUP = 9, /** The user clicked the close button of a window. - * This event is used internally only to trigger the callback of - * Fl_Window derived classed. The default callback closes the - * window calling Fl_Window::hide(). + This event is used internally only to trigger the callback of + Fl_Window derived classed. The default callback closes the + window calling Fl_Window::hide(). */ FL_CLOSE = 10, /** The mouse has moved without any mouse buttons held down. - * This event is sent to the Fl::belowmouse() widget. - * - * In order to receive FL_MOVE events, the widget must return - * non-zero when handling FL_ENTER. + This event is sent to the Fl::belowmouse() widget. + + In order to receive FL_MOVE events, the widget must return + non-zero when handling FL_ENTER. */ FL_MOVE = 11, /** If the Fl::focus() widget is zero or ignores an FL_KEYBOARD - * event then FLTK tries sending this event to every widget it - * can, until one of them returns non-zero. FL_SHORTCUT is first - * sent to the Fl::belowmouse() widget, then its parents and siblings, - * and eventually to every widget in the window, trying to find an - * object that returns non-zero. FLTK tries really hard to not to ignore - * any keystrokes! - * - * You can also make "global" shortcuts by using Fl::add_handler(). A - * global shortcut will work no matter what windows are displayed or - * which one has the focus. + event then FLTK tries sending this event to every widget it + can, until one of them returns non-zero. FL_SHORTCUT is first + sent to the Fl::belowmouse() widget, then its parents and siblings, + and eventually to every widget in the window, trying to find an + object that returns non-zero. FLTK tries really hard to not to ignore + any keystrokes! + + You can also make "global" shortcuts by using Fl::add_handler(). A + global shortcut will work no matter what windows are displayed or + which one has the focus. */ FL_SHORTCUT = 12, /** This widget is no longer active, due to Fl_Widget::deactivate() - * being called on it or one of its parents. Fl_Widget::active() may - * still be true after this, the widget is only active if Fl_Widget::active() - * is true on it and all its parents (use Fl_Widget::active_r() to check this). + being called on it or one of its parents. Fl_Widget::active() may + still be true after this, the widget is only active if Fl_Widget::active() + is true on it and all its parents (use Fl_Widget::active_r() to check this). */ FL_DEACTIVATE = 13, /** This widget is now active, due to Fl_Widget::activate() being - * called on it or one of its parents. + called on it or one of its parents. */ FL_ACTIVATE = 14, /** This widget is no longer visible, due to Fl_Widget::hide() being - * called on it or one of its parents, or due to a parent window being - * minimized. Fl_Widget::visible() may still be true after this, but the - * widget is visible only if visible() is true for it and all its - * parents (use Fl_Widget::visible_r() to check this). + called on it or one of its parents, or due to a parent window being + minimized. Fl_Widget::visible() may still be true after this, but the + widget is visible only if visible() is true for it and all its + parents (use Fl_Widget::visible_r() to check this). */ FL_HIDE = 15, /** This widget is visible again, due to Fl_Widget::show() being called on - * it or one of its parents, or due to a parent window being restored. - * Child Fl_Windows respond to this by actually creating the window if not - * done already, so if you subclass a window, be sure to pass FL_SHOW - * to the base class Fl_Widget::handle() method! + it or one of its parents, or due to a parent window being restored. + Child Fl_Windows respond to this by actually creating the window if not + done already, so if you subclass a window, be sure to pass FL_SHOW + to the base class Fl_Widget::handle() method! */ FL_SHOW = 16, /** You should get this event some time after you call Fl::paste(). - * The contents of Fl::event_text() is the text to insert and the number - * of characters is in Fl::event_length(). + The contents of Fl::event_text() is the text to insert and the number + of characters is in Fl::event_length(). */ FL_PASTE = 17, /** The Fl::selection_owner() will get this event before the selection is - * moved to another widget. This indicates that some other widget or program - * has claimed the selection. Motif programs used this to clear the selection - * indication. Most modern programs ignore this. + moved to another widget. This indicates that some other widget or program + has claimed the selection. Motif programs used this to clear the selection + indication. Most modern programs ignore this. */ FL_SELECTIONCLEAR = 18, /** The user has moved the mouse wheel. The Fl::event_dx() and Fl::event_dy() - * methods can be used to find the amount to scroll horizontally and vertically. + methods can be used to find the amount to scroll horizontally and vertically. */ FL_MOUSEWHEEL = 19, /** The mouse has been moved to point at this widget. A widget that is - * interested in receiving drag'n'drop data must return 1 to receive - * FL_DND_DRAG, FL_DND_LEAVE and FL_DND_RELEASE events. + interested in receiving drag'n'drop data must return 1 to receive + FL_DND_DRAG, FL_DND_LEAVE and FL_DND_RELEASE events. */ FL_DND_ENTER = 20, /** The mouse has been moved inside a widget while dragging data. A - * widget that is interested in receiving drag'n'drop data should - * indicate the possible drop position. + widget that is interested in receiving drag'n'drop data should + indicate the possible drop position. */ FL_DND_DRAG = 21, @@ -291,8 +289,8 @@ enum Fl_Event { // events FL_DND_LEAVE = 22, /** The user has released the mouse button dropping data into the widget. - * If the widget returns 1, it will receive the data in the immediately - * following FL_PASTE event. + If the widget returns 1, it will receive the data in the immediately + following FL_PASTE event. */ FL_DND_RELEASE = 23 }; @@ -300,9 +298,9 @@ enum Fl_Event { // events /** \name When Conditions */ /*@{*/ /** These constants determine when a callback is performed. - * - * \sa Fl_Widget::when(); - * \todo doxygen comments for values are incomplete and maybe wrong or unclear + + \sa Fl_Widget::when(); + \todo doxygen comments for values are incomplete and maybe wrong or unclear */ enum Fl_When { // Fl_Widget::when(): FL_WHEN_NEVER = 0, ///< Never call the callback @@ -412,15 +410,15 @@ enum Fl_When { // Fl_Widget::when(): #define FL_BUTTONS 0x7f000000 ///< Any mouse button is pushed #define FL_BUTTON(n) (0x00800000<<(n)) ///< Mouse button n (n > 0) is pushed -#define FL_KEY_MASK 0x0000ffff ///< All keys are 16 bit for now - // FIXME: Unicode needs 24 bits! +#define FL_KEY_MASK 0x0000ffff ///< All keys are 16 bit for now + // FIXME: Unicode needs 24 bits! #ifdef __APPLE__ -# define FL_COMMAND FL_META ///< An alias for FL_CTRL on WIN32 and X11, or FL_META on MacOS X -# define FL_CONTROL FL_CTRL ///< An alias for FL_META on WIN32 and X11, or FL_CTRL on MacOS X +# define FL_COMMAND FL_META ///< An alias for FL_CTRL on WIN32 and X11, or FL_META on MacOS X +# define FL_CONTROL FL_CTRL ///< An alias for FL_META on WIN32 and X11, or FL_CTRL on MacOS X #else # define FL_COMMAND FL_CTRL ///< An alias for FL_CTRL on WIN32 and X11, or FL_META on MacOS X -# define FL_CONTROL FL_META ///< An alias for FL_META on WIN32 and X11, or FL_CTRL on MacOS X +# define FL_CONTROL FL_META ///< An alias for FL_META on WIN32 and X11, or FL_CTRL on MacOS X #endif // __APPLE__ /*@}*/ // group: Event States @@ -542,24 +540,24 @@ extern FL_EXPORT Fl_Boxtype fl_define_FL_GTK_UP_BOX(); /** Get the filled version of a frame. If no filled version of a given frame exists, the behavior of this function - is undefined and some random box or frame is returned, - */ + is undefined and some random box or frame is returned. + */ inline Fl_Boxtype fl_box(Fl_Boxtype b) { return (Fl_Boxtype)((b1)?b:(b-2)); } /** Get the "pressed" or "down" version of a box. If no "down" version of a given box exists, the behavior of this function - is undefined and some random box or frame is returned, - */ + is undefined and some random box or frame is returned. + */ inline Fl_Boxtype fl_down(Fl_Boxtype b) { return (Fl_Boxtype)((b Fl_Color => 0xrrggbbii | | | | @@ -740,10 +738,10 @@ extern FL_EXPORT Fl_Fontsize FL_NORMAL_SIZE; ///< normal font size | +------- green component (8 bit) +--------- red component (8 bit) - + A color can have either an index or an rgb value. Colors with rgb set and an index >0 are reserved for special use. - + */ /*@{*/ /** an FLTK color value */ @@ -758,14 +756,14 @@ const Fl_Color FL_SELECTION_COLOR = 15; ///< the default selection/highlight c // boxtypes generally limit themselves to these colors so // the whole ramp is not allocated: -const Fl_Color FL_GRAY0 = 32; // 'A' -const Fl_Color FL_DARK3 = 39; // 'H' -const Fl_Color FL_DARK2 = 45; // 'N' -const Fl_Color FL_DARK1 = 47; // 'P' +const Fl_Color FL_GRAY0 = 32; // 'A' +const Fl_Color FL_DARK3 = 39; // 'H' +const Fl_Color FL_DARK2 = 45; // 'N' +const Fl_Color FL_DARK1 = 47; // 'P' const Fl_Color FL_BACKGROUND_COLOR = 49; // 'R' default background color -const Fl_Color FL_LIGHT1 = 50; // 'S' -const Fl_Color FL_LIGHT2 = 52; // 'U' -const Fl_Color FL_LIGHT3 = 54; // 'W' +const Fl_Color FL_LIGHT1 = 50; // 'S' +const Fl_Color FL_LIGHT2 = 52; // 'U' +const Fl_Color FL_LIGHT3 = 54; // 'W' // FLTK provides a 5x8x5 color cube that is used with colormap visuals @@ -809,38 +807,41 @@ inline Fl_Color fl_lighter(Fl_Color c) { return fl_color_average(c, FL_WHITE, .6 /** Returns a darker version of the specified color. */ inline Fl_Color fl_darker(Fl_Color c) { return fl_color_average(c, FL_BLACK, .67f); } -/** return 24-bit color value closest to \p r, \p g, \p b. */ +/** Returns the 24-bit color value closest to \p r, \p g, \p b. */ inline Fl_Color fl_rgb_color(uchar r, uchar g, uchar b) { if (!r && !g && !b) return FL_BLACK; else return (Fl_Color)(((((r << 8) | g) << 8) | b) << 8); } -/** return 24-bit color value closest to \p grayscale */ +/** Returns the 24-bit color value closest to \p g (grayscale). */ inline Fl_Color fl_rgb_color(uchar g) { if (!g) return FL_BLACK; else return (Fl_Color)(((((g << 8) | g) << 8) | g) << 8); } /** Returns a gray color value from black (i == 0) to white (i == FL_NUM_GRAY - 1). - FL_NUM_GRAY is defined to be 24 in the current FLTK release. - To get the closest FLTK gray value to an 8-bit grayscale color 'I' use: -\code - fl_gray_ramp(I * (FL_NUM_GRAY - 1) / 255) + FL_NUM_GRAY is defined to be 24 in the current FLTK release. + To get the closest FLTK gray value to an 8-bit grayscale color 'I' use: + + \code + fl_gray_ramp(I * (FL_NUM_GRAY - 1) / 255) \endcode */ inline Fl_Color fl_gray_ramp(int i) {return (Fl_Color)(i+FL_GRAY_RAMP);} -/** Returns a color out of the color cube. - r must be in the range 0 to FL_NUM_RED (5) minus 1, - g must be in the range 0 to FL_NUM_GREEN (8) minus 1, - b must be in the range 0 to FL_NUM_BLUE (5) minus 1. - - To get the closest color to a 8-bit set of R,G,B values use: - \code - fl_color_cube(R * (FL_NUM_RED - 1) / 255, - G * (FL_NUM_GREEN - 1) / 255, - B * (FL_NUM_BLUE - 1) / 255); - \endcode +/** Returns a color out of the color cube. + + \p r must be in the range 0 to FL_NUM_RED (5) minus 1, + \p g must be in the range 0 to FL_NUM_GREEN (8) minus 1, + \p b must be in the range 0 to FL_NUM_BLUE (5) minus 1. + + To get the closest color to a 8-bit set of R,G,B values use: + + \code + fl_color_cube(R * (FL_NUM_RED - 1) / 255, + G * (FL_NUM_GREEN - 1) / 255, + B * (FL_NUM_BLUE - 1) / 255); + \endcode */ inline Fl_Color fl_color_cube(int r, int g, int b) { return (Fl_Color)((b*FL_NUM_RED + r) * FL_NUM_GREEN + g + FL_COLOR_CUBE);} @@ -851,11 +852,11 @@ inline Fl_Color fl_color_cube(int r, int g, int b) { /*@{*/ /** The following constants define the mouse cursors that are available in FLTK. - + The double-headed arrows are bitmaps provided by FLTK on X, the others are provided by system-defined cursors. - - \todo enum Fl_Cursor needs maybe an image. + + \todo enum Fl_Cursor needs maybe an image. */ enum Fl_Cursor { FL_CURSOR_DEFAULT = 0, /**< the default cursor, usually an arrow. */ @@ -872,15 +873,15 @@ enum Fl_Cursor { FL_CURSOR_NWSE = 80, /**< diagonal arrow. */ FL_CURSOR_NESW = 81, /**< diagonal arrow. */ FL_CURSOR_NONE =255, /**< invisible. */ - // for back compatability (non MSWindows ones): - FL_CURSOR_N = 70, /**< for back compatability. */ - FL_CURSOR_NE = 69, /**< for back compatability. */ - FL_CURSOR_E = 49, /**< for back compatability. */ - FL_CURSOR_SE = 8, /**< for back compatability. */ - FL_CURSOR_S = 9, /**< for back compatability. */ - FL_CURSOR_SW = 7, /**< for back compatability. */ - FL_CURSOR_W = 36, /**< for back compatability. */ - FL_CURSOR_NW = 68 /**< for back compatability. */ + // for back compatibility (non MSWindows ones): + FL_CURSOR_N = 70, /**< for back compatibility. */ + FL_CURSOR_NE = 69, /**< for back compatibility. */ + FL_CURSOR_E = 49, /**< for back compatibility. */ + FL_CURSOR_SE = 8, /**< for back compatibility. */ + FL_CURSOR_S = 9, /**< for back compatibility. */ + FL_CURSOR_SW = 7, /**< for back compatibility. */ + FL_CURSOR_W = 36, /**< for back compatibility. */ + FL_CURSOR_NW = 68 /**< for back compatibility. */ }; /*@}*/ // group: Cursors diff --git a/FL/Fl_Browser.H b/FL/Fl_Browser.H index 6154a39ea..7a6edf518 100644 --- a/FL/Fl_Browser.H +++ b/FL/Fl_Browser.H @@ -3,7 +3,7 @@ // // Browser header file for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2011 by Bill Spitzak and others. // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Library General Public @@ -28,7 +28,7 @@ /* \file Fl_Browser widget . */ -// Forms-compatable browser. Probably useful for other +// Forms-compatible browser. Probably useful for other // lists of textual data. Notice that the line numbers // start from 1, and 0 means "no line". diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H index 4d6ec528e..61804ea8a 100644 --- a/FL/Fl_Widget.H +++ b/FL/Fl_Widget.H @@ -162,7 +162,7 @@ protected: */ enum { INACTIVE = 1<<0, ///< the widget can't receive focus, and is disabled but potentially visible - INVISIBLE = 1<<1, ///< the widget is not drawn but can receive events + INVISIBLE = 1<<1, ///< the widget is not drawn, but can receive a few special events OUTPUT = 1<<2, ///< for output only NOBORDER = 1<<3, ///< don't draw a decoration (Fl_Window) FORCE_POSITION = 1<<4, ///< don't let the window manager position the window (Fl_Window) @@ -660,14 +660,17 @@ public: int visible_r() const; /** Makes a widget visible. - An invisible widget never gets redrawn and does not get events. - The visible() method returns true if the widget is set to be - visible. The visible_r() method returns true if the widget and - all of its parents are visible. A widget is only visible if - visible() is true on it and all of its parents. - Changing it will send FL_SHOW or FL_HIDE events to - the widget. Do not change it if the parent is not visible, as this + An invisible widget never gets redrawn and does not get keyboard + or mouse events, but can receive a few other events like FL_SHOW. + + The visible() method returns true if the widget is set to be + visible. The visible_r() method returns true if the widget and + all of its parents are visible. A widget is only visible if + visible() is true on it and all of its parents. + + Changing it will send FL_SHOW or FL_HIDE events to the widget. + Do not change it if the parent is not visible, as this will send false FL_SHOW or FL_HIDE events to the widget. redraw() is called if necessary on this or the parent. @@ -720,7 +723,7 @@ public: Changing this value will send FL_DEACTIVATE to the widget if active_r() is true. - + Currently you cannot deactivate Fl_Window widgets. \see activate(), active(), active_r() @@ -748,10 +751,10 @@ public: void clear_output() {flags_ &= ~OUTPUT;} /** Returns if the widget is able to take events. - This is the same as (active() && !output() - && visible()) but is faster. + This is the same as (active() && !output() && visible()) + but is faster. \retval 0 if the widget takes no events - */ + */ unsigned int takesevents() const {return !(flags_&(INACTIVE|INVISIBLE|OUTPUT));} /** diff --git a/FL/dirent.h b/FL/dirent.h index 0426a712b..3c9d00d4a 100644 --- a/FL/dirent.h +++ b/FL/dirent.h @@ -3,7 +3,7 @@ // // Directory header file for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2011 by Bill Spitzak and others. // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Library General Public @@ -26,7 +26,7 @@ // -// this file is for back-compatability only +// this file is for back-compatibility only #include "filename.H" // diff --git a/FL/forms.H b/FL/forms.H index e90e3b61c..a2d1fc6e1 100644 --- a/FL/forms.H +++ b/FL/forms.H @@ -3,7 +3,7 @@ // // Forms emulation header file for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2011 by Bill Spitzak and others. // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Library General Public @@ -674,7 +674,7 @@ inline int fl_show_choices(const char* c,int n,const char* b1,const char* b2, #include "Fl_File_Chooser.H" inline int do_matching(char* a, const char* b) {return fl_filename_match(a,b);} -// Forms-compatable file chooser (implementation in fselect.C): +// Forms-compatible file chooser (implementation in fselect.C): FL_EXPORT char* fl_show_file_selector(const char* message,const char* dir, const char* pat,const char* fname); FL_EXPORT char* fl_get_directory(); diff --git a/FL/gl.h b/FL/gl.h index a2e5e0b9a..5afeb2f32 100644 --- a/FL/gl.h +++ b/FL/gl.h @@ -3,7 +3,7 @@ // // OpenGL header file for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2011 by Bill Spitzak and others. // // You must include this instead of GL/gl.h to get the Microsoft // APIENTRY stuff included (from ) prior to the OpenGL @@ -73,7 +73,7 @@ FL_EXPORT void gl_start(); FL_EXPORT void gl_finish(); FL_EXPORT void gl_color(Fl_Color i); -/** back compatability */ +/** back compatibility */ inline void gl_color(int c) {gl_color((Fl_Color)c);} FL_EXPORT void gl_rect(int x,int y,int w,int h); diff --git a/FL/glut.H b/FL/glut.H index 7dac1746d..38248066b 100644 --- a/FL/glut.H +++ b/FL/glut.H @@ -3,7 +3,7 @@ // // GLUT emulation header file for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2011 by Bill Spitzak and others. // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Library General Public @@ -407,7 +407,7 @@ FL_EXPORT GLUTproc glutGetProcAddress(const char *procName); //inline void glutVideoPan(int x, int y, int width, int height); -// Font argument must be a void* for compatability, so... +// Font argument must be a void* for compatibility, so... /** fltk glut font/size attributes used in the glutXXX functions */ struct Fl_Glut_Bitmap_Font {Fl_Font font; Fl_Fontsize size;}; diff --git a/documentation/src/events.dox b/documentation/src/events.dox index 73920feaf..2cbeba67a 100644 --- a/documentation/src/events.dox +++ b/documentation/src/events.dox @@ -128,47 +128,40 @@ This indicates an \e attempt to give a widget the keyboard focus. If a widget wants the focus, it should change itself to display the fact that it has the focus, and return non-zero from its -\p handle() -method. It then becomes the -Fl::focus() -widget and gets -\p FL_KEYDOWN, \p FL_KEYUP, and \p FL_UNFOCUS -events. +\p handle() method. It then becomes the Fl::focus() widget and gets +\p FL_KEYDOWN, \p FL_KEYUP, and \p FL_UNFOCUS events. -The focus will change either because the window manager -changed which window gets the focus, or because the user tried -to navigate using tab, arrows, or other keys. You can check -Fl::event_key() -to figure out why it moved. For navigation it will be the key -pressed and interaction with the window manager it will be zero. +The focus will change either because the window manager changed which +window gets the focus, or because the user tried to navigate using tab, +arrows, or other keys. You can check Fl::event_key() to figure out why +it moved. For navigation it will be the key pressed and for interaction +with the window manager it will be zero. \subsection events_fl_unfocus FL_UNFOCUS -This event is sent to the previous -Fl::focus() -widget when another widget gets the focus or the window loses focus. +This event is sent to the previous Fl::focus() widget when another +widget gets the focus or the window loses focus. \section events_keyboard Keyboard Events -\subsection events_fl_keydown FL_KEYDOWN, FL_KEYUP +\subsection events_fl_keydown FL_KEYBOARD, FL_KEYDOWN, FL_KEYUP -A key was pressed or released. The key can be found in -Fl::event_key(). -The text that the key should insert can be found with -Fl::event_text() -and its length is in -Fl::event_length(). -If you use the key, then -\p handle() -should return 1. If you +A key was pressed (FL_KEYDOWN) or released (FL_KEYUP). FL_KEYBOARD +is a synonym for FL_KEYDOWN, and both names are used interchangeably +in this documentation. + +The key can be found in Fl::event_key(). +The text that the key should insert can be found with Fl::event_text() +and its length is in Fl::event_length(). + +If you use the key, then \p handle() should return 1. If you return zero then FLTK assumes you ignored the key and will then attempt to send it to a parent widget. If none of them want it, it will change the event into a \p FL_SHORTCUT event. FL_KEYBOARD events are also generated by the character palette/map. -To receive \p FL_KEYBOARD events you must also -respond to the \p FL_FOCUS and \p FL_UNFOCUS -events. +To receive \p FL_KEYBOARD events you must also respond to the +\p FL_FOCUS and \p FL_UNFOCUS events. If you are writing a text-editing widget you may also want to call the Fl::compose() @@ -181,10 +174,8 @@ because focus may have changed between events. \subsection events_fl_shortcut FL_SHORTCUT -If the -Fl::focus() -widget is zero or ignores an \p FL_KEYBOARD event then -FLTK tries sending this event to every widget it can, until one +If the Fl::focus() widget is zero or ignores an \p FL_KEYBOARD event +then FLTK tries sending this event to every widget it can, until one of them returns non-zero. \p FL_SHORTCUT is first sent to the Fl::belowmouse() widget, then its parents and siblings, and eventually to every widget in the window, trying @@ -246,16 +237,20 @@ class \p handle() method! +\note The events in this chapter ("Widget Events"), i.e. + FL_ACTIVATE, FL_DEACTIVATE, FL_SHOW, and FL_HIDE, + are the only events deactivated and invisible widgets + can usually get, depending on their states. Under certain + circumstances, there may also be FL_LEAVE or FL_UNFOCUS + events delivered to deactivated or hidden widgets. + \section events_clipboard Clipboard Events \subsection events_fl_paste FL_PASTE -You should get this event some time after you call -Fl::paste(). -The contents of -Fl::event_text() -is the text to insert and the number of characters is in -Fl::event_length(). +You should get this event some time after you call Fl::paste(). +The contents of Fl::event_text() is the text to insert and the +number of characters is in Fl::event_length(). \subsection events_fl_selectionclear FL_SELECTIONCLEAR @@ -268,8 +263,8 @@ selection indication. Most modern programs ignore this. \section events_dnd Drag and Drop Events FLTK supports drag and drop of text and files from any -application on the desktop to an FLTK widget. Text is transfered using -the current code page. Files are received as a list of full path +application on the desktop to an FLTK widget. Text is transferred +using UTF-8 encoding. Files are received as a list of full path and file names, separated by newline. On some platforms, path names are prepended with %file://. See Fl::dnd() for drag and drop from an FLTK widget. @@ -305,7 +300,6 @@ The user has released the mouse button dropping data into the widget. If the widget returns 1, it will receive the data in the immediately following \p FL_PASTE event. - \section events_event_xxx Fl::event_*() methods @@ -345,17 +339,15 @@ event by returning 1. FLTK will then remove the event and wait for further event from the host. If the widget's handle function returns 0, FLTK may redistribute the event based on a few rules. -Most events are sent directly to the -\p handle() -method +Most events are sent directly to the \p handle() method of the Fl_Window that the window system says they belong to. The window (actually the Fl_Group that Fl_Window is a subclass of) is responsible for sending the events on to any child widgets. To make the Fl_Group code somewhat easier, FLTK sends some events (\p FL_DRAG, \p FL_RELEASE, \p FL_KEYBOARD, -\p FL_SHORTCUT, \p FL_UNFOCUS, and -\p FL_LEAVE) directly to leaf widgets. These procedures +\p FL_SHORTCUT, \p FL_UNFOCUS, and \p FL_LEAVE) +directly to leaf widgets. These procedures control those leaf widgets: \li Fl::add_handler() @@ -364,7 +356,7 @@ control those leaf widgets: \li Fl::grab() \li Fl::modal() \li Fl::pushed() -\li Fl::release() +\li Fl::release() (deprecated, see Fl::grab(0)) \li Fl_Widget::take_focus() FLTK propagates events along the widget hierarchy depending on the kind of event @@ -377,11 +369,8 @@ is below the click position. If that widget uses the given event, the widget is marked "pushed" and will receive all following mouse motion (FL_DRAG) events until the mouse button is released. -\todo Is this correct? IMHO, mouse motion (FL_MOVE) events are sent to the -belowmouse() widget, i.e. the widget that returned 1 on an FL_ENTER event. -The pushed() widget will usually get an FL_FOCUS event and becomes the focus() -widget if it returns 1 on FL_FOCUS, and will then get keyboard events (see -below). +Mouse motion (FL_MOVE) events are sent to the Fl::belowmouse() widget, i.e. +the widget that returned 1 on the last FL_ENTER event. Mouse wheel events are sent to the window that caused the event. The window propagates the event down the tree, first to the widget that is below the diff --git a/src/Fl_PostScript.cxx b/src/Fl_PostScript.cxx index 5a61e3a10..d02919379 100644 --- a/src/Fl_PostScript.cxx +++ b/src/Fl_PostScript.cxx @@ -3,7 +3,7 @@ // // PostScript device support for the Fast Light Tool Kit (FLTK). // -// Copyright 2010 by Bill Spitzak and others. +// Copyright 2010-2011 by Bill Spitzak and others. // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Library General Public @@ -867,7 +867,7 @@ void Fl_PostScript_Graphics_Driver::line_style(int style, int width, char* dashe linedash_[0]=0; char width0 = 0; if(!width){ - width=1; //for screen drawing compatability + width=1; //for screen drawing compatibility width0=1; } diff --git a/src/Fl_win32.cxx b/src/Fl_win32.cxx index 1fae9cf52..783f8d6b6 100644 --- a/src/Fl_win32.cxx +++ b/src/Fl_win32.cxx @@ -1561,7 +1561,7 @@ Fl_X* Fl_X::make(Fl_Window* w) { w->redraw(); // force draw to happen } // If we've captured the mouse, we dont want to activate any - // other windows from the code, or we loose the capture. + // other windows from the code, or we lose the capture. ShowWindow(x->xid, !showit ? SW_SHOWMINNOACTIVE : (Fl::grab() || (style & WS_POPUP)) ? SW_SHOWNOACTIVATE : SW_SHOWNORMAL); diff --git a/src/Fl_x.cxx b/src/Fl_x.cxx index 6b5ddf45f..51570d9f5 100644 --- a/src/Fl_x.cxx +++ b/src/Fl_x.cxx @@ -3,7 +3,7 @@ // // X specific code for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2011 by Bill Spitzak and others. // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Library General Public @@ -1253,7 +1253,7 @@ int fl_handle(const XEvent& thisevent) len = fl_utf8encode(XKeysymToUcs(keysym), buffer); if (len < 1) len = 1; // ignore all effects of shift on the keysyms, which makes it a lot - // easier to program shortcuts and is Windoze-compatable: + // easier to program shortcuts and is Windoze-compatible: keysym = XKeycodeToKeysym(fl_display, keycode, 0); } }