mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation updates, also fixing STR #2574, trying to make clear

Browse Source 
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
This commit is contained in:
Albrecht Schlosser 2011-04-24 17:09:41 +00:00
parent 89be9d5e04
commit 3b76848435
11 changed files with 296 additions and 303 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

449
FL/Enumerations.H
View File

@ -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 <I>attempt</I> 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)((b<FL_UP_BOX||b%4>1)?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_UP_BOX)?b:(b|1));
}
/**
Get the unfilled, frame only version of a box.
If no frame 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_frame(Fl_Boxtype b) {
return (Fl_Boxtype)((b%4<2)?b:(b+2));
}
@ -589,7 +587,7 @@ enum Fl_Labeltype { // labeltypes:
FL_NO_LABEL, ///< does nothing
_FL_SHADOW_LABEL, ///< draws a drop shadow under the text
_FL_ENGRAVED_LABEL, ///< draws edges as though the text is engraved
_FL_EMBOSSED_LABEL, ///< draws edges as thought the text is raised
_FL_EMBOSSED_LABEL, ///< draws edges as though the text is raised
_FL_MULTI_LABEL, ///< ?
_FL_ICON_LABEL, ///< draws the icon associated with the text
_FL_IMAGE_LABEL, ///< ?
@ -598,7 +596,7 @@ enum Fl_Labeltype { // labeltypes:
};
/**
Sets the current label type and return its corresponding Fl_Labeltype value.
Sets the current label type and return its corresponding Fl_Labeltype value.
@{
*/
#define FL_SYMBOL_LABEL FL_NORMAL_LABEL
@ -611,33 +609,33 @@ extern Fl_Labeltype FL_EXPORT fl_define_FL_EMBOSSED_LABEL();
/** @} */
/** \name Alignment Flags
* Flags to control the label alignment.
* This controls how the label is displayed next to or inside the widget.
* The default value is FL_ALIGN_CENTER for most widgets, which centers the label
* inside the widget.
*
* Flags can be or'd to achieve a combination of alignments.
*
* \code
* Outside alignments:
* TOP_LEFT TOP TOP_RIGHT
* LEFT_TOP+---------------------------------+RIGHT_TOP
* | |
* LEFT| |RIGHT
* | |
* LEFT_BOTTOM+---------------------------------+RIGHT_BOTTOM
* BOTTOM_RIGHT BOTTOM BOTTOM_LEFT
*
* Inside alignments:
* +---------------------------------+
* |TOP_LEFT TOP TOP_RIGHT|
* | |
* |LEFT RIGHT|
* | |
* |BOTTOM_RIGHT BOTTOM BOTTOM_LEFT|
* +---------------------------------+
* \endcode
* \see #FL_ALIGN_CENTER, etc.
Flags to control the label alignment.
This controls how the label is displayed next to or inside the widget.
The default value is FL_ALIGN_CENTER for most widgets, which centers the label
inside the widget.
Flags can be or'd to achieve a combination of alignments.
\code
Outside alignments:
TOP_LEFT TOP TOP_RIGHT
LEFT_TOP+---------------------------------+RIGHT_TOP
| |
LEFT| |RIGHT
| |
LEFT_BOTTOM+---------------------------------+RIGHT_BOTTOM
BOTTOM_RIGHT BOTTOM BOTTOM_LEFT
Inside alignments:
+---------------------------------+
|TOP_LEFT TOP TOP_RIGHT|
| |
|LEFT RIGHT|
| |
|BOTTOM_RIGHT BOTTOM BOTTOM_LEFT|
+---------------------------------+
\endcode
\see #FL_ALIGN_CENTER, etc.
*/
/*@{*/
/** FLTK type for alignment control */
@ -645,13 +643,13 @@ typedef unsigned Fl_Align;
/** Align the label horizontally in the middle. */
const Fl_Align FL_ALIGN_CENTER = (Fl_Align)0;
/** Align the label at the top of the widget. Inside labels appear below the top,
* outside labels are drawn on top of the widget. */
outside labels are drawn on top of the widget. */
const Fl_Align FL_ALIGN_TOP = (Fl_Align)1;
/** Align the label at the bottom of the widget. */
const Fl_Align FL_ALIGN_BOTTOM = (Fl_Align)2;
/** Align the label at the left of the widget. Inside labels appear left-justified
* starting at the left side of the widget, outside labels are right-justified and
* drawn to the left of the widget. */
starting at the left side of the widget, outside labels are right-justified and
drawn to the left of the widget. */
const Fl_Align FL_ALIGN_LEFT = (Fl_Align)4;
/** Align the label to the right of the widget. */
const Fl_Align FL_ALIGN_RIGHT = (Fl_Align)8;
@ -669,7 +667,7 @@ const Fl_Align FL_ALIGN_WRAP = (Fl_Align)128;
const Fl_Align FL_ALIGN_IMAGE_NEXT_TO_TEXT = (Fl_Align)0x0100;
/** If the label contains an image, draw the text to the left of the image. */
const Fl_Align FL_ALIGN_TEXT_NEXT_TO_IMAGE = (Fl_Align)0x0120;
/** If the label contains an image, draw the image or deimage in the backgroup. */
/** If the label contains an image, draw the image or deimage in the background. */
const Fl_Align FL_ALIGN_IMAGE_BACKDROP = (Fl_Align)0x0200;
const Fl_Align FL_ALIGN_TOP_LEFT = FL_ALIGN_TOP | FL_ALIGN_LEFT;
const Fl_Align FL_ALIGN_TOP_RIGHT = FL_ALIGN_TOP | FL_ALIGN_RIGHT;
@ -679,14 +677,14 @@ const Fl_Align FL_ALIGN_LEFT_TOP = 0x0007; // magic value
const Fl_Align FL_ALIGN_RIGHT_TOP = 0x000b; // magic value
const Fl_Align FL_ALIGN_LEFT_BOTTOM = 0x000d; // magic value
const Fl_Align FL_ALIGN_RIGHT_BOTTOM = 0x000e; // magic value
const Fl_Align FL_ALIGN_NOWRAP = (Fl_Align)0; // for back compatability
const Fl_Align FL_ALIGN_NOWRAP = (Fl_Align)0; // for back compatibility
const Fl_Align FL_ALIGN_POSITION_MASK = 0x000f; // left, right, top, bottom
const Fl_Align FL_ALIGN_IMAGE_MASK = 0x0320; // l/r, t/b, backdrop
/*@}*/
/** \name Font Numbers
The following constants define the standard FLTK fonts:
/** \name Font Numbers
The following constants define the standard FLTK fonts:
*/
/*@{*/
/** A font number is an index into the internal font table. */
@ -717,7 +715,7 @@ const Fl_Font FL_BOLD_ITALIC = 3; ///< add this to helvetica, courier
/*@}*/
/** Size of a font in pixels.
* This is the approximate height of a font in pixels.
This is the approximate height of a font in pixels.
*/
typedef int Fl_Fontsize;
@ -728,10 +726,10 @@ extern FL_EXPORT Fl_Fontsize FL_NORMAL_SIZE; ///< normal font size
Colors are either 8-bit indexes into a virtual colormap
or 24-bit RGB color values.
Color indices occupy the lower 8 bits of the value, while
RGB colors occupy the upper 24 bits, for a byte organization of RGBI.
<pre>
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)
</pre>
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

4
FL/Fl_Browser.H
View File

@ -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".

27
FL/Fl_Widget.H
View File

@ -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 <I>and all of its parents</I>.
Changing it will send FL_SHOW or FL_HIDE events to
the widget. <I>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 <I>and all of its parents</I>.
Changing it will send FL_SHOW or FL_HIDE events to the widget.
<I>Do not change it if the parent is not visible, as this
will send false FL_SHOW or FL_HIDE events to the widget</I>.
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));}
/**

4
FL/dirent.h
View File

@ -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"
//

4
FL/forms.H
View File

@ -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();

4
FL/gl.h
View File

@ -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 <windows.h>) 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);

4
FL/glut.H
View File

@ -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;};

93
documentation/src/events.dox
View File

@ -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!</I>
\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 <tt>%file://</tt>.
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.
<!-- NEED 6in -->
\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

4
src/Fl_PostScript.cxx
View File

@ -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;
}

2
src/Fl_win32.cxx
View File

@ -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);

4
src/Fl_x.cxx
View File

@ -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);
}
}