Chapter 20 - Sys_Event Subroutine

As the user of the program manipulates the mouse, clicking on various controls, selecting windows, etc., these activities are reported back to the program as events. In True BASIC, these events do not generate interrupts, but rather are placed on a single queue (list). Calling the built-in subroutine SYS_EVENT allows the program to examine the event, if any, at the front of the list.

(We strongly recommend that you use True Controls. Its subroutine, TC_Event, calls Sys_Event and then per- forms several operations on scroll bars, check boxes, radio buttons, etc. Call Sys_Event directly only for special purposes not covered by True Controls.)

This model, examining one at a time the events from the event queue by calling the subroutine SYS_EVENT, pro- vides the simplest possible way to respond to the many things that can happen within the user interface. These events occur asynchronously and can be reported in an order different from that in which the programmer intended.

The standard way to build a program might be illustrated as follows:
DO
CALL Sys_Event ... SELECT CASE event$ CASE “event 1”
CALL Response1
CASE “event 2” CALL Response2
...
CASE “event n” CALL Responsen
CASE else
! Must be an error
END SELECT LOOP

Of course, the event names from SYS_EVENT are more suggestive, and additional information is also provided. The rest of this chapter lists the different events that can occur for each of the windows, menus, and controls.

———————————————–––————————————————————————
[ ! ] Note: Graphics objects in themselves cannot be the cause of any events
—————————————————–––——————————————————————

The Sys_Event Subroutine
The calling sequence for the SYS_EVENT subroutine is
CALL Sys_Event (timer, event$, window, x1, x2)
The value of timer specifies the amount of time to wait for an event if the event queue is empty. The subroutine
338 True BASIC Language System

will return immediately if timer = 0. In either case, if there is no event on the event queue, then event$ will be the null string.

The name of the event itself is returned in event$ and is capitalized. Event names are listed later according to the type of object or control that generated them.

The ID number of the physical window in which the event occurred is returned in the third argument window. This is the physical window ID number, and has no relation to any True BASIC logical windows that might be in use.

The last two parameters, x1, and x2, provide additional numeric information in most cases. If either, or both, is not used, it is set to 0.

The rest of this chapter lists the events, by type of object or control that can generate them.

Events for Windows
KEYPRESS The user has pressed a key. The window ID will be that of the active window, the one des- ignated to receive input. X1 is the ASCII number of the character generated. X2 contains the shift key codes; if x2 = 1, the shift key was held down; if 2, the control key was held down; if 0, neither key was held down; if 3, both keys were held down.

The following thirteen events are mouse events. They all have the same definition for x1 and x2. x1 x-coordinate mouse position
x2 y-coordinate mouse position

SINGLE A single click of the left button, or of the only button, on the mouse has occurred. Note that a mouse click that selects a window will return a SELECT event. But a second click in the window, once the window has been selected, will return this event or one like it.
DOUBLE A double mouse click has occurred with the left or only mouse button. Note that this event will always be preceded by a SINGLE event. That is, if a second click has occurred within a small time increment, this second click will generate a DOUBLE event.
EXTEND A mouse click with the shift key held down has occurred. This is used most commonly to select multiple items from a list.
SINGLE RIGHT DOUBLE RIGHT EXTEND RIGHT

SINGLE MIDDLE DOUBLE MIDDLE EXTEND MIDDLE

MOUSE UP MOUSE UP RIGHT

These events are just like the three above, but apply to the right mouse button.

These events are like those above, but apply to the middle mouse button.
MOUSE UP MIDDLE

The mouse button has been released. The first event applies to the left button, the next two to the right and middle buttons, if any.
MOUSE MOVE

The mouse has moved since the last time Sys_Event was called. This event will not be returned unless the MOUSE MOVE attribute has been turned on.
SIZE The window (see the third argument) has been resized. Note that just moving the win- dow without resizing it will generate no event. x1 and x2 are not used.
When a window has been resized, it may be necessary to regenerate its contents.
Sys_Event Subroutine

339

REFRESH The window, which was formerly partially or completely hidden or covered by other win- dows, is now fully visible. If the window is not IMMUNE, then its contents will have to be regenerated. X1 and x2 are not used.

If the window is IMMUNE, then its contents will not have to be regenerated, but the
REFRESH event will still occur.

SELECT The window has been selected (made active) or deselected. x1 = 1 if the window was selected, and = 0 if the window was deselected. (This says nothing about the window being a target for input and output.) The window selected will also have focus.

HIDE The window has been hidden or closed. This can occur by clicking in the close box. x1 and
x2 are not used.

The following twelve events can occur if there are scroll bars attached to the window. x1
and x2 are not used.

UP The up arrow in an attached vertical scroll bar has been clicked. DOWN The down arrow in an attached vertical scroll bar has been clicked. LEFT The left arrow in an attached horizontal scroll bar has been clicked. RIGHT The right arrow in an attached horizontal scroll bar has been clicked.
PAGEUP The trough above the slider in an attached vertical scroll bar has been clicked. PAGEDOWN The trough below the slider in an attached vertical scroll bar has been clicked. PAGELEFT The trough to the left of the slider in an attached horizontal scroll bar has been clicked. PAGERIGHT The trough to the right of the slider in an attached horizontal scroll bar has been clicked.
VSCROLL The slider in an attached vertical scroll bar is being moved. (By how much and in what direction can be determined using the OBJM_GET method.)

HSCROLL The slider in an attached horizontal scroll bar is being moved. (By how much and in what direction can be determined using the OBJM_GET method.)

END VSCROLL The end of a slider movement in an attached vertical scroll bar has occurred. This will happen when the user releases the mouse button.

END HSCROLL The end of a slider movement in an attached horizontal scroll bar has occurred. This will happen when the user releases the mouse button.

MENU The user has selected a menu item. X2 contains the ID number of the menu item selected.

Events for Graphics Objects
Graphics objects cannot generate events.

Events for Controls
Many controls can generate the same event. For completeness, all such events are listed for the particular type of control.

Events for Push Buttons
CONTROL The user has clicked the mouse on a push button. X2 contains the ID number
SELECT of the push button.

Normally, this event will not be returned by the SYS_EVENT subroutine until the matching CONTROL DESELECTED event has occurred.
340 True BASIC Language System

CONTROL The user has released the mouse button whilst still pointing to a push button. DESELECTED X2 contains the ID number of the push button.

Events for Radio Buttons
CONTROL The user has clicked the mouse on a radio button. X2 contains the ID number
SELECT of the radio button.

Normally, this event will not be returned by the SYS_EVENT subroutine until the matching CONTROL DESELECTED event has occurred.

CONTROL The user has released the mouse button whilst still pointing to a radio button. DESELECTED X2 contains the ID number of the radio button.

Which radio button is on can also be determined by using the OBJM_GET method.

Events for Check Boxes
CONTROL The user has clicked the mouse on a check box. X2 contains the ID number of
SELECT the check box.

Normally, this event will not be returned by the SYS_EVENT subroutine until the matching CONTROL DESELECTED event has occurred.

CONTROL The user has released the mouse button whilst still pointing to a check box. DESELECTED X2 contains the ID number of the check box.

The current state of the check box can be determined by using the OBJM_GET method.

Events for Scroll Bars
The events for scroll bars that are not attached to windows follow. In each case, x2 contains the ID number of the scroll bar control.
UP The user has clicked in the up arrow of a vertical scroll bar. DOWN The user has clicked in the down arrow of a vertical scroll bar. LEFT The user has clicked in the left arrow of a horizontal scroll bar. RIGHT The user has clicked in the right arrow of a horizontal scroll bar.
PAGEUP The user has clicked in the trough above the slider in a vertical scroll bar. PAGEDOWN The user has clicked in the trough below the slider in a vertical scroll bar. PAGELEFT The user has clicked in the trough to the left of the slider in a horizontal scroll bar. PAGERIGHT The user has clicked in the trough to the right of the slider in a horizontal scroll bar. VSCROLL The user is in the process of moving the vertical slider in a scroll bar.
HSCROLL The user is in the process of moving the horizontal slider in a scroll bar.
END VSCROLL The user has released the mouse button after having moved the vertical slider. END HSCROLL The user has released the mouse button after having moved the horizontal slider.

Events for Edit Fields
CONTROL The user has clicked the mouse on an edit field. X2 contains the ID number of
SELECT the edit field.

CONTROL The user has finished editing one edit field, and has moved the mouse to a new edit
DESELECTED field, causing the first edit field to be deselected. Certain key strokes can also be used to advance to the next edit field, causing the former edit field to become deselected. At this point it is possible to interrogate the text the user has edited and to match the text against a desired format. x2 contains the ID number of the edit field deselected.
Sys_Event Subroutine

341

If the deselection was caused by the user pressing a key specified as an EXIT CHAR, then the character number is returned in x1.

Events for Static Text
Static Text cannot generate events.

Events for Selection List Boxes
CONTROL SINGLE The user has clicked on an item in the selection list. X2 contains the ID number of the selection list box control. Which item has been selected can be determined using the OBJM_GET method.

CONTROL DOUBLE The user has double-clicked on an item in the selection list. X2 contains the ID num- ber of the selection list box control. Which item has been selected can be determined using the OBJM_GET method.

This event will always be preceded by a CONTROL SINGLE event. (Note: the CON- TROL DOUBLE event often is a signal that the user has completed the examination of the selection list box; thus it is the equivalent of selecting an “Ok” button, were there one to select.)

Events for List Buttons
CONTROL SINGLE The user has clicked on an item in the list button. X2 contains the ID number of the list button control. Which item has been selected can be determined using the OBJM_GET method.

Events for List Edit Buttons
CONTROL SELECT The user has clicked the mouse on a list edit button. x2 contains the ID number of the list edit button.

CONTROL The user has finished editing the list edit button, and has moved the mouse
DESELECTED elsewhere. Certain key strokes can also be used to generate this event. At this point it is possible to interrogate the text the user has edited. X2 contains the ID number of the edit field deselected.
KEYPRESS The user has pressed a key that has been defined to cause a focus shift. X1 contains the ASCII value of the key.

Events for Group Boxes
Groups Boxes cannot generate events.

Events for Text Edit Controls
TXE MOUSE The user has clicked the mouse in a text edit control when MOUSE EVENTS had been selected as an option.
TXE VSCROLL The user is in the process of scrolling the text vertically by holding the mouse button down while moving the mouse to the extreme top or bottom of the text edit control.
TXE HSCROLL The user is in the process of scrolling the text horizontally by holding the mouse but- ton down while moving the mouse to the extreme left or right of the text edit control.
TXE KEYPRESS The user has pressed a key when KEY EVENTS has been selected as an option, or the user has pressed one of the TRAP characters. If the Shift Key is also pressed, 256 will be added to the key code. If the Control Key is also pressed, 512 will be added to the key code. If both are pressed, 768 (256 + 512) will be added to the key code.
342 True BASIC Language System

Events for Groups (currently, only Radio Groups)
CONTROL SELECT The user has clicked the mouse on a radio button. X2 contains the ID number of the radio button.
Normally, this event will not be returned by the SYS_EVENT subroutine until the matching CONTROL DESELECTED event has occurred.
CONTROL The user has finished clicking on a radio button, and has moved the mouse
DESELECTED elsewhere. X2 contains the ID number of the button deselected. (At this point it is pos- sible to interrogate the radio group control to learn which button is on.)

Summary of Events
All the possible events are listed below, followed by the objects or controls that can generate them.

The following nine events can be generated by mouse clicks within windows, but not clicks on most controls (which generate events like CONTROL SELECT.) Window contains the window ID number. X1 contains the x-coordinate of the mouse position in window coordinates, and x2 contains the y-coordinate of the mouse position.
SINGLE DOUBLE EXTEND SINGLE RIGHT DOUBLE RIGHT EXTEND RIGHT
SINGLE MIDDLE DOUBLE MIDDLE EXTEND MIDDLE MOUSE UP MOUSE UP RIGHT
MOUSE UP MIDDLE MOUSE MOVE

The following four events are all window-related. The window ID is returned in window. x1 and x2 are ignored.
SIZE REFRESH SELECT HIDE MENU

The following twelve events are generated by scroll bars. If the scroll bars are attached to a window, then x1 and
x2 are ignored. If the scroll bars are not attached to a window, then x2 contains the ID number of the scroll bar.
UP DOWN LEFT RIGHT PAGEUP
PAGEDOWN PAGELEFT PAGERIGHT VSCROLL HSCROLL
END VSCROLL END HSCROLL
Sys_Event Subroutine

343

The following two events can be generated only from selection list boxes, but only the first for list buttons. In each case window gives the window ID, and x2 gives the control ID.

CONTROL SINGLE CONTROL DOUBLE

The following two events can be generated from push buttons, radio buttons, check boxes, edit fields, list edit buttons, and text edit controls. In each case window gives the window ID, and x2 gives the control ID.

CONTROL SELECT CONTROL DESELECTED

The following event can be generated from a window. Window gives the window ID, x1 gives the ASCII values of the key stroke, and x2 gives the shift key code; if x2 = 1, the shift key was held down; 2, the control key was held down; if 0, neither key was held down; if 3, both keys were held down.

KEYPRESS

The following four events can be generated only from a text edit control. For TXE KEYPRESS, x1 is the key and
x2 is the control ID. For the other three, x1 is 0 and x2 is the ID.

TXE KEYPRESS TXE MOUSE TXE VSCROLL TXE HSCROLL
344 True BASIC Language System
345