GEOS SDK TechDocs
|
| 
3.2 Input Messages
| 
3.4 Standard GCN Messages
The User Interface generates many messages which may alert objects to events which will allow them to work with the user. These events include those generated from the actions of input devices and clipboard-related events.
The following messages are used to implement common clipboard functions.
@importMessage MetaUIMessages, void MSG_META_CLIPBOARD_CUT();
This message is sent to an object which is supposed to be the destination of a clipboard operation.
MSG_META_CLIPBOARD_CUT
should register the current selection with the UI as the new clipboard item, but also delete the current selection.
Source: Sent by anyone to perform clipboard operation.
Destination: Object which will support clipboard operations. By default, a GenEditControl sends this message to the targeted object.
Interception: May be intercepted to add clipboard support to existing class that doesn't currently have clipboard support or to enhance or replace functionality of object that does support the clipboard.
Parameters: None.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_CLIPBOARD_COPY();
This message is sent to an object which is supposed to be the destination of a clipboard operation.
MSG_META_CLIPBOARD_COPY
should be handled by registering the current selection with UI as the new clipboard item.
Source: Sent by anyone to perform clipboard operation.
Destination: Object which will support clipboard operations. By default, a GenEditControl sends this message to the targeted object.
Interception: May be intercepted to add clipboard support to existing class that doesn't currently have clipboard support or to enhance or replace functionality of object that does support the clipboard.
Parameters: None.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_CLIPBOARD_PASTE();
This message is sent to an object which is supposed to be the destination of a clipboard operation.
MSG_META_CLIPBOARD_PASTE
should replace the current selection with the current clipboard item, which can be obtained from the UI.
Source: Sent by anyone to perform clipboard operation.
Destination: Object which will support clipboard operations. By default, a GenEditControl sends this message to the targeted object.
Interception: May be intercepted to add clipboard support to existing class that doesn't currently have clipboard support or to enhance or replace functionality of object that does support the clipboard.
Parameters: None.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_FEEDBACK(
ClipboardQuickNotifyFlags flags);
This message is sent to the source of a quick transfer item when a potential destination provides feedback to the user indicating whether a move, a copy or no operation will occur. The default behavior is determined by the destination, but the user may be able to override with the MOVE or COPY override keys.
Source: Sent by quick-transfer mechanism.
Destination: Sent to optr passed to
ClipboardStartQuickTransfer()
. Handled if the quick-transfer source needs to know what quick-transfer operation a potential destination will perform. Handler need not call superclass.
Interception: Message sent directly to destination, no need to intercept.
Parameters: flags Quick transfer cursor action specified by source (see
ClipboardSetQuickTransferFeedback()
).
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_FEEDBACK(
ClipboardQuickNotifyFlags flags);
This message is sent to the source of a quick transfer item when the operation is completed. The
ClipboardQuickNotifyFlags
are set by any
MSG_META_END_MOVE_COPY
handler. This is only sent out if the source requests notification with the CQTF_NOTIFICATION flag passed to
ClipboardStartQuickTransfer()
.
Source: Sent by quick-transfer mechanism.
Destination: Sent to optr passed to
ClipboardStartQuickTransfer()
. Handled if the quick-transfer source needs to know what quick-transfer operation was performed. Handler need not call superclass.
Interception: Message sent directly to source of transfer; no need to intercept.
Parameters: flags Quick transfer cursor action specified by source (see
ClipboardSetQuickTransferFeedback()
).
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_CLIPBOARD_NOTIFY_TRANSFER_ITEM_FREED(
VMFileHandle itemFile,
VMBlockHandle itemBlock);
Sent to all ODs in Transfer Notify List to help maintain integrity of transfer items from VM files other than the UI's transfer VM file. Only sent if VM file handle of transfer item that is being freed is different from UI's transfer VM file handle. If a transfer item from a VM file other than the UI's transfer VM file is registered, the VM blocks in that transfer item cannot be freed and the VM file cannot be closed until notification is sent saying that the transfer item has been freed. Registrars of such transfer items should keep track of the VM file handle and VM block handle of the item to check against the info sent by this message.
Source: Sent by the clipboard mechanism.
Destination: Sent to optrs on transfer notification list, added with
ClipboardAddToNotificationList()
. Handled if clipboard changes need to be monitored.
Interception: Unlikely.
Parameters: itemFile File containing the transfer item.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_CLIPBOARD_NOTIFY_NORMAL_TRANSFER_ITEM_CHANGED();
Sent to all ODs in Transfer Notify List to help with updating of Cut, Copy, and Paste button states. Recipients can call
ClipboardQueryItem()
to check if the new normal transfer item contains formats that the recipient supports. If not, Paste button can be disabled.
Source: Sent by the clipboard mechanism, relayed by GenEditControl.
Destination: Sent to optrs on transfer notification list, added with
ClipboardAddToNotificationList()
. Handled if clipboard changes need to be monitored.
Interception: Unlikely.
Parameters: None.
Return: Nothing.
These messages implement the "undo" mechanism which allows objects to store a chain of actions which can later be undone.
@importMessage MetaUIMessages, void MSG_META_UNDO(
AddUndoActionStruct *data);
This message is sent to an object which is supposed to be the destination of a clipboard operation.
Source: Sent by anyone to perform clipboard operation.
Destination: Object which will support clipboard operations. By default, a GenEditControl sends this message to the targeted object.
Interception: May be intercepted to add clipboard support to existing class that doesn't currently have clipboard support or to enhance or replace functionality of object that does support the clipboard.
Parameters: None.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_UNDO_FREEING_ACTION(
AddUndoActionStruct *data);
This message is sent to an object which is supposed to be the destination of a clipboard operation. This message is used to undo those actions which may free an important block of memory.
Source: Sent by anyone to perform clipboard operation.
Destination: Object which will support clipboard operations. By default, a GenEditControl sends this message to the targeted object.
Interception: May be intercepted to add clipboard support to existing class that doesn't currently have clipboard support or to enhance or replace functionality of object that does support the clipboard.
Parameters: None.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_SELECT_ALL();
This message is sent to an object which is supposed to be the destination of a clipboard operation.
Source: Sent by anyone to perform clipboard operation.
Destination: Object which will support clipboard operations. By default, a GenEditControl sends this message to the targeted object.
Interception: May be intercepted to add clipboard support to existing class that doesn't currently have clipboard support or to enhance or replace functionality of object that does support the clipboard.
Parameters: None.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_DELETE();
This message is sent to an object which is supposed to be the destination of a clipboard operation.
Source: Sent by anyone to perform clipboard operation.
Destination: Object which will support clipboard operations. By default, a GenEditControl sends this message to the targeted object.
Interception: May be intercepted to add clipboard support to existing class that doesn't currently have clipboard support or to enhance or replace functionality of object that does support the clipboard.
Parameters: None.
Return: Nothing.
These are perhaps the most often intercepted messages, allowing objects to detect input events.
@importMessage MetaUIMessages, void MSG_META_GAINED_MOUSE_EXCL();
The object will receive this message when it has received the mouse exclusive.
@importMessage MetaUIMessages, void MSG_META_LOST_MOUSE_EXCL();
The object will receive this message when it has lost the mouse exclusive.
@importMessage MetaUIMessages, void MSG_META_GAINED_KBD_EXCL();
The object will receive this message when it has received the keyboard exclusive.
@importMessage MetaUIMessages, void MSG_META_LOST_KBD_EXCL();
The object will receive this message when it has lost the keyboard exclusive.
@importMessage MetaUIMessages, void MSG_META_GAINED_PRESSURE_EXCL();
The object will receive this message when it has received the pressure exclusive, meaning it will get certain low-level mouse events.
@importMessage MetaUIMessages, void MSG_META_LOST_PRESSURE_EXCL();
The object will receive this message when it has lost the pressure exclusive.
@importMessage MetaUIMessages, void MSG_META_GAINED_DIRECTION_EXCL();
The object will receive this message when it has received the direction exclusive, meaning it will get certain low-level mouse events.
@importMessage MetaUIMessages, void MSG_META_LOST_DIRECTION_EXCL();
The object will receive this message when it has lost the direction exclusive.
These messages allow object to detect changes in the makeup of the three hierarchies which affect the paths of input and actions within the system: the Focus, Target, and Model hierarchies. These hierarchies are discussed in the Input chapter.
@importMessage MetaUIMessages, void MSG_META_GRAB_FOCUS_EXCL();
May be passed to any visible or generic object to cause it to become the active focus within its focus level. The leaf object in the hierarchy which gains the focus exclusive will automatically be given the keyboard exclusive, and will thereby receive
MSG_META_KBD_CHAR
events that follow.
Commonly sent to text objects and other gadgets to switch the current focus. May also be passed to GenPrimarys, GenDisplays, independently realizable GenInteractions, GenDisplayControl, GenViews, etc. (windowed things) to cause them to become the active focus window within their level of the focus hierarchy, if possible (specific UI's having real-estate focus, for instance, would ignore this request).
Note that the object will not actually gain the focus exclusive until all other nodes above it in the hierarchy also have the focus in their levels.
This is the message equivalent of HINT_DEFAULT_FOCUS on generic objects.
@importMessage MetaUIMessages, void MSG_META_RELEASE_FOCUS_EXCL();
Opposite of
MSG_META_GRAB_FOCUS_EXCL
. If the object does not currently have the exclusive, nothing will be done.
@importMessage MetaUIMessages, Boolean MSG_META_GET_FOCUS_EXCL(
optr *focusObject);
May be sent to any visible or generic object which is a focus node, to get current focus object directly below the node, if any, regardless of whether current node is active (has the exclusive itself).
Focus nodes in Generic UI library: GenSystem, GenField, GenApplication, GenPrimary, GenDisplayGroup, GenDisplay, GenView, GenInteraction (independently displayable only). Focus nodes in Visible UI library: VisContent.
Parameters: focusObject This will be filled with return value, the focus object below the object receiving the message.
Return: Will return true if message responded to. Will return false if the message was sent to an object which is not a focus node.
Warnings: This is a bad way to go about sending a message to currently active objects. For example, if you call from the application thread to the UI thread to find out which is the current focus gadget and then send a message to it, it is possible for the active gadget to change between the two calls. Use
MSG_META_SEND_CLASSED_EVENT
for this type of operation if at all possible.
@importMessage MetaUIMessages, void MSG_META_GRAB_TARGET_EXCL();
May be passed to any visible or generic object to cause it to become the active target within the target level that it is in. The active target hierarchy is the path for the transmission of messages via TO_TARGET request of
MSG_META_SEND_CLASSED_EVENT
.
Commonly sent to text objects and views to switch which is the current target. May also be passed to GenPrimarys, GenDisplays, independently realizable GenInteractions, GenDisplayControl, GenViews, etc. (windowed things) to cause them to become the active target window within their level f the target hierarchy.
The specific UI will automatically grab the Target exclusive for an object on any mouse press within the object if it is marked as GA_TARGETABLE.
Note that the object will not actually gain the target exclusive until all other nodes above it in the hierarchy also have the target exclusive within their levels. This is the message equivalent of HINT_DEFAULT_TARGET.
@importMessage MetaUIMessages, void MSG_META_RELEASE_TARGET_EXCL();
Opposite of
MSG_META_GRAB_TARGET_EXCL
. If the object does not currently have the exclusive, nothing will be done.
@importMessage MetaUIMessages, void MSG_META_GET_TARGET_EXCL(
optr targetObject);
May be sent to any visible or generic object which is a target node, to get the current target object directly below the node, if any, regardless of whether the current node is active (has the exclusive itself).
Target nodes in Generic UI library: GenSystem, GenField, GenApplication, GenPrimary, GenDisplay, GenView, GenInteraction (independently displayable only). Target nodes in Visible UI library: VisContent.
Parameters: targetObject This will be filled with return value, the target object below the object receiving the message.
Return: Will return true if message responded to. Will return false if the message was sent to an object which is not a target node.
Warnings: This is a bad way to go about sending a message to currently active objects. For example, if you call from the application thread to the UI thread to find out which is the current target display, and then send a message to it, it is possible for the active display to change between the two calls. Use MSG_META_SEND_CLASSED_EVENT for this type of operation if at all possible.
@importMessage MetaUIMessages, void MSG_META_GRAB_MODEL_EXCL();
May be passed to any visible or generic object to cause it to become the active model within the model level that it is in. The active model hierarchy is the override path for the transmission of messages via TO_MODEL of
MSG_META_SEND_CLASSED_EVENT
. (If no model hierarchy exists, the messages will be sent down the Target hierarchy.)
Note that the object will not actually gain the model exclusive until all other nodes above it in the hierarchy also have the model exclusive within their levels. This is the message equivalent of HINT_MAKE_DEFAULT_MODEL.
@importMessage MetaUIMessages, void MSG_META_RELEASE_MODEL_EXCL();
Opposite of
MSG_META_GRAB_MODEL_EXCL
. If the object does not currently have the exclusive, nothing will be done.
@importMessage MetaUIMessages, void MSG_META_GET_MODEL_EXCL(
optr targetObject);
May be sent to any visible or generic object which is a model node, to get current model object directly below the node, if any, regardless of whether current node is active (has the exclusive itself).
Model nodes in Generic UI library: GenSystem, GenApplication, GenDocumentControl, GenDocumentGroup.
Parameters: modelObject This will be filled with return value, the target object below the object receiving the message.
Return: Will return true if message responded to. Will return false if the message was sent to an object which is not a target node.
Warnings: This is a bad way to go about sending a message to currently active objects. For example, if you call from the application thread to the UI thread to find out which is the current model display, and then send a message to it, it is possible for the active display to change between the two calls. Use MSG_META_SEND_CLASSED_EVENT for this type of operation if at all possible.
@importMessage MetaUIMessages, void MSG_META_GAINED_FOCUS_EXCL();
See description for this and other gained/lost exclusive messages below.
Special note on
MSG_META_GAINED_FOCUS_EXCL
and
MSG_META_LOST_FOCUS_EXCL
: If the object receiving
MSG_META_GAINED_FOCUS_EXCL
is the leaf object in the hierarchy, meaning that it is either not a node itself, or if it is a node, does not have any object below it which has grabbed the exclusive, then the object will automatically be granted the
MSG_META_GAINED_KBD_EXCL
as well, and thereby receive any
MSG_META_KBD_CHAR
messages which are generated. The object will receive
MSG_META_LOST_KBD_EXCL
before MSG_META_LOST_FOCUS_EXCL.
@importMessage MetaUIMessages, void MSG_META_LOST_FOCUS_EXCL();
See description for this and other gained/lost exclusive messages below.
Special note on
MSG_META_GAINED_FOCUS_EXCL
and
MSG_META_LOST_FOCUS_EXCL
: If the object receiving
MSG_META_GAINED_FOCUS_EXCL
is the leaf object in the hierarchy, meaning that it is either not a node itself, or if it is a node, does not have any object below it which has grabbed the exclusive, then the object will automatically be granted the
MSG_META_GAINED_KBD_EXCL
as well, and thereby receive any
MSG_META_KBD_CHAR
messages which are generated. The object will receive
MSG_META_LOST_KBD_EXCL
before MSG_META_LOST_FOCUS_EXCL.
Tips and Tricks: If you intercept this message and call the superclass, be aware that the superclass' handler does some of the focus-releasing tasks by sending messages. This can lead to synchronization problems if your method's code looks like the following:
@callsuper(); call self::MSG_GEN_APPLY();
To make sure that the superclass is finished updating the focus before carrying out any operations which rely upon a valid focus, you would change the above code to read:
@callsuper(); @send ,forceQueue ,insertAtFront self::MSG_GEN_APPLY();
@importMessage MetaUIMessages, void MSG_META_GAINED_SYS_FOCUS_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_LOST_SYS_FOCUS_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_GAINED_TARGET_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_LOST_TARGET_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_GAINED_SYS_TARGET_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_LOST_SYS_TARGET_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_GAINED_MODEL_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_LOST_MODEL_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_GAINED_SYS_MODEL_EXCL();
See description for this and other gained/lost exclusive messages below.
@importMessage MetaUIMessages, void MSG_META_LOST_SYS_MODEL_EXCL();
These paired gained/lost messages for the Focus, Target, and Model hierarchies are sent, always in the order GAINED, then at some point LOST, to objects on the hierarchy. The GAINED message is sent only when the object in question and all nodes in the hierarchy above that object have gained the exclusive from the node above them, all the way up to the application object.
In other words, just grabbing the exclusive from the next node up doesn't always guarantee you'll get a GAINED message; the node you're grabbing from must have itself received a GAINED message but not yet the LOST message. Your object will receive the LOST message if it has either released the exclusive, or the node from which you grabbed the exclusive itself received a LOST message.
The GAINED_SYS and LOST_SYS messages behave similarly, except that an object can only gain the SYS_EXCL (System exclusive) if it and all nodes above it to the GenSystem object have the grab from the next node up. An object will never receive a GAINED_SYS_EXCL message if it has not already received an (Application) GAINED_EXCL message also. Similarly, an object will always receive a LOST_SYS_EXCL message before it receives an (Application) LOST_EXCL message.
Source: Do not send these messages to objects yourself, unless you are implementing or extending the above mechanism. These messages should be sent only by the node object which is above the object receiving the message.
Destination: Any
MetaClass
object which has grabbed and not yet released the focus exclusive.
Interception: Generic UI objects,
VisTextClass
, and all node objects provide default behavior for processing this message. If you intercept above any of these levels, be sure to call the superclass to let these objects know the exclusive has been gained.
@importMessage MetaUIMessages, void MSG_META_GRAB_KBD();
This message grabs the keyboard for an object. The grab will not be taken away from another object if it currently has the keyboard grab. To forcefully grab the keyboard in this case, use MSG_META_FORCE_GRAB_KBD.
@importMessage MetaUIMessages, void MSG_META_FORCE_GRAB_KBD();
This message forcefully grabs the keyboard for an object, tasking the grab away from another object, if necessary.
@importMessage MetaUIMessages, void MSG_META_RELEASE_KBD();
This message releases the keyboard grab for an object.
@importMessage MetaUIMessages, void MSG_META_RELEASE_FT_EXCL();
This message releases exclusive(s) that the object may have on the Focus and Target hierarchies.
@importMessage MetaUIMessages, void MSG_META_GAINED_DEFAULT_EXCL();
This message notifies a GenTrigger that it has gained the default exclusive.
@importMessage MetaUIMessages, void MSG_META_LOST_DEFAULT_EXCL();
This message notifies a GenTrigger that it has lost the default exclusive.
@importMessage MetaUIMessages, void MSG_META_GAINED_FULL_SCREEN_EXCL();
This message is sent to GenFields or GenApplications upon gain of the "full-screen" exclusive. The full-screen exclusive grants the object the top screen-dominating object at its level.
@importMessage MetaUIMessages, void MSG_META_LOST_FULL_SCREEN_EXCL();
This message is sent to GenFields or GenApplications upon loss of the "full-screen" exclusive. The full-screen exclusive grants the object the top screen-dominating object at its level.
@importMessage MetaUIMessages, void MSG_META_MOUSE_BUMP_NOTIFICATION(
sword xBump,
sword yBump);
This message is an event that the input manager places in the input queue to notify the UI that it has bumped the mouse position past this point in the queue. This method is sent only when
IMBumpMouse()
is called.
Parameters: xBump Horizontal relative bump.
@importMessage MetaUIMessages, Boolean MSG_META_FUP_KBD_CHAR(
word character,
word flags,
word state);
When a leaf object in the focus hierarchy gets a MSG_META_KBD_CHAR, and does not care about the character, it sends this message to itself to see if a parent object wants to handle it.
Parameters: character The low byte contains a
Char
value.
ShiftState
field; low byte is a
CharFlags
field.
ToggleState
field.Return: Will return true if the character was handled by someone (and should not be used elsewhere).
@importMessage MetaUIMessages, KbdReturnFlags MSG_META_PRE_PASSIVE_KBD_CHAR(
word character,
word flags,
word state);
This message sends a keyboard character to any object requesting preview of the keyboard events.
Parameters: character The low byte contains a
Char
value.
ShiftState
field; low byte is a
CharFlags
field.
ToggleState
field.Return: Flags field specifying what should happen to event.
Structures:
typedef WordFlags KbdReturnFlags;
#define KRF_PREVENT_PASS_THROUGH 0x8000 /* Set for passive keyboard routines if event should * be destroyed and not passed on to implied or * default grab. */
@importMessage MetaUIMessages, KbdReturnFlags MSG_META_POST_PASSIVE_KBD_CHAR(
word character,
word flags,
word state);
This message passes keyboard characters to all objects having registered interest in getting keyboard events after they have been handled.
Parameters: character The low byte contains a
Char
value.
ShiftState
field; low byte is a
CharFlags
field.
ToggleState
field.Return: Flags field specifying what should happen to event.
Structures:
typedef WordFlags KbdReturnFlags;
#define KRF_PREVENT_PASS_THROUGH 0x8000 /* Set for passive keyboard routines if event should * be destroyed and not passed on to implied or * default grab. */
@importMessage MetaUIMessages, void MSG_META_QUERY_IF_PRESS_IS_INK(
InkReturnParams *retVal,
sword xPosition,
sword yPosition);
Return whether or not a
MSG_META_START_SELECT
should be passed on to the object, or whether it should be intercepted and turned into ink.
Source: Sent by any object (usually VisComp) to determine if one of its children wants ink.
Destination: Any object in the Vis linkage that may be clicked on with the mouse.
Interception: The default handler returns IRV_NO_INK (filling in the
inkType
field of the
retVal
argument). Objects that want presses to be turned into ink need to return IRV_DESIRES_INK. Some objects that need to do work on another thread (such as a GenView) to determine whether the press should be ink or not can return IRV_WAIT, which holds up the
MSG_META_START_SELECT
until a
MSG_GEN_APPLICATION_INK_QUERY_REPLY
is sent to the application object. By default, clicks on VisComp-derived objects will
not
be ink. To change this, set
VisCompMakePressesInk()
as the handler for this message.
Parameters: retVal Empty structure which will be filled with return value information.
Return: Indication whether object thinks the press was ink.
@importMessage MetaUIMessages, void MSG_META_LARGE_QUERY_IF_PRESS_IS_INK(
InkReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
This message is sent by the system to children with the VCNA_LARGE_DOCUMENT_MODEL bit set to determines whether or not a MSG_META_LARGE_START_SELECT should be processed as ink.
Source: Sent by any object (usually VisComp) to determine if one of its children wants ink.
Destination: Any object in the Vis linkage that may be clicked on with the mouse.
Parameters:
retVal
Pointer to an
InkReturnParams
structure that will be filled in by the handler for this message.
LargeMouseData
struct that stores information about the large mouse event.
Interception: The default handler returns IRV_NO_INK. Objects that want presses to be turned into ink need to return IRV_DESIRES_INK. Some objects that need to do work on another thread (such as a VisContent) to determine whether the press should be ink or not can return IRV_WAIT, which holds up the
MSG_META_LARGE_START_SELECT
until a
MSG_GEN_APPLICATION_INK_QUERY_REPLY
is sent to the application object.
The following messages allow an application to detect the nature and behavior of pointing devices within the system.
@importMessage MetaUIMessages, void MSG_META_START_SELECT(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_END_SELECT(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_START_MOVE_COPY(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_END_MOVE_COPY(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_START_FEATURES(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_END_FEATURES(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_START_OTHER(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_END_OTHER(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_DRAG_SELECT(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_DRAG_MOVE_COPY(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_DRAG_FEATURES(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_DRAG_OTHER(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_BUTTON(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_BUTTON(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_START_SELECT(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_START_SELECT(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_END_SELECT(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_END_SELECT(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_START_MOVE_COPY(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_START_MOVE_COPY(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_END_MOVE_COPY(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_END_MOVE_COPY(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_START_FEATURES(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_START_FEATURES(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_END_FEATURES(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_END_FEATURES(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_START_OTHER(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_START_OTHER(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_PRE_PASSIVE_END_OTHER(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
For description of this and other button messages, see below.
@importMessage MetaUIMessages, void MSG_META_POST_PASSIVE_END_OTHER(
MouseReturnParams *retVal,
sword xPosition,
sword yPosition,
word inputState);
The above messages are the standard button functions generated by the UI upon receiving
MSG_META_BUTTON
events from the Input Manager. These messages are sent out to whatever object has the implied grab (whichever window the mouse is over), until the mouse is "grabbed" by an object, after which the messages go there until the mouse is released (ungrabbed).
Parameters: retVal Structure to hold return values.
UIFunctionsActive
structure; low byte is
ButtonInfo
structure.Structures:
typedef struct {
word unused;
MouseReturnFlags flags;
optr ptrImage;
} MouseReturnParams;
typedef WordFlags MouseReturnFlags; /* These flags may be combined using | and &: MRF_PROCESSED, MRF_REPLAY, MRF_PREVENT_PASS_THROUGH, MRF_SET_POINTER_IMAGE, MRF_CLEAR_POINTER_IMAGE */
@importMessage MetaUIMessages, void MSG_META_LARGE_PTR(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_START_SELECT(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_END_SELECT(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_START_MOVE_COPY(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_END_MOVE_COPY(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_START_FEATURES(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_END_FEATURES(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_START_OTHER(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_END_OTHER(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_DRAG_SELECT(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_DRAG_MOVE_COPY(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_DRAG_FEATURES(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
See below for information about this and other large mouse messages.
@importMessage MetaUIMessages, void MSG_META_LARGE_DRAG_OTHER(
MouseReturnParams *retVal,
LargeMouseData *largeMouseDataStruct);
Objects which have been set up with 32-bit coordinate spaces must be prepared to handle large mouse events along with regular mouse events.
These messages are available by request for use within 32-bit visible document models. Mouse position data is in full 32-bit integer, 16-bit fraction format, as generated by GenView.
Parameters: retVal Structure to hold return values.
Return: Nothing returned explicitly.
Structures:
typedef struct {
PointDWFixed LMD_location;
byte LMD_buttonInfo;
UIFunctionsActive LMD_uiFunctionsActive;
} LargeMouseData;
typedef struct {
word unused;
MouseReturnFlags flags;
optr ptrImage;
/* Pointer image to use, if MRF_SET_PTR_IMAGE
* returned */
} MouseReturnParams;
@importMessage MetaUIMessages, MouseReturnFlags MSG_META_ENSURE_MOUSE_NOT_ACTIVELY_TRESPASSING();
Sent to the passive, active, or implied mouse grab chain whenever modality status changes within the system--any object receiving this message which has a window grabbed should make sure that it has a legitimate right to have the window grab active--if not, it should be released (along with the mouse). In particular, menus in stay-up mode should come down, any interaction between the mouse and primary, display, menu, or view windows should be terminated.
MSG_GEN_APPLICATION_TEST_WIN_INTERACTABILITY
is useful; this message will test any passed OD against the list of window(s) which the mouse is allowed to interact with (Generally, top most system modal window, else top most application modal window, else all windows), and return a flag indicating the result.
Parameters: None.
Return: Flags field which system normally ignores.
@importMessage MetaUIMessages, MouseReturnFlags MSG_META_ENSURE_NO_MENUS_IN_STAY_UP_MODE();
Sent to the passive, active/implied mouse grab chain whenever we want to make sure all of an application's menus are closed. Sent directly to the Flow object from the global shortcut code. Any menus receiving this message which are in stay-up mode should dismiss themselves.
Parameters: None.
Return: Flags field, normally ignored by system.
@importMessage MetaUIMessages, void MSG_META_ENSURE_ACTIVE_FT();
Makes sure that some object with the Focus/Target node to which this message may be sent has the Focus and Target exclusives. Called from within the UI, usually when windowed objects below the node have closed, or moved to the back, to give the Focus and/or Target to the most suitable window.
Behavior as implemented in
GenApplicationClass
:
Checks to make sure that something within the application has the Focus and Target exclusives. Called from within the UI, usually on the closure of a window, to give the Focus and/or Target to the next best location.
Typical click-to-type model is implemented using the following rules:
For Target, the priority order is:
For Focus, priority goes to:
Source: Most always internally from the UI, though is unrestricted.
Destination: Focus/Target node, specifically: GenSystem, GenField, or GenApplication object.
Interception: No reason to intercept. Default behavior is provided by above objects. Could possibly be replaced, but as default behavior varies by specific UI, results could be unpredictable.
Parameters: None.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_NOTIFY_NO_FOCUS_WITHIN_NODE();
Notification from Focus node
MSG_META_ENSURE_ACTIVE_FT
handler that it was unable to keep/find an object below it suitable for being the focus. The most likely cause is that the last focusable geode/object running below this point has been shut down/closed.
Source: Focus node,
MSG_META_ENSURE_ACTIVE_FT
handler
Destination: Self
Interception: Intercepted to find something safe to do for the user, such as push this field/application to the back, or mark this object as no longer "focusable" and call
MSG_META_ENSURE_ACTIVE_FT
on the node above this one, in an attempt to find something for the user to access. If there's nothing left at all in the system, the last focusable application has exited, so it's time to shut down.
Parameters: None.
Return: Nothing.
@importMessage MetaUIMessages, void MSG_META_UI_FORCE_CONTROLLER_UPDATE(
ManufacturerID manufID,
word changeID);
This message forces an object to update one or all of the GCN notification lists that it communicates with.
Source: Usually sent by a controller to its output.
Destination: Any object.
Parameters:
manufID
ManufacturerID
of GCN lists.
Interception: Objects that send notification for controllers should respond to this message.
@importMessage MetaUIMessages, Boolean MSG_META_GEN_PATH_RESTORE_DISK_PROMPT(
DiskRestoreError *error,
GenPathDiskRestoreArgs *args);
This message prompts the user to insert a particular disk into a particular drive when restoring a disk handle for the object's path.
Source: Sent by the callback passed to
DiskRestore()
when a disk handle saved in an object's path is being restored after a shutdown.
Destination: Any object possessing a path.
Parameters:
error
Pointer to store an error code. This error code will be returned to
DiskRestore()
.
GenPathDiskRestoreArgs
.Structures:
typedef struct {
word GPDRA_pathType;
word GPDRA_savedDiskType;
char *GPDRA_driveName;
char *GPDRA_diskName;
DiskRestoreError GPDRA_errorCode;
} GenPathDiskRestoreArgs;
GPDRA_
pathType
stores the vardata tag holding the path.
GPDRA_
savedDiskType
stores the vardata tag holding the saved disk handle.
GPDRA_
driveName
and GPDRA_
diskName
store pointers to the null-terminated drive and disk names.
GPDRA_
errorCode
stores the error code that is returned to
DiskRestore()
.
Interception: May be intercepted if the object has more information to provide to the user, or if the object doesn't wish to prompt the user. If this message is intercepted, it should not call its superclass.
@importMessage MetaUIMessages, void MSG_META_PAGED_OBJECT_GOTO_PAGE(
word page);
This message instructs a GenDocument to go to the passed page.
This message is sent out by the GenPageControl object and is handled by a GenApplication's subclassed GenDocument object.
Source: GenPageControl object.
Destination: GenDocument object.
Parameters: page Page to set the GenDocument to display.
Interception: You may intercept to provide custom paging behavior.
@importMessage MetaUIMessages, void MSG_META_PAGED_OBJECT_NEXT_PAGE();
This message instructs a GenDocument to go to the next page.
This message is sent out by the GenPageControl object and is handled by a GenApplication's subclassed GenDocument object.
Source: GenPageControl object.
Destination: GenDocument object.
Interception: You may intercept to provide custom paging behavior.
@importMessage MetaUIMessages, void MSG_META_PAGED_OBJECT_PREVIOUS_PAGE();
This message instructs a GenDocument to go to the previous page.
This message is sent out by the GenPageControl object and is handled by a GenApplication's subclassed GenDocument object.
Source: GenPageControl object.
Destination: GenDocument object.
Interception: You may intercept to provide custom paging behavior.
@importMessage MetaUIMessages, void MSG_META_DELETE_RANGE_OF_CHARS(@stack
VisTextRange rangeToDelete);
This message instructs an object to delete a range of characters passed in a
VisTextRange
. Generally, this message is sent out when the user crosses out characters within a HWR grid.
Source: GenPenInputControl.
Destination: Any focused object.
Parameters:
rangeToDelete
VisTextRange
of characters to delete. Objects that are not text objects will need to know how to interpret this value.
Interception: May intercept to provide custom deletion behavior.
@importMessage MetaUIMessages, void MSG_META_NOTIFY_TASK_SELECTED();
This message is sent when a task list item of an application in the Express Menu is selected. The default behavior brings the application to the front and gives it the focus.
@importMessage MetaUIMessages, void MSG_META_FIELD_NOTIFY_DETACH(
optr field,
word shutdownFlag);
This message is sent by the GenField object when it is detaching.
Source: GenField.
Destination: The notification destination of the GenField object.
Parameters: field Optr of the GenField sending notification.
Interception: The object receiving notification may handle as desired. As this is a notification only, you should not call the superclass.
@importMessage MetaUIMessages, void MSG_META_FIELD_NOTIFY_NO_FOCUS(
optr field,
word shutdownFlag);
This message is sent by the GenField when it no longer has any applications in the focus hierarchy.
Source: GenField.
Destination: The notification destination of the GenField object.
Parameters: field Optr of the GenField sending notification.
Interception: The object receiving notification may handle as desired. As this is a notification only, you should not call the superclass.
@importMessage MetaUIMessages, void MSG_META_FIELD_NOTIFY_START_LAUNCHER_ERROR(
optr field);
This message is sent by the GenField when an error occurs while attempting to run the launcher for the field object.
Source: GenField.
Destination: The notification destination of the GenField object.
Parameters: field Optr of the GenField sending notification.
Interception: The object receiving notification may handle as desired. As this is a notification only, you should not call the superclass.
@importMessage MetaUIMessages, Boolean MSG_META_TEST_WIN_INTERACTIBILITY(
optr inputOD,
WindowHandle window);
This message checks whether a pointing device (usually a mouse) can interact with the passed window.
Source:
Destination: A windowed object.
Parameters: inputOD Input optr of the windowed object to check.
Return: true if window is interactable.
@importMessage MetaUIMessages, Boolean MSG_META_CHECK_IF_INTERACTIBLE_OBJECT(
optr obj);
This message is sent o objects on the GAGCNLT_ALWAYS_INTERACTABLE_WINDOWS GCN list.
Source: GenApplication object.
Destination: Objects on the GAGCNLT_ALWAYS_INTERACTABLE_WINDOWS GCN list.
Parameters: obj Object whose interactable state is being checked.
Return: true if object is interactable.
Interception: May intercept.
GEOS SDK TechDocs
|
| 3.2 Input Messages
| 3.4 Standard GCN Messages