BB___WHEN

=WHEN= toc

Description
> Capturing keypresses and mouse movements is called trapping an //event// - a keyboard event or a mouse event. The WHEN command tells the graphic window or the graphicbox control to process those events.

Hints
>> code format="lb" code >> WARNING: using graphicboxes in dialog-type windows is fine, but they do not properly accept the input focus for keyboard input. If a program needs graphicboxes that trap keyboard events, then a window of type "window" must be used.
 * //**Events.**// Events can only be trapped and processed if the window or control has the input focus. See SETFOCUS.
 * //**Event handlers.**// An event is processed by the code in an event handler, which can be a branch label or a subroutine.
 * //**Keyboard Events.**// When a keyboard event is trapped, the key string value is placed in the special variable INKEY$.
 * //**Mouse Events.**// When a mouse event is trapped, the position of the mouse in X and Y pixel coords from the upper left corner of the window or control is placed in the variables MouseX and MouseY.
 * //**Cancel Event Trapping.**//Issuing a WHEN statement without an eventHandler routine will cancel the trapping of that event:
 * 1) handle.ext "when leftButtonDown"
 * //**Use in windows of type dialog.**//Here's a warning taken from the JB Help file on Graphics Commands:

List of Events
The following events can be trapped - names are **case sensitive**: code leftButtonDown     - the left mouse button is now down leftButtonUp       - the left mouse button has been released leftButtonMove     - the mouse moved while the left button was down leftButtonDouble   - the left mouse button has been double-clicked rightButtonDown    - the right mouse button is now down rightButtonUp      - the right mouse button has been released rightButtonMove    - the mouse moved while the right button was down rightButtonDouble  - the right mouse button has been double-clicked middleButtonDown   - the middle mouse button is now down middleButtonUp     - the middle mouse button has been released middleButtonMove   - the mouse moved while the middle button was down middleButtonDouble - the middle mouse button has been double-clicked mouseMove          - the mouse moved when no button was down characterInput     - a key was pressed while the graphics window has input focus (see the setfocus command, above) code

Example
A very good example from the JB Help file on Reading Mouse Events and Keystrokes.

code format="lb" 'A graphics window or graphicbox is able to read mouse and keyboard input. 'Here is the world's smallest painting program!

open "Paint something!" for graphics as #w print #w, "when leftButtonMove [paint]" print #w, "when characterInput [letter]" print #w, "down ; size 3" wait [paint] print #w, "set "; MouseX; " "; MouseY wait [letter] print #w, "\"; Inkey$ wait code

Useful Functions
code format="lb" Place a useful function using this keyword here code