|void||Await_Event (char *type)|
|Waits for the occurrence of a new event of any type. More...|
|void Await_Event||(||char *||type||)|
Waits for the occurrence of a new event of any type.
type - The type of the new current event—either "selection", "location", "string", "button", "wakeup", or "special". Note that the characters are lowercase. Passed by reference always. Returned to user.
An "event" is a piece of information that has recently arrived from outside your program. The information has been saved with other pending events, and is waiting for disposition. Typical events might include the user using a mouse to point to something on the screen, or a wakeup going off.
The "event queue" is the place within the system where the events are saved while waiting for disposition. The events are listed in the order in which they were received. The "front" of the queue is the oldest event, and the "back" of the queue is the newest.
The "current event" is the event most recently "dequeued" from the front of the event queue. Await_Event() is the routine that does the dequeuing. Once an event becomes "current", there are a variety of Show routines your program can use to look at it.
Await_Event() begins by discarding the old "current event", if there is one. If there are no events in the event queue, Await_Event() reproduces any changes you've made in the database on the screen. Then Await_Event() calls Update_Display() and waits for at least one event to appear. It removes the event at the front of the queue (i.e., the event that's been waiting the longest) and puts it where the various "Show" routines can find it. Finally Await_Event() returns the event type to your program. Your program is then expected to take a look at the event type, make whatever Show calls it needs to gather further information, take some action, and eventually call Await_Event() to repeat the cycle.
In comparison the Get routines provide a simplified interface between your program and the user. The Get routines include calling Await_Event() as one element in a larger series of actions. See the Get pages for details. If you want to be able to accommodate more than one type of event at a time, or if you want to exert finer control over the system, skip the Get routines and use Await_Event() and the necessary Show routines directly.
If the segment and/or item pointed to by a selection event was deleted or seriously modified (for example, set "invisible") in the time between recording and dequeuing the event, the event is discarded.