event function

	<< Index >>	FutureBasic 5
event		function

Syntax:
eventRecPtr& = event

Description:
This function returns a pointer to a system event record. If your program has designated a system event-handling routine using the on event statement, then your routine should check the contents of this record every time the routine is called. The record will contain a description of the event that triggered the call to your system event-handling routine.
If you store the record pointer into a long integer or pointer variable (e.g., eventRecPtr& = event), then you can examine the individual fields of the event record as follows:
type% = eventRecPtr&.evtNum%
This represents the event type, which will be one of the following constants:

`type%`	Description
`_nullEvt (0)`	No event occurred
`_mButDwnEvt (1)`	mouse button pressed
`_mButUpEvt (2)`	mouse button released
`_keyDwnEvt (3)`	key pressed
`_keyUpEvt (4)`	key released
`_autoKeyEvt (5)`	key repeatedly held down
`_updatEvt (6)`	window needs updating
`_diskInsertEvt (7)`	disk inserted
`_activateEvt (8)`	window was brought to front or moved to back (see the `evtMeta%` field to determine which)
`_osEvt (15)`	operating system events (suspend, resume, mouse moved)
`_kHighLevelEvent (23)`	high-level events (includes Apple Events)

message& = eventRecPtr&.evtMessage&
This contains additional information about the event, which varies depending on the type of event that occurred.

`type%`	`message&`
`_keyDwnEvt, _keyUpEvt, autoKeyEvt`	bits 0-7 = ASCII char; bits 8-15 = key code; for ADB keyboards, bits 16-23 = keyboard's ADB address.
`_updatEvt, activateEvt`	pointer to the window
`_diskInsertEvt`	bits 0-15 = drive ID; bits 16-31 = error code
`_osEvt`	high-order byte = 1 for suspend/resume events; high-order byte = 250 for mouse-moved event. For suspend/resume events: bit 0 = 0 for suspend; bit 0 = 1 for resume. For resume event: bit 1 = 1 if clipboard was changed.
`_kHighLevelEvent`	Class of events to which the high level event belongs. This is used with the `_evtMouse` field to identify the specific type of high-level event received.

ticks& = eventRecPtr&.evtTicks&

This gives the tickcount value (time since system startup, in ticks) when the event occurred. You can compare this against the current value of fn TickCount, to determine how long ago the event occurred.

mousePt;4 = eventRecPtr& + _evtMouse

For low level events (i.e., all types except _kHighLevelEvent), this gives the mouse cursor location, in global coordinates, at the time the event occurred. mousePt should be dim'ed as a 4-byte record.

highLevelEvtID& = eventRecPtr&.evtMouse&

For high-level events (i.e., of type _kHighLevelEvent), this gives the high-level Event ID, which together with message& identifies the type of high-level event.

modKeys% = eventRecPtr&.evtMeta%

Contains information about the state of the modifier keys (Control, Shift, etc.) and the mouse button, at the time the event occurred. For activate events, bit 0 = 1 if the window should be activated; bit 0 = 0 if the window should be deactivated. The state of the modifier keys and mouse button is determined by specific bit values in this short integer; see the event% function for more information.

"Clearing" an Event
After you've finished looking at an event record and you exit your system event-handling routine, FutureBasic examines that same event record to determine whether the event can be translated into one of the "FB events" that your program typically detects using the dialog function, the menu function, etc. For example, if FutureBasic sees an event record in which a _mButDwn event has occurred, it checks whether the mouse was clicked inside a button, and tracks the mouse in preparation for a possible dialog event of type _btnClick.
If you've handled the event completely within your on event routine, and you don't want FutureBasic to do anything else with the event record afterwards, then you should set the event type to _nullEvt before you exit your on event routine. You can do this as follows:
eventRecPtr&.evtNum% = _nullEvt
This will "fool" FutureBasic into thinking that the event was a null event, and the record will subsequently be ignored.

See Also:
on event; HandleEvents