Functions | |
void | Enable_Location_Events (const char *locater, const char *display, const char *action) |
void | Disable_Location_Events (const char *locater, const char *display, const char *action) |
void Enable_Location_Events | ( | const char * | locater, | |
const char * | display, | |||
const char * | action | |||
) |
Tells the system it should start gathering raw 2-D positions from the user.
locater | - Commonly "?locater". In general, a segment with an attached device driver that knows about a particular physical locater device, such as a mouse, tablet, or trackball. | |
display | - Commonly "?Picture". In general, a segment with an attached device driver that knows how to draw a hardware cursor on a display. | |
action | - Commonly "v". In general, a special string indicating the user action(s) that should initiate an event. See below for details. |
In order for location input to occur, you have to name the device you're interested in hearing from and the type of action you're interested in hearing about. You can also name a display to track a cursor on. Then you have to start looking for location events to occur.
The easiest way to do all this is to let one of the high-level "Get" routines do it for you. In the case of location events, the Get routine is Get_Location() . The main problem with the Get routines is that unexpected events are thrown away, so you can't gracefully allow for input from a keyboard and a locater simultaneously. Also you have no control over which locater device is picked, or which actions trigger the event.
If you want to do better, call Enable_Location_Events() directly to establish interest in a device and start it running. Then call Await_Event() to acquire new events. Finally call Show_Location() (or a related routine) to take a look at the events. When your program (or subsection of your program) is done with the device, it can call Disable_Location_Events() to restore operations to their previous state.
Different levels of your program can simultaneously have the same type of event-enable in effect. The system keeps a count of how many "enables" do not have a matching "disable" yet, and turns off the input only when this "enable count" reaches zero.
The choices for action are the same as for the selectability and consist of the following:
"v" (lowercase letter "v")---indicates the locater device just went from "no buttons pushed" to "at least one button pushed".
"^" (up-arrow or caret)---means the locater just went from "one or more buttons pushed" to "no buttons pushed".
"*" (asterisk)---means the location has changed, and one or more buttons are still pushed.
"O" (uppercase letter O)---means the location has changed, and there are still no buttons pushed.
More than one eligible action can be specified. For example, "O*" asks for all motion to be reported, no matter whether the buttons are up or down.
Display is the name of a display-device segment that should be used to display a cursor that moves in synch with locater. This function is optional---you may not have a screen at hand, or your screen may already be tracking a cursor coming from a different locater (only one cursor at a time is supported). Enable_Selection_Events() also connects locaters to screens. If you want to omit the cursor, specify display as a blank or zero-length string. The implementation of this feature is highly system-dependent---the cursor may or may not disappear.
When a source of input is finally turned off, any pending events originating from it are discarded from the event queue.
The definition of "v" and "*", and of "^" and "O", overlap slightly. When a locater button is first pressed, if neither "v" nor "*" is enabled, no event will be reported. If "v" events are enabled and "*" events are either enabled or disabled, a "v" event will be reported. Finally if "*" events are enabled and "v" events are disabled, a "*" event will be reported. The "^" and "O" choices work similarly.
The system does not guarantee that an "up" event will always be available between "down" events, although this will generally be the case. The exception occurs if the event queue overflows or if the user slides out of the main HOOPS window when running under a windowing system.
Location events and Selection events can be enabled on the same locater simultaneously. Both events will be queued---which will be first is left up to the system.
On the extended DOS platform, exiting a window with a mouse button depressed generates an event. This limitation can lead to multiple selections with a single click.
void Disable_Location_Events | ( | const char * | locater, | |
const char * | display, | |||
const char * | action | |||
) |
Disables mouse or other pointer events.
locater | - Commonly "?locater". In general, a segment with an attached device driver that knows about a particular physical locater device, such as a mouse, tablet, or trackball. | |
display | - Commonly "?Picture". In general, a segment with an attached device driver that knows how to draw a hardware cursor on a display. | |
action | - Commonly "v". In general, a special string indicating the user action(s) that should initiate an event. See below for details. |