Input: 4.2 Pen Input and Ink: Ink Input Flow

When the Input Manager receives a Button event, it checks to see if that event should be treated as Ink input. It first holds up input, putting the Button event in the holdup queue, and then it queries the appropriate application with MSG_META_QUERY_IF_PRESS_IS_INK . Typically the application will pass the message down its object tree to the appropriate visible or generic object that should initially have received the Button event.

Determining if a Press Is Ink

It is up to the application or its visible object to determine whether the input should be treated as Ink. If you don't ever handle Ink, you do not need to do anything different. If any of your objects handles Ink, however, you should set up your GenView to pass Ink events on to its content. Depending how you set up your GenView, you may or may not have to write a handler for MSG_META_QUERY_IF_PRESS_IS_INK . The context and details of this message are described below.

To set up your GenView for passing Ink input, set the proper flag in its GVI_inkType

GVIT_PRESSES_ARE_NOT_INK: Objects running under this GenView never handle Ink input. This flag is set as the default. Your objects will not have to handle MSG_META_QUERY_IF_PRESS_IS_INK or MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK .
GVIT_PRESSES_ARE_INK: Objects running under this GenView always want Ink input. Your objects will not have to handle the message MSG_META_QUERY_IF_PRESS_IS_INK , but they will have to handle MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK .
GVIT_INK_WITH_STANDARD_OVERRIDE: Objects running under this GenView want Ink, but the user can override it to give mouse events. Your objects will not have to handle MSG_META_QUERY_IF_PRESS_IS_INK , but they will have to handle MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK .
GVIT_QUERY_OUTPUT: The Objects running under this GenView want Ink input, but only under certain circumstances. Your objects will have to handle both MSG_META_QUERY_IF_PRESS_IS_INK and MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK . Note that this option may cause the UI to query across threads, something that could cause performance lags on a busy system. Therefore, whenever possible, you should set one of the other three flags.

Depending on how you set up your GenView, you may need to subclass MSG_META_QUERY_IF_PRESS_IS_INK (see above). This message is sent by the Input Manager to see if the object clicked on can handle Ink input. Objects that handle Ink should return IRV_DESIRES_INK. (There is an analogous MSG_META_LARGE_QUERY_IF_PRESS_IS_INK for objects and contents using large documents.)

If the application sends the query message to a Process object acting as a view's content, the Process object should not return a value. Instead, it should respond by sending MSG_GEN_APPLICATION_INK_QUERY_REPLY to its GenApplication object; the application object will then pass the appropriate value on to the Input Manager.

Some objects may want both Ink and mouse input; the VisText object is a good example of this--it accepts Ink for handwriting recognition and mouse events for cursor movement and text selection. GEOS uses a convention for objects that want both types of input: quick-clicks and click-and-holds in the object are mouse events, but click-and-drags are Ink events.

To use both pen and mouse input, your object should return IRV_INK_WITH_STANDARD_OVERRIDE instead of IRV_DESIRES_INK in its MSG_META_QUERY_IF_PRESS_IS_INK handler. (Or if all objects running in the same GenView want this behavior, you can simply set the GenView's GVIT_INK_WITH_STANDARD_OVERRIDE flag.)

Controlling the Ink

When an object requests Ink input by returning IRV_DESIRES_INK or IRV_INK_WITH_STANDARD_OVERRIDE, it must also specify the eventual destination of the Ink data block. Additionally, it can set any characteristics in a GState for the Ink--clipping area, drawing color, etc.

These specifics are set in an InkDestinationInfo structure set up by your MSG_META_QUERY_IF_PRESS_IS_INK handler (through a call to UserCreateInkDestinationInfo() ); the handler for the routine returns the handle of a block containing the structure. Certain default values and behavior are implemented if you return a null handle or if you set the GenView flags to avoid the query (GVIT_PRESSES_ARE_INK or GVIT_INK_WITH_STANDARD_OVERRIDE).

If you choose not to set any of these specifics, Ink will have the following default behaviors:

The destination of the Ink will be the object that would have received the initial click event (typically the implied mouse grab) or the object that fielded the MSG_META_QUERY_IF_PRESS_IS_INK .
The Ink will not be clipped; the user may draw over the entire screen, overlapping generic objects and other windows. (All the Ink will still be sent to the same destination, however.)
The Ink will be drawn in a standard color and brush thickness.

All of the above behavior can be changed in the InkDestinationInfo structure. The structure should be created automatically with the routine UserCreateInkDestinationInfo() ; you can then pass the block handle of this structure blindly to routines that demand an InkDestinationInfo structure. Among the four fields of the structure, the following need to be passed toUserCreateInkDestinationInfo() :

dest: The optr of the object that will receive the Ink data block after all the Ink has been collected. An object may use this field to force the destination of the Ink to be any particular object.
gs: The handle of a Graphic State (GState) containing clipping, color, or other information about how the Ink should be drawn on the screen. To use the default values, set this to zero. This will allow the user to draw Ink all over the screen. See the Graphics Environment chapter for full information on GStates.
brushSize: The thickness of the brush used when drawing the Ink on the screen. This is the same as the brush thickness for polylines; see the Drawing Shapes chapter for more information on brush thickness.
callback: Virtual fptr to a callback routine to determine whether a stroke is a gesture or not. This callback routine will be passed to ProcCallFixedOrMovable() .

How Ink Is Stored and Passed On

When the user presses the pen to the screen and the input is determined to be Ink, the Input Manager generates a mouse button press event and begins storing up the subsequent mouse events. The UI then determines whether that press event should be treated as Ink or not (the default behavior is to treat them as normal mouse events).

If the events should not be treated as Ink, they are passed on as normal mouse events. If they are to be treated as Ink, they are stored and are not passed on. Instead, the UI stores them up in a special data block until the Ink input is stopped. Ink input is stopped when the user removes the pen from the screen for a user-specified amount of time. This amount of time is specified in the GEOS.INI file in the [system] category under the key inkTimeout .

After the user finishes entering the Ink input, the Input Manager determines which object will receive the data block (it may not be the original object that received the initial press). It first queries the original object with MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK . Any object handling Ink input must subclass this message and make sure that the top Ink point is not above its upper bound; it should then return its upper bound and its optr. GEOS provides a routine that does just this; if your object will always handle Ink input, you can set this routine up as the method to be used as follows:

@method VisObjectHandlesInkReply, YourClassName,
                MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK;

If the object handles Ink, the Input Manager sends the entire data block off to the GenSystem object using MSG_META_NOTIFY_WITH_DATA_BLOCK with the identifier NT_INK. (For information on this and other notification messages, see the General Change Notification chapter.)

GEOS SDK TechDocs |

4.1 Ink Data Structures | Next:

5 Input Hierarchies