Introduction

Getting Started

Programming Guides

API Reference

Additional Resources

Enable_Location_Events

Functions

void Disable_Location_Events (const char *locator, const char *display, const char *action)
 Disables mouse or other pointer events. More...
 
void Enable_Location_Events (const char *locator, const char *display, const char *action)
 Tells the system it should start gathering raw 2-D positions from the user. More...
 

Detailed Description

Function Documentation

void Disable_Location_Events ( const char *  locator,
const char *  display,
const char *  action 
)

Disables mouse or other pointer events.

Parameters
locator- Commonly "?locator". In general, a segment with an attached device driver that knows about a particular physical locator 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.

DETAILS

No additional details. See Enable_Location_Events()

void Enable_Location_Events ( const char *  locator,
const char *  display,
const char *  action 
)

Tells the system it should start gathering raw 2-D positions from the user.

Parameters
locator- Commonly "?locator". In general, a segment with an attached device driver that knows about a particular physical locator 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.

DETAILS

Location events are similar to Selection events. Location events return raw device coordinates. Selection events test the coordinates against the elements in a specified scene, and return the name of a window or piece of geometry. Typical HOOPS programs use Selections commonly, and Locations only rarely. Location events might be appropriate, for example, when you don't particularly care how a position relates to an existing picture—as when you're just entering map data from a large digitizing table, and there is no display device at all.

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 locator simultaneously. Also you have no control over which locator 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 locator device just went from "no buttons pushed" to "at least one button pushed".

"^" (up-arrow or caret)—means the locator 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 locator. 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 locator (only one cursor at a time is supported). Enable_Selection_Events() also connects locators 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.

NOTES

The Enable or Disable call does not take effect until the next call to Await_Event() or Check_For_Events() .

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 locator 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 locator simultaneously. Both events will be queued—which will be first is left up to the system.

RESTRICTIONS

Flagging enabled events causes confusion when a window with events enabled becomes invisible. The work around is to disable events before setting the visibility to off.

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.

See also
Get_Location, Show_Location, Await_Event, Flush_All_Events, Enable_Selection_Events, Enable_String_Events, Enable_Button_Events, Enable_Wakeup_Events.