Functions | |
void | Queue_Selection_Event (const char *locater, const char *display, const char *action, int status, const char *pathname, HC_KEY key, double offset1, double offset2, double offset3, double xw, double yw, double zw, double xc, double yc, double zc) |
Allows you to insert events into the event queue exactly as if they were coming from a physical input device. More... | |
void Queue_Selection_Event | ( | const char * | locater, |
const char * | display, | ||
const char * | action, | ||
int | status, | ||
const char * | pathname, | ||
HC_KEY | key, | ||
double | offset1, | ||
double | offset2, | ||
double | offset3, | ||
double | xw, | ||
double | yw, | ||
double | zw, | ||
double | xc, | ||
double | yc, | ||
double | zc | ||
) |
Allows you to insert events into the event queue exactly as if they were coming from a physical input device.
locater | The segment that represents the nominal source of the event. Usually "?locater". |
display | The segment that represents the nominal display screen for the event. Usually "?Picture". |
action | The nominal button action: "v", "^", "*", or "O". |
status | The nominal button and shift-key status. |
pathname | The nominal selection segment, in the style of Show_Selection_Pathname(). |
key | The key of the selected geometry item, or, if a window is being selected, the key of the segment that has the window. |
offset1 | The x-offset within key, in the style of Show_Selection_Element(). |
offset2 | The y-offset within key, in the style of Show_Selection_Element(). |
offset3 | The z-offset within key, in the style of Show_Selection_Element(). |
xw | The window x-coordinate of the selection, in the range of -1 to +1. |
yw | The window y-coordinate of the selection, in the range of -1 to +1. |
zw | The window z-coordinate of the selection, in the range of -1 to +1. |
xc | The camera x-coordinate of the selection. Any value is accepted. |
yc | The camera y-coordinate of the selection. Any value is accepted. |
zc | The camera z-coordinate of the selection. Any value is accepted. |
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.
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.