Input: 2.2 Mouse Input: Gaining the Mouse Grab

When no object has the active mouse grab, mouse events are passed to whichever object is directly under the pointer's image. If any object has the grab, however, mouse events will be passed only to the object with the grab, no matter where the pointer is on the screen.

When the user clicks inside a view, the GenView automatically grabs the mouse while the user holds the mouse button down. This allows the view to know when drag scrolling takes place (the user drags the pointer outside the view's bounds, but the mouse event is still passed to the GenView). Process objects acting as a GenView's content therefore do not have to worry about grabbing the mouse. If you are displaying visible objects within the GenView, however, your objects will likely want to grab the mouse for themselves.

Typically, a visible object will grab the mouse on a MSG_META_START_... event and release it on a MSG_META_END_... event. To grab the mouse, a visible object has to send itself the message MSG_VIS_GRAB_MOUSE ; to release the grab, it must send itself MSG_VIS_RELEASE_MOUSE .

The TicTac sample application shows an example of visible objects grabbing the mouse and handling several mouse events. This sample application is described in detail in the UI Overview.

There are two other types of mouse grabs besides the active grab. With very rare exceptions, application programmers can ignore these. They are the pre-passive and post-passive grabs.

If an object has a pre-passive grab, it will receive copies of all Button events before the events are passed on to their true destinations. Pre-passive grabs are used by window objects to bring themselves to the front when the user clicks in them. Any number of objects may have pre-passive grabs. To gain a pre-passive grab, a visible object must send itself MSG_VIS_ADD_BUTTON_PRE_PASSIVE ; to release it, the object must send itself MSG_VIS_REMOVE_BUTTON_PRE_PASSIVE .

If an object has a post-passive grab, it will receive copies of all Button events after the events have been handled. Any number of objects may have post-passive grabs. To gain a post-passive grab, a visible object must send itself MSG_VIS_ADD_BUTTON_POST_PASSIVE ; to release the grab, the object must send itself MSG_VIS_REMOVE_BUTTON_POST_PASSIVE .

GEOS uses different messages to indicate that the event is a pre-passive or a post-passive event. All the normal Button events have pre-passive and post-passive counterparts which take the form MSG_META_PRE_PASSIVE_... and MSG_META_POST_PASSIVE_... . For example, the pre-passive version of MSG_META_START_SELECT is MSG_META_PRE_PASSIVE_START_SELECT .

Below are listed the pre-passive equivalents of the above messages. Note that the drag events and large events do not have pre-passive equivalents.

MSG_META_PRE_PASSIVE_START_SELECT: MSG_META_PRE_PASSIVE_END_SELECT MSG_META_PRE_PASSIVE_START_MOVE_COPY MSG_META_PRE_PASSIVE_END_MOVE_COPY MSG_META_PRE_PASSIVE_START_FEATURES MSG_META_PRE_PASSIVE_END_FEATURES MSG_META_PRE_PASSIVE_START_OTHER MSG_META_PRE_PASSIVE_END_OTHER

Listed below are the post-passive equivalents of the above messages. Note that the drag events and large events do not have post-passive equivalents.

MSG_META_POST_PASSIVE_START_SELECT: MSG_META_POST_PASSIVE_END_SELECT MSG_META_POST_PASSIVE_START_ADJUST MSG_META_POST_PASSIVE_END_MOVE_COPY MSG_META_POST_PASSIVE_START_FEATURES MSG_META_POST_PASSIVE_END_FEATURES MSG_META_POST_PASSIVE_START_OTHER MSG_META_POST_PASSIVE_END_OTHER

GEOS SDK TechDocs |

2.1 Mouse Events | Next:

2.3 Large Mouse Events