Fltk only thinks about one event at a time. Therefore all of the other data about the event is stored in static memory, rather than a typical "event structure". It is accessed with fast inline functions of the form fltk::event_*.
FLTK has very simple rules for sending events to widgets. The major unusual aspect of FLTK is that widgets indicate if they "handled" an event by returning non-zero from their fltk::Widget::handle() method. If they return zero, FLTK can then try the event elsewhere. This eliminates the need for "interests" (event masks or tables), and this is the main reason FLTK is much smaller than other toolkits.
Most events are sent to the outermost fltk::Window containing the event, and those widgets are responsible for finding and sending the events to child widgets. Some events are sent directly to fltk::Widgets, this is controlled by the following methods, which the container widgets are required to call:
If all the widgets that FLTK tries to send an event to return zero, then you can add global functions that FLTK will call with these events. This is done with fltk::add_event_handler()
You can generate fake events by calling handle(int) on the correct widgets (usally a window). Currently you can change the values returned by the fltk::event_*() functions by storing the desired value into the static variables fltk::e_*, but this may change in future versions.
|
|
Numbers passed to Widget::handle() and returned by event().
|
|
|
Values returned by event_key(), passed to event_key_state() and get_key_state(), and used for the low 16 bits of add_shortcut(). The actual values returned are based on X11 keysym values, though fltk always returns "unshifted" values much like Windows does. A given key always returns the same value no matter what shift keys are held down. Use event_text() to see the results of any shift keys. The lowercase letters 'a' through 'z' and the ascii symbols '`', '-', '=', '[', ']', '\', ',', '.', '/', ';', '\'' and space are used to identify the keys in the main keyboard. On X systems unrecognized keys are returned unchanged as their X keysym value. If they have no keysym it uses the scan code or'd with 0x8000, this is what all those blue buttons on a Microsoft keyboard will do. I don't know how to get those buttons on Windows.
|
|
|
Flags returned by event_state(), and used as the high 16 bits of Widget::add_shortcut() values (the low 16 bits are all zero, so these may be or'd with key values). The inline function BUTTON(n) will turn n (1-8) into the flag for a mouse button.
|
|
|
|
Returns the most recent event handled, such as fltk::PUSH or fltk::KEY. This is useful so callbacks can find out why they were called. |
|
|
Returns the distance the mouse is to the right of the left edge of the widget. Widget::send() modifies this as needed before calling the Widget::handle() method. |
|
|
Returns the distance the mouse is below the top edge of the widget. Widget::send() modifies this as needed before calling the Widget::handle() method. |
|
|
For fltk::MOUSEWHEEL events this is how many clicks the user moved in the x and y directions (currently dx is always zero). |
|
|
Reserved for future use if horizontal mouse wheels (or some kind of joystick on the mouse) becomes popular. |
|
|
Return the absolute horizontal position of the mouse. Usually this is relative to the left edge of the screen, but multiple Monitor setup may change that. To find the absolute position of the current widget, subtract event_x_root()-event_x(). |
|
|
Return the absolute vertical position of the mouse. Zero is at the top. |
|
|
Returns the number of times the last mouse button was pushed while fltk::event_is_click() was true. For a normal fltk::PUSH this is zero, if the user "double-clicks" this is 1, and it is N-1 for each subsequent click. This is also used to indicate if fltk::KEY events are caused by the key repeating. Zero means the user pushed the key down, non-zero means it is being held down and is repeating. |
|
|
Setting this value can be used to make callbacks think things were (or were not) double-clicked, and thus act differently. |
|
|
This is true if the time and mouse movement since the last fltk::PUSH or fltk::KEY is short enough that the user is intending to "click". After enough time or after enough mouse movement this turns off. The main use of this is to decide whether to increment fltk::event_clicks() when the user clicks the mouse. But you can also test this on a fltk::RELEASE or fltk::KEYUP event to decide if the user clicked quickly, versus holding the mouse or key down. |
|
|
You can set this to zero with fltk::event_is_click(0), this can be used to prevent the next mouse click from being considered a double click. Only false works, attempts to set this true are ignored. |
|
|
This is a bitfield of what shift states were on and what mouse buttons were held down during the most recent event. The flags to pass are described under fltk::SHIFT. Because Emacs screws up if any key returns the predefined META flag, lots of X servers have really botched up the key assignments trying to make Emacs work. Fltk tries to work around this but you may find that Alt or Meta don't work, since I have seen at least 3 mutually incompatable arrangements. Non-XFree86 machines may also have selected different values so that NUMLOCK, META, and SCROLLLOCK are mixed up. In addition X reports the state before the last key was pressed so the state looks backwards for any shift keys, currently fltk only fixes this bug for the mouse buttons. |
|
|
Same as event_state()&mask, returns true if any of the passed bits were turned on during the last event. So doing event_state(SHIFT) will return true if the shift keys are held down. This is provided to make the calling code easier to read. The flags to pass are described under fltk::SHIFT. |
|
|
Returns which key on the keyboard was last pushed. Most non-keyboard events set this to values that do not correspond to any keys, so you can test this in callbacks without having to test first if the event really was a keystroke. The values returned are described under fltk::SpaceKey. |
|
|
Returns which mouse button was pressed or released by a PUSH or RELEASE event. Returns garbage for other events, so be careful (this actually is the same as event_key(), the buttons have been assigned the key values 1,2,3, etc. |
|
|
Returns true if the given key was held down (or pressed) during the last event. This is constant until the next event is read from the server. The possible values for the key are listed under fltk::SpaceKey. On Win32 event_key_state(KeypadEnter) does not work. |
|
|
Returns the ASCII text (in the future this may be UTF-8) produced by the last fltk::KEY or fltk::PASTE or possibly other event. A zero-length string is returned for any keyboard function keys that do not produce text. This pointer points at a static buffer and is only valid until the next event is processed. Under X this is the result of calling XLookupString(). |
|
|
Returns the length of the text in fltk::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. |
|
|
Returns true if the current fltk::event_x() and fltk::event_y() put it inside the Rectangle. You should always call this rather than doing your own comparison so you are consistent about edge effects. |
|
|
Use of this function is very simple. Any text editing widget should call this for each fltk::KEY event. If true is returned, then it has modified the fltk::event_text() and fltk::event_length() to a set of bytes to insert (it may be of zero length!). It will also set the del parameter to the number of bytes to the left of the cursor to delete, this is used to delete the results of the previous call to fltk::compose(). Compose may consume the key, which is indicated by returning true, but both the length and del are set to zero. Compose returns false if it thinks the key is a function key that the widget should handle itself, and not an attempt by the user to insert text. Though the current implementation returns immediately, future versions may take quite awhile, as they may pop up a window or do other user-interface things to allow international characters to be selected. |
|
|
If the user moves the cursor, be sure to call fltk::compose_reset(). The next call to fltk::compose() will start out in an initial state. In particular it will not set "del" to non-zero. This call is very fast so it is ok to call it many times and in many places. |
|
||||||||||||
|
Returns an array of shortcut assignments that match the given value for key. The number of matching ones is put in count. If there are no matches count is set to zero. Do not assumme any particular order for the returned array. Also there may be entries with widget==0, ignore them. The returned array is temporary storage and can be overwritten by the next call to alter or query shortcuts! |
|
||||||||||||
|
Returns an array of shortcut assignments for this widget. The number of matching ones is put in count. Do not assumme any particular order for the returned array. Also there may be entries with key==0, ignore them. The returned array is temporary storage and can be overwritten by the next call to alter or query shortcuts! |
|
|
Returns an array of every shortcut assignment. They are sorted by the key, and then by shift flags. The returned array is temporary storage and will be overwritten by the next call to alter or query shortcuts! Also there may be entries with widget==0, ignore them. |
|
|
Returns an array of shortcut assignments that match the current event, which should be a KEY, SHORTCUT, or KEYUP event. The number of matching ones is put in count. If there are no matches null is returned and count is set to zero. The returned array is temporary storage and can be overwritten by the next call to alter or query shortcuts! Also there may be entries with widget==0, ignore them. This is very similar to list_shortcuts(event_key()|event_state()) except if no exact match is found, it will try to locate a "close" matching key assignment and return that:
|
|
|
Try sending the current KEY event as a SHORTCUT event. Normally the focus() gets all keystrokes, and shortcuts are only tested if that widget indicates it is uninterested by returning zero from Widget::handle(). However in some cases the focus wants to use the keystroke only if it is not a shortcut. The most common example is Emacs-style editing keystrokes in text editing widgets, which conflict with Microsoft-compatable menu key bindings, but we want the editing keys to work if there is no conflict. This will send a SHORTCUT event just like the focus returned zero, to every widget in the focus window, and to the add_handler() calls, if any. It will return true if any widgets were found that were interested in it. A handle() method can call this in a KEY event. If it returns true, return 1 immediatly, as the shortcut will have executed and may very well have destroyed your widget. If this returns false, then do what you want the key to do. |
|
|
Unparse a fltk::Widget::shortcut() or fltk::event_key() value into human-readable text. Returns a pointer to a human-readable string like "Alt+N". If hotkey is zero an empty string is returned. The return value points at a static buffer that is overwritten with each call. The opposite function is fltk::key(). |
|
|
Turn a string into a fltk::event_key() value or'd with fltk::event_shift() flags. The returned value can be used by by fltk::Widget::add_shortcut(). Any error, or a null or zero-length string, returns 0. Currently this understands prefixes of "Alt+", "Shift+", and "Ctrl+" to turn on fltk::ALT, fltk::SHIFT, and fltk::CTRL. Case is ignored and the '+' can be a '-' instead and the prefixes can be in any order. You can also use '#' instead of "Alt+", '+' instead of "Shift+", and '^' instead of Ctrl+. After the shift prefixes there can either be a single ASCII letter, "Fn" where n is a number to indicate a function key, or "0xnnnn" to get an arbitrary fltk::event_key() enumeration value. The inverse function to turn a number into a string is fltk::key_name(). Currently this function does not parse some strings fltk::key_name() can return, such as the names of arrow keys! |
|
|
Returns true if the given key is held down now. This is different than event_key_state() as that returns how the key was during the last event. This can also be slower as it requires a round-trip query to the window server. The values to pass are described under fltk::SpaceKey. On Win32 fltk::get_key_state(fltk::KeypadEnter) does not work. |
|
||||||||||||
|
This is the function called from the system-specific code for all events that can be passed to Widget::handle(). You can call it directly to fake events happening to your widgets. Currently data other than the event number can only be faked by writing to the undocumented fltk::e_* variables, for instance to make event_x() return 5, you should do fltk::e_x = 5. This may change in future versions. This will redirect events to the modal(), pushed(), belowmouse(), or focus() widget depending on those settings and the event type. It will turn MOVE into DRAG if any buttons are down. If the resulting widget returns 0 (or the window or widget is null) then the functions pointed to by add_event_handler() are called. |
|
|
Install a function to parse unrecognized events. If FLTK cannot figure out what to do with an event, it calls each of these functions (most recent first) until one of them returns non-zero. If none of them returns non zero then the event is ignored. Currently this is called for these reasons:
|
|
|
Get the widget that is below the mouse. This is the last widget to respond to an fltk::ENTER event as long as the mouse is still pointing at it. This is for highlighting buttons and bringing up tooltips. It is not used to send fltk::PUSH or fltk::MOVE directly, for several obscure reasons, but those events typically go to this widget. |
|
|
Change the fltk::belowmouse() widget, the previous one and all parents (that don't contain the new widget) are sent fltk::LEAVE events. Changing this does not send fltk::ENTER to this or any widget, because sending fltk::ENTER is supposed to test if the widget wants the mouse (by it returning non-zero from handle()). |
|
|
Get the widget that is being pushed. fltk::DRAG or fltk::RELEASE (and any more fltk::PUSH) events will be sent to this widget. This is null if no mouse button is being held down, or if no widget responded to the fltk::PUSH event. |
|
|
Change the fltk::pushed() widget. This sends no events. |
|
|
Returns the widgets that will receive fltk::KEY events. This is NULL if the application does not have focus now, or if no widgets accepted focus. |
|
|
Change fltk::focus() to the given widget, the previous widget and all parents (that don't contain the new widget) are sent fltk::UNFOCUS events, the new widget is sent an fltk::FOCUS event, and all parents of it get fltk::FOCUS_CHANGE events. fltk::focus() is set whether or not the applicaton has the focus or if the widgets accept the focus. You may want to use fltk::Widget::take_focus() instead, it will test first. |
|
||||||||||||
|
Restricts events to a certain widget. First thing: much of the time fltk::Window::exec() will do what you want, so try using that. This function sets the passed widget as the "modal widget". All user events are directed to it or a child of it, preventing the user from messing with other widgets. The modal widget does not have to be visible or even a child of an fltk::Window for this to work (but if it not visible, fltk::event_x() and fltk::event_y() are meaningless, use fltk::event_x_root() and fltk::event_y_root()). The calling code is responsible for saving the current value of modal() and grab() and restoring them by calling this after it is done. The code calling this should then loop calling fltk::wait() until fltk::exit_modal_flag() is set or you otherwise decide to get out of the modal state. It is the calling code's responsibility to monitor this flag and restore the modal widget to it's previous value when it turns on. grab indicates that the modal widget should get events from anywhere on the screen. This is done by messing with the window system. If fltk::exit_modal() is called in response to an fltk::PUSH event (rather than waiting for the drag or release event) fltk will "repost" the event so that it is handled after modal state is exited. This may also be done for keystrokes in the future. On both X and WIN32 grab will not work unless you have some visible window because the system interface needs a visible window id. On X be careful that your program does not enter an infinite loop while grab() is on, it will lock up your screen! |
|
|
Returns the current modal widget, or null if there isn't one. It is useful to test these in timeouts and file descriptor callbacks in order to block actions that should not happen while the modal window is up. You also need these in order to save and restore the modal state. |
|
|
returns the current value of grab (this is always false if modal() is null). |
|
|
Turns on exit_modal_flag(). This may be used by user callbacks to cancel modal state. |
|
|
True if exit_modal() has been called. The flag is also set by the destruction or hiding of the modal widget, and on Windows by other applications taking the focus when grab is on. |
|
|
Add a new shortcut assignment. Returns true if successful. If key is zero or the assignment already exists this does nothing and returns false. There can be any number of shortcut assignments, fltk stores them in internal tables shared by all widgets. A widget can have any number of shortcuts (though most have zero or one), and a given shortcut value can be assigned to more than one widget. You can examine the assignments with fltk::list_shortcuts(). If you only want one shortcut use shortcut() to assign it. The shortcut value is a bitwise OR (or sum) of a any set of shift flags returned by fltk::event_state(), and either a key symbol returned by fltk::event_key(), or an ASCII character. Examples:
When FLTK gets a keystroke, it sends it to the fltk::focus() widget. If that widget's handle() returns 0, it will also send the keystroke to all parents of that widget (this is mostly for keyboard navigation to work). If all of them return 0, or the fltk::focus() is null, then it will try sending a SHORTCUT event to every single widget inside the same window as the focus until one of them returns non-zero. In most cases widgets will call Widget::test_shortcut() to see if the keystroke is registered here (many widgets will also directly test the key to see if it is something they are interested in). |
|
|
Delete a shortcut assignment. Returns true if it actually existed. |
|
|
Remove all shortcuts for the widget. Returns true if there were any. This is automatically done by the Widget destructor. |
|
|
Returns one of the add_shortcut() assignments for this widget, or returns zero if there are none. If you want to look at more than onle you must use fltk::list_shortcuts(this). |
|
|
Same as remove_shortcuts(), add_shortcut(key) except it may be implemented in a more efficient way. The result is exactly one shortcut (or none if key is zero). Return value is intended to indicate if the shortcut changed, but that is nyi. |
|
|
Returns a value that can be passed to add_shortcut() so that this widget has a real shortcut assignment to match any &x in it's label(). The returned value is ALT|c where c is the character after the first '&' in the label, or zero if there isn't any '&' sign or if flags() has RAW_LABEL turned on. |
|
|
Test to see if the current KEY or SHORTCUT event matches a shortcut specified with &x in the label. This will match if the character after the first '&' matches the event_text()[0]. Case is ignored. The caller may want to check if ALT or some other shift key is held down before calling this so that plain keys do not do anything, and should certainly make sure no other widgets want the shortcut. This is ignored if flags() has RAW_LABEL turned on (which stops the &x from printing as an underscore. The sequence "&&" is ignored as well because that is used to print a plain '&' in the label. |
|
|
Same as test_shortcut(true) |
|
|
Returns true if the current event matches one of the assignements made with add_shortcut(), or if test_label is true and test_label_shortcut() returns true. Normally a widget calls this in response to a SHORTCUT event to see if the shortcut key is assigned to it. This is done by doing list_matching_shortcuts() and seeing if this widget is in the returned list. If the list is empty and test_label is true, it will return test_label_shortcut(). If the current event matches a different widget "better" than this one, then false is returned. For instance if this widget has 'x' as a shortcut, this will return true if the user types 'X'. But if another widget has 'X' then this will return false. See fltk::list_matching_shortcuts() for the rules about what ones are "better". |
|
|
Handle an Event Types and Event Handling(event). Returns non-zero if the widget understood and used the event. The default version returns true for fltk::ENTER and fltk::MOVE events, this is done so you can put tooltips on the base widget. All other events return zero. Information on how to write your own version of handle() is can be found under Event Types and Event Handling. If you want to send an event to a widget you probably want to call send(), not handle(). Send will do extra work with each event before calling this, such as turning HIGHLIGHT and FOCUSED flags on/off. Reimplemented in Divider, Group, Input, Item, ItemGroup, NumericInput, and Valuator. |
|
|
Wrapper for handle(). This should be called to send events. It does a few things:
|
|
|
Call handle(TIMEOUT) at the given time in the future. This will happen exactly once. To make it happen repeatedly, call repeat_timeout() from inside handle(TIMEOUT). |
|
|
Call handle(TIMEOUT) at the given time interval since the last timeout. This will produce much more accurate time intervals than add_timeout(). |
|
|
Cancel any and all pending handle(TIMEOUT) callbacks. |
©2004 Bill Spitzak and others. See Main Page
for details.