FLTK 1.4.4: Fl Class Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
Fl Class Reference

The Fl is the FLTK global (static) class containing state information and global methods for the current application. More...

`#include <Fl.H>`

## Public Types
enum | Fl_Option { OPTION_ARROW_FOCUS = 0 , OPTION_VISIBLE_FOCUS , OPTION_DND_TEXT , OPTION_SHOW_TOOLTIPS , OPTION_FNFC_USES_GTK , OPTION_FNFC_USES_ZENITY , OPTION_FNFC_USES_KDIALOG , OPTION_PRINTER_USES_GTK , OPTION_SHOW_SCALING , OPTION_SIMPLE_ZOOM_SHORTCUT , OPTION_LAST }
| Enumerator for global FLTK options. More...

## Static Public Member Functions
static int | abi_check (const int val=FL_ABI_VERSION)
| Returns whether the runtime library ABI version is correct.
static int | abi_version ()
| Returns the compiled-in value of the FL_ABI_VERSION constant.
static int | add_awake_handler_ (Fl_Awake_Handler, void *)
| Adds an awake handler for use in awake().
static void | add_check (Fl_Timeout_Handler, void *=0)
| FLTK will call this callback just before it flushes the display and waits for events.
static void | add_clipboard_notify (Fl_Clipboard_Notify_Handler h, void *data=0)
| FLTK will call the registered callback whenever there is a change to the selection buffer or the clipboard.
static void | add_fd (int fd, Fl_FD_Handler cb, void *=0)
| Adds file descriptor fd to listen to.
static void | add_fd (int fd, int when, Fl_FD_Handler cb, void *=0)
| Adds file descriptor fd to listen to.
static void | add_handler (Fl_Event_Handler ha)
| Install a function to parse unrecognized events.
static void | add_handler (Fl_Event_Handler ha, Fl_Event_Handler before)
| Install a function to parse unrecognized events with less priority than another function.
static void | add_idle (Fl_Idle_Handler cb, void *data=0)
| 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 function is called repeatedly).
static void | add_system_handler (Fl_System_Handler h, void *data)
| Install a function to intercept system events.
static void | add_timeout (double t, Fl_Timeout_Handler cb, void *data=0)
| Adds a one-shot timeout callback.
static int | api_version ()
| Returns the compiled-in value of the FL_API_VERSION constant.
static int | arg (int argc, char **argv, int &i)
| Parse a single switch from `argv`, starting at word `i`.
static void | args (int argc, char **argv)
| Parse all command line switches matching standard FLTK options only.
static int | args (int argc, char **argv, int &i, Fl_Args_Handler cb=0)
| Parse command line switches using the `cb` argument handler.
static int | args_to_utf8 (int argc, char **&argv)
| Convert Windows commandline arguments to UTF-8.
static int | awake (Fl_Awake_Handler cb, void *message=0)
| See void awake(void* message=0).
static void | awake (void *message=0)
| Sends a message pointer to the main thread, causing any pending Fl::wait() call to terminate so that the main thread can retrieve the message and any pending redraws can be processed.
static void | background (uchar, uchar, uchar)
| Changes fl_color(FL_BACKGROUND_COLOR) to the given color, and changes the gray ramp from 32 to 56 to black to white.
static void | background2 (uchar, uchar, uchar)
| Changes the alternative background color.
static Fl_Widget * | belowmouse ()
| Gets the widget that is below the mouse.
static void | belowmouse (Fl_Widget *)
| Sets the widget that is below the mouse.
static int | box_border_radius_max ()
| Get the maximum border radius of all "rounded" boxtypes in pixels.
static void | box_border_radius_max (int R)
| Set the maximum border radius of all "rounded" boxtypes in pixels.
static Fl_Color | box_color (Fl_Color)
| Gets the drawing color to be used for the background of a box.
static int | box_dh (Fl_Boxtype)
| Returns the height offset for the given boxtype.
static int | box_dw (Fl_Boxtype)
| Returns the width offset for the given boxtype.
static int | box_dx (Fl_Boxtype)
| Returns the X offset for the given boxtype.
static int | box_dy (Fl_Boxtype)
| Returns the Y offset for the given boxtype.
static int | box_shadow_width ()
| Get the box shadow width of all "shadow" boxtypes in pixels.
static void | box_shadow_width (int W)
| Set the box shadow width of all "shadow" boxtypes in pixels.
static bool | cairo_autolink_context ()
| Gets the current autolink mode for Cairo support.
static void | cairo_autolink_context (bool alink)
| When FLTK_HAVE_CAIRO is defined and cairo_autolink_context() is true, any current window dc is linked to a current Cairo context.
static cairo_t * | cairo_cc ()
| Gets the current Cairo context linked with a fltk window.
static void | cairo_cc (cairo_t *c, bool own=false)
| Sets the current Cairo context to `c`.
static void | cairo_flush (cairo_t *c)
| Flush Cairo drawings on Cairo context `c`.
static cairo_t * | cairo_make_current (Fl_Window *w)
| Provides a Cairo context for window wi.
static Fl_Callback_Reason | callback_reason ()
| Give the reason for calling a callback.
static int | check ()
| Same as Fl::wait(0).
static void | clear_widget_pointer (Fl_Widget const *w)
| Clears a widget pointer in the watch list.
static int | clipboard_contains (const char *type)
| Returns non 0 if the clipboard contains data matching `type`.
static int | compose (int &del)
| Any text editing widget should call this for each FL_KEYBOARD event.
static void | compose_reset ()
| If the user moves the cursor, be sure to call Fl::compose_reset().
static void | copy (const char *stuff, int len, int destination=0, const char *type=Fl::clipboard_plain_text)
| Copies data to the selection buffer, the clipboard, or both.
static int | damage ()
| If true then flush() will do something.
static void | damage (int d)
| If true then flush() will do something.
static void | default_atclose (Fl_Window *, void *)
| Default callback for window widgets.
static void | delete_widget (Fl_Widget *w)
| Schedules a widget for deletion at the next call to the event loop.
static void | disable_im ()
| Disables the system input methods facilities.
static void | display (const char *)
| Sets the X or Wayland display to use for all windows.
static int | dnd ()
| Initiate a Drag And Drop operation.
static int | dnd_text_ops ()
| Gets whether drag and drop text operations are supported.
static void | dnd_text_ops (int v)
| Sets whether drag and drop text operations are supported.
static void | do_widget_deletion ()
| Deletes widgets previously scheduled for deletion.
static int | draw_box_active ()
| Determines if the currently drawn box is active or inactive.
static int | draw_GL_text_with_textures ()
| returns whether whether OpenGL uses textures to draw all text.
static void | draw_GL_text_with_textures (int val)
| sets whether OpenGL uses textures to draw all text.
static void | enable_im ()
| Enables the system input methods facilities.
static int | event ()
| Returns the last event that was processed.
static int | event_alt ()
| Returns non-zero if the Alt key is pressed.
static int | event_button ()
| Gets which particular mouse button caused the current event.
static int | event_button1 ()
| Returns non-zero if mouse button 1 is currently held down.
static int | event_button2 ()
| Returns non-zero if mouse button 2 is currently held down.
static int | event_button3 ()
| Returns non-zero if mouse button 3 is currently held down.
static int | event_button4 ()
| Returns non-zero if mouse button 4 is currently held down.
static int | event_button5 ()
| Returns non-zero if mouse button 5 is currently held down.
static int | event_buttons ()
| Returns the mouse buttons state bits; if non-zero, then at least one button is pressed now.
static int | event_clicks ()
| Returns non zero if we had a double click event.
static void | event_clicks (int i)
| Manually sets the number returned by Fl::event_clicks().
static void * | event_clipboard ()
| During an FL_PASTE event of non-textual data, returns a pointer to the pasted data.
static const char * | event_clipboard_type ()
| Returns the type of the pasted data during an FL_PASTE event.
static int | event_command ()
| Returns non-zero if the FL_COMMAND key is pressed, either FL_CTRL or on OSX FL_META.
static int | event_ctrl ()
| Returns non-zero if the Control key is pressed.
static Fl_Event_Dispatch | event_dispatch ()
| Return the current event dispatch function.
static void | event_dispatch (Fl_Event_Dispatch d)
| Set a new event dispatch function.
static int | event_dx ()
| Returns the current horizontal mouse scrolling associated with the FL_MOUSEWHEEL event.
static int | event_dy ()
| Returns the current vertical mouse scrolling associated with the FL_MOUSEWHEEL event.
static int | event_inside (const Fl_Widget *)
| Returns whether or not the mouse event is inside a given child widget.
static int | event_inside (int, int, int, int)
| Returns whether or not the mouse event is inside the given rectangle.
static int | event_is_click ()
| 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".
static void | event_is_click (int i)
| Clears the value returned by Fl::event_is_click().
static int | event_key ()
| Gets which key on the keyboard was last pushed.
static int | event_key (int key)
| Returns true if the given `key` was held down (or pressed) during the last event.
static int | event_length ()
| Returns the length of the text in Fl::event_text().
static int | event_original_key ()
| Returns the keycode of the last key event, regardless of the NumLock state.
static int | event_shift ()
| Returns non-zero if the Shift key is pressed.
static int | event_state ()
| Returns the keyboard and mouse button states of the last event.
static int | event_state (int mask)
| Returns non-zero if any of the passed event state bits are turned on.
static const char * | event_text ()
| Returns the text associated with the current event, including FL_PASTE or FL_DND_RELEASE events.
static int | event_x ()
| Returns the mouse position of the event relative to the Fl_Window it was passed to.
static int | event_x_root ()
| Returns the mouse position on the screen of the event.
static int | event_y ()
| Returns the mouse position of the event relative to the Fl_Window it was passed to.
static int | event_y_root ()
| Returns the mouse position on the screen of the event.
static Fl_Window * | first_window ()
| Returns the first top-level window in the list of shown() windows.
static void | first_window (Fl_Window *)
| Sets the window that is returned by first_window().
static void | flush ()
| Causes all the windows that need it to be redrawn and graphics forced out through the pipes.
static Fl_Widget * | focus ()
| Gets the current Fl::focus() widget.
static void | focus (Fl_Widget *)
| Sets the widget that will receive FL_KEYBOARD events.
static void | foreground (uchar, uchar, uchar)
| Changes fl_color(FL_FOREGROUND_COLOR).
static void | free_color (Fl_Color i, int overlay=0)
| Frees the specified color from the colormap, if applicable.
static int | get_awake_handler_ (Fl_Awake_Handler &, void *&)
| Gets the last stored awake handler for use in awake().
static Fl_Box_Draw_F * | get_boxtype (Fl_Boxtype)
| Gets the current box drawing function for the specified box type.
static unsigned | get_color (Fl_Color i)
| Returns the RGB value(s) for the given FLTK color index.
static void | get_color (Fl_Color i, uchar &red, uchar &green, uchar &blue)
| Returns the RGB value(s) for the given FLTK color index.
static void | get_color (Fl_Color i, uchar &red, uchar &green, uchar &blue, uchar &alpha)
| Returns the RGBA value(s) for the given FLTK color index.
static const char * | get_font (Fl_Font)
| Gets the string for this face.
static const char * | get_font_name (Fl_Font, int *attributes=0)
| Get a human-readable string describing the family of this face.
static int | get_font_sizes (Fl_Font, int *&sizep)
| Return an array of sizes in `sizep`.
static int | get_key (int key)
| Returns true if the given `key` is held down now.
static void | get_mouse (int &, int &)
| Return where the mouse is on the screen by doing a round-trip query to the server.
static void | get_system_colors ()
| Read the user preference colors from the system and use them to call Fl::foreground(), Fl::background(), and Fl::background2().
static int | gl_visual (int, int *alist=0)
| This does the same thing as Fl::visual(int) but also requires OpenGL drawing to work.
static Fl_Window * | grab ()
| Returns the window that currently receives all events.
static void | grab (Fl_Window &win)
| See grab(Fl_Window*)
static void | grab (Fl_Window *)
| Selects the window to grab.
static int | h ()
| Returns the height in pixels of the main screen work area.
static int | handle (int, Fl_Window *)
| Handle events from the window system.
static int | handle_ (int, Fl_Window *)
| Handle events from the window system.
static int | has_check (Fl_Timeout_Handler, void *=0)
| Returns 1 if the check exists and has not been called yet, 0 otherwise.
static int | has_idle (Fl_Idle_Handler cb, void *data=0)
| Returns true if the specified idle callback is currently installed.
static int | has_timeout (Fl_Timeout_Handler cb, void *data=0)
| Returns true if the timeout exists and has not been called yet.
static void | hide_all_windows ()
| Hide all visible windows to make FLTK leave Fl::run().
static int | is_scheme (const char *name)
| Returns whether the current scheme is the given name.
static void | keyboard_screen_scaling (int value)
| Controls the possibility to scale all windows by ctrl/+/-/0/ or cmd/+/-/0/.
static Fl_Event_Handler | last_handler ()
| Returns the last function installed by a call to Fl::add_handler().
static int | lock ()
| The lock() method blocks the current thread until it can safely access FLTK widgets and data.
static int | menu_linespacing ()
| Gets the default line spacing used by menus.
static void | menu_linespacing (int H)
| Sets the default line spacing used by menus.
static Fl_Window * | modal ()
| Returns the top-most modal() window currently shown.
static Fl_Window * | next_window (const Fl_Window *)
| Returns the next top-level window in the list of shown() windows.
static Fl_Timestamp | now (double offset=0)
| Set a time stamp at this point in time with optional signed offset in seconds.
static bool | option (Fl_Option opt)
| FLTK library options management.
static void | option (Fl_Option opt, bool val)
| Override an option while the application is running.
static void | own_colormap ()
| Makes FLTK use its own colormap.
static void | paste (Fl_Widget &receiver)
| Backward compatibility only.
static void | paste (Fl_Widget &receiver, int source, const char *type=Fl::clipboard_plain_text)
| Pastes the data from the selection buffer (`source` is 0) or the clipboard (`source` is 1) into `receiver`.
static int | program_should_quit ()
| Returns non-zero when a request for program termination was received and accepted.
static void | program_should_quit (int should_i)
| Indicate to the FLTK library whether a program termination request was received and accepted.
static Fl_Widget * | pushed ()
| Gets the widget that is being pushed.
static void | pushed (Fl_Widget *)
| Sets the widget that is being pushed.
static Fl_Widget * | readqueue ()
| Reads the default callback queue and returns the first widget.
static int | ready ()
| 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.
static void | redraw ()
| Redraws all widgets.
static void | release ()
| Releases the current grabbed window, equals grab(0).
static void | release_widget_pointer (Fl_Widget *&w)
| Releases a widget pointer from the watch list.
static int | reload_scheme ()
| Called internally when setting a new scheme according to scheme name.
static void | remove_check (Fl_Timeout_Handler, void *=0)
| Removes a check callback.
static void | remove_clipboard_notify (Fl_Clipboard_Notify_Handler h)
| Stop calling the specified callback when there are changes to the selection buffer or the clipboard.
static void | remove_fd (int)
| Removes a file descriptor handler.
static void | remove_fd (int, int when)
| Removes a file descriptor handler.
static void | remove_handler (Fl_Event_Handler h)
| Removes a previously added event handler.
static void | remove_idle (Fl_Idle_Handler cb, void *data=0)
| Removes the specified idle callback, if it is installed.
static int | remove_next_timeout (Fl_Timeout_Handler cb, void *data=0, void **data_return=0)
| Remove the next matching timeout callback and return its `data` pointer.
static void | remove_system_handler (Fl_System_Handler h)
| Removes a previously added system event handler.
static void | remove_timeout (Fl_Timeout_Handler cb, void *data=0)
| Remove one or more matching timeout callbacks from the timer queue.
static void | repeat_timeout (double t, Fl_Timeout_Handler cb, void *data=0)
| Repeats a timeout callback from the expiration of the previous timeout, allowing for more accurate timing.
static int | run ()
| Calls Fl::wait()repeatedly as long as any windows are displayed.
static void | run_checks ()
static void | run_idle ()
static const char * | scheme ()
| See void scheme(const char *name)
static int | scheme (const char *name)
| Sets the current widget scheme.
static int | screen_count ()
| Gets the total count of available screens.
static void | screen_dpi (float &h, float &v, int n=0)
| Gets the screen resolution in dots-per-inch for the given screen.
static Fl_Screen_Driver * | screen_driver ()
| Returns a pointer to the unique Fl_Screen_Driver object of the platform.
static int | screen_num (int x, int y)
| Gets the screen number of a screen that contains the specified screen position `x`, `y`.
static int | screen_num (int x, int y, int w, int h)
| Gets the screen number of the screen which intersects the most with the rectangle defined by `x`, `y`, `w`, `h`.
static float | screen_scale (int n)
| Gets the GUI scaling factor of screen number `n`.
static void | screen_scale (int n, float factor)
| Sets the GUI scaling factor of screen number `n`.
static int | screen_scaling_supported ()
| Returns whether scaling factors are supported by this platform.
static void | screen_work_area (int &X, int &Y, int &W, int &H)
| Gets the bounding box of the work area of the screen that contains the mouse pointer.
static void | screen_work_area (int &X, int &Y, int &W, int &H, int mx, int my)
| Gets the bounding box of the work area of a screen that contains the specified screen position `mx`, `my`.
static void | screen_work_area (int &X, int &Y, int &W, int &H, int n)
| Gets the bounding box of the work area of the given screen.
static void | screen_xywh (int &X, int &Y, int &W, int &H)
| Gets the bounding box of a screen that contains the mouse pointer.
static void | screen_xywh (int &X, int &Y, int &W, int &H, int mx, int my)
| Gets the bounding box of a screen that contains the specified screen position `mx`, `my`.
static void | screen_xywh (int &X, int &Y, int &W, int &H, int mx, int my, int mw, int mh)
| Gets the screen bounding rect for the screen which intersects the most with the rectangle defined by `mx`, `my`, `mw`, `mh`.
static void | screen_xywh (int &X, int &Y, int &W, int &H, int n)
| Gets the screen bounding rect for the given screen.
static int | scrollbar_size ()
| Gets the default scrollbar size used by Fl_Browser_, Fl_Help_View, Fl_Scroll, and Fl_Text_Display widgets.
static void | scrollbar_size (int W)
| Sets the default scrollbar size that is used by the Fl_Browser_, Fl_Help_View, Fl_Scroll, and Fl_Text_Display widgets.
static double | seconds_between (Fl_Timestamp &back, Fl_Timestamp &further_back)
| Return the time in seconds between two time stamps.
static double | seconds_since (Fl_Timestamp &then)
| Return the time in seconds between now and a previously taken time stamp.
static void | selection (Fl_Widget &owner, const char *, int len)
| Changes the current selection.
static Fl_Widget * | selection_owner ()
| back-compatibility only: Gets the widget owning the current selection
static void | selection_owner (Fl_Widget *)
| Back-compatibility only: The single-argument 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.
static int | selection_to_clipboard ()
| Returns the current selection_to_clipboard mode.
static void | selection_to_clipboard (int mode)
| Copies selections on X11 directly to the clipboard if enabled.
static void | set_abort (Fl_Abort_Handler f)
| For back compatibility, sets the void Fl::fatal handler callback.
static void | set_atclose (Fl_Atclose_Handler f)
| For back compatibility, sets the Fl::atclose handler callback.
static void | set_box_color (Fl_Color)
| Sets the drawing color for the box that is currently drawn.
static void | set_boxtype (Fl_Boxtype, Fl_Box_Draw_F *, uchar, uchar, uchar, uchar, Fl_Box_Draw_Focus_F *=NULL)
| Sets the function to call to draw a specific box type.
static void | set_boxtype (Fl_Boxtype, Fl_Boxtype from)
| Copies the from boxtype.
static void | set_color (Fl_Color i, unsigned c)
| Sets an entry in the fl_color index table.
static void | set_color (Fl_Color, uchar, uchar, uchar)
| Sets an entry in the fl_color index table.
static void | set_color (Fl_Color, uchar, uchar, uchar, uchar)
| Sets an entry in the fl_color index table.
static void | set_font (Fl_Font, const char *)
| Changes a face.
static void | set_font (Fl_Font, Fl_Font)
| Copies one face to another.
static Fl_Font | set_fonts (const char *=0)
| FLTK will open the display, and add every fonts on the server to the face table.
static void | set_idle (Fl_Old_Idle_Handler cb)
| Sets an idle callback.
static void | set_labeltype (Fl_Labeltype, Fl_Label_Draw_F *, Fl_Label_Measure_F *)
| Sets the functions to call to draw and measure a specific labeltype.
static void | set_labeltype (Fl_Labeltype, Fl_Labeltype from)
| Sets the functions to call to draw and measure a specific labeltype.
static int | system (const char *command)
| Run a command line on the computer.
static Fl_System_Driver * | system_driver ()
| Returns a pointer to the unique Fl_System_Driver object of the platform.
static int | test_shortcut (Fl_Shortcut)
| Tests the current event, which must be an FL_KEYBOARD or FL_SHORTCUT, against a shortcut value (described in Fl_Button).
static void * | thread_message ()
| The thread_message() method returns the last message that was sent from a child by the awake() method.
static long | ticks_between (Fl_Timestamp &back, Fl_Timestamp &further_back)
| Return the time in ticks (60Hz) between two time stamps.
static long | ticks_since (Fl_Timestamp &then)
| Return the time in ticks (60Hz) between now and a previously taken time stamp.
static void | unlock ()
| The unlock() method releases the lock that was set using the lock() method.
static int | use_high_res_GL ()
| returns whether GL windows should be drawn at high resolution on Apple computers with retina displays.
static void | use_high_res_GL (int val)
| sets whether GL windows should be drawn at high resolution on Apple computers with retina displays
static double | version ()
| Returns the compiled-in value of the FL_VERSION constant.
static int | visible_focus ()
| Gets or sets the visible keyboard focus on buttons and other non-text widgets.
static void | visible_focus (int v)
| Gets or sets the visible keyboard focus on buttons and other non-text widgets.
static int | visual (int)
| Selects a visual so that your graphics are drawn correctly.
static int | w ()
| Returns the width in pixels of the main screen work area.
static int | wait ()
| Waits until "something happens" and then returns.
static double | wait (double time)
| Waits a maximum of `time_to_wait` seconds or until "something happens".
static void | watch_widget_pointer (Fl_Widget *&w)
| Adds a widget pointer to the widget watch list.
static int | x ()
| Returns the leftmost x coordinate of the main screen work area.
static int | y ()
| Returns the topmost y coordinate of the main screen work area.

## Static Public Attributes
static void(* | atclose )(Fl_Window *, void *)
| Back compatibility: default window callback handler.
static char const *const | clipboard_image = "image"
| Denotes image data.
static char const *const | clipboard_plain_text = "text/plain"
| Denotes plain textual data.
static void(* | error )(const char *,...) = Fl_System_Driver::error
| FLTK calls Fl::error() to output a normal error message.
static void(* | fatal )(const char *,...) = Fl_System_Driver::fatal
| FLTK calls Fl::fatal() to output a fatal error message.
static const char *const | help = helpmsg+13
| Usage string displayed if Fl::args() detects an invalid argument.
static void(* | idle )()
| The currently executing idle callback function: DO NOT USE THIS DIRECTLY!
static void(* | warning )(const char *,...) = Fl_System_Driver::warning
| FLTK calls Fl::warning() to output a warning message.

## Friends
class | Fl_System_Driver

## Detailed Description

The Fl is the FLTK global (static) class containing state information and global methods for the current application.

## Member Enumeration Documentation

## ◆ Fl_Option

enum Fl::Fl_Option

Enumerator for global FLTK options.

These options can be set system wide, per user, or for the running application only.

See also
  Fl::option(Fl_Option, bool)
  Fl::option(Fl_Option)

Enumerator
OPTION_ARROW_FOCUS | When switched on, moving the text cursor beyond the start or end of a text in a text widget will change focus to the next text widget. (This is considered 'old' behavior) When switched off (default), the cursor will stop at the end of the text. Pressing Tab or Ctrl-Tab will advance the keyboard focus. See also: Fl_Input_::tab_nav()
OPTION_VISIBLE_FOCUS | If visible focus is switched on (default), FLTK will draw a dotted rectangle inside the widget that will receive the next keystroke. If switched off, no such indicator will be drawn and keyboard navigation is disabled.
OPTION_DND_TEXT | If text drag-and-drop is enabled (default), the user can select and drag text from any text widget. If disabled, no dragging is possible, however dropping text from other applications still works.
OPTION_SHOW_TOOLTIPS | If tooltips are enabled (default), hovering the mouse over a widget with a tooltip text will open a little tooltip window until the mouse leaves the widget. If disabled, no tooltip is shown.
OPTION_FNFC_USES_GTK | When switched on (default), Fl_Native_File_Chooser runs GTK file dialogs if the GTK library is available on the platform (linux/unix only). When switched off, GTK file dialogs aren't used even if the GTK library is available.
OPTION_FNFC_USES_ZENITY | Meaningful for the Wayland/X11 platform only. When switched on, the library uses a Zenity-based file dialog. When switched off (default), no zenity-based file dialog is used.
OPTION_FNFC_USES_KDIALOG | Meaningful for the Wayland/X11 platform only. When switched on, the library uses a kdialog-based file dialog if command 'kdialog' is available on the running system. When switched off (default), no kdialog-based file dialog is used.
OPTION_PRINTER_USES_GTK | When switched on (default), Fl_Printer runs the GTK printer dialog if the GTK library is available on the platform (linux/unix only). When switched off, the GTK printer dialog isn't used even if the GTK library is available.
OPTION_SHOW_SCALING | When switched on (default), the library shows in a transient yellow window the zoom factor value. When switched off, no such window gets displayed.
OPTION_SIMPLE_ZOOM_SHORTCUT | When switched on and when the keyboard in use has '+' in the shifted position of its key, pressing that key and ctrl triggers the zoom-in operation. When switched off (default), the zoom-in operation requires that also the shift key is pressed. Under macOS, this option has no effect because the OS itself generates ⌘= followed by ⌘+ when pressing ⌘ and the '=|+' key without pressing shift.
OPTION_LAST | For internal use only.

## Member Function Documentation

## ◆ abi_check()

int Fl::abi_check | ( | const int | val = FL_ABI_VERSION | ) |
| inlinestatic

Returns whether the runtime library ABI version is correct.

This enables you to check the ABI version of the linked FLTK library at runtime.

Returns 1 (true) if the compiled ABI version (in the header files) and the linked library ABI version (used at runtime) are the same, 0 (false) otherwise.

Argument `val` can be used to query a particular library ABI version. Use for instance 10303 to query if the runtime library is compatible with FLTK ABI version 1.3.3. This is rarely useful.

The default `val` argument is FL_ABI_VERSION, which checks the version defined at configure time (i.e. in the header files at program compilation time) against the linked library version used at runtime. This is particularly useful if you linked with a shared object library, but it also concerns static linking.

See also
  Fl::abi_version()

## ◆ abi_version()

int Fl::abi_version | ( |  | ) |
| static

Returns the compiled-in value of the FL_ABI_VERSION constant.

This is useful for checking the version of a shared library.

## ◆ add_check()

void Fl::add_check | ( | Fl_Timeout_Handler | cb,
|  | void * | argp = 0 )
| static

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.

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(callback);
return Fl::run();
}
Fl::run
static int run()
Calls Fl::wait()repeatedly as long as any windows are displayed.
Definition Fl.cxx:651
Fl::add_check
static void add_check(Fl_Timeout_Handler, void *=0)
FLTK will call this callback just before it flushes the display and waits for events.
Definition Fl.cxx:459

## ◆ add_fd() [1/2]

void Fl::add_fd | ( | int | fd,
|  | Fl_FD_Handler | cb,
|  | void * | d = 0 )
| static

Adds file descriptor fd to listen to.

See Fl::add_fd(int fd, int when, Fl_FD_Handler cb, void* = 0) for details

## ◆ add_fd() [2/2]

void Fl::add_fd | ( | int | fd,
|  | int | when,
|  | Fl_FD_Handler | cb,
|  | void * | d = 0 )
| static

Adds 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.

This 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/Linux/macOS any file descriptor can be monitored (files, devices, pipes, sockets, etc.). Due to limitations in Microsoft Windows, Windows applications can only monitor sockets.

Under macOS, Fl::add_fd() opens the display if that's not been done before.

## ◆ add_idle()

void Fl::add_idle | ( | Fl_Idle_Handler | cb,
|  | void * | data = 0 )
| static

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 function 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.

Parameters

  [in] | cb | your idle callback
  [in] | data | an arbitrary data value provided to your callback

## ◆ add_timeout()

void Fl::add_timeout | ( | double | time,
|  | Fl_Timeout_Handler | cb,
|  | void * | data = 0 )
| static

Adds a one-shot timeout callback.

The callback function `cb` will be called by Fl::wait() at `time` seconds after this function is called. The callback function must have the signature Fl_Timeout_Handler. The optional `data` argument is passed to the callback (default: NULL).

The timer is removed from the timer queue before the callback function is called. It is safe to reschedule the timeout inside the callback function.

You can have multiple timeout callbacks, even the same timeout callback with different timeout values and/or different `data` values. They are all considered different timer objects.

To remove a timeout while it is active (pending) use Fl::remove_timeout().

If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to reschedule the subsequent timeouts. Please see Fl::repeat_timeout() for an example.

Since version 1.4, a timeout can be started from a child thread under the condition that the call to Fl::add_timeout is wrapped in Fl::lock() and Fl::unlock().

Parameters

  [in] | time | delta time in seconds until the timer expires
  [in] | cb | callback function
  [in] | data | optional user data (default: `NULL`)

See also
  Fl_Timeout_Handler
  Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *data)
  Fl::remove_timeout(Fl_Timeout_Handler cb, void *data)
  Fl::has_timeout(Fl_Timeout_Handler cb, void *data)

## ◆ api_version()

int Fl::api_version | ( |  | ) |
| static

Returns the compiled-in value of the FL_API_VERSION constant.

This is useful for checking the version of a shared library.

## ◆ arg()

int Fl::arg | ( | int | argc,
|  | char ** | argv,
|  | int & | i )
| static

Parse 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`.

This is the default argument handler used internally by Fl::args(...), but you can use this function if you prefer to step through the standard FLTK switches yourself.

All standard FLTK switches except -bg2 may be abbreviated to just one letter and case is ignored:

- -bg color or -background color
  Sets the background color using Fl::background().

- -bg2 color or -background2 color
  Sets the secondary background color using Fl::background2().

- -display host:n.n
  Sets the X display to use; this option is silently ignored under Windows and MacOS.

- -dnd and -nodnd
  Enables or disables drag and drop text operations using Fl::dnd_text_ops().

- -fg color or -foreground color
  Sets the foreground color using Fl::foreground().

- -geometry WxH+X+Y
  Sets the initial window position and size according to the standard X geometry string.

- -iconic
  Iconifies the window using Fl_Window::iconize().

- -kbd and -nokbd
  Enables or disables visible keyboard focus for non-text widgets using Fl::visible_focus().

- -name string
  Sets the window class using Fl_Window::xclass().

- -scheme string
  Sets the widget scheme using Fl::scheme().

- -title string
  Sets the window title using Fl_Window::label().

- -tooltips and -notooltips
  Enables or disables tooltips using Fl_Tooltip::enable().

Color values are commonly given as three digit or six digit hex numbers.

- The order of fg, bg, and bg2 in the command line does not matter
- There is no way at the moment to set the selection color.
- Setting the bg2 color also changes the fg color to have sufficient contrast
- Explicitly setting fg color overrides the bg2/contrast constraint.
- Setting the bg color will update the color lookup table for the gray ramp, so color index values can stay the same for all apps, it's just mapped to different RGB values.
- The calculation of the gray ramp is only based on the bg color, so there is no way at the moment to create an inverted (dark mode) ramp.
- Consequently, setting bg to black creates a an all-black ramp, setting a somewhat dark bg color creates a extremely dark ramp.
- Setting the bg has no influence on bg2 or fg.

If your program requires other switches in addition to the standard FLTK options, you will need to pass your own argument handler to Fl::args(int,char**,int&,Fl_Args_Handler) explicitly.

See also
  fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b) to see how color values can be defined

## ◆ args() [1/2]

void Fl::args | ( | int | argc,
|  | char ** | argv )
| static

Parse all command line switches matching standard FLTK options only.

It parses all the switches, and if any are not recognized it calls Fl::abort(Fl::help), i.e. unlike the long form, an unrecognized switch generates an error message and causes the program to exit.

## ◆ args() [2/2]

int Fl::args | ( | int | argc,
|  | char ** | argv,
|  | int & | i,
|  | Fl_Args_Handler | cb = 0 )
| static

Parse command line switches using the `cb` argument handler.

Returns 0 on error, or the number of words processed.

FLTK provides this as an entirely optional command line switch parser. You don't have to call it if you don't want to. 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.

Providing an argument handler callback `cb` lets you define your own switches. It is called with the same `argc` and `argv`, and with `i` set to the index of the switch to be processed. The `cb` handler should return zero if the switch is unrecognized, and not change `i`. It should return non-zero to indicate the number of words processed if the switch is recognized, i.e. 1 for just the switch, and more than 1 for the switch plus associated parameters. `i` should be incremented by the same amount.

The `cb` handler is called before any other tests, so you can also override any standard FLTK switch (this is why FLTK can use very short switches instead of the long ones all other toolkits force you to use). See Fl::arg() for descriptions of the standard switches.

On return `i` is set to the index of the first non-switch. This is either:

- The first word that does not start with '-'.
- The word '-' (used by many programs to name stdin as a file)
- The first unrecognized switch (return value is 0).
- `argc`

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`.

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.

A very simple command line parser can be found in examples/howto-parse-args.cxx

The simpler Fl::args(int argc, char **argv) form is useful if your program does not have command line switches of its own.

## ◆ args_to_utf8()

int Fl::args_to_utf8 | ( | int | argc,
|  | char **& | argv )
| static

Convert Windows commandline arguments to UTF-8.

Note
  This function does nothing on other (non-Windows) platforms, hence you may call it on all platforms or only on Windows by using platform specific code like '#ifdef _WIN32' etc. - it's your choice. Calling it on other platforms returns quickly w/o wasting much CPU time.

This function must be called on Windows platforms in `main()` before the array `argv` is used if your program uses any commandline argument strings (these should be UTF-8 encoded). This applies also to standard FLTK commandline arguments like "-name" (class name) and "-title" (window title in the title bar).

Unfortunately Windows neither provides commandline arguments in UTF-8 encoding nor as Windows "Wide Character" strings in the standard `main()` and/or the Windows specific `WinMain()` function.

On Windows platforms (no matter which build system) this function calls a Windows specific function to retrieve commandline arguments as Windows "Wide Character" strings, converts these strings to an internally allocated buffer (or multiple buffers) and returns the result in `argv`. For implementation details please refer to the source code; however these details may be changed in the future.

Note that `argv` is provided by reference so it can be overwritten.

In the recommended simple form the function overwrites the variable `argv` and allocates a new array of strings pointed to by `argv`. You may use this form on all platforms and it is as simple as adding one line to old programs to make them work with international (UTF-8) commandline arguments.

int main(int argc, char **argv) {
Fl::args_to_utf8(argc, argv); // add this line
// ... use argc and argv, e.g. for commandline parsing
window->show(argc, argv);
return Fl::run();
}
Fl::args_to_utf8
static int args_to_utf8(int argc, char **&argv)
Convert Windows commandline arguments to UTF-8.
Definition Fl.cxx:2514

For an example see 'examples/howto-parse-args.cxx' in the FLTK sources.

If you want to retain the original `argc` and `argv` variables the following slightly longer and more complicated code works as well on all platforms.

int main(int argc, char **argv) {
char **argvn = argv; // must copy argv to work on all platforms
int argcn = Fl::args_to_utf8(argc, argvn);
// ... use argcn and argvn, e.g. for commandline parsing
window->show(argcn, argvn);
return Fl::run();
}

Parameters

  [in] | argc | used only on non-Windows platforms
  [out] | argv | modified only on Windows platforms

Returns
  argument count (always the same as argc)

Since
  1.4.0

## ◆ background()

void Fl::background | ( | uchar | r,
|  | uchar | g,
|  | uchar | b )
| static

Changes fl_color(FL_BACKGROUND_COLOR) 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.

## ◆ background2()

void Fl::background2 | ( | uchar | r,
|  | uchar | g,
|  | uchar | b )
| static

Changes the alternative background color.

This color is used as a background by Fl_Input and other text widgets.

This call may change fl_color(FL_FOREGROUND_COLOR) if it does not provide sufficient contrast to FL_BACKGROUND2_COLOR.

## ◆ box_border_radius_max() [1/2]

int Fl::box_border_radius_max | ( |  | ) |
| inlinestatic

Get the maximum border radius of all "rounded" boxtypes in pixels.

Since
  1.4.0

## ◆ box_border_radius_max() [2/2]

void Fl::box_border_radius_max | ( | int | R | ) |
| inlinestatic

Set the maximum border radius of all "rounded" boxtypes in pixels.

Must be at least 5, default = 15.

Note
  This does not apply to the "round" boxtypes which have really round sides (i.e. composed of half circles) as opposed to "rounded" boxtypes that have only rounded corners with a straight border between corners.

The box border radius of "rounded" boxtypes is typically calculated as about 2/5 of the box height or width, whichever is smaller. The upper limit can be set by this method for all "rounded" boxtypes.

Since
  1.4.0

## ◆ box_color()

Fl_Color Fl::box_color | ( | Fl_Color | c | ) |
| static

Gets the drawing color to be used for the background of a box.

This method is only useful inside box drawing code. It returns the color to be used, either fl_inactive(c) if the widget is !active_r() or `c` otherwise.

## ◆ box_dh()

int Fl::box_dh | ( | Fl_Boxtype | t | ) |
| static

Returns the height offset for the given boxtype.

See also
  box_dy().

## ◆ box_dw()

int Fl::box_dw | ( | Fl_Boxtype | t | ) |
| static

Returns the width offset for the given boxtype.

See also
  box_dy().

## ◆ box_dx()

int Fl::box_dx | ( | Fl_Boxtype | t | ) |
| static

Returns the X offset for the given boxtype.

See also
  box_dy()

## ◆ box_dy()

int Fl::box_dy | ( | Fl_Boxtype | t | ) |
| static

Returns the Y offset for the given boxtype.

These functions return the offset values necessary for a given boxtype, useful for computing the area inside a box's borders, to prevent overdrawing the borders.

For instance, in the case of a boxtype like FL_DOWN_BOX where the border width might be 2 pixels all around, the above functions would return 2, 2, 4, and 4 for box_dx, box_dy, box_dw, and box_dh respectively.

An example to compute the area inside a widget's box():

int X = yourwidget->x() + Fl::box_dx(yourwidget->box());
int Y = yourwidget->y() + Fl::box_dy(yourwidget->box());
int W = yourwidget->w() - Fl::box_dw(yourwidget->box());
int H = yourwidget->h() - Fl::box_dh(yourwidget->box());
Fl::box_dx
static int box_dx(Fl_Boxtype)
Returns the X offset for the given boxtype.
Definition fl_boxtype.cxx:379
Fl::box_dw
static int box_dw(Fl_Boxtype)
Returns the width offset for the given boxtype.
Definition fl_boxtype.cxx:410
Fl::box_dy
static int box_dy(Fl_Boxtype)
Returns the Y offset for the given boxtype.
Definition fl_boxtype.cxx:404
Fl::box_dh
static int box_dh(Fl_Boxtype)
Returns the height offset for the given boxtype.
Definition fl_boxtype.cxx:416

These functions are mainly useful in the draw() code for deriving custom widgets, where one wants to avoid drawing over the widget's own border box().

## ◆ box_shadow_width() [1/2]

int Fl::box_shadow_width | ( |  | ) |
| inlinestatic

Get the box shadow width of all "shadow" boxtypes in pixels.

Since
  1.4.0

## ◆ box_shadow_width() [2/2]

void Fl::box_shadow_width | ( | int | W | ) |
| inlinestatic

Set the box shadow width of all "shadow" boxtypes in pixels.

Must be at least 1, default = 3. There is no upper limit.

Since
  1.4.0

## ◆ check()

int Fl::check | ( |  | ) |
| static

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;
}
Fl::check
static int check()
Same as Fl::wait(0).
Definition Fl.cxx:694

This 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).

## ◆ display()

void Fl::display | ( | const char * | d | ) |
| static

Sets the X or Wayland display to use for all windows.

This sets the environment variable $DISPLAY or $WAYLAND_DISPLAY to the passed string, so this only works before you show() the first window or otherwise open the display.

This does nothing on other platforms.

## ◆ dnd_text_ops() [1/2]

int Fl::dnd_text_ops | ( |  | ) |
| inlinestatic

Gets whether drag and drop text operations are supported.

This returns whether selected text can be dragged from text fields or dragged within a text field as a cut/paste shortcut.

## ◆ dnd_text_ops() [2/2]

void Fl::dnd_text_ops | ( | int | v | ) |
| inlinestatic

Sets whether drag and drop text operations are supported.

This specifically affects whether selected text can be dragged from text fields or dragged within a text field as a cut/paste shortcut.

## ◆ draw_box_active()

int Fl::draw_box_active | ( |  | ) |
| static

Determines if the currently drawn box is active or inactive.

If inactive, the box color should be changed to the inactive color.

See also
  Fl::box_color(Fl_Color c)

## ◆ draw_GL_text_with_textures() [1/2]

int Fl::draw_GL_text_with_textures | ( |  | ) |
| inlinestatic

returns whether whether OpenGL uses textures to draw all text.

Default is yes.

See also
  draw_GL_text_with_textures(int val)

Version
  1.4.0

## ◆ draw_GL_text_with_textures() [2/2]

void Fl::draw_GL_text_with_textures | ( | int | val | ) |
| inlinestatic

sets whether OpenGL uses textures to draw all text.

By default, FLTK draws OpenGL text using textures, if the necessary hardware support is available. Call `Fl::draw_GL_text_with_textures(0)` once in your program before the first call to gl_font() to have FLTK draw instead OpenGL text using a legacy, platform-dependent procedure. It's recommended not to deactivate textures under the MacOS platform because the MacOS legacy procedure is extremely rudimentary.

Parameters

  val | use 0 to prevent FLTK from drawing GL text with textures

See also
  gl_texture_pile_height(int max)

Version
  1.4.0

## ◆ flush()

void Fl::flush | ( |  | ) |
| static

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.

Note: in multi-threaded applications you should only call Fl::flush() from the main thread. If a child thread needs to trigger a redraw event, it should instead call Fl::awake() to get the main thread to process the event queue.

## ◆ get_system_colors()

void Fl::get_system_colors | ( |  | ) |
| static

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.

## ◆ gl_visual()

int Fl::gl_visual | ( | int | ,
|  | int * | alist = 0 )
| static

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.

## ◆ has_idle()

int Fl::has_idle | ( | Fl_Idle_Handler | cb,
|  | void * | data = 0 )
| static

Returns true if the specified idle callback is currently installed.

An idle callback matches the request only if `data` matches the `data` argument when the callback was installed. There is no "wildcard" search.

Parameters

  [in] | cb | idle callback in question
  [in] | data | optional data. Default: zero / nullptr.

Returns
  Whether the given callback `cb` is queued with `data`.

Return values

  1 | The callback is currently in the callback queue.
  0 | The callback is not queued, or `data` doesn't match.

## ◆ has_timeout()

int Fl::has_timeout | ( | Fl_Timeout_Handler | cb,
|  | void * | data = 0 )
| static

Returns true if the timeout exists and has not been called yet.

Both arguments `cb` and `data` must match with at least one timer in the queue of active timers to return true (1).

Note
  It is a known inconsistency that Fl::has_timeout() does not use the `data` argument as a wildcard (match all) if it is zero (NULL) which Fl::remove_timeout() does. This is so for backwards compatibility with FLTK 1.3.x. Therefore using 0 (zero, NULL) as the timeout `data` value is discouraged unless you're sure that you don't need to use `Fl::has_timeout(callback, (void *)0);` or `Fl::remove_timeout(callback, (void *)0);`.

Parameters

  [in] | cb | Timer callback
  [in] | data | User data

Returns
  whether the timer was found in the queue

Return values

  0 | not found
  1 | found

## ◆ hide_all_windows()

void Fl::hide_all_windows | ( |  | ) |
| static

Hide all visible windows to make FLTK leave Fl::run().

Fl:run() will run as long as there are visible windows. Call Fl::hide_all_windows() to hide (close) all currently shown (visible) windows, effectively terminating the Fl::run() loop.

See also
  Fl::run()

Since
  1.4.0

## ◆ is_scheme()

int Fl::is_scheme | ( | const char * | name | ) |
| inlinestatic

Returns whether the current scheme is the given name.

This is a fast inline convenience function to support scheme-specific code in widgets, e.g. in their draw() methods, if required.

Use a valid scheme name, not `NULL` (although `NULL` is allowed, this is not a useful argument - see below).

If Fl::scheme() has not been set or has been set to the default scheme ("none" or "base"), then this will always return 0 regardless of the argument, because Fl::scheme() is `NULL` in this case.

Note
  The stored scheme name is always lowercase, and this method will do a case-sensitive compare, so you must provide a lowercase string to return the correct value. This is intentional for performance reasons.

Example:

if (Fl::is_scheme("gtk+")) { your_code_here(); }
Fl::is_scheme
static int is_scheme(const char *name)
Returns whether the current scheme is the given name.
Definition Fl.H:440

Parameters

  [in] | name | lowercase string of requested scheme name.

Returns
  1 if the given scheme is active, 0 otherwise.

See also
  Fl::scheme(const char *name)

## ◆ menu_linespacing() [1/2]

int Fl::menu_linespacing | ( |  | ) |
| static

Gets the default line spacing used by menus.

Returns
  The default line spacing, in pixels.

Since
  1.4.0

## ◆ menu_linespacing() [2/2]

void Fl::menu_linespacing | ( | int | H | ) |
| static

Sets the default line spacing used by menus.

Default is 4.

Parameters

  [in] | H | The new default line spacing between menu items, in pixels.

Since
  1.4.0

## ◆ now()

Fl_Timestamp Fl::now | ( | double | offset = 0 | ) |
| static

Set a time stamp at this point in time with optional signed offset in seconds.

The time stamp is an opaque type and does not represent the time of day or some time and date in the calendar. It is used with Fl::seconds_between() and Fl::seconds_since() to measure elapsed time.

Fl_Timestamp start = Fl::now();
// do something
double s = Fl::seconds_since(start);
printf("That operation took %g seconds\n", s);
Fl::now
static Fl_Timestamp now(double offset=0)
Set a time stamp at this point in time with optional signed offset in seconds.
Definition Fl_Timeout.cxx:79
Fl::seconds_since
static double seconds_since(Fl_Timestamp &then)
Return the time in seconds between now and a previously taken time stamp.
Definition Fl_Timeout.cxx:112
Fl_Timestamp
opaque Fl_Timestamp
Platform-specific point in time, used for delta time calculation.
Definition platform_types.h:73

Depending on the system the resolution may be milliseconds or microseconds. Under certain conditions (particularly on Windows) the value in member sec may wrap around and does not represent a real time (maybe runtime of the system). Function seconds_since() below uses this to subtract two timestamps which is always a correct delta time with milliseconds or microseconds resolution.

Parameters

  offset | optional signed offset in seconds added to the current time

Returns
  this moment in time offset by `offset` as an opaque time stamp

Todo
  Fl::system_driver()->gettime() was implemented for the Forms library and has a limited resolution (on Windows: milliseconds). On POSIX platforms it uses gettimeofday() with microsecond resolution. A new function could use a better resolution on Windows with its multimedia timers which requires a new dependency: winmm.lib (dll). This could be a future improvement, maybe set as a build option or generally (requires Win95 or 98?).

See also
  Fl::seconds_since(Fl_Timestamp& then)
  Fl::seconds_between(Fl_Timestamp& back, Fl_Timestamp& further_back)
  Fl::ticks_since(Fl_Timestamp& then)
  Fl::ticks_between(Fl_Timestamp& back, Fl_Timestamp& further_back)

## ◆ option() [1/2]

bool Fl::option | ( | Fl_Option | opt | ) |
| static

FLTK library options management.

Options provide a way for the user to modify the behavior of an FLTK application. For example, clearing the OPTION_SHOW_TOOLTIPS will disable tooltips for all FLTK applications.

Options are set by the user or the administrator on user or machine level. In 1.3, FLUID has an Options dialog for that. In 1.4, there is an app named fltk-options that can be used from the command line or as a GUI tool. The machine level setting is read first, and the user setting can override the machine setting.

This function is used throughout FLTK to quickly query the user's wishes. There are options for using a native file chooser instead of the FLTK one wherever possible, disabling tooltips, disabling visible focus, disabling FLTK file chooser preview, etc. .

See Fl::Fl_Option for a list of available options.

Example:

if ( Fl::option(Fl::OPTION_ARROW_FOCUS) )
{ ..on.. }
else
{ ..off.. }
Fl::OPTION_ARROW_FOCUS
@ OPTION_ARROW_FOCUS
When switched on, moving the text cursor beyond the start or end of a text in a text widget will chan...
Definition Fl.H:244
Fl::option
static bool option(Fl_Option opt)
FLTK library options management.
Definition Fl.cxx:2047

Note
  Since FLTK 1.4.0 options can be managed with the `fltk-options` program. In FLTK 1.3.x options can be set in FLUID.

Parameters

  opt | which option

Returns
  true or false

See also
  enum Fl::Fl_Option
  Fl::option(Fl_Option, bool)
  fltk-options application in command line and GUI mode

Since
  FLTK 1.3.0

## ◆ option() [2/2]

void Fl::option | ( | Fl_Option | opt,
|  | bool | val )
| static

Override an option while the application is running.

Apps can override the machine settings and the user settings by calling Fl::option(option, bool). The override takes effect immediately for this option for all widgets in the app for the life time of the app.

The override is not saved anywhere, and relaunching the app will restore the old settings.

Example:

Fl::option(Fl::OPTION_ARROW_FOCUS, true); // on
Fl::option(Fl::OPTION_ARROW_FOCUS, false); // off

Parameters

  opt | which option
  val | set to true or false

See also
  enum Fl::Fl_Option
  bool Fl::option(Fl_Option)

## ◆ own_colormap()

void Fl::own_colormap | ( |  | ) |
| static

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.

## ◆ program_should_quit() [1/2]

int Fl::program_should_quit | ( |  | ) |
| inlinestatic

Returns non-zero when a request for program termination was received and accepted.

On the MacOS platform, the "Quit xxx" item of the application menu is such a request, that is considered accepted when all windows are closed. On other platforms, this function returns 0 until `Fl::program_should_quit(1)` is called.

Version
  1.4.0

## ◆ program_should_quit() [2/2]

void Fl::program_should_quit | ( | int | should_i | ) |
| inlinestatic

Indicate to the FLTK library whether a program termination request was received and accepted.

A program may set this to 1, for example, while performing a platform-independent command asking the program to cleanly terminate, similarly to the "Quit xxx" item of the application menu under MacOS.

Version
  1.4.0

## ◆ readqueue()

Fl_Widget * Fl::readqueue | ( |  | ) |
| static

Reads the default callback queue and returns the first widget.

All Fl_Widgets that don't have a callback defined use the default callback `static` Fl_Widget::default_callback() that puts a pointer to the widget in a queue. This method reads the oldest widget out of this queue.

The queue (FIFO) is limited (currently 20 items). If the queue overflows, the oldest entry (Fl_Widget *) is discarded.

Relying on the default callback and reading the callback queue with Fl::readqueue() is not recommended. If you need a callback, you should set one with Fl_Widget::callback(Fl_Callback *cb, void *data) or one of its variants.

See also
  Fl_Widget::callback()
  Fl_Widget::callback(Fl_Callback *cb, void *data)
  Fl_Widget::default_callback()

## ◆ ready()

int Fl::ready | ( |  | ) |
| static

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;
}
}
Fl::ready
static int ready()
This is similar to Fl::check() except this does not call Fl::flush() or any callbacks,...
Definition Fl.cxx:717

## ◆ release()

void Fl::release | ( |  | ) |
| inlinestatic

Releases the current grabbed window, equals grab(0).

Deprecated
  Use Fl::grab(0) instead.

See also
  grab(Fl_Window*)

## ◆ reload_scheme()

int Fl::reload_scheme | ( |  | ) |
| static

Called internally when setting a new scheme according to scheme name.

Loads or reloads the current scheme selection.

Returns
  Always 1 (this may change in the future)

See void Fl::scheme(const char *name)

## ◆ remove_check()

void Fl::remove_check | ( | Fl_Timeout_Handler | cb,
|  | void * | argp = 0 )
| static

Removes a check callback.

It is harmless to remove a check callback that no longer exists.

## ◆ remove_idle()

void Fl::remove_idle | ( | Fl_Idle_Handler | cb,
|  | void * | data = 0 )
| static

Removes the specified idle callback, if it is installed.

The given idle callback is only removed if `data` matches the value used when the idle callback was installed. If the idle callback wants to remove itself, the value provided by the `data` argument can (and should) be used.

Example for a "one-shot" idle callback, i.e. one that removes itself when it is called for the first time.

#include <FL/Fl.H>
#include <FL/Fl_Double_Window.H>
#include <FL/Fl_Button.H>
void idle1(void *data) {
printf("idle1 called with data %4d\n", fl_int(data));
fflush(stdout);
// ... do something ...
Fl::remove_idle(idle1, data);
}
void quit_cb(Fl_Widget *w, void *v) {
w->window()->hide();
}
int main(int argc, char **argv) {
Fl_Double_Window *window = new Fl_Double_Window(200, 100);
Fl_Button *button = new Fl_Button(20, 20, 160, 60, "Quit");
button->callback(quit_cb);
window->end();
window->show(argc, argv);
Fl::add_idle(idle1, (void *)1234);
return Fl::run();
}
Fl.H
Fl static class.
Fl_Double_Window::show
void show() FL_OVERRIDE
Makes a widget visible.
Definition Fl_Double_Window.cxx:45
Fl_Group::end
void end()
Exactly the same as current(this->parent()).
Definition Fl_Group.cxx:73
Fl_Widget
Fl_Widget is the base class for all widgets in FLTK.
Definition Fl_Widget.H:112
Fl_Widget::callback
Fl_Callback_p callback() const
Gets the current callback function for the widget.
Definition Fl_Widget.H:740
Fl::remove_idle
static void remove_idle(Fl_Idle_Handler cb, void *data=0)
Removes the specified idle callback, if it is installed.
Definition Fl_add_idle.cxx:144
Fl::add_idle
static void add_idle(Fl_Idle_Handler cb, void *data=0)
Adds a callback function that is called every time by Fl::wait() and also makes it act as though the ...
Definition Fl_add_idle.cxx:68

Parameters

  [in] | cb | idle callback in question
  [in] | data | optional data. Default: zero / NULL.

## ◆ remove_next_timeout()

int Fl::remove_next_timeout | ( | Fl_Timeout_Handler | cb,
|  | void * | data = 0,
|  | void ** | data_return = 0 )
| static

Remove the next matching timeout callback and return its `data` pointer.

This method removes only the next matching timeout and returns in `data_return` (if non-NULL) the `data` member given when the timeout was scheduled.

This method is useful if you remove a timeout before it is scheduled and you need to get and use its data value, for instance to free() or delete the data associated with the timeout.

This method returns non-zero if a matching timeout was found and zero if no timeout matched the request.

If the return value is `N` > 1 then there are N - 1 more matching timeouts pending.

If you need to remove all timeouts with a particular callback `cb` you must repeat this call until it returns 1 (all timeouts removed) or zero (no matching timeout), whichever occurs first.

Parameters

  [in] | cb | Timer callback to be removed (must match)
  [in] | data | Wildcard if NULL, must match otherwise
  [in,out] | data_return | Pointer to (void *) to receive the data value

Returns
  non-zero if a timer was found and removed

Return values

  0 | no matching timer was found
  1 | the last matching timeout was found and removed
  N>1 | a matching timeout was removed and there are (N - 1) matching timeouts pending

See also
  Fl::remove_timeout(Fl_Timeout_Handler cb, void *data)

Since
  1.4.0

## ◆ remove_timeout()

void Fl::remove_timeout | ( | Fl_Timeout_Handler | cb,
|  | void * | data = 0 )
| static

Remove one or more matching timeout callbacks from the timer queue.

This method removes all matching timeouts, not just the first one.

If the `data` argument is `NULL` (the default!) only the callback `cb` must match, i.e. all timer entries with this callback are removed.

It is harmless to remove a timeout callback that no longer exists.

If you want to remove only the next matching timeout you can use Fl::remove_next_timeout(Fl_Timeout_Handler cb, void *data, void **data_return) (available since FLTK 1.4.0).

Parameters

  [in] | cb | Timer callback to be removed (must match)
  [in] | data | Wildcard if NULL (default), must match otherwise

See also
  Fl::remove_next_timeout(Fl_Timeout_Handler cb, void *data, void **data_return)

## ◆ repeat_timeout()

void Fl::repeat_timeout | ( | double | time,
|  | Fl_Timeout_Handler | cb,
|  | void * | data = 0 )
| static

Repeats a timeout callback from the expiration of the previous timeout, allowing for more accurate timing.

You should call this method only inside a timeout callback of the same or a logically related timer from whose expiration time the new timeout shall be scheduled. Otherwise the timing accuracy can't be improved and the exact behavior is undefined.

If you call this outside a timeout callback the behavior is the same as Fl::add_timeout().

Example: The following code will print "TICK" each second on stdout with a fair degree of accuracy:

#include <FL/Fl.H>
#include <FL/Fl_Window.H>
#include <stdio.h>
void callback(void *) {
printf("TICK\n");
Fl::repeat_timeout(1.0, callback); // retrigger timeout
}
int main() {
Fl_Window win(100, 100);
win.show();
Fl::add_timeout(1.0, callback); // set up first timeout
return Fl::run();
}
Fl_Window.H
Fl_Window widget .
Fl_Window
This widget produces an actual window.
Definition Fl_Window.H:55
Fl::repeat_timeout
static void repeat_timeout(double t, Fl_Timeout_Handler cb, void *data=0)
Repeats a timeout callback from the expiration of the previous timeout, allowing for more accurate ti...
Definition Fl.cxx:318
Fl::add_timeout
static void add_timeout(double t, Fl_Timeout_Handler cb, void *data=0)
Adds a one-shot timeout callback.
Definition Fl.cxx:277

Parameters

  [in] | time | delta time in seconds until the timer expires
  [in] | cb | callback function
  [in] | data | optional user data (default: `NULL`)

## ◆ run()

int Fl::run | ( |  | ) |
| static

Calls Fl::wait()repeatedly as long as any windows are displayed.

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

Note
  Fl::run() and Fl::wait() (but not Fl::wait(double)) both return when all FLTK windows are closed. Therefore, a MacOS FLTK application possessing Fl_Sys_Menu_Bar items able to create new windows and expected to keep running without any open window cannot use these two functions. One solution is to run the event loop as follows:
  while (!Fl::program_should_quit()) Fl::wait(1e20);
  Fl::wait
  static int wait()
  Waits until "something happens" and then returns.
  Definition Fl.cxx:672
  Fl::program_should_quit
  static int program_should_quit()
  Returns non-zero when a request for program termination was received and accepted.
  Definition Fl.H:463

## ◆ scheme()

int Fl::scheme | ( | const char * | s | ) |
| static

Sets the current widget scheme.

NULL will use the scheme defined in the FLTK_SCHEME environment variable or the scheme resource under X11. Otherwise, any of the following schemes can be used:

- "none" - This is the default look-n-feel which resembles old Windows (95/98/Me/NT/2000) and old GTK/KDE
- "base" - This is an alias for "none"
- "plastic" - This scheme is inspired by the Aqua user interface on macOS
- "gtk+" - This scheme is inspired by the Red Hat Bluecurve theme
- "gleam" - This scheme is inspired by the Clearlooks Glossy scheme. (Colin Jones and Edmanuel Torres).
- "oxy" - This is a subset of Dmitrij K's oxy scheme (STR 2675, 3477)

If the given scheme name is unknown, the default scheme will be used.

Setting the scheme (name) is case insensitive, but the stored scheme name will always be lowercase and Fl::scheme() will return this lowercase name or `NULL` if no scheme or the default scheme ("none" or "base") was set.

Parameters

  [in] | s | Scheme name of NULL

Return values

  0 | if the scheme has not been set or is the default scheme
  1 | if a scheme other than "none"/"base" was set

See also
  Fl::scheme() to get the name of the current scheme
  Fl::is_scheme(const char*) to test if the specified scheme is set

## ◆ scrollbar_size() [1/2]

int Fl::scrollbar_size | ( |  | ) |
| static

Gets the default scrollbar size used by Fl_Browser_, Fl_Help_View, Fl_Scroll, and Fl_Text_Display widgets.

Returns
  The default size for widget scrollbars, in pixels.

## ◆ scrollbar_size() [2/2]

void Fl::scrollbar_size | ( | int | W | ) |
| static

Sets the default scrollbar size that is used by the Fl_Browser_, Fl_Help_View, Fl_Scroll, and Fl_Text_Display widgets.

Parameters

  [in] | W | The new default size for widget scrollbars, in pixels.

## ◆ seconds_between()

double Fl::seconds_between | ( | Fl_Timestamp & | back,
|  | Fl_Timestamp & | further_back )
| static

Return the time in seconds between two time stamps.

Parameters

  [in] | back | a previously taken time stamp
  [in] | further_back | an even earlier time stamp

Returns
  elapsed seconds and fractions of a second

See also
  Fl::seconds_since(Fl_Timestamp& then)
  Fl::now()

## ◆ seconds_since()

double Fl::seconds_since | ( | Fl_Timestamp & | then | ) |
| static

Return the time in seconds between now and a previously taken time stamp.

Parameters

  [in] | then | a previously taken time stamp

Returns
  elapsed seconds and fractions of a second

See also
  Fl::seconds_between(Fl_Timestamp& back, Fl_Timestamp& further_back)
  Fl::now()
  Fl::distant_past()

## ◆ set_box_color()

void Fl::set_box_color | ( | Fl_Color | c | ) |
| static

Sets the drawing color for the box that is currently drawn.

This method sets the current drawing color fl_color() depending on the widget's state to either `c` or fl_inactive(c).

It should be used whenever a box background is drawn in the box (type) drawing code instead of calling fl_color(Fl_Color bg) with the background color `bg`, usually Fl_Widget::color().

This method is only useful inside box drawing code. Whenever a box is drawn with one of the standard box drawing methods, a static variable is set depending on the widget's current state - if the widget is !active_r() then the internal variable is false (0), otherwise it is true (1). This is faster than calling Fl_Widget::active_r() because the state is cached.

See also
  Fl::draw_box_active()
  Fl::box_color(Fl_Color)

## ◆ set_boxtype()

void Fl::set_boxtype | ( | Fl_Boxtype | t,
|  | Fl_Box_Draw_F * | f,
|  | uchar | dx,
|  | uchar | dy,
|  | uchar | dw,
|  | uchar | dh,
|  | Fl_Box_Draw_Focus_F * | ff = NULL )
| static

Sets the function to call to draw a specific box type.

Parameters

  [in] | t | index of the box type between 0 (FL_NO_BOX) and up to and including FL_MAX_BOXTYPE
  [in] | f | callback function that draws the box
  [in] | dx,dy | top left frame width, distance in pixels to box contents
  [in] | dw,dh | left plus right frame width, top plus bottom frame width
  [in] | ff | optional callback that draws the box focus, defaults to a rectangle, inset by dx, dy, dw, dh

## ◆ set_idle()

void Fl::set_idle | ( | Fl_Old_Idle_Handler | cb | ) |
| inlinestatic

Sets an idle callback.

Deprecated
  This method is obsolete - use the add_idle() method instead.

## ◆ ticks_between()

long Fl::ticks_between | ( | Fl_Timestamp & | back,
|  | Fl_Timestamp & | further_back )
| static

Return the time in ticks (60Hz) between two time stamps.

Parameters

  [in] | back | a previously taken time stamp
  [in] | further_back | an even earlier time stamp

Returns
  elapsed ticks in 60th of a second

See also
  Fl::ticks_since(Fl_Timestamp& then)
  Fl::now()

## ◆ ticks_since()

long Fl::ticks_since | ( | Fl_Timestamp & | then | ) |
| static

Return the time in ticks (60Hz) between now and a previously taken time stamp.

Ticks are a convenient way to time animations 'per frame'. Even though modern computers use all kinds of screen refresh rates, 60Hz is a very good base for animation that is typically shown in user interface graphics.

Parameters

  [in] | then | a previously taken time stamp

Returns
  elapsed ticks in 60th of a second

See also
  Fl::ticks_between(Fl_Timestamp& back, Fl_Timestamp& further_back)
  Fl::now()

## ◆ use_high_res_GL() [1/2]

int Fl::use_high_res_GL | ( |  | ) |
| inlinestatic

returns whether GL windows should be drawn at high resolution on Apple computers with retina displays.

Default is no.

Version
  1.3.4

## ◆ use_high_res_GL() [2/2]

void Fl::use_high_res_GL | ( | int | val | ) |
| inlinestatic

sets whether GL windows should be drawn at high resolution on Apple computers with retina displays

Version
  1.3.4

## ◆ version()

double Fl::version | ( |  | ) |
| static

Returns the compiled-in value of the FL_VERSION constant.

This is useful for checking the version of a shared library.

Deprecated
  Use int Fl::api_version() instead.

## ◆ visible_focus() [1/2]

int Fl::visible_focus | ( |  | ) |
| inlinestatic

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.

## ◆ visible_focus() [2/2]

void Fl::visible_focus | ( | int | v | ) |
| inlinestatic

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.

## ◆ visual()

int Fl::visual | ( | int | flags | ) |
| static

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:

- Fl::visual(FL_RGB)
  Full/true color (if there are several depths FLTK chooses the largest). Do this if you use fl_draw_image for much better (non-dithered) output.
- Fl::visual(FL_RGB8)
  Full color with at least 24 bits of color. FL_RGB will always pick this if available, but if not it will happily return a less-than-24 bit deep visual. This call fails if 24 bits are not available.

This returns true if the system has the capabilities by default or FLTK succeeded in turning them on. Your program will still work even if this returns false (it just won't look as good).

## ◆ wait() [1/2]

int Fl::wait | ( |  | ) |
| static

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.

Returns
  non-zero if there are any visible windows - this may change in future versions of FLTK.

## ◆ wait() [2/2]

double Fl::wait | ( | double | time_to_wait | ) |
| static

Waits a maximum of `time_to_wait` seconds or until "something happens".

See Fl::wait() for the description of operations performed when "something happens".

Returns
  Always 1 on Windows. Otherwise, it is positive if an event or fd happens before the time elapsed. It is zero if nothing happens. It is negative if an error occurs (this will happen on X11 if a signal happens).

## Member Data Documentation

## ◆ help

const char *const Fl::help = helpmsg+13
| static

Usage string displayed if Fl::args() detects an invalid argument.

This may be changed to point to customized text at run-time.

## ◆ idle

void(* Fl::idle)()
| static

The currently executing idle callback function: DO NOT USE THIS DIRECTLY!

This is now used as part of a higher level system allowing multiple idle callback functions to be called.

See also
  add_idle(), remove_idle()

The documentation for this class was generated from the following files:

- Fl.H
- Fl.cxx
- Fl_abort.cxx
- Fl_add_idle.cxx
- Fl_arg.cxx
- fl_boxtype.cxx
- Fl_Cairo.cxx
- fl_color.cxx
- Fl_compose.cxx
- Fl_display.cxx
- Fl_get_system_colors.cxx
- Fl_grab.cxx
- fl_labeltype.cxx
- Fl_lock.cxx
- Fl_own_colormap.cxx
- fl_set_font.cxx
- fl_shortcut.cxx
- Fl_Timeout.cxx
- Fl_visual.cxx
- Fl_Widget.cxx
- Fl_Window.cxx
- screen_xywh.cxx