Brief Index      Full Index      Events Index      I.M. Reference

Queue_String_Event

Functions

void Queue_String_Event (const char *keyboard, const char *string, HC_KEY cursor_key)
 

Detailed Description

Function Documentation

void Queue_String_Event ( const char *  keyboard,
const char *  string,
HC_KEY  cursor_key 
)

Allows you to insert events into the event queue exactly as if they were coming from a physical input device.

Parameters
keyboardThe segment that represents the nominal source of the event. Usually "?Keyboard".
stringThe string nominally acquired by the String Event.
cursor_keyThe key of the cursor being used for string echoing.

DETAILS

The "Queue" routines are the opposite of the Await_Event() and Show_Input() routines: they allow you to place events into the queue of pending events. They do not compute anything, they simply place the specified information into the event queue ( see Compute_Selection() ).

These routines are most often used when HOOPS input has been disabled ("no input" Driver Option) and you are doing the system input calls yourself. The "event checker" system option might be useful in this context.

A second use is to get an event from the front of the queue to the back of the queue, perhaps to implement "spying" on the queue.

Lastly, explicit event queueing can be used to implement a simple event record-and-playback mechanism: every Await_Event() call during recording would need to be turned into an await-event-and-write-to-file, while every Await during playback would be a read-file-and-queue-event.

Queue_Related_Selection() is the complement of Find_Related_Selection(). To queue a selection with related selections you would first call Queue_Selection_Event() with the "best" selected item, and then you would call Queue_Related_Selection() repeatedly to add in information about the other not-as-good items.

NOTES

Locater, keyboard, and picture must all refer to valid enabled driver segments. If the appropriate event type is not enabled, a warning is given and nothing is queued. (If the event type is disabled later when the event reaches the front of the queue, Await_Event() will discard it.) If you don't want to enable input, use the "disable input" Driver Option before calling the Enable routines.

The events are guaranteed to come off the event queue in the same order you put them on the queue. System-generated events can only be interleaved at the times your program calls Check_For_Events() or Await_Event().

Considerable care is needed when implementing an event-playback: the values for key, the aspect ratio of the display, and any segment names that involve the translation of "?Picture" may change from one run of your program to the next.

The "Queue" routines have no side effects: Queue_Button_Event() does not cause the button to be added to an in-progress string event; Queue_Location_Event() does not implicitly check for a Selection.

The "event checker" System Option may be convenient for getting your queueing code called at appropriate intervals.

The argument list length for Queue_Selection_Event() is unfortunate.

The encoding you should use for string depends on the encoding of the text pointed to by cursor_key.

See Also
Compute_Selection, Find_Related_Selection, Queue_Special_Event, Requeue_Event, Check_For_Events, Define_System_Options, Set_Driver_Options

Brief Index      Full Index      Events Index      I.M. Reference