VisContent: 1.4 VisContent Instance Data: Fields That Affect Input Events

1.3 Fields That Affect the Document | Next:

One of the main features of VisContentClass is its ability to handle, manage, and pass on input events sent through the GenView. The content has a large amount of functionality built into it to provide these features.

Mouse and Keyboard Grabs

VCNI_prePassiveMouseGrabList, VCNI_impliedMouseGrab, VCNI_activeMouseGrab, VCNI_postPassiveMouseGrabList, VCNI_kbdGrab, MSG_VIS_CONTENT_UNWANTED_MOUSE_EVENT, MSG_VIS_CONTENT_UNWANTED_KBD_EVENT, MSG_VIS_CONTENT_TEST_IF_ACTIVE_OR_IMPLIED_WIN

VisContentClass , as the head of the visible tree displayed in the view, keeps track of which object in its tree has each different type of input grab. With this information, the content can simply pass the input event directly to the object that has the grab. It can also easily send the event to both the prepassive and postpassive grab objects, if any.

VCNI_prePassiveMouseGrabList: This field is a pointer to a chunkarray containing the list of objects that currently have the prepassive mouse grab.
VCNI_impliedMouseGrab: This field is a VisMouseGrab (described below) structure that contains details about the object which has the implied mouse grab.
VCNI_activeMouseGrab: This field is a VisMouseGrab (described below) structure that contains details about the object which has the active mouse grab.
VCNI_postPassiveMouseGrabList: This field is a pointer to a chunkarray containing the list of objects that currently have the postpassive mouse grab.
VCNI_kbdGrab: This field is a KbdGrab structure that contains details about the object which currently has the keyboard grab.

You will probably not ever have to know the structure of these fields, how to set them, or the information they contain. However the two structures VisMouseGrab and KbdGrab are shown in Grab Data Structures for your information.

Code Display 17-2 Grab Data Structures

/* These structures are obscure, and you will likely never have to use them. */

  /* The VisMouseGrab structure contains information about the object that
 * currently has the mouse grab. */

typedef struct {
    optr		VMG_object;		/* The optr of the object that has the grab.
				 * If no object has the grab, this is zero. */
    WindowHandle		VMG_gWin;		/* The window handle of the window with the object
				 * having the grab, if it's different from
				 * the content's window. If it's in the content's
				 * window, this field contains zero.	*/
    PointDWord		VMG_translation;		/* The 32-bit translation applied to mouse events
				 * if the large document model is in use. This is
				 * set with a previous message call. */
    VisInputFlowGrabFlags VMG_flags; /* A record of VisInputFlowGrabFlags,
				   * described below. */
    byte		VMG_unused;		/* Reserved byte. */
} VisMouseGrab;

/* The VisInputFlowGrabFlags determine the type and context of the grab. These
 * flags are not listed here for simplicity. You do not have to know these flags;
 * they are set with MSG_VIS_VUP_ALTER_INPUT_FLOW. */

  /* The KbdGrab structure contains information about the object that currently
 * has the keyboard grab. */

typedef struct {
    optr		KG_OD;		/* The optr of the object that has the
				 * keyboard grab. */
    word		KG_unused;		/* Reserved word. */
} KbdGrab;

In addition, the VisContent has the following messages that are affected by the input grab fields:

MSG_VIS_CONTENT_TEST_IF_ACTIVE_OR_IMPLIED_WIN: This message returns true if the passed window handle is the same as the active or implied window currently translating mouse events. It returns false otherwise. This is used by specific UI objects.
MSG_VIS_CONTENT_UNWANTED_MOUSE_EVENT: This message is sent by the content to itself if a mouse event has arrived and there is no implied or active grab in the content's visible tree. The default reaction is to beep if the event is a button press. It's highly unlikely that you'll send or intercept this message.
MSG_VIS_CONTENT_UNWANTED_KBD_EVENT: This message is sent by the content to itself if a keyboard event has arrived and there is no keyboard grab set up. It is highly unlikely that you will ever send or intercept this message.

MSG_VIS_CONTENT_TEST_IF_ACTIVE_OR_IMPLIED_WIN

Boolean	MSG_VIS_CONTENT_TEST_IF_ACTIVE_OR_IMPLIED_WIN(
        WindowHandle window);

This message checks to see if the passed window handle is the same as the window of the object having either the implied or active mouse grab. This is typically used by objects in a Specific UI library to determine if the mouse event was actually within the window or directly on the window's border.

Source: Unrestricted.

Destination: Any VisContent object.

Parameters: window The window handle to be checked.

Return: True if the window handle is the same as either the active or the implied window, false otherwise.

Interception: Unlikely.

MSG_VIS_CONTENT_UNWANTED_MOUSE_EVENT

void	MSG_VIS_CONTENT_UNWANTED_MOUSE_EVENT(
        VisMouseGrab *mouseGrab,
        word	inputState);

This message is received by the content if a mouse event was received and there was no active or implied grab. This is most frequently encountered when the user presses a mouse button outside a modal dialog box. The default action of this handler is to beep (on presses only, not releases) and get rid of the event as if it had been handled.

Source: Input flow mechanism.

Destination: The affected VisContent object.

Parameters: mouseGrab A pointer to the appropriate VisMouseGrab structure.

inputState: Same as passed with the actual event.

Return: Nothing.

Interception: Unlikely.

MSG_VIS_CONTENT_NOTIFY_ACTIVE_MOUSE_GRAB_WIN_CHANGED

void 	MSG_VIS_CONTENT_NOTIFY_ACTIVE_MOUSE_GRAB_WIN_CHANGED();

A message we send ourselves from within our MSG_VIS_VUP_ALTER_INPUT_FLOW handler in the case that VCNI_activeMouseGrab .VMG_gWin changes. Used by the specific UI's implementation of GenApplicationClass to keep track of the currently active window within the application.

Source: See above.

Destination: Self.

Parameters: None

Return: Nothing.

Interception: Intercepted by specific UI's implementation of GenApplication for the purpose of finding out a change in the active window within the application has occurred. It will in turn update the window system so that mouse grabs and pointer image changes work properly.

MSG_VIS_CONTENT_UNWANTED_KBD_EVENT

void	MSG_VIS_CONTENT_UNWANTED_KBD_EVENT(
        word	character,
        word	flags,
        word	state);

This message will be received by the content if a keyboard event was sent and there was no keyboard grab set up. The default action of the content is to beep (on presses only, not releases) and return as if the event had been processed.

Source: Input flow mechanism.

Destination: The affected VisContent object.

Parameters: character The keyboard character pressed.

flags: A word of flags: The low byte is a CharFlags record, and the high byte is a ShiftState record. Both are the same as passed with the original MSG_META_KBD_CHAR .
state: A word containing two values: The low byte is a record of ToggleState , and the high byte is the scan code. Both are the same as passed with the original MSG_META_KBD_CHAR .

Return: Nothing.

Interception: Unlikely.

Focus and Target

VCNI_focusExcl, VCNI_targetExcl, MSG_META_CONTENT_APPLY_DEFAULT_FOCUS

In addition to keeping track of which of its children have the mouse and keyboard grabs, the content also keeps track of which objects have the focus and target input exclusives. Both VCNI_focusExcl and VCNI_targetExcl contain a structure of type FTVMCGrab that describes the object that has the subject exclusive. The messages sent by the GenView that set these fields are described in Messages Received from the View .

Input Flow Control

VCNI_holdUpInputQueue, VCNI_holdUpInputCount, VCNI_holdUpInputFlags, MSG_VIS_CONTENT_HOLD_UP_INPUT_FLOW, MSG_VIS_CONTENT_RESUME_INPUT_FLOW, MSG_VIS_CONTENT_DISABLE_HOLD_UP, MSG_VIS_CONTENT_ENABLE_HOLD_UP

GEOS allows a visible tree to hold up input--that is, input will be stored elsewhere while the visible tree is doing something else. This can be useful if complex tree operations are going on and you don't want input to go to the wrong object.

VisContentClass provides three instance fields that define the input holdup mechanism. These three fields are

VCNI_holdUpInputQueue: This field contains the queue handle of the queue where held-up input will be temporarily stored. Input events will go into this event queue until they are allowed to be handled again; then they will be sent to their proper recipients.
VCNI_holdUpInputCount: This field contains a count of the number of objects that have requested that input be held up. If this count is positive, input will be held up and input events will go into the hold-up queue.
VCNI_holdUpInputFlags: This field contains a record of flags which determine the state of the hold-up mechanism. The following two flags are allowed:
HUIF_FLUSHING_QUEUE: This flag indicates that the hold-up queue is currently being flushed.
HUIF_HOLD_UP_MODE_DISABLED: This flag forces input events to flow normally. It is used primarily by GEOS to ensure that the user can interact with a system-modal dialog box.

VisContentClass has four messages that it sends to itself to set the state of information hold-up. These messages are detailed below.

MSG_VIS_CONTENT_HOLD_UP_INPUT_FLOW

void	MSG_VIS_CONTENT_HOLD_UP_INPUT_FLOW();

This message increments the count in VCNI_holdUpInputCount . If this count is nonzero and HUIF_HOLD_UP_MODE_DISABLED is clear, subsequent input events will be sent into the hold-up queue until either the flag is set or the count once more drops to zero.

Source: Unrestricted.

Destination: Any VisContent object.

Interception: Unlikely.

Warnings: Do not forget to resume input with a later use of the message MSG_VIS_CONTENT_RESUME_INPUT_FLOW .

MSG_VIS_CONTENT_RESUME_INPUT_FLOW

void	MSG_VIS_CONTENT_RESUME_INPUT_FLOW();

This message decrements the count in VCNI_holdUpInputCount . If the count becomes zero with this call, the hold-up event queue is flushed and all the events in it are "played back." If the count goes below zero, GEOS will give an error. Therefore, do not use this message unless it is preceded with a MSG_VIS_CONTENT_HOLD_UP_INPUT_FLOW .

Source: Unrestricted.

Destination: Any VisContent object.

Interception: Unlikely.

Warnings: If this message is used without first holding up input with MSG_VIS_CONTENT_HOLD_UP_INPUT_FLOW , an error will be the likely result. The error condition is the VCNI_holdUpInputCount field going below zero.

MSG_VIS_CONTENT_DISABLE_HOLD_UP

void	MSG_VIS_CONTENT_DISABLE_HOLD_UP();

This message sets the HUIF_HOLD_UP_MODE_DISABLED flag, forcing all input events to flow normally until the flag is cleared. In essence, it turns off the hold-up mechanism.

Source: Unrestricted.

Destination: Any VisContent object.

Interception: Unlikely.

MSG_VIS_CONTENT_ENABLE_HOLD_UP

void	MSG_VIS_CONTENT_ENABLE_HOLD_UP();

This message clears the HUIF_HOLD_UP_MODE_DISABLED flag, allowing input events to be held up in the hold-up event queue.

Source: Unrestricted.

Destination: Any VisContent object.

Interception: Unlikely.

GEOS SDK TechDocs |

1.3 Fields That Affect the Document | Next:

2 Basic VisContent Usage