/ 
FLTK-0.532007
/ FLTK::events

NAME

FLTK::events - Event types and data

Description

Event types and data. A Widget::handle() method needs this.

Functions

BUTTON

my $flags = FLTK::BUTTON( $number );

The function BUTTON(n) will turn number (1 .. 8) into the flag for a mouse button.

Import this function with the :events tag.

belowmouse

my $under = FLTK::belowmouse( );

Get the widget that is below the mouse. This is the last widget to respond to an 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 PUSH or MOVE directly, for several obscure reasons, but those events typically go to this widget.

Import this function with the :events tag.

FLTK::belowmouse( $widget );

Change the belowmouse() widget, the previous one and all parents (that don't contain the new widget) are sent LEAVE events. Changing this does not send ENTER to this or any widget, because sending ENTER is supposed to test if the widget wants the mouse (by it returning non-zero from handle()).

Import this function with the :events tag.

compose

my $changed = FLTK::compose( $del );

Use of this function is very simple. Any text editing widget should call this for each KEY event.

If a true value is returned, then it has modified the event_text() and 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 compose(). Compose may consume the key, which is indicated by returning true, but both the length and del are set to zero.

Compose returns a false value 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.

Import this function with the :events tag.

compose_reset

FLTK::compose_reset( );

If the user moves the cursor, be sure to call compose_reset(). The next call to 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.

Import this function with the :events tag.

copy

FLTK::copy( $stuff, $length, $clipboard );

Change the current selection. The block of text is copied to an internal buffer by FLTK (be careful if doing this in response to a PASTE as this may be the same buffer returned by event_text()).

The block of text may be retrieved (from this program or whatever program last set it) with paste().

There are actually two buffers. If clipboard is true then the text goes into the user-visible selection that is moved around with cut/copy/paste commands (on X this is the CLIPBOARD selection). If clipboard is false then the text goes into a less-visible buffer used for temporarily selecting text with the mouse and for drag & drop (on X this is the XA_PRIMARY selection).

Import this function with the :events tag.

dnd

my $drag = FLTK::dnd( );

Drag and drop the data set by the most recent copy() (with the clipboard argument false). Returns true if the data was dropped on something that accepted it.

By default only blocks of text are dragged. You can use system-specific variables to change the type of data.

Import this function with the :events tag.

event

my $event = FLTK::event( );

Import this function with the :events tag.

event_button

my $button = FLTK::event_button( );

Import this function with the :events tag.

event_clicks

FLTK::event_clicks( $i );

Import this function with the :events tag.

my $clicks = FLTK::event_clicks( );

Import this function with the :events tag.

event_device

my $id = FLTK::event_device( );

Import this function with the :events tag.

event_dx

my $dx = FLTK::event_dx( );

Import this function with the :events tag.

event_dy

my $dy = FLTK::event_dy( );

Import this function with the :events tag.

event_inside

my $in = FLTK::event_inside( $rectangle );

Returns true if the current event_x() and 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.

Import this function with the :events tag.

event_is_click

my $click = FLTK::event_is_click( );

Import this function with the :events tag.

FLTK::event_is_click( $value );

Import this function with the :events tag.

event_key

my $key = FLTK::event_key( );

Import this function with the :events tag.

event_key_repeated

my $repeated = FLTK::event_key_repeated( );

Import this function with the :events tag.

event_key_state

my $state = FLTK::event_key_state( $state );

Import this function with the :events tag.

event_length

my $length = FLTK::event_length( );

Import this function with the :events tag.

event_name

my $string = FLTK::event_name( $event );

Return the corresponding name of an event, should not consume memory if api is not used. This is really only good for debugging.

Import this function with the :events tag.

event_pressure

my $pressure = FLTK::event_pressure( );

Import this function with the :events tag.

event_state

my $state = FLTK::event_state( );

Import this function with the :events tag.

my $state = FLTK::event_state( $state );

Import this function with the :events tag.

event_text

my $string = FLTK::event_text( );

Import this function with the :events tag.

event_x

my $x = FLTK::event_x( );

Import this function with the :events tag.

event_x_root

my $x = FLTK::event_x_root( );

Import this function with the :events tag.

event_x_tilt

my $tilt_x = FLTK::event_x_tilt( );

Import this function with the :events tag.

event_y

my $y = FLTK::event_y( );

Import this function with the :events tag.

event_y_root

my $y = FLTK::event_y_root( );

Import this function with the :events tag.

event_y_tilt

my $tilt_y = FLTK::event_y_tilt( );

Import this function with the :events tag.

exit_modal

FLTK::exit_modal( );

Turns on exit_modal_flag(). This may be used by user callbacks to cancel modal state. See also Window::make_exec_return().

Import this function with the :events tag.

exit_modal_flag

my $eh = FLTK::exit_modal_flag( );

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.

Import this function with the :events tag.

focus

my $widget = FLTK::focus( );

Returns the widgets that will receive KEY events. This is undef if the application does not have focus now, or if no widgets accepted focus.

Import this function with the :events tag.

FLTK::focus( $widget );

Change focus() to the given widget, the previous widget and all parents (that don't contain the new widget) are sent UNFOCUS events, the new widget is sent an FOCUS event, and all parents of it get FOCUS_CHANGE events.

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.

Import this function with the :events tag.

foreachShortcut

my $value = FLTK::foreachShortcut( $SF, $widget );

Calls the handle() method from the passed ShortcutFunctor object for every Widget::shortcut() assignment known. If any return true then this immediately returns that shortcut value, else this returns zero after calling it for the last one. This is most useful for making a display of shortcuts for the user, or implementing a shortcut editor.

If widget is not null, only do assignments for that widget, this is much faster than searching the entire list. This is useful for drawing the shortcuts on a widget (though most fltk widgets only draw the first one).

Import this function with the :events tag.

my $value = FLTK::foreachShortcut( $SF );

Same. But without widget NULL by default.

Import this function with the :events tag.

get_key_state

my $state = FLTK::get_key_state( $key );

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

Note: On Win32, event_key_state(KeypadEnter) does not work.

Import this function with the :events tag.

get_mouse

my @xy = FLTK::get_mouse( );

Return where the mouse is on the screen by doing a round-trip query to the server. You should use event_x_root() and 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.

Import this function with the :events tag.

grab

my $cvalue = FLTK::grab( );

Returns the current value of grab (this is always false if modal() is undef).

Import this function with the :events tag.

handle

my $handled = FLTK::handle( $event, $window );

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 whould do fltk::e_x = 5. This may change in future versions of fltk toolkit and is currently not supported by the FLTK module.

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 undef) then the functions pointed to by add_event_handler() are called.

key

my $key = FLTK::key( $name );

Turn a string into a event_key() value or'd with 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 ALT, SHIFT, and 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 event_key() enumeration value.

The inverse function to turn a number into a string is key_name(). Currently this function does not parse some strings key_name() can return, such as the names of arrow keys!

Import this function with the :events tag.

key_name

my $string = FLTK::key_name( $hotkey );

Unparse a FLTK::Widget::shortcut(), an event_key(), or an event_key() or'd with event_state(). Returns a human-readable string like "Alt+N". If hotkey is zero an empty string is returned.

The opposite function is key().

Import this function with the :events tag.

FLTK::modal( $widget, $grab );

Restricts events to a certain widget.

First thing: much of the time 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 a Window for this to work (but if it not visible, event_x() and event_y() are meaningless, use event_x_root() and 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 wait() until 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 exit_modal() is called in response to a 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!

Import this function with the :events tag.

my $current = FLTK::modal( );

Returns the current modal widget, or undef 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.

Import this function with the :events tag.

paste

FLTK::paste( $widget, $clipboard );

This is what a widget does when a "paste" command (like Ctrl+V or the middle mouse click) is done to it. Cause a PASTE event to be sent to the receiver with the contents of the current selection in the event_text(). The selection can be set by copy().

There are actually two buffers. If clipboard is true then the text is from the user-visible selection that is moved around with cut/copy/paste commands (on X this is the CLIPBOARD selection). If clipboard is false then the text is from a less-visible buffer used for temporarily selecting text with the mouse and for drag & drop (on X this is the XA_PRIMARY selection).

The reciever should be prepared to be called directly by this or, for it to happen later, or possibly not at all. This allows the window system to take as long as necessary to retrieve the paste buffer (or even to screw up completely) without complex and error-prone synchronization code most toolkits require.

Import this function with the :events tag.

pushed

my $current = FLTK::pushed( );

Get the widget that is being pushed. DRAG or RELEASE (and any more 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 PUSH event.

Import this function with the :events tag.

FLTK::pushed( $widget );

Change the pushed() widget. This sends no events.

Import this function with the :events tag.

try_shortcut

my $handled = FLTK::try_shortcut( );

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.

Import this function with the :events tag.

warp_mouse

my $worked = FLTK::warp_mouse( $x, $y );

Change where the mouse is on the screen.

Returns true if successful, false on failure (exactly what success and failure means depends on the os).

Import this function with the :events tag.

Events

FLTK's event system passes numbered arguments to Widget::handle() and returns the same from event(). These events may be imported with the events tag and include the following:

NO_EVENT
PUSH
RELEASE
ENTER
LEAVE
DRAG
FOCUS
UNFOCUS
KEY
KEYUP
FOCUS_CHANGE
MOVE
SHORTCUT
DEACTIVATE
ACTIVATE
HIDE
SHOW
PASTE
TIMEOUT
MOUSEWHEEL
DND_ENTER
DND_DRAG
DND_LEAVE
DND_RELEASE
TOOLTIP

If you're rolling your own event system (See FLTK::Subclass), you're gonna need these.

Event Keys

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.

Supported keys may be imported with the events tag and include...

LeftButton
MiddleButton
RightButton
SpaceKey
BackSpaceKey
TabKey
ClearKey

On some systems with NumLock off '5' produces this.

ReturnKey

Main Enter key, Windows and X documentation calls this "Return"

PauseKey

Pause / Break button

ScrollLockKey
EscapeKey
HomeKey
LeftKey
UpKey
RightKey
DownKey
PageUpKey
PageDownKey
EndKey
PrintKey

Print Scr / Sys Rq key

InsertKey

Key in lower-right (between Ctrl and Win) with picture of popup menu

HelpKey

Help key on Macintosh keyboards

NumLockKey
Keypad

Add ASCII to this to get keypad keys.

As in Keypad + "+" is the same as AddKey.

KeypadEnter

Enter on the keypad. Same as Keypad + "\r"

MultiplyKey

* on the keypad. Same as Keypad + "*"

AddKey

+ on the keypad. Same as Keypad + "+"

SubtractKey

- on the keypad. Same as Keypad + "-"

DecimalKey

. on the keypad

DivideKey

/ on the keypad

Keypad0

0 on the keypad

Keypad1

1 on the keypad

Keypad2

2 on the keypad

Keypad3

3 on the keypad

Keypad4

4 on the keypad

Keypad5

5 on the keypad

Keypad6

6 on the keypad

Keypad7

7 on the keypad

Keypad8

8 on the keypad

Keypad9

9 on the keypad

KeypadLast

Keypad + '=', largest legal keypad key

F0Key

Add a number to get function key.

As in F0Key + 3 is the same as F3Key

F1Key
F2Key
F3Key
F4Key
F5Key
F6Key
F7Key
F8Key
F9Key
F10Key
F11Key
F12Key
LastFunctionKey

Largest legal function key. Same as F0Key + 35

LeftShiftKey

Left-hand Shift

RightShiftKey

Right-hand Shift

LeftCtrlKey

Left-hand Ctrl

RightCtrlKey

Right-hand Ctrl

CapsLockKey

Caps Lock

LeftMetaKey

The left "Windows" or "Apple" key

RightMetaKey

The right "Windows" or "Apple" key

LeftAltKey

Left-hand Alt (option on Mac)

RightAltKey

Right-hand Alt (option on Mac)

DeleteKey

Delete

LeftAccKey

Same as LeftCtrlKey on Mac, LeftAltKey on other systems.

RightAccKey

Same as RightCtrlKey on Mac, RightAltKey on other systems.

LeftCmdKey

Same as LeftMetaKey on Mac, LeftCtrlKey on other systems.

RightCmdKey

Same as RightMetaKey on Mac, RightCtrlKey on other systems.

...in addition to the above, letters a .. z and all punctuation are passed by their ordinal values.

Flags

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 function BUTTON(n) will turn n (1 .. 8) into the flag for a mouse button.

The current flags imported with the :events targ are...

SHIFT

Either shift key held down

CAPSLOCK

Caps lock is toggled on =item CTRL

Either ctrl key held down

ALT

Either alt key held down

NUMLOCK

Num Lock turned on.

META

"Windows" or the "Apple" keys held down.

SCROLLLOCK

Scroll Lock turned on.

BUTTON1

Left mouse button held down.

BUTTON2

Middle mouse button held down.

BUTTON3

Right mouse button held down.

ANY_BUTTON

Any mouse button (up to 8).

ACCELERATOR

ALT on Windows/Linux, CTRL on OS/X, use for menu accelerators.

COMMAND

CTRL on Windows/Linux, META on OS/X, use for menu shortcuts.

OPTION

ALT|META on Windows/Linux, just ALT on OS/X, use as a drag modifier.

Devices

Device identifiers are returned by event_device(). This is useful to get the device type that caused a PUSH, RELEASE, DRAG or MOVE event.

Current devices (which are imported with the events tag) include...

DEVICE_MOUSE

Event triggered by the system mouse.

DEVICE_STYLUS

Event triggered by a pen on a tablet, givin pressure and tilt information.

DEVICE_ERASER

Event triggered by an eraser on a tablet, givin pressure and tilt information.

DEVICE_CURSOR

Event triggered by a puck style device on a tablet.

DEVICE_AIRBRUSH

Event triggered by an airbrush on a tablet, giving pressure and tilt information.

DEVICE_TOUCH

Event triggered by touch a touch screen device.

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

License and Legal

Copyright (C) 2008-2010 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.