WHEN

Description

Capturing key-presses and mouse movements is called trapping an event - a keyboard event or a mouse event. The WHEN command tells the graphic window or the graphic-box control to process those events.

Syntax

1. #handle.ext "when event [branch]"
2. #handle.ext "when event subroutine"

Hints

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 coordinates 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:

#handle.ext "when leftButtonDown"

Use in windows of type dialog

Here's a warning taken from the Help file on Graphics Commands:

WARNING: using graphic-boxes in dialog-type windows is fine, but they do not properly accept the input focus for keyboard input. If a program needs graphic-boxes that trap keyboard events, then a window of type "window" must be used.

List of Events

The following events can be trapped - names are case sensitive:

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)

Example

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

'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

Useful Procedures

' Place a useful function or sub using this keyword here