Class Fl

(back to index)

Utilities and app-wide functions

Property index


Function index


Key properties

integer Fl.event_clicksMouse click count
boolean Fl.event_is_clickMouse click timer
readonly integer Fl.event_xMouse window x of event
readonly integer Fl.event_yMouse window y of event
readonly string Fl.event_textLast text typed
readonly Key Fl.event_keyLast key pressed
readonly integer Fl.event_stateLast modifiers pressed

Key functions

boolean Fl:run()Run until all windows close
boolean Fl:wait(number time=1e6)Wait for events
void Fl:enable_symbols()Allow symbol specs in labels


Fl isn't a widget class; it's a namespace for functions and properties. It's never instantiated. All properties and functions are invoked directly on it.

Detailed reference

Fl:display(string displayname): void

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.

Fl:visual(integer visualnumber): boolean

Selects a visual so that your graphics are drawn correctly. 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() 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).

Fl:own_colormap(): void

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.

Fl:get_system_colors(): void

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; most Lua FLTK apps won't use that function.)

Currently this only does something on WIN32. In future versions for X it may read the window manager (KDE, Gnome, etc.) setup as well.

Fl:foreground(integer r, integer g, integer b): void

Changes Also changes Color.inactive and Color.selection to be a ramp between this and Color.white.

Fl:background(integer r, integer g, integer b): void

Changes Color.gray to the given color, and changes the gray ramp from 32 to 56 to black to white. These are the colors used as backgrounds by almost all widgets and used to draw the edges of all the boxtypes.

Fl:background2(integer r, integer g, integer b): void

Changes Color.white and the same colors as Fl:foreground(). This color is used as a background by Input and other text widgets.

Fl:wait(number time=1e6): boolean

Normally called with no argument.

Calls the idle function if any, then calls any pending timeout functions, then calls Fl:flush(). If there are any windows displayed it then waits some time for events (zero if there is an idle(), the shortest timeout if there are any timeouts, or forever) and calls the handle() function on those events, and then returns true.

Your program can check its global state and update things after each call to Fl:wait(), which can be very useful in complex programs.

If there are no windows (this is checked after the idle and timeouts are called) then Fl:wait() returns nil without waiting for any events. Your program can either exit at this point, or call show() on some window so the GUI can continue to operate. If you give an argument, Fl::wait() waits only a certain amount of time for anything to happen. This does the same as wait() except if the given time (in seconds) passes it returns. The return value is how much time remains. If the return value is zero or negative then the entire time period elapsed.

If you do several wait(time) calls in a row, the subsequent ones are measured from when the first one is called, even if you do time-consuming calculations after they return. This allows you to accurately make something happen at regular intervals. The following C++ code will accurately call A() once per second (as long as it takes less than a second to execute):

Fl:check(): boolean

This does the same thing as Fl:wait(0), except because it does not have to return the elapsed time value it can be implemented faster on certain systems. Use this to interrupt a big calculation:

This returns true if any windows are displayed, and nil if no windows are displayed.

Fl:ready(): boolean

Returns non-zero if there are pending timeouts or events or file descriptors. This does not call Fl:flush() or any callbacks, which is useful if your program is in a state where such callbacks are illegal:

Fl:run(): boolean

Runs FLTK until there are no windows displayed, and then returns nil. Fl:run() is exactly equivalent to this C++ code:

Fl.damage: readonly boolean

If true then flush() will do something.

Fl:redraw(): void

Redraws all widgets.

Fl:flush(): void

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. You need to call this if you want the on-screen appearance of a widget to change before you process events again.

Fl.first_window: readonly Window

Returns the first top-level window in the list of shown windows. If a modal window is shown this is the top-most modal window, otherwise it is the most recent window to get an event.

Fl:next_window(Window prev): Window

Given a top-level Window, return the next top-level window in the widget hierarchy. You can use this call to iterate through all the windows that are shown().

Fl.modal: readonly Window

Returns the top-most modal window currently shown. This is the most recently shown() window with modal true, or nil if there are no modal windows shown(). The modal window has its handle() method called for all events, and no other windows will have handle() called (grab() overrides this).

Fl.grab: readonly Window

The current grab window, or nil if none. See set_grab() for more information.

Fl:set_grab(Window grab): void

(You probably don't want to use this in Lua FLTK.)

This is used when pop-up menu systems are active. Send all events to the passed window no matter where the pointer or focus is (including in other programs). The window does not have to be shown(); this lets the handle() method of a "dummy" window override all event handling and allows you to map and unmap a complex set of windows (under both X and WIN32 some window must be mapped because the system interface needs a window id).

If grab is on it will also affect show() of windows by doing system-specific operations (on X it turns on override-redirect). These are designed to make menus popup reliably and faster on the system.

To turn off grabbing do Fl:grab(nil).

Be careful that your program does not enter an infinite loop while grab() is on. On X this will lock up your screen!

Fl.event_x: readonly integer

Mouse position of the last event relative to the Window that processed the event.

Fl.event_y: readonly integer

Mouse position of the last event relative to the Window that processed the event.

Fl.event_x_root: readonly integer

Returns the mouse position on the screen of the event. To find the absolute position of an Window on the screen, use the difference between event_x_root,event_y_root and event_x,event_y.

Fl.event_y_root: readonly integer

Returns the mouse position on the screen of the event. To find the absolute position of an Window on the screen, use the difference between event_x_root,event_y_root and event_x,event_y.

Fl:get_mouse(): integer x, integer y

Return where the mouse is on the screen by doing a round-trip query to the server. You should use Fl.event_x_root and Fl.event_y_root if possible, but this is necessary if you are not sure if a mouse event has been processed recently (such as to position your first window). If the display is not open, this will open it.

Fl.event_clicks: integer

Non-zero if the most recent Event.push or Event.keyboard was a "double click". Returns N-1 for N clicks. A double click is counted if the same button is pressed again while event_is_click is true.

You can modify this property; this can be used to set it to zero so that later code does not think an item was double-clicked.

Fl.event_is_click: boolean

event_is_click is true if the mouse has not moved far enough and not enough time has passed since the last Even.push or Event.keyboard event for it to be considered a "drag" rather than a "click". You can test this on Event.drag, Event.release, and Event.move events. You can set this property to nil. This is useful to prevent the next click from being counted as a double-click or to make a popup menu pick an item with a single click. Don't set it to a true value.

Fl.event_button: readonly integer

Returns which mouse button was pressed. This returns garbage if the most recent event was not a Event.push or Event.release event.

Fl.event_state: readonly integer

This is a bitfield of what shift states were on and what mouse buttons were held down during the most recent event. Names of modifiers are given in Modifier:

X servers do not agree on shift states, and Modifier.num_lock, Modifier.meta, and Modifer.scroll_lock may not work. The values were selected to match the XFree86 server on Linux. In addition there is a bug in the way X works so that the shift state is not correctly reported until the first event after the shift key is pressed or released.

Fl:event_state_matches(Modifier m): boolean

True if the current event_state contains any of the modifiers given in m.

Fl.event_key: readonly Key

Contains the last key on the keyboard pressed.

Keys are identified by the unshifted values. FLTK defines a set of symbols that should work on most modern machines for every key on the keyboard:

Fl:event_key_matches(Key k): boolean

True if the given key was held down (or pressed) during the last event. This is constant until the next event is read from the server.

Fl:get_key(Key k): boolean

Returns true if the given key is held down now. Under X this requires a round-trip to the server and is much slower than Fl:event_key_matches(int).

Fl.event_text: readonly string

Returns the ASCII text (in the future this may be UTF-8) produced by the last Event.keyboard or Event.pastem or possibly other event. A zero-length string is returned for any keyboard function keys that do not produce text.

Under X this is the result of calling XLookupString().

Fl.event_length: readonly integer

Returns the intended length of the text in Fl.event_text. There will always be a nul at this position in the text. However there may be a nul before that if the keystroke translates to a nul character or you paste a nul character.

Fl:event_inside(integer x, integer y, integer w, integer h): boolean

You may call this function with a Widget instead of coordinates.

Returns true if the current event_x and event_y put it inside the widget or inside an arbitrary bounding box. You should always call this rather than doing your own comparison so you are consistent about edge effects.

Fl:test_shortcut(Modified_Key k): boolean

Returns true if the current event matches k. See Button.shortcut for more information on shortcuts.

Fl:handle(Event e, Window w): boolean

Sends the event to a window for processing. Returns true if any widget uses the event.

Fl.belowmouse: Widget

Get or set the widget that is below the mouse. This is for highlighting buttons. It is not used to send Event.push or Event.move directly, for several obscure reasons, but those events typically go to this widget. This is also the first widget tried for Event.shortcut events.

If you change the belowmouse widget, the previous one and all parents (that don't contain the new widget) are sent Event.leave events. Changing this does not send Event.enter to this or any widget, because sending Event.enter is supposed to test if the widget wants the mouse (by it returning true from handle()).

Fl.pushed: Widget

Get or set the widget that is being pushed. Event.drag or Event.release (and any more Event.push) events will be sent to this widget.

If you change the pushed widget, the previous one and all parents (that don't contain the new widget) are sent Event.release events. Changing this does not send Event.push to this or any widget, because sending Event.push is supposed to test if the widget wants the mouse (by it returning true from handle()).

Fl.focus: Widget

Get or set the widget that will receive Event.keyboard events.

If you change Fl.focus, the previous widget and all parents (that don't contain the new widget) are sent Event.unfocus events. Changing the focus does not send Event.focus to this or any widget, because sending Event.focus is supposed to test if the widget wants the focus (by it returning true from handle()).

Fl.selection_owner: Widget

This can move the selection to another widget or to set the owner to nil , without changing the actual text of the selection. Event.selectionclear is sent to the previous selection owner, if any.

Fl.x: readonly integer

The x coordinate of the upper left of the screen. 0 on X.

Fl.y: readonly integer

The y coordinate of the upper left of the screen. 0 on X.

Fl.w: readonly integer

The width of the screen.

Fl.h: readonly integer

The height of the screen.

Fl:enable_symbols(): void

Enables the symbol drawing codes for labels. See Labeltype for more information.

doctool generated at Sun Aug 12 22:23:18 2001