Functions | |
void | Queue_Related_Selection (const char *pathname, HC_KEY key, int offset1, int offset2, int offset3, double xw, double yw, double zw, double xc, double yc, double zc) |
void Queue_Related_Selection | ( | const char * | pathname, | |
HC_KEY | key, | |||
int | offset1, | |||
int | offset2, | |||
int | 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.
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. |
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.
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.