Reading Events from the Event Queue

To read events from the global event queue, call the function evnt_get()::

int evnt_get(eventp)

EVENTPTR eventp;        /* Pointer to event structure to hold event     */

You should pass a pointer to a previously allocated event structure (of type EVENTPTR) to evnt_get(). evnt_get() fills this structure with the values for the current event, if one is available. The function returns a 1 if an event is available, and a 0 if there is no event to get.

evnt_get() first checks the global event queue for a posted event. If an event is available, the information about the event is transferred into the event structure passed to evnt_get(), and the event is removed from the queue. If no event is available, evnt_get() then checks the keyboard buffer to see if a keystroke is available. If so, it fills the event structure with information about the keystroke, and uses AC_KEYPRESS for the event type. If no event is available from either the event queue or the keyboard buffer, evnt_get() fills the event structure with a NULL_EVENT and returns a 0.

If evnt_get() reads a key from the keyboard buffer, it calls the key filter function, if one is installed. Processing of the key filter function is the same, whether ki() or evnt_get() calls the function: if the key filter function returns a 0, evnt_get() fills the event structure with a NULL_EVENT and returns a 0, indicating that no event was available; if the key filter function returns a non-zero value, evnt_get() uses this value as the value of the keystroke to return.

However, because evnt_get() does not wait for user input, it does not call the keyloop function. If you are calling evnt_get() directly in your code, and you want the keyloop function to be called, you must check the event type returned by evnt_get() and call the keyloop function directly. To mirror the way Vermont Views handles keyloop functions, you would need to call the keyloop function in the following manner:

• nThe first time evnt_get() returns a NULL_EVENT, you call the keyloop function and pass it the value KL_INIT. Note that if evnt_get() returns an event the first time you call it, the keyloop function may not be called at all.
  
  
• nFor each subsequent time that evnt_get() returns a NULL_EVENT, you call the keyloop function and pass it the value KL_WAIT.
  
  
• nWhen evnt_get() returns an actual event, you should check the type of the event. If the type is AC_KEYPRESS, the user has pressed a key. You then call the keyloop function and pass it the value KL_DONE. If the event type is not AC_KEYPRESS, you should probably pass the keyloop function a value of KL_WAIT and continue waiting for a keystroke; however, this may be dependent on your application.

Keep in mind that a keyloop function is guaranteed to be called at least twice: once with a value of KL_INIT and once with a value of KL_DONE. If you are calling the keyloop function directly, you should observe this convention. For more information about keyloop functions, see Chapter 40, "Writing Keyloop, Key Filter and Abort Functions."