Introduction

Getting Started

Programming Guides

API Reference

Additional Resources

Queue_Related_Selection

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)
 Allows you to insert events into the event queue exactly as if they were coming from a physical input device. More...
 

Detailed Description

Function Documentation

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.

Parameters
pathnameThe nominal selection segment, in the style of Show_Selection_Pathname().
keyThe key of the selected geometry item, or, if a window is being selected, the key of the segment that has the window.
offset1The x-offset within key, in the style of Show_Selection_Element().
offset2The y-offset within key, in the style of Show_Selection_Element().
offset3The z-offset within key, in the style of Show_Selection_Element().
xwThe window x-coordinate of the selection, in the range of -1 to +1.
ywThe window y-coordinate of the selection, in the range of -1 to +1.
zwThe window z-coordinate of the selection, in the range of -1 to +1.
xcThe camera x-coordinate of the selection. Any value is accepted.
ycThe camera y-coordinate of the selection. Any value is accepted.
zcThe camera z-coordinate of the selection. Any value is accepted.

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