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_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. More...

static int	abi_version ()
	Returns the compiled-in value of the FL_ABI_VERSION constant. More...

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

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

static void	add_fd (int fd, Fl_FD_Handler cb, void *=0)
	See void add_fd(int fd, int when, Fl_FD_Handler cb, void* = 0)

static void	add_fd (int fd, int when, Fl_FD_Handler cb, void *=0)
	Adds file descriptor fd to listen to. More...

static void	add_handler (Fl_Event_Handler h)
	Install a function to parse unrecognized events. More...

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 fucntion is called repeatedly). More...

static void	add_system_handler (Fl_System_Handler h, void *data)
	Install a function to intercept system events. More...

static void	add_timeout (double t, Fl_Timeout_Handler, void *=0)
	Adds a one-shot timeout callback. More...

static int	api_version ()
	Returns the compiled-in value of the FL_API_VERSION constant. More...

static int	arg (int argc, char **argv, int &i)
	Parse a single switch from `argv`, starting at word `i`. More...

static void	args (int argc, char **argv)
	Parse all command line switches matching standard FLTK options only. More...

static int	args (int argc, char **argv, int &i, Fl_Args_Handler cb=0)
	Parse command line switches using the `cb` argument handler. More...

static int	awake (Fl_Awake_Handler cb, void *message=0)
	See void awake(void* message=0). More...

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

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

static void	background2 (uchar, uchar, uchar)
	Changes the alternative background color. More...

static Fl_Widget *	belowmouse ()
	Gets the widget that is below the mouse. More...

static void	belowmouse (Fl_Widget *)
	Sets the widget that is below the mouse. More...

static Fl_Color	box_color (Fl_Color)
	Gets the drawing color to be used for the background of a box. More...

static int	box_dh (Fl_Boxtype)
	Returns the height offset for the given boxtype. More...

static int	box_dw (Fl_Boxtype)
	Returns the width offset for the given boxtype. More...

static int	box_dx (Fl_Boxtype)
	Returns the X offset for the given boxtype. More...

static int	box_dy (Fl_Boxtype)
	Returns the Y offset for the given boxtype. More...

static bool	cairo_autolink_context ()
	Gets the current autolink mode for cairo support. More...

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

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

static cairo_t *	cairo_make_current (Fl_Window *w)
	Provides a corresponding cairo context for window wi. More...

static int	check ()
	Same as Fl::wait(0). More...

static void	clear_widget_pointer (Fl_Widget const *w)
	Clears a widget pointer in the watch list. More...

static int	clipboard_contains (const char *type)
	Returns non 0 if the clipboard contains data matching `type`. More...

static int	compose (int &del)
	Any text editing widget should call this for each FL_KEYBOARD event. More...

static void	compose_reset ()
	If the user moves the cursor, be sure to call Fl::compose_reset(). More...

static void	copy (const char stuff, int len, int destination=0, const char type=Fl::clipboard_plain_text)
	Copies the data pointed to by `stuff` to the selection buffer (`destination` is 0), the clipboard (`destination` is 1), or both (`destination` is 2). More...

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

static void	delete_widget (Fl_Widget *w)
	Schedules a widget for deletion at the next call to the event loop. More...

static void	disable_im ()
	Disables the system input methods facilities. More...

static void	display (const char *)
	Sets the X display to use for all windows. More...

static int	dnd ()
	Initiate a Drag And Drop operation. More...

static int	dnd_text_ops ()
	Gets or sets whether drag and drop text operations are supported. More...

static void	dnd_text_ops (int v)
	Gets or sets whether drag and drop text operations are supported. More...

static void	do_widget_deletion ()
	Deletes widgets previously scheduled for deletion. More...

static int	draw_box_active ()
	Determines if the currently drawn box is active or inactive. More...

static void	enable_im ()
	Enables the system input methods facilities. More...

static int	event ()
	Returns the last event that was processed. More...

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

static int	event_button1 ()
	Returns non-zero if mouse button 1 is currently held down. More...

static int	event_button2 ()
	Returns non-zero if button 2 is currently held down. More...

static int	event_button3 ()
	Returns non-zero if button 3 is currently held down. More...

static int	event_buttons ()
	Returns the mouse buttons state bits; if non-zero, then at least one button is pressed now. More...

static int	event_clicks ()
	Returns non zero if we had a double click event. More...

static void	event_clicks (int i)
	Manually sets the number returned by Fl::event_clicks(). More...

static void *	event_clipboard ()
	During an FL_PASTE event of non-textual data, returns a pointer to the pasted data. More...

static const char *	event_clipboard_type ()
	Returns the type of the pasted data during an FL_PASTE event. More...

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

static int	event_dx ()
	Returns the current horizontal mouse scrolling associated with the FL_MOUSEWHEEL event. More...

static int	event_dy ()
	Returns the current vertical mouse scrolling associated with the FL_MOUSEWHEEL event. More...

static int	event_inside (const Fl_Widget *)
	Returns whether or not the mouse event is inside a given child widget. More...

static int	event_inside (int, int, int, int)
	Returns whether or not the mouse event is inside the given rectangle. More...

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

static void	event_is_click (int i)
	Clears the value returned by Fl::event_is_click(). More...

static int	event_key ()
	Gets which key on the keyboard was last pushed. More...

static int	event_key (int key)
	Returns true if the given `key` was held down (or pressed) during the last event. More...

static int	event_length ()
	Returns the length of the text in Fl::event_text(). More...

static int	event_original_key ()
	Returns the keycode of the last key event, regardless of the NumLock state. More...

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

static int	event_state (int mask)
	Returns non-zero if any of the passed event state bits are turned on. More...

static const char *	event_text ()
	Returns the text associated with the current event, including FL_PASTE or FL_DND_RELEASE events. More...

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

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

static Fl_Window *	first_window ()
	Returns the first top-level window in the list of shown() windows. More...

static void	first_window (Fl_Window *)
	Sets the window that is returned by first_window(). More...

static void	flush ()
	Causes all the windows that need it to be redrawn and graphics forced out through the pipes. More...

static Fl_Widget *	focus ()
	Gets the current Fl::focus() widget. More...

static void	focus (Fl_Widget *)
	Sets the widget that will receive FL_KEYBOARD events. More...

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

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

static void	get_color (Fl_Color i, uchar &red, uchar &green, uchar &blue)
	Returns the RGB value(s) for the given FLTK color index. More...

static const char *	get_font (Fl_Font)
	Gets the string for this face. More...

static const char *	get_font_name (Fl_Font, int *attributes=0)
	Get a human-readable string describing the family of this face. More...

static int	get_font_sizes (Fl_Font, int *&sizep)
	Return an array of sizes in `sizep`. More...

static int	get_key (int key)
	Returns true if the given `key` is held down now. More...

static void	get_mouse (int &, int &)
	Return where the mouse is on the screen by doing a round-trip query to the server. More...

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

static int	gl_visual (int, int *alist=0)
	This does the same thing as Fl::visual(int) but also requires OpenGL drawing to work. More...

static Fl_Window *	grab ()
	Returns the window that currently receives all events. More...

static void	grab (Fl_Window &win)
	See grab(Fl_Window*)

static void	grab (Fl_Window *)
	Selects the window to grab. More...

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

static int	handle_ (int, Fl_Window *)
	Handle events from the window system. More...

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, void *=0)
	Returns true if the timeout exists and has not been called yet.

static int	is_scheme (const char *name)
	Returns whether the current scheme is the given name. More...

static int	lock ()
	The lock() method blocks the current thread until it can safely access FLTK widgets and data. More...

static Fl_Window *	modal ()
	Returns the top-most modal() window currently shown. More...

static Fl_Window *	next_window (const Fl_Window *)
	Returns the next top-level window in the list of shown() windows. More...

static bool	option (Fl_Option opt)
	FLTK library options management. More...

static void	option (Fl_Option opt, bool val)
	Override an option while the application is running. More...

static void	own_colormap ()
	Makes FLTK use its own colormap. More...

static void	paste (Fl_Widget &receiver)
	Backward compatibility only. More...

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

static Fl_Widget *	pushed ()
	Gets the widget that is being pushed. More...

static void	pushed (Fl_Widget *)
	Sets the widget that is being pushed. More...

static Fl_Widget *	readqueue ()
	Reads the default callback queue and returns the first widget. More...

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

static void	redraw ()
	Redraws all widgets.

static void	release ()
	Releases the current grabbed window, equals grab(0). More...

static void	release_widget_pointer (Fl_Widget *&w)
	Releases a widget pointer from the watch list. More...

static int	reload_scheme ()
	Called by scheme according to scheme name. More...

static void	remove_check (Fl_Timeout_Handler, void *=0)
	Removes a check callback. More...

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

static void	remove_idle (Fl_Idle_Handler cb, void *data=0)
	Removes the specified idle callback, if it is installed.

static void	remove_system_handler (Fl_System_Handler h)
	Removes a previously added system event handler. More...

static void	remove_timeout (Fl_Timeout_Handler, void *=0)
	Removes a timeout callback. More...

static void	repeat_timeout (double t, Fl_Timeout_Handler, void *=0)
	Repeats a timeout callback from the expiration of the previous timeout, allowing for more accurate timing. More...

static int	run ()
	As long as any windows are displayed this calls Fl::wait() repeatedly. More...

static const char *	scheme ()
	See void scheme(const char *name)

static int	scheme (const char *name)
	Sets the current widget scheme. More...

static int	screen_count ()
	Gets the number 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. More...

static int	screen_num (int x, int y)
	Gets the screen number of a screen that contains the specified screen position `x`, `y`. More...

static int	screen_num (int x, int y, int w, int h)
	Gets the screen number for the screen which intersects the most with the rectangle defined by `x`, `y`, `w`, `h`. More...

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

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

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

static void	screen_xywh (int &X, int &Y, int &W, int &H)
	Gets the bounding box of a screen that contains the mouse pointer. More...

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

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

static void	screen_xywh (int &X, int &Y, int &W, int &H, int n)
	Gets the screen bounding rect for the given screen. More...

static int	scrollbar_size ()
	Gets the default scrollbar size used by Fl_Browser_, Fl_Help_View, Fl_Scroll, and Fl_Text_Display widgets. More...

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

static void	selection (Fl_Widget &owner, const char *, int len)
	Changes the current selection. More...

static Fl_Widget *	selection_owner ()
	back-compatibility only: Gets the widget owning the current selection More...

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

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

static void	set_box_color (Fl_Color)
	Sets the drawing color for the box that is currently drawn. More...

static void	set_boxtype (Fl_Boxtype, Fl_Box_Draw_F *, uchar, uchar, uchar, uchar)
	Sets the function to call to draw a specific boxtype.

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

static void	set_color (Fl_Color, uchar, uchar, uchar)
	Sets an entry in the fl_color index table. More...

static void	set_font (Fl_Font, const char *)
	Changes a face. More...

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

static void	set_idle (Fl_Old_Idle_Handler cb)
	Sets an idle callback. More...

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

static void *	thread_message ()
	The thread_message() method returns the last message that was sent from a child by the awake() method. More...

static void	unlock ()
	The unlock() method releases the lock that was set using the lock() method. More...

static int	use_high_res_GL ()
	returns whether GL windows should be drawn at high resolution on Apple computers with retina displays. More...

static void	use_high_res_GL (int val)
	sets whether GL windows should be drawn at high resolution on Apple computers with retina displays More...

static double	version ()
	Returns the compiled-in value of the FL_VERSION constant. More...

static int	visible_focus ()
	Gets or sets the visible keyboard focus on buttons and other non-text widgets. More...

static void	visible_focus (int v)
	Gets or sets the visible keyboard focus on buttons and other non-text widgets. More...

static int	visual (int)
	Selects a visual so that your graphics are drawn correctly. More...

static int	w ()
	Returns the width in pixels of the main screen work area.

static int	wait ()
	Waits until "something happens" and then returns. More...

static double	wait (double time)
	See int Fl::wait()

static void	watch_widget_pointer (Fl_Widget *&w)
	Adds a widget pointer to the widget watch list. More...

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

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 *,...) = ::error
	FLTK calls Fl::error() to output a normal error message. More...

static void(*	fatal )(const char *,...) = ::fatal
	FLTK calls Fl::fatal() to output a fatal error message. More...

static const char *const	help = helpmsg+13
	Usage string displayed if Fl::args() detects an invalid argument. More...

static void(*	idle )()
	The currently executing idle callback function: DO NOT USE THIS DIRECTLY! More...

static void(*	warning )(const char *,...) = ::warning
	FLTK calls Fl::warning() to output a warning message. More...

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_LAST	For internal use only.

Member Function Documentation

◆ abi_check()

static 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-&gt;redraw();
}
 
main() {
 Fl::add_check(callback);
 return Fl::run();
}

◆ add_fd()

static void Fl::add_fd	(	int	fd,
		int	when,
		Fl_FD_Handler	cb,
		void *	= `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.

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.

◆ 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 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_timeout()

void Fl::add_timeout	(	double	t,
		Fl_Timeout_Handler	cb,
		void *	argp = `0`
	)

static

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

You can have multiple timeout callbacks. To remove a timeout callback use Fl::remove_timeout().

If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to reschedule the subsequent timeouts.

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

#include <stdio.h>
#include <FL/Fl.H>
#include <FL/Fl_Window.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();
}

◆ 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 WIN32 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().

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.

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

◆ 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_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 inactive_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());

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

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

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

◆ dnd_text_ops() [1/2]

static int Fl::dnd_text_ops ( )

inlinestatic

Gets or 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.

◆ dnd_text_ops() [2/2]

static void Fl::dnd_text_ops ( int v )

inlinestatic

Gets or 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)

◆ 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	mode,
		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.

◆ is_scheme()

static 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:368

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)

◆ option() [1/2]

bool Fl::option ( Fl_Option opt )

static

FLTK library options management.

This function needs to be documented in more detail. It can be used for more optional settings, such as using a native file chooser instead of the FLTK one wherever possible, disabling tooltips, disabling visible focus, disabling FLTK file chooser preview, etc. .

There should be a command line option interface.

There should be an application that manages options system wide, per user, and per application.

Example:

if ( Fl::option(Fl::OPTION_ARROW_FOCUS) )
    { ..on..  }
else
    { ..off..  }

Note: As of FLTK 1.3.0, options can be managed within fluid, using the menu Edit/Global FLTK Settings.

Parameters

opt	which option

Returns: true or false

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

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.

This function does not change any system or user 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.

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

◆ release()

static 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 by scheme according to scheme name.

Loads or reloads the current scheme selection. See void 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_timeout()

void Fl::remove_timeout	(	Fl_Timeout_Handler	cb,
		void *	argp = `0`
	)

static

Removes a timeout callback.

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

Note: This version removes all matching timeouts, not just the first one. This may change in the future.

◆ repeat_timeout()

void Fl::repeat_timeout	(	double	t,
		Fl_Timeout_Handler	cb,
		void *	argp = `0`
	)

static

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

You may only call this method inside a timeout callback.

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

void callback(void*) {
  puts("TICK");
  Fl::repeat_timeout(1.0, callback);
}
 
int main() {
  Fl::add_timeout(1.0, callback);
  return Fl::run();
}

◆ run()

int Fl::run ( )

static

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

◆ 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 Mac OS X

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

Uppercase scheme names are equivalent, but the stored scheme name will always be lowercase and Fl::scheme() will return this lowercase name.

If the resulting scheme name is not defined, the default scheme will be used and Fl::scheme() will return NULL.

See also: Fl::is_scheme()

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

◆ 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 inactive_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_idle()

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

◆ use_high_res_GL() [1/2]

static 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]

static 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]

static 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]

static 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.
Fl::visual(FL_DOUBLE|FL_INDEX)
Hardware double buffering. Call this if you are going to use Fl_Double_Window.
Fl::visual(FL_DOUBLE|FL_RGB)
Fl::visual(FL_DOUBLE|FL_RGB8)
Hardware double buffering and full color.

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

◆ wait()

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.

The return value of Fl::wait() is non-zero if there are any visible windows - this may change in future versions of FLTK.

Fl::wait(time) 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).

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_color.cxx
fl_color_mac.cxx
fl_color_win32.cxx
Fl_compose.cxx
Fl_display.cxx
fl_dnd_win32.cxx
fl_dnd_x.cxx
Fl_get_key.cxx
Fl_get_key_mac.cxx
Fl_get_key_win32.cxx
Fl_get_system_colors.cxx
Fl_grab.cxx
fl_labeltype.cxx
Fl_lock.cxx
Fl_own_colormap.cxx
fl_set_font.cxx
fl_set_fonts_mac.cxx
fl_set_fonts_win32.cxx
fl_set_fonts_x.cxx
fl_set_fonts_xft.cxx
fl_shortcut.cxx
Fl_visual.cxx
Fl_Widget.cxx
Fl_Window.cxx
gl_start.cxx
screen_xywh.cxx
Fl_Cairo.cxx

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Fl_Option

Member Function Documentation

◆ abi_check()

◆ abi_version()

◆ add_check()

◆ add_fd()

◆ add_idle()

◆ add_timeout()

◆ api_version()

◆ arg()

◆ args() [1/2]

◆ args() [2/2]

◆ background()

◆ background2()

◆ box_color()

◆ box_dh()

◆ box_dw()

◆ box_dx()

◆ box_dy()

◆ check()

◆ display()

◆ dnd_text_ops() [1/2]

◆ dnd_text_ops() [2/2]

◆ draw_box_active()

◆ flush()

◆ get_system_colors()

◆ gl_visual()

◆ is_scheme()

◆ option() [1/2]

◆ option() [2/2]

◆ own_colormap()

◆ readqueue()

◆ ready()

◆ release()

◆ reload_scheme()

◆ remove_check()

◆ remove_timeout()

◆ repeat_timeout()

◆ run()

◆ scheme()

◆ scrollbar_size() [1/2]

◆ scrollbar_size() [2/2]

◆ set_box_color()

◆ set_idle()

◆ use_high_res_GL() [1/2]

◆ use_high_res_GL() [2/2]

◆ version()

◆ visible_focus() [1/2]

◆ visible_focus() [2/2]

◆ visual()

◆ wait()

Member Data Documentation

◆ help

◆ idle