Next: , Previous: Window Operations for OS/2 Graphics, Up: OS/2 Graphics

17.11.4 Event Operations for OS/2 Graphics

These operations allow you to read some of the events that are generated by the Presentation Manager and put in the message queue of a graphics-device window.

— operation on os2-graphics-device: read-button

This operation waits for the user to push a mouse button inside the client area of the graphics-device window. It then returns four values (see Continuations) which are: the button number; the x and y coordinates of the mouse pointer at the time the button was pressed, in pels (pixels) relative to the lower left hand corner of the client area; and the graphics device that the mouse pointer was over at the time the button was pressed.

Note that this operation only works when button events are selected (which is the default).

— operation on os2-graphics-device: select-user-events mask

This operation sets the event-selection mask for the graphics device to mask. The event-selection mask is an exact non-negative integer that specifies which types of incoming events are to be saved in the user-event queue for later retrieval by the read-user-event operation. The mask is specified by setting the bits corresponding to the event types that you are interested in, as follows: 

          Number  Mask    Description
          ------  -----   -----------
          0       #x001   Button press/release
          1       #x002   Close (close the window) [WM_CLOSE]
          2       #x004   Focus change [WM_SETFOCUS]
          3       #x008   Key press/release [WM_CHAR]
          4       #x010   Paint [WM_PAINT]
          5       #x020   Size change [WM_SIZE]
          6       #x040   Visibility change [WM_SHOW]
          7       #x080   Command [WM_COMMAND]
          8       #x100   Help [WM_HELP]
          9       #x200   Mouse-move [WM_MOUSEMOVE]

Note that this operation does not affect any events that are already in the user-event queue. Changing the mask only affects what events will be added to the queue in the future.

— operation on os2-graphics-device: read-user-event

This operation returns the next user event available from the user-event queue. If there are no events in the queue, the operation waits for an event to arrive before returning.

An event is a vector whose first element is the event-type number, whose second element is the graphics device that the event refers to, and whose remaining elements provide information about the event. Here is a table of the possible event types and their vector layout:

#(0 device number type x y flags)
A button event. Number is the button number, for example button number 0 is usually the left mouse button, 1 is usually the right button, etc. Type specifies what occurred: 0 means the button was pressed, 1 means the button was released, 2 means the button was clicked, and 3 means the button was double clicked. X and y are the position of the mouse pointer at the time of the event, in units of pels (pixels) measured from the lower left corner of the client area of the associated window. Finally, flags specifies what shift keys were pressed at the time of the button event; it is a mask word created by combining zero or more of the following flags: #x08 means the shift key was pressed, #x10 means the control key was pressed, and #x20 means the alt key was pressed.
#(1 device)
A close event. The user has selected the close button from the system menu, or typed <Alt-f4>.
#(2 device gained?)
A focus event. If gained? is #t, the keyboard focus is being gained, and if gained? is #f, it is being lost.
#(3 device code flags repeat)
A keyboard event. This is much too complicated to describe here. See the OS/2 toolkit documentation for details.
#(4 device xl xh yl yh)
A paint event. Part of the graphics-device window that was obscured has been revealed and the Presentation Manager is informing the window that it must repaint that area. Scheme will take care of the painting for you, so this event isn't very useful.
#(5 device width height)
A size-change event. The size of the graphics-device window has changed, and width and height specify the new size in pels (pixels).
#(6 device shown?)
A visibility event. Indicates that the graphics-device window has been hidden or revealed. If shown? is #f, the window is hidden, and if it is #t, the window is shown.
#(7 device source mouse?)
#(8 device source mouse?)
A menu command. Source specifies which menu item was selected to cause this event, and mouse? is a boolean indicating whether the item was selected with the mouse or the keyboard. The event-type number 7 indicates a command from a ‘WM_COMMAND’ message, while 8 is a command from a ‘WM_HELP’ message.
#(9 device x y hit-test flags)
The mouse was moved. X and y specify the position of the mouse, hit-test contains the hit-test information, and flags specifies the modifier keys that were pressed at the time.
— operation on os2-graphics-device: discard-events

This operation discards any events that are in the user-event queue. This is sometimes useful when you want to prompt the user for some input and don't want to consider any previous input.