-Fl_Image - | - +----Fl_Bitmap - | - +----Fl_XBM_Image +Fl
-#include <FL/Fl_Bitmap.H> +#include <FL/Fl.H>
The Fl_Bitmap class supports caching and drawing of mono-color -(bitmap) images. Images are drawn using the current color.
+The Fl class is the FLTK global (static) class containing +state information and global methods for the current application.
The constructors create a new bitmap from the specified bitmap data.
+FLTK will call this callback just before it flushes the display and +waits for events. This is different than an idle callback because it +is only called once, then FLTK calls the system and tells it not to +return until an event happens. -
This can be used by code that wants to monitor the +application's state, such as to keep a display up to date. The +advantage of using a check callback is that it is called only when no +events are pending. If events are coming in quickly, whole blocks of +them will be processed before this is called once. This can save +significant time and avoid the application falling behind the events. -
The destructor free all memory and server resources that are used by -the bitmap.
+Sample code: + +
+bool state_changed; // anything that changes the display turns this on
+
+void callback(void*) {
+ if (!state_changed) return;
+ state_changed = false;
+ do_expensive_calculation();
+ widget->redraw();
+}
+
+main() {
+ Fl::add_check(1.0,callback);
+ return Fl::run();
+}
+
+
+Add file descriptor fd to listen to. When the fd +becomes ready for reading Fl::wait() will call the callback +and then return. The callback is +passed the fd and the arbitrary void* argument.
+ +The second version takes a when bitfield, with the bits +FL_READ, FL_WRITE, and FL_EXCEPT defined, +to indicate when the callback should be done. + +
There can only be one callback of each type for a file descriptor. +Fl::remove_fd() gets rid of all the callbacks for a given +file descriptor. + +
Under UNIX any file descriptor can be monitored (files, +devices, pipes, sockets, etc.) Due to limitations in Microsoft Windows, +WIN32 applications can only monitor sockets. + +
Install a function to parse unrecognized events. If FLTK cannot +figure out what to do with an event, it calls each of these functions +(most recent first) until one of them returns non-zero. If none of +them returns non zero then the event is ignored. Events that cause +this to be called are: + +
Adds a callback function that is called every time by +Fl::wait() and also makes it act as though the timeout is +zero (this makes Fl::wait() return immediately, so if it is +in a loop it is called repeatedly, and thus the idle fucntion is +called repeatedly). The idle function can be used to get background +processing done. + +
You can have multiple idle callbacks. To remove an idle callback use Fl::remove_idle(). + +
Fl::wait() and Fl::check() call idle callbacks, +but Fl::ready() does not. + +
The idle callback can call any FLTK functions, including +Fl::wait(), Fl::check(), and Fl::ready(). +FLTK will not recursively call the idle callback. + +
Add a one-shot timeout callback. The function will be called by +Fl::wait() at t seconds after this function is called. +The optional void* argument is passed to the callback. + +
Consume a single switch from argv, starting at word i. +Returns the number of words eaten (1 or 2, or 0 if it is not +recognized) and adds the same value to i. You can use this +function if you prefer to control the incrementing through the +arguments yourself. + +
FLTK provides an entirely optional command-line switch parser. +You don't have to call it if you don't like them! Everything it can do +can be done with other calls to FLTK. + +
To use the switch parser, call Fl::args(...) near the start +of your program. This does not open the display, instead +switches that need the display open are stashed into static variables. +Then you must display your first window by calling +window->show(argc,argv), which will do anything stored in the +static variables. + +
callback lets you define your own switches. It is called +with the same argc and argv, and with i the +index of each word. The callback should return zero if the switch is +unrecognized, and not change i. It should return non-zero if +the switch is recognized, and add at least 1 to i (it can add +more to consume words after the switch). This function is called +before any other tests, so you can override any FLTK +switch (this is why FLTK can use very short switches instead of +the long ones all other toolkits force you to use). + +
On return i is set to the index of the first non-switch. +This is either: + +
The return value is i unless an unrecognized switch is found, +in which case it is zero. If your program takes no arguments other +than switches you should produce an error if the return value is less +than argc. + +
All switches except -bg2 may be abbreviated one letter and case is ignored: + +
The second form of Fl::args() is useful if your program does +not have command line switches of its own. It parses all the switches, +and if any are not recognized it calls Fl::abort(Fl::help). + +
A usage string is displayed if Fl::args() detects an invalid +argument on the command-line. You can change the message by setting the +Fl::help pointer. + +
Changes fl_color(FL_WHITE) and the same colors as +Fl::foreground(). This color is used as a background by +Fl_Input and other text widgets. + +
Changes fl_color(FL_GRAY) to the given color, and changes the +gray ramp from 32 to 56 to black to white. These are the colors used +as backgrounds by almost all widgets and used to draw the edges of all +the boxtypes. + +
Get or set the widget that is below the mouse. This is for +highlighting buttons. It is not used to send FL_PUSH or +FL_MOVE directly, for several obscure reasons, but those events +typically go to this widget. This is also the first widget tried for +FL_SHORTCUT events. + +
If you change the belowmouse widget, the previous one and all +parents (that don't contain the new widget) are sent FL_LEAVE +events. Changing this does not send FL_ENTER to this +or any widget, because sending FL_ENTER is supposed to test +if the widget wants the mouse (by it returning non-zero from +handle()). + +
Returns the height offset for the given boxtype. + +
Returns the width offset for the given boxtype. + +
Returns the X offset for the given boxtype. + +
Returns the Y offset for the given boxtype. + +
Same as Fl::wait(0). Calling this during a big calculation +will keep the screen up to date and the interface responsive: + +
+while (!calculation_done()) {
+ calculate();
+ Fl::check();
+ if (user_hit_abort_button()) break;
+}
+
+
+The returns non-zero if any windows are displayed, and 0 if no +windows are displayed (this is likely to change in future versions of +FLTK). + +
If true then flush() will do something. + +
Sets the X display to use for all windows. Actually this just sets +the environment variable $DISPLAY to the passed string, so this only +works before you show() the first window or otherwise open the display, +and does nothing useful under WIN32. + +
FLTK calls this to print a normal error message. You can +override the behavior by setting the function pointer to your +own routine. + +
Fl::error means there is a recoverable error such as +the inability to read an image file. The default implementation +prints the error message to stderr and returns. + +
Returns which mouse button was pressed. This returns garbage if the +most recent event was not a FL_PUSH or FL_RELEASE +event. + +
The first form returns non-zero if the most recent FL_PUSH or +FL_KEYBOARD was a "double click". Returns N-1 for +N clicks. A double click is counted if the same button is pressed +again while event_is_click() is true. + +
The second form directly sets the number returned by +Fl::event_clicks(). This can be used to set it to zero so that +later code does not think an item was double-clicked. + +
Returns non-zero if the current event_x and event_y +put it inside the widget or inside an arbitrary bounding box. You +should always call this rather than doing your own comparison so you +are consistent about edge effects. + +
The first form returns non-zero if the mouse has not moved far enough +and not enough time has passed since the last FL_PUSH or +FL_KEYBOARD event for it to be considered a "drag" rather than a +"click". You can test this on FL_DRAG, FL_RELEASE, +and FL_MOVE events. The second form clears the value returned +by Fl::event_is_click(). Useful to prevent the next +click from being counted as a double-click or to make a popup menu +pick an item with a single click. Don't pass non-zero to this. + +
Fl::event_key() returns which key on the keyboard was last +pushed. It returns zero if the last event was not a key press or release. + +
Fl::event_key(int) returns true if the given key was held +down (or pressed) during the last event. This is constant until +the next event is read from the server. + +
Fl::get_key(int) returns true if the given key is held down +now. Under X this requires a round-trip to the server and is +much slower than Fl::event_key(int). + +
Keys are identified by the unshifted values. FLTK defines a +set of symbols that should work on most modern machines for every key +on the keyboard: + +
On X Fl::get_key(FL_Button+n) does not work. + +
On WIN32 Fl::get_key(FL_KP_Enter) and +Fl::event_key(FL_KP_Enter) do not work. + +
Returns the length of the text in Fl::event_text(). There +will always be a nul at this position in the text. However there may +be a nul before that if the keystroke translates to a nul character or +you paste a nul character. + +
This is a bitfield of what shift states were on and what mouse buttons +were held down during the most recent event. The second version +returns non-zero if any of the passed bits are turned on. The legal +bits are: + +
X servers do not agree on shift states, and FL_NUM_LOCK, FL_META, and +FL_SCROLL_LOCK may not work. The values were selected to match the +XFree86 server on Linux. In addition there is a bug in the way X works +so that the shift state is not correctly reported until the first event +after the shift key is pressed or released. + +
Returns the mouse position of the event relative to the Fl_Window +it was passed to. + +
Returns the mouse position on the screen of the event. To find the +absolute position of an Fl_Window on the screen, use the +difference between event_x_root(),event_y_root() and +event_x(),event_y(). + +
Returns the mouse position of the event relative to the Fl_Window +it was passed to. + +
Returns the mouse position on the screen of the event. To find the +absolute position of an Fl_Window on the screen, use the +difference between event_x_root(),event_y_root() and +event_x(),event_y(). + +
FLTK calls this to print a fatal error message. You can +override the behavior by setting the function pointer to your +own routine. + +
Fl::fatal must not return, as FLTK is in an unusable +state, however your version may be able to use longjmp +or an exception to continue, as long as it does not call FLTK +again. The default implementation prints the error message to +stderr and exits with status 1. + +
Returns the first top-level window in the list of shown() windows. If +a modal() window is shown this is the top-most modal window, otherwise +it is the most recent window to get an event. + +
The second form sets the window that is returned by +first_window. The window is removed from wherever it is in the +list and inserted at the top. This is not done if Fl::modal() +is on or if the window is not shown(). Because the first window +is used to set the "parent" of modal windows, this is often +useful. + +
Causes all the windows that need it to be redrawn and graphics forced +out through the pipes. This is what wait() does before +looking for events. + +
Get or set the widget that will receive FL_KEYBOARD events. + +
If you change Fl::focus(), the previous widget and all +parents (that don't contain the new widget) are sent FL_UNFOCUS +events. Changing the focus does not send FL_FOCUS to +this or any widget, because sending FL_FOCUS is supposed to +test if the widget wants the focus (by it returning non-zero from +handle()). + +
Changes fl_color(FL_BLACK). Also changes +FL_INACTIVE_COLOR and FL_SELECTION_COLOR to be a ramp +between this and FL_WHITE. + +
Frees the specified color from the colormap, if applicable. +If overlay is non-zero then the color is freed from the +overlay colormap. + +
Returns the color index or RGB value for the given FLTK color index. + +
Get the string for this face. This string is different for each +face. Under X this value is passed to XListFonts to get all the sizes +of this face. + +
Get a human-readable string describing the family of this face. This +is useful if you are presenting a choice to the user. There is no +guarantee that each face has a different name. The return value points +to a static buffer that is overwritten each call. + +
The integer pointed to by attributes (if the pointer is not +zero) is set to zero, FL_BOLD or FL_ITALIC or +FL_BOLD | FL_ITALIC. To locate a "family" of fonts, search +forward and back for a set with non-zero attributes, these faces along +with the face with a zero attribute before them constitute a family. + +
Return an array of sizes in sizep. The return value is the +length of this array. The sizes are sorted from smallest to largest +and indicate what sizes can be given to fl_font() that will +be matched exactly (fl_font() will pick the closest size for +other sizes). A zero in the first location of the array indicates a +scalable font, where any size works, although the array may list sizes +that work "better" than others. Warning: the returned array +points at a static buffer that is overwritten each call. Under X this +will open the display. + +
Return where the mouse is on the screen by doing a round-trip query to +the server. You should use Fl::event_x_root() and +Fl::event_y_root() if possible, but this is necessary if you are +not sure if a mouse event has been processed recently (such as to +position your first window). If the display is not open, this will +open it. + +
Read the user preference colors from the system and use them to call + Fl::foreground(), Fl::background(), and +Fl::background2(). This is done by +Fl_Window::show(argc,argv) before applying the -fg and -bg +switches. + +
On X this reads some common values from the Xdefaults database. +KDE users can set these values by running the "krdb" program, and +newer versions of KDE set this automatically if you check the "apply +style to other X programs" switch in their control panel. + +
This does the same thing as +Fl::visual(int) but also +requires OpenGL drawing to work. This must be done if +you want to draw in normal windows with OpenGL with gl_start() and +gl_end(). It may be useful to call this so your X +windows use the same visual as an +Fl_Gl_Window, which on +some servers will reduce colormap flashing. + +
See Fl_Gl_Window +for a list of additional values for the argument. + +
This is used when pop-up menu systems are active. Send all events to +the passed window no matter where the pointer or focus is (including +in other programs). The window does not have to be +shown() , this lets the handle() method of a +"dummy" window override all event handling and allows you to +map and unmap a complex set of windows (under both X and WIN32 +some window must be mapped because the system interface needs a +window id). + +
If grab() is on it will also affect show() of windows by +doing system-specific operations (on X it turns on +override-redirect). These are designed to make menus popup reliably +and faster on the system. + +
To turn off grabbing do Fl::grab(0). + +
Be careful that your program does not enter an infinite loop +while grab() is on. On X this will lock up your screen! + +
Returns the height of the screen in pixels. + +
Sends the event to a window for processing. Returns non-zero if any +widget uses the event. + +
Returns true if the check exists and has not been called yet. + +
Returns true if the specified idle callback is currently installed. + +
Returns true if the timeout exists and has not been called yet. + +
Returns the top-most modal() window currently shown. +This is the most recently +shown() window with +modal() true, or NULL if there are no modal() +windows shown(). +The modal() window has its handle() method called +for all events, and no other windows will have handle() +called (grab() overrides this). + +
Returns the next top-level window in the list of shown() windows. You can +use this call to iterate through all the windows that are shown(). + +
Makes FLTK use its own colormap. This may make FLTK display better +and will reduce conflicts with other programs that want lots of colors. +However the colors may flash as you move the cursor between windows. + +
This does nothing if the current visual is not colormapped. + +
Set things up so the receiver widget will be called with an +FL_PASTE event some time in the future. The reciever +should be prepared to be called directly by this, or for it to +happen later, or possibly not at all. This allows the +window system to take as long as necessary to retrieve the paste buffer +(or even to screw up completely) without complex and error-prone +synchronization code in FLTK. + +
Get or set the widget that is being pushed. FL_DRAG or +FL_RELEASE (and any more FL_PUSH) events will be sent to +this widget. + +
If you change the pushed widget, the previous one and all parents +(that don't contain the new widget) are sent FL_RELEASE +events. Changing this does not send FL_PUSH to this +or any widget, because sending FL_PUSH is supposed to test +if the widget wants the mouse (by it returning non-zero from +handle()). + +
All Fl_Widgets that don't have a callback defined use a +default callback that puts a pointer to the widget in this queue, and +this method reads the oldest widget out of this queue. + +
This is similar to Fl::check() except this does not +call Fl::flush() or any callbacks, which is useful if your +program is in a state where such callbacks are illegal. This returns +true if Fl::check() would do anything (it will continue to +return true until you call Fl::check() or Fl::wait()). + +
+while (!calculation_done()) {
+ calculate();
+ if (Fl::ready()) {
+ do_expensive_cleanup();
+ Fl::check();
+ if (user_hit_abort_button()) break;
+ }
+}
+
+
+Redraws all widgets. + +
Removes a check callback. It is harmless to remove a check +callback that no longer exists. + +
Removes the specified idle callback, if it is installed. + +
Removes a timeout callback. It is harmless to remove a timeout +callback that no longer exists. + +
Inside a timeout callback you can call this to add another timeout. +Rather than the time being measured from "now", it is measured from +when the system call elapsed that caused this timeout to be called. This +will result in far more accurate spacing of the timeout callbacks, it +also has slightly less system call overhead. (It will also use all +your machine time if your timeout code and FLTK's overhead take more +than t seconds, as the real timeout will be reduced to zero). + +
It is undefined what this does if called from outside a timeout +callback. + +
This code will print "TICK" each second on stdout, with a +fair degree of accuracy: + +
+void callback(void*) {
+ printf("TICK\n");
+ Fl::repeat_timeout(1.0,callback);
+}
+
+main() {
+ Fl::add_timeout(1.0,callback);
+ return Fl::run();
+}
+
+
+As long as any windows are displayed this calls Fl::wait() +repeatedly. When all the windows are closed it returns zero +(supposedly it would return non-zero on any errors, but FLTK calls +exit directly for these). A normal program will end main() +with return Fl::run();. + +
Changes the current selection. The block of text is +copied to an internal buffer by FLTK (be careful if doing this in +response to an FL_PASTE as this may be the same buffer +returned by event_text()). The selection_owner() +widget is set to the passed owner (possibly sending +FL_SELECTIONCLEAR to the previous owner). + +
The single-argument selection_owner(x) call can be used to +move the selection to another widget or to set the owner to +NULL, without changing the actual text of the +selection. FL_SELECTIONCLEAR is sent to the previous +selection owner, if any. + +
Copying the buffer every time the selection is changed is +obviously wasteful, especially for large selections. An interface will +probably be added in a future version to allow the selection to be made +by a callback function. The current interface will be emulated on top +of this. + +
The first form sets the function to call to draw a specific boxtype. + +
The second form copies the from boxtype. + +
Sets an entry in the fl_color index table. You can set it to +any 8-bit RGB color. The color is not allocated until fl_color(i) +is used. + +
The first form changes a face. The string pointer is simply stored, +the string is not copied, so the string must be in static memory. + +
The second form copies one face to another. + +
FLTK will open the display, and add every font on the server to the +face table. It will attempt to put "families" of faces together, so +that the normal one is first, followed by bold, italic, and bold +italic. + +
The optional argument is a string to describe the set of fonts to +add. Passing NULL will select only fonts that have the +ISO8859-1 character set (and are thus usable by normal text). Passing +"-*" will select all fonts with any encoding as long as they have +normal X font names with dashes in them. Passing "*" will list every +font that exists (on X this may produce some strange output). Other +values may be useful but are system dependent. With WIN32 NULL +selects fonts with ISO8859-1 encoding and non-NULL selects +all fonts. + +
The return value is how many faces are in the table after this is +done. + +
The first form sets the functions to call to draw and measure a +specific labeltype. + +
The second form copies the from labeltype. + +
Test the current event, which must be an FL_KEYBOARD or +FL_SHORTCUT, against a shortcut value (described in +Fl_Button). Returns non-zero if there is a match. Not to +be confused with +Fl_Widget::test_shortcut(). + +
Returns the compiled-in value of the FL_VERSION constant. This +is useful for checking the version of a shared library. + +
Gets or sets the visible keyboard focus on buttons and other +non-text widgets. The default mode is to enable keyboard focus +for all widgets. + +
Selects a visual so that your graphics are drawn correctly. This is +only allowed before you call show() on any windows. This does nothing +if the default visual satisfies the capabilities, or if no visual +satisfies the capabilities, or on systems that don't have such +brain-dead notions. + +
Only the following combinations do anything useful: + +
This returns true if the system has the capabilities by default or +FLTK suceeded in turing them on. Your program will still work even if +this returns false (it just won't look as good). + +
Returns the width of the screen in pixels. + +
Waits until "something happens" and then returns. Call this +repeatedly to "run" your program. You can also check what happened +each time after this returns, which is quite useful for managing +program state. + +
What this really does is call all idle callbacks, all elapsed +timeouts, call Fl::flush() to get the screen to update, and +then wait some time (zero if there are idle callbacks, the shortest of +all pending timeouts, or infinity), for any events from the user or +any Fl::add_fd() callbacks. It then handles the events and +calls the callbacks and then returns. + +
The return value of the first form is non-zero if there are +any visible windows - this may change in future versions of +FLTK. + +
The second form waits a maximum of time +seconds. It can return much sooner if something happens. + +
The return value is positive if an event or fd happens before the +time elapsed. It is zero if nothing happens (on Win32 this will only +return zero if time is zero). It is negative if an error +occurs (this will happen on Unix if a signal happens). + +
FLTK calls this to print a warning message. You can +override the behavior by setting the function pointer to your +own routine. + +
Fl::warning means that there was a recoverable +problem, the display may be messed up but the user can probably +keep working - all X protocol errors call this, for example. + +
Returns the origin of the current screen, where 0 indicates +the left side of the screen. + +
Returns the origin of the current screen, where 0 indicates +the top edge of the screen.