Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                            The Event Dispatcher


Most GEM applications and all desk accessories rely on one of the AES
event processing calls to direct program flow. After program
initialization, an application enters a message loop which waits for and
reacts to messages sent by the AES. Five basic types of events are
generated by the AES and each can be read by a specialized event library
call as follows:

Event Type      AES Function

Message         evnt_mesag()

Mouse Button    evnt_button()

Keyboard        evnt_keybd()

Timer           evnt_timer()

Mouse Movement  evnt_mouse()

In addition to these five basic calls, the AES offers one multi-purpose
call which waits for any combination of the above events called
evnt_multi(). The evnt_multi() call is often the most important function
call in any GEM application. A typical message loop follows.

When an event library function is called, the program is effectively
halted until a message which is being waited for becomes available. Not
all applications will require all events so the above code may be
considered flexible.

Message Events

Each standard GEM message event (MU_MESAG) uses some or all of an 8 WORD
message buffer. Each entry in this buffer is assigned as follows:

msg[x]  Meaning

0       Message type.

1       The application identifier of the process sending the message.

2       The length of the message beyond 16 bytes (in bytes). For all
        standard GEM messages, this values is 0.

3       Depends on message.

4       Depends on message.

5       Depends on message.

6       Depends on message.

7       Depends on message.

The entry for evnt_mesag() later in this chapter has a comprehensive list
of all system messages and the action that should be taken when they are
received.

User-Defined Message Events

Applications may write customized messages to other applications (or
themselves) using appl_write(). The structure of the message buffer should
remain the same as shown above. If more than the standard eight WORDs of
data are sent, however, appl_read() must be used to read the additional
bytes. It is recommended that user-defined messages be set to a multiple
of 8 bytes.

You can use this method to send your own application standard messages by
filling in the message buffer appropriately and using appl_write(). This
method is often used to force redraw or window events.

Mouse Button Events

When a mouse button (MU_BUTTON) event happens, the evnt_button() or
evnt_multi() call is returned with the mouse coordinates, the number of
clicks that occurred, and the keyboard shift state.

Keyboard Events

Keyboard events (MU_KEYBD) are generated whenever a key is struck. The
IKBD scan code (see Appendix F: IKBD Scan Codes) and current key shift
state are returned by either evnt_keybd() or . If your application is
designed to run on machines in other countries, you might consider
translating the scan codes using the tables returned by the XBIOS call
Keytbl().

Timer Events

evnt_timer() or evnt_multi( MU_TIMER, ... ) can be used to request
a timer event(s) be scheduled in a certain number of milliseconds. The
time between the actual function call and the event may, however, be
greater than the time specified.

Mouse Rectangle Events

Mouse rectangle events (MU_M1 and/or MU_M2) are generated by evnt_mouse()
and evnt_multi() when the mouse pointer enters or leaves (depending on how
you program it) a specified rectangle.