Item Hook Function Messages

The messageType field of a dialog item message determines the message's type. This section discusses each individual dialog item message, including any additional information. The following messages are listed in this section:

General Message	Sent
DITEM_MESSAGE_CREATE	After an item is created.
DITEM_MESSAGE_ALLCREATED	After all the items contained in the parent dialog box have been sent the DITEM_MESSAGE_CREATE message.
DITEM_MESSAGE_INIT	After an item is created, and after its internal value is initialized with the state of an underlying application variable.
DITEM_MESSAGE_DESTROY	When an item is about to be destroyed.
DITEM_MESSAGE_GETSTATE	When an item handler needs to determine an item's state.
DITEM_MESSAGE_SETSTATE	When an item handler needs to set an item's state.
DITEM_MESSAGE_QUEUECOMMAND	After the DITEM_MESSAGE_SETSTATE message if an item's internal value differed from its state.
DITEM_MESSAGE_SYNCHRONIZE	When an item's visible display and internal value is forced to match the item's external state.
DITEM_MESSAGE_STATECHANGED	When an item's state changes.
DITEM_MESSAGE_USER	To an item hook function with the mdlDialog_hookItemSendUserMsg function to send message from one item hook to another.
DITEM_MESSAGE_BUTTON	When a mouse button event occurs within a mouse-sensitive item.
DITEM_MESSAGE_JOURNALSTATE	When CAD input journaling is active and the internal state of an item has changed.
DITEM_MESSAGE_MOTION	When there is mouse motion into, within, and out of an item.
DITEM_MESSAGE_NOMOTION	When there is no mouse motion within an item.
DITEM_MESSAGE_STATECHANGING	Before the state of an item changes (only for Text SubEditor and Tree items).
DITEM_MESSAGE_RESETPREBUTTON	Before the processing of a Reset mouse click (only for ListBox and Tree items).
DITEM_MESSAGE_SCREENCHANGE	Before and after an application screen change.
DITEM_MESSAGE_REDIRECT
DITEM_MESSAGE_HIDE	When an item is being hidden.
DITEM_MESSAGE_OBSCURED	When an item is being obscured, e.g. when the Tab Page an is on is no longer the current page.
DITEM_MESSAGE_UNOBSCURED	When an item is being unobscured, e.g. when the Tab Page an item is on becomes the current tab page.
DITEM_MESSAGE_RELOADDATA	When an item needs to reload its data, e.g. from a ListModel or GuiTreeModel. See the mdlDialog_itemReloadData, mdlDialog_rItemReloadData and mdlDialog_synonymReloadData functions.
DITEM_MESSAGE_POPUP	To open or close the item's associated popup window.
DITEM_MESSAGE_POPUPCLOSED	To notify an item handler when its associated popup window is closed.
DITEM_MESSAGE_STYLECHANGED	When the style changes in the editor (HTML item only).

focusable Message	Sent
DITEM_MESSAGE_FOCUSIN	When an item gains the input focus.
DITEM_MESSAGE_FOCUSOUT	When an item will soon lose the input focus.
DITEM_MESSAGE_KEYSTROKE	When a key is pressed while the item has the input focus.
DITEM_MESSAGE_POSTKEYSTROKE	After the item handler's default keystroke handling processes a key.

Generic Message	Sent
DITEM_MESSAGE_SETLABEL	When the item's label needs to be changed.
DITEM_MESSAGE_GETVALUE	When the item's internal value is needed.
DITEM_MESSAGE_SETVALUE	When the item's internal value will be set.
DITEM_MESSAGE_DRAW	When the item should draw itself.
DITEM_MESSAGE_HIGHLIGHT	When the item needs to change its highlight state.
DITEM_MESSAGE_MOVE	When the item needs to be moved.
DITEM_MESSAGE_SETEXTENT	When the item size needs to be changed.
DITEM_MESSAGE_FONTCHANGED	When the dialog box is moved to a screen that uses a different font size than the previous screen.
DITEM_MESSAGE_SETENABLEDSTATE	When the item's enabled state is changed.
DITEM_MESSAGE_ACTIVATE	When the item is activated.

General item hook function messages

A dialog item message's messageType field determines the message's type. Based on this field's value, the DialogItemMessage structure's u field can have additional information. This section discusses each dialog item message, including any additional information.

The dialog item message structures are not used only for item hook functions. In addition, the item handler functions that actually implement the standard dialog items use them. In fact, many of the fields are appropriate for item handlers, and these fields can be safely ignored for item hook functions.

DITEM_MESSAGE_CREATE

The DITEM_MESSAGE_CREATE message is sent after an item is created. All item handlers will send this message. Additional information is included in the create member of the DialogItemMessage union u as follows:

struct
{
    boolean             createFailed;                           // <= set TRUE if error
    void                *resourceDataP;                         // => 
    Sextent             *itemListExtentP;                               // => 
    char                *labelP;                                // =>
    long                itemArg;                                // =>
    void                *ownerMD;                               // =>
    DialogItem *parentDiP;                                              // => NULL = owner is dialog
    boolean             dontDisplayAlert;                               // <= TRUE = no alert msg
} create;

Field	Description
createFailed	Indicates whether the item hook function's handling of the create message failed. If so, the function sets this field to TRUE. The dialog box will then remain unopened and an alert will display instead.
resourceDataP	Points to the item's loaded resource specification.
itemListExtentP	Points to the extent(in pixels) that is specified in the item's item list specification.
labelP	Points to the dialog item list override label.The various item handlers use this field internally, and it can be ignored.
itemArg	Contains the value of the itemArg field that is specified in the item's item list specification.
ownerMD	The various item handlers use this field internally, and it should be ignored.
parentDiP	Points to the DialogItem field of the item's parent item.The various item handlers use this field internally, and it can be ignored.
dontDisplayAlert	Indicates whether or not an alert box should be displayed if the create fails for any reason.A value of TRUE indicates that no alert box should be displayed.

Item hook functions usually need to allocate memory for an item in their DITEM_MESSAGE_CREATE message handling and store a pointer to the data in the allocated memory in dimP->dialogItemP->rawItemP->userDataP.At this point, items later in the dialog item list are not yet created, so manipulating them is illegal(and meaningless).Instead, multi - item initializations should be handled in a dialog hook function when the DIALOG_MESSAGE_INIT message is received.

DITEM_MESSAGE_ALLCREATED

The DITEM_MESSAGE_ALLCREATED message is sent after the all items contained in the parent dialog box have been sent the DITEM_MESSAGE_CREATE message. Additional information is included in the allCreated member of the DialogItemMessage union u as follows:

struct
{
    boolean createFailed;                                       // <= set TRUE if error
} allCreated; 

Field	Description
createFailed	Indicates whether the item hook function's handling of this message failed. If so, the function sets this field to TRUE. The dialog box will then remain unopened and an alert will display instead.

DITEM_MESSAGE_INIT

The DITEM_MESSAGE_INIT message is sent after the item is created, and after its internal value is initialized with the state of an underlying application variable.Additional information is included in the init member of the DialogItemMessage union u as follows :

struct
    {
    boolean initFailed;                         // <= set TRUE if error
    } init;                                     // sent after initial GetState

Field	Description
initFailed	Indicates whether the item hook function's handling of the init message failed. If so, the function sets this field to TRUE. The dialog box will then remain unopened and an alert will display instead.

DITEM_MESSAGE_DESTROY

The DITEM_MESSAGE_DESTROY message is sent when the item is about to be destroyed. Memory that was allocated in response to the DITEM_MESSAGE_CREATE or DITEM_MESSAGE_INIT message should be freed at this time.

DITEM_MESSAGE_GETSTATE

The DITEM_MESSAGE_GETSTATE message is sent when an item handler needs to determine an item's state (the value of the item's underlying application variable). This state is then typically used to set the item's internal value. Additional information is included in the value member of the DialogItemMessage union u as follows:

struct          // used by GETSTATE, SETSTATE, GETVALUE, SETVALUE
{
    boolean             hookHandled;                            // <= only for hooks,TRUE = handled
    boolean             valueChanged;                           // <= on SET's if value changed
    int         formatType;                             // defined in vartypes.h
    ValueUnion value;
    char                *stringValueP;                          // only if string
    char                *formatStrP;                            // only if string
    int         maxStringSize;                          // only if string & GETs
} value;

Field	Description
hookHandled	Indicates whether the dialog box manager should continue its default handling for obtaining the item state.The item hook function should set this field to TRUE to stop the default handling.
valueChanged	Is ignored for the DITEM_MESSAGE_GETSTATE message.
formatType	Returns the item state's format if the item hook function is handling the DITEM_MESSAGE_GETSTATE message. formatType is FMT_LONG(defined in vartypes.h) for all items with an internal value that is an integer.In this case, the item state should be returned in : dimP->u.value.value.sLongFormat Currently, all items except text items specify FMT_LONG for formatType. formatType is FMT_STRING(defined in vartypes.h) for all items whose internal value is stored as a string.Currently, only text items meet this requirement.In this case, the item hook function returns the item state by setting the string pointed to by dimP->u.value.stringValueP.
value	Returns the item's state for all items except text items. This field is a union of the standard C types. Currently, all items except text items use the signed long member dimP->u.value.value.sLongFormat to return the item's state.Text items expect the string pointed to by the stringValueP field to be set to the item's state.
stringValueP	Returns the item's state if the item's internal value is contained in a string. (Currently, only text items store their internal values as strings.) The string pointed to by stringValueP should be set to the item's state.
formatStrP	Points to the formatToDisplay string that is part of an item's resource specification. This pointer, if non-NULL, can be used with the sprintf function to convert an application variable to a string. This field is used only if the item stores its internal value as a string. (Currently, only text items store their internal values as strings).
maxStringSize	Specifies the size of the buffer pointed to by stringValueP.The size of the string copied in the buffer should not exceed maxStringSize.This field is used only if a string will be returned.

Sometimes the "state" of an application variable is not a simple thing to determine, or the "variable" is really a set of variables.In those cases, the item hook function can trap the DITEM_MESSAGE_GETSTATE and DITEM_MESSAGE_SETSTATE messages to come up with a composite state that can be used to set an item's internal value.

DITEM_MESSAGE_SETSTATE

The DITEM_MESSAGE_SETSTATE message is sent when an item handler needs to set an item's state (the value of its underlying application variable) using the item's internal value. Remember that with modal dialogs, unless the DIALOGATTR_ALWAYSSETSTATE attribute is set, SETSTATE messages will not be sent until the user OK's the modal dialog box. If the user cancels the dialog box, SETSTATE messages will never be sent. This leaves the dialog box items' underlying application variables unchanged, which is what is desired when canceling a dialog.

See ModelessAndModalDialogBoxes for more information on modal dialog boxes.

Additional information is included in the value member of the DialogItemMessage union u as follows:

struct          // used by GETSTATE, SETSTATE, GETVALUE, SETVALUE
{
    boolean             hookHandled;                            // <= only for hooks,TRUE = handled
    boolean             valueChanged;                           // <= on SET's if value changed
    int         formatType;                             // defined in vartypes.h
    ValueUnion value;
    char                *stringValueP;                          // only if string
    char                *formatStrP;                            // only if string
    int         maxStringSize;                          // only if string & GETs
} value; 

Field	Description
hookHandled	Indicates whether the dialog box manager should continue default handling for setting the item state.The item hook function should set this field to TRUE to stop the default handling.
valueChanged	Contains an indication of whether the item's internal value differed from the item's external state.The item hook function should set this field if hookHandled is TRUE.
formatType	Specifies the type of the item's internal value. If formatType is FMT_LONG, the item's internal value is stored as a signed long and can be found in the value.sLongFormat field. If formatType is FMT_STRING the item's internal value is stored as a string that is pointed to by stringValueP. Currently, formatType will be FMT_LONG(defined in vartypes.h) for all items except text items.For text items, it will be FMT_STRING.
value	Specifies the item's internal value for all items except text items. This field is a union of the standard C types. Currently all items except text items use the signed long member dimP->u.value.value.sLongFormat to contain the item's internal value.Text items will set the stringValueP field to point to the item's internal string value.
stringValueP	Points to the item's internal value if the value is contained in a string. (Currently, only text items store their internal values as strings).
formatStrP	Points to the formatToInternal string that is part of an item's resource specification. This pointer, if non-NULL, can be used with the sscanf function to convert an item's internal string to an application variable.This field is used only if the item stores its internal value as a string. (Currently, only text items store their internal values as strings.)
maxStringSize	Is ignored for the DITEM_MESSAGE_SETSTATE message.

DITEM_MESSAGE_QUEUECOMMAND

The DITEM_MESSAGE_QUEUECOMMAND message is sent after the DITEM_MESSAGE_SETSTATE message if the item's internal value differed from its state. It can be used to dynamically determine the command to queue based on the item's or dialog box's state. Additional information is included in the queueCommand member of the DialogItemMessage union u as follows:

struct
{
boolean         hookHandled;                    // <= only for hooks,TRUE = handled
int             subItemIndex;                   // =>
} queueCommand; 

Field	Description
hookHandled	Indicates whether the dialog box manager should continue default handling for queuing a command.After it queues a command, the item hook function should set this field to TRUE to prevent the item handler from queuing another command.
subItemIndex	Contains the current subitem index for the item.For certain items, such as option buttons, knowing the item's current value is useful in determining the command to queue. (An option button's current value is also the index of the subitem currently selected.For this reason, this field is called subItemIndex).

DITEM_MESSAGE_SYNCHRONIZE

The DITEM_MESSAGE_SYNCHRONIZE message is sent when an item's visible display and internal value is forced to match the item's external state(the value of its underlying application variable).Additional information is included in the synchronize member of the DialogItemMessage union u as follows :

struct
    {
    boolean             redrawn;                // => item had to be redrawn
    } synchronize; 

Field	Description
redrawn	TRUE if the item had to be redrawn in order to match its external state.

DITEM_MESSAGE_STATECHANGED

The DITEM_MESSAGE_STATECHANGED message is sent when an item's state has changed. Information about the command is included in the stateChanged member of the DialogItemMessage union u as follows:

struct
{
    boolean              reallyChanged;                         // => TRUE=item's value changed
} stateChanged; 

Field	Description
reallyChanged	Indicates whether, during DITEM_MESSAGE_SETSTATE processing, an actual change in the value of the dialog item was detected.If the user selected the dialog item but entered or selected the same value as was there before, the item's state will have changed but reallyChanged will return FALSE.

DITEM_MESSAGE_USER

The DITEM_MESSAGE_USER message can be sent to an item hook function with the mdlDialog_hookItemSendUserMsg function.This function can be used to send messages from one item hook function to another.Additional information is included in the user member of the DialogItemMessage union u as follows :

struct
{
    int type;                   // => type of user message
    void        *userDataP;                     // =>
} user; 

Field	Description
type	Contains the type that is specified in the mdlDialog_hookItemSendUserMsg function call.
userDataP	Contains the userDataP that is specified in the mdlDialog_hookItemSendUserMsg function call.

DITEM_MESSAGE_BUTTON

The DITEM_MESSAGE_BUTTON message can be sent only for items that are mouse-sensitive. See the individual item descriptions in Standard dialog items to determine if this message will be sent to an item's hook function.

This message is sent when a mouse button event occurs within a mouse-sensitive item. The screen extent of an item is specified in its DialogItem rect field. (See DialogItemRscStructure for more information). A button event happens when the mouse button is pressed or released, or when a button timeout occurs because the mouse button is pressed for an extended period of time or too much time elapses between presses. Additional information is included in the button member of the DialogItemMessage union u as follows:

struct
{
    boolean             couldSetState;                          // <= if not modal, could set State
    void(*motionFunc)();                                // <= for mouse down only
    void                *motionMD;                              // <= for mouse down only
                                    (only for item handlers)
    int         buttonNumber;                           // => button number
    int         buttonTrans;                            // => type of transition
    int         qualifierMask;                          // => ctrl/alt/shift keys down
    int         upNumber;                               // => 1=singleClick, 2=dblClick,etc
    boolean             clicked;                                // => FALSE = press or drag
    ULong               buttonTime;                             // => time of transition
    Point2d             pt;                             // => point in local coords
    Inputq_element *iqelP;
} button;

field	Description
couldSetState	Specifies whether the item state should be changed as a result of the button event. The item hook function should set this field to TRUE if the item state should be changed. The various item handlers use this field internally, and it can be ignored except for generic items.
motionFunc	Specifies the address of a function that should be called while the mouse moves with the button pressed. This field is used only if buttonTrans is BUTTONTRANS_DOWN, and only for generic items. The motion function specified should accept a single argument: a pointer to a MotionFuncArg structure (defined in dlogitem.h).
motionMD	(This field is used internally by the various item handlers and can be ignored.)
buttonNumber	Contains the mouse button number. This number will be either DATAPNT, TENTPNT or RESET.
buttonTrans	Contains the type of button transition that just occurred. Possible values are: BUTTONTRANS_UP - Indicates that the mouse button was just released. BUTTONTRANS_DOWN - Indicates that the mouse button was just pressed. BUTTONTRANS_TIMEOUT - Indicates that a button timeout event just occurred. See upNumber to determine the type of timeout.
qualifierMask	Contains the state of the qualifier keys when the button event occurred. The possible qualifier keys are SHIFTKEY, CTRLKEY and ALTKEY. These bitmasks are defined in keys.h.
upNumber	Contains the number of times the button was released within the amount of time specified by the variable doubleClickTime when buttonTrans is either BUTTONTRANS_UP or BUTTONTRANS_DOWN. When buttonTrans is equal to BUTTONTRANS_UP, a value of 1 means a single-click just occurred, 2 means a double-click just occurred, and so on. In a button press series, the amount of time between presses must be less than the amount specified by the doubleClickTime variable. When buttonTrans is equal to BUTTONTRANS_DOWN, a value of 0 means this is the first button press in the series; a value of 1 means that this is the next press, and so on. upNumber specifies the type of button timeout event if buttonTrans is BUTTONTRANS_TIMEOUT. In this case, upNumber can have the following values: BUTTONTIMEOUT_CLICK - Indicates that more than half a doubleClickTime amount of time elapsed between the time the button last went down and when it came back up. BUTTONTIMEOUT_DOUBLECLICK - Indicates that more than a doubleClickTime amount of time elapsed since the button last went down.
clicked	Specifies whether the button came back up because of a click. (The mouse came up within half a doubleClickAmount of time and did not move by an appreciable distance). This field is meaningless for mouse down events.
buttonTime	Specifies the time of the button event in ticks.
pt	Specifies the location, in local coordinates, of the mouse cursor at the time of the button event.
iqelP	Contains a pointer to the raw input queue element for the button event. See msinputq.h for the declaration of the InputQ_element structure.

DITEM_MESSAGE_JOURNALSTATE

When CAD input journaling is active, the DITEM_MESSAGE_JOURNALSTATE message is sent after the DITEM_MESSAGE_SETSTATE message if the item's internal value differed from it's state and before the DITEM_MESSAGE_QUEUECOMMAND is sent. This message can be used to journal a command equivalent to setting the item's access string or to prevent any journaling at all. At this time, CAD input journaling is used to generate macros.

  Additional information is included in the value member of the
  DialogItemMessage union u as follows:
struct          // used by GETSTATE, SETSTATE, GETVALUE, SETVALUE
{
    boolean             hookHandled;                            // <= only for hooks,TRUE = handled
    boolean             valueChanged;                           // <= on SET's if value changed
    int         formatType;                             // defined in vartypes.h
    ValueUnion value;
    char                *stringValueP;                          // only if string
    char                *formatStrP;                            // only if string
    int         maxStringSize;                          // only if string & GETs
} value;

field	Description
hookHandled	Indicates whether the dialog box manager should continue default handling for journaling the item state.The item hook function should set this field to TRUE to stop default handling.
valueChanged	Is ignored for the DITEM_MESSAGE_JOURNALSTATE message.
formatType	Specifies the type of the item's internal value. If formatType is FMT_LONG, the item's internal value is stored as a signed long and can be found in the value.sLongFormat field. If formatType is FMT_DPFP, the item's internal value is stored as a double precision floating point value and can be found in value.doubleFormat field. If formatType is FMT_STRING, the item's internal value is stored as a string that is pointed to by stringValueP.
value	Specifies the item's internal value for all items except text items. This field is a union of the standard C types. Text items will set the stringValueP field to point to the item's internal string value.
stringValueP	Points to the item's internal value if the value is contained in a string.
formatStrP	Points to the formatToInternal string that is part of an item's resource specification. This pointer, if non-NULL, can be used with the sscanf function to convert an item's internal string to an application variable.This field is used only if the item stores its internal value as a string.
maxStringSize	Is ignored for the DITEM_MESSAGE_JOURNALSTATE message.

DITEM_MESSAGE_MOTION

The DITEM_MESSAGE_MOTION message is sent to the item hook function as the mouse moves into, within, and out of the item. The dialog resource must have the DIALOGATTR_MOTIONTOITEMS attribute for the dialog items to receive the DITEM_MESSAGE_MOTION and DITEM_MESSAGE_NOMOTION item messages.

Information about the command is included in the motion member of the DialogItemMessage union u as follows:

struct
{
    int         motionTrans;      // => type of transition
    ULong       motionTime;       // => time of transition
    Point2d     newPoint;         // => location in local coords
    Point2d     oldPoint;         // => location in local coords
    void(*motionFunc)();  // <= item hook may change
    void        *motionMD;        // <= item hook may change
    RawItemHdr  *motionRiP;
    int         eventCreatedBy;  // 0-handler, 16,17 ptr exit & enter
    BoolInt     otherWinPopup;   // TRUE = other win part of cursor msg
                             was a popup
} motion; 

Field	Description
motionTrans	Indicates the type of motion : - MOTION_ENTER - MOTION_IN_ITEM - MOTION_EXIT
motionTime	Indicates the clock time of the motion.
newPoint	New location of the pointer, in local coordinates.
oldPoint	Old location of the pointer, in local coordinates.
motionFunc	Function pointer of the function to call for motion events.
motionMD	MDL Descriptor of the function to call for motion events.
motionRiP	RawItemHdr pointer of the item.
eventCreatedBy	The Window Manager message, CHANGE_POINTERENTER or CHANGE_POINTEREIXT.
otherWinPopup	Set to TRUE if the other window in the Window Manager message is a popup window.

DITEM_MESSAGE_NOMOTION

The DITEM_MESSAGE_NOMOTION message is sent to the item hook function as the mouse hovers over the item. The dialog resource must have the DIALOGATTR_MOTIONTOITEMS attribute for the dialog to receive the DITEM_MESSAGE_MOTION and DITEM_MESSAGE_NOMOTION item messages.

Information about the command is included in the noMotion member of the DialogItemMessage union u as follows:

struct 
{ 
   ULong       time;               // => time of transition 
   Point2d     pt;                 // => location in local coords
   void        (*noMotionFunc)();  // <= item hook may change
   void        *noMotionMD;        // <= item hook may change
   RawItemHdr  *noMotionRiP;       // current msg sent to this item
   int         showBalloon;        // TRUE to show
   RawItemHdr  *previousRiP;       // prev msg sent to this item
} noMotion; 

Field	Description
time	Computer time of the event.
pt	Location of the mouse, in local coordinates.
noMotionFunc	Function pointer of the function to call for noMotion events.
noMotionMD	MDL descriptor of the function to call for noMotion events.
noMotionRiP	RawItemHdr pointer of the item.
showBalloon	Set to TRUE if the item should show the balloon window.
previousRiP	Item the previous noMotion event was sent to.

DITEM_MESSAGE_STATECHANGING

The DITEM_MESSAGE_STATECHANGING message is sent to the item hook function before the state of a Tree or Text (only as a Cell Editor) changes.

Information about the command is included in the stateChanging member of the DialogItemMessage union u as follows:

struct 
{ 
   int         changeType;     // => indicates the type of change
   int         cause;          // => how the change was initiated
   int         currentType;    // => defined in vartypes.h
   ValueUnion  currentValue;   // => Indicates the current value
   int         proposedType;   // => Type of the proposed value
   ValueUnion  proposedValue;  // => The proposed value
   int         row;            // => row for listbox/tree
   int         column;         // => column for listbox/tree
   int         response;       // <= Allow or disallow change 
} stateChanging; 

Field	Description
changeType	One of the following values: STATECHANGING_TYPE_VALUECHANGE STATECHANGING_TYPE_NODEEXPANDING STATECHANGING_TYPE_NODECOLLAPSING
cause	One of the following values: STATECHANGING_CAUSE_HANDLECLICK STATECHANGING_CAUSE_DOUBLECLICK STATECHANGING_CAUSE_PROGRAMMATIC STATECHANGING_CAUSE_KEYSTROKE
currentType	If changeType is STATECHANGING_TYPE_VALUECHANGE, this member indicates the data type of the current value. See vartypes.h for valid values (FMT_).
currentValue	Indicates the current value.
proposedType	Indicates the data type of the proposed value.
proposedValue	Indicates the proposed value.
row	If changeType is STATECHANGING_TYPE_NODEEXPANDING or STATECHANGING_TYPE_NODECOLLAPSING this member indicates the index of the Tree item row.
column	If changeType is STATECHANGING_TYPE_NODEEXPANDING or STATECHANGING_TYPE_NODECOLLAPSING this member indicates the index of the Tree item column.
response	One of the following values: STATECHANGING_RESPONSE_ALLOW STATECHANGING_RESPONSE_DISALLOW

DITEM_MESSAGE_RESETPREBUTTON

The DITEM_MESSAGE_RESETPREBUTTON function is sent to the item hook function when an item is clicked with the Reset button. This message is sent before the DIALOG_MESSAGE_PREBUTTON message is sent to the dialog hook.

The button member of the DialogItemMessage union u is popul;ated for this message as it is for the DITEM_MESSAGE_BUTTON. Please see the documentation for that message.

DITEM_MESSAGE_SCREENCHANGE

The DITEM_MESSAGE_SCREENCHANGE message is sent to each item's hook function before and after the dialog containing the items is moved to a different MicroStation application screen using the "Change Screen" system menu item.

Information about the command is included in the screenChange member of the DialogItemMessage union u as follows:

struct
{
    int      oldScreenNum;  /* => screen window was on
    BSIRect  oldSizeRect;   /* => old content size
    int      newScreenNum;  /* => screen going to
    BSIRect  newSizeRect;   /* => new content size
    int      before;        /* TURE if before the change occurs
    int      hookHandled;   /* <= set to TRUE if handled
    int      disallow;      /* <= set to TRUE if handled
} screenChange; 

Field	Description
oldScreenNum	Indicates the number of the screen the dialog was on before the change.
oldSizeRect	Indicates the content rectangle of the dialog before the change.
newScreenNum	Indicates the number of the screen the dialog is on after the change.
newSizeRect	Indicates the content rectangle of the dialog after the change.
before	Set to TRUE if this message is sent before the screen change, FALSE if this message is sent after the change.
hookHandled	The hook should set this to TRUE if the message is handled.
disallow	If the before member is TRUE, this may be set TRUE to disallow the screen change.

DITEM_MESSAGE_REDIRECT

The DITEM_MESSAGE_REDIRECT message is sent to the item hook function when an accelerator keystroke combination is typed.

The keystrokeRedirect member of the DialogItemMessage union u is similar to the keystroke member and is populated in a similar manner, with the exception of the redirectAllowed flag.

struct
{
    BoolInt         hookHandled;      // <= TRUE if handled, hooks only 
    BoolInt         redirectAllowed;  // <= set to FALSE => send to item
    int             keystroke;        // <> virtual keystroke
    int             rawkeystroke;     // <> raw keystroke
    int             qualifierMask;    // =>
    Inputq_element  *iquelP;          // => source queue element
    ULong           commandNumber;    // <> accelerator key cmd
    char            *unparsedP;       // <> accelerator key unparsed
    char            *commandTaskIdP;  // <> accelerator key cmd taskId 
} keystrokeRedirect; 

Field	Description
redirectAllowed	Set to FALSE to disallow redirecting accelerated keystrokes to the top level MicroStation window and receive the keystrokes in the DITEM_MESSAGE_KEYSTROKE message.

DITEM_MESSAGE_HIDE

The DITEM_MESSAGE_HIDE function is sent to the item hook function when an item is to be hidden. This message needs to be handled only if the hiding of the item is different than a rectangle clear of the rect member of the DialogItem structure.

The hide member of the DialogItemMessage union u currently has no members.

DITEM_MESSAGE_OBSCURED

The DITEM_MESSAGE_OBSCURED function is sent to the item hook function when an item is being obscured, for example, when the TabPage an item belongs to is no longer the current page.

The obscured member of the DialogItemMessage union u currently has no members.

DITEM_MESSAGE_UNOBSCURED

The DITEM_MESSAGE_UNOBSCURED function is sent to the item hook function when an item is being unobscured, for example, when the TabPage an item belongs to is becoming the current tab page.

DITEM_MESSAGE_RELOADDATA

The DITEM_MESSAGE_RELOADDATA message is sent to the item hook function when an item needs to reload its data, for example, from a ListModel or GuiTreeModel. This message is sent as a result of an application calling the mdlDialog_itemReloadData, mdlDialog_rItemReloadData, or mdlDialog_synonymReloadData functions.

Information about the command is included in the reloadData member of the DialogItemMessage union u as follows:

struct 
{ 
   BoolInt   redraw;  // => redraw item after update?
} reloadData; 

Field	Description
redraw	Set to TRUE if the item should redraw after the reload occurs.

DITEM_MESSAGE_POPUP

The DIREM_MESSAGE_POPUP message is sent to the item hook function when an item's popup should be opened or closed.

Information about the command is include in the popup member of the DialogItemMessage union u as follows:

struct
{
    BoolInt    bOpen;        // => TRUE=open, FALSE=close
    BoolInt    bGrabMouse;   // => TRUE=grab mouse after opening popup
    BoolInt    bUpdate;      // => TRUE=update value after closing
    DialogBox  **popupDbPP;  // <> returned DialogBox* of popup wind.
} popup; 

Field	Description
bOpen	Set to TRUE if the popup window is to be opened, FALSE if closed.
bGrabMouse	Set to TRUE if the item should grab the mouse after opening the popup.
pPopupPt	Set to TRUE if the items value should be updated after closing the popup window.
popupDbPP	Popuplated with the DialogBox pointer of the popup window.

DITEM_MESSAGE_POPUPCLOSED

The DITEM_MESSAGE_POPUPCLOSED message is sent to the item hook function after the item's associated popup window is closed.

The popupClosed member of the DialogItemMessage union u currently has no members.

DITEM_MESSAGE_STYLECHANGED

The DITEM_MESSAGE_STYLECHANGED message is sent to an HTML item's hook function when the style (e.g. Bold, Italic, Underline) changes in the editor.

Information about the command is included in the styleChanged member of the DialogItemMessage union u as follows:

struct
{
    HTML_StyleInfo   styleInfo;  // => HTML sytle information
} styleChanged; 

Field	Description
styleInfo	An HTML_StyleInfo structure reflecting the new style in the HTML editor.See dlogitem.h for the definition of HTML_StyleInfo.

Input focusable item hook function messages

Input focusable item hook function messages can be sent only for items that can accept the input focus. See the individual item descriptions in "The Standard Dialog Box Items" to determine whether a message will be sent to an item's hook function.

The first two of these messages use the focusOutType field, which can have the following values:

focusOutType Value	Meaning
FOCUSOUT_KEYSWITCH	Focus has changed as a result of a keyboard action.
FOCUSOUT_BUTTONSWITCH	Focus has changed as a result of a button action.
FOCUSOUT_SETITEM	Focus has changes as a result of a dialog item programmatically being assigned focus.
FOCUSOUT_HIDEITEM	Focus has changed as a result of the previous item being hidden.
FOCUSOUT_DISABLEITEM	Focus has changed as a result of the previous item being disabled.
FOCUSOUT_SWITCHDIALOG	Focus has changed as a result of a new dialog box receiving focus.
FOCUSOUT_APPLYDIALOG	Focus has changed as a result of an apply operation being performed on the dialog box containing the item.

DITEM_MESSAGE_FOCUSIN

The DITEM_MESSAGE_FOCUSIN message is sent when an item gains the input focus. Additional information is included in the focusIn member of the DialogItemMessage union u.

struct
{
    int focusOutType;                           / => reason focus out of prev item
} focusIn; 

Field	Description
focusOutType	Specifies the reason the focus changed from the previous item to the one about to get focus.Possible values for this field are listed at the top of this section and are defined in msdefs.h.

DITEM_MESSAGE_FOCUSOUT

The DITEM_MESSAGE_FOCUSOUT message is sent when an item will soon lose the input focus. When receiving the DITEM_MESSAGE_FOCUSOUT message, the item hook function can optionally determine whether the item's internal value is out of range. Additional information is included in the focusOut member of the DialogItemMessage union u as follows:

struct
{
    boolean              hookHandled;                           // <= only for hooks,TRUE = handled 
    boolean              outOfRange;                            // <= if current value out of range
    int         nextFocusItemIndex;                             // <=> index of next focus item
    char                *stringValueP;                          // => hooks only, string value
    char                *formatStrP;                            // => hooks only, to internal format
    char                *minStrP;                               // => hooks only, max string
    char                *maxStrP;                               // => hooks only, min string
    int         focusOutType;                           // => reason for focus out
    int         moveDirection;                          // <=> 1: forward, -1: backward
    RawItemHdr *nextFocusRiP;                                           // <=> next item to get focus
} focusOut; 

Field	Description
hookHandled	Indicates whether the dialog box manager should continue its default handling for the focus out message.The item hook function should set this field to TRUE to stop the default handling.
outOfRange	Indicates whether the current input focus item contains a value that is out of range.The dialog hook function sets this field to TRUE for an out - of - range value.In this case, the dialog will not lose the input focus unless it is forced to. (Some methods of changing the input focus allow out - of - range focus - out errors to be ignored).
nextFocusItemIndex	Contains the index of the next item to receive focus as a result of this focus out message.A value of - 1 means search for the next focusable item in the direction indicated by the moveDirection field.
stringValueP	Contains the item's current string value. This field will be non-NULL only for items that store their internal values as strings. Currently, only text items do this. The string value can be checked against the strings pointed to by minStrP and maxStrP to see if it is in range.
formatStrP	Points to the formatToInternal string that is part of an item's resource specification. This pointer, if non-NULL, can be used with the sscanf function to convert stringValueP, minStrP and maxStrP to integers or doubles to range-check stringValueP. This field is used only if the item that is losing the focus stores its internal value as a string. Currently, only text items do this.
minStrP	Points to a minimum string that is a part of an item's resource specification. (Only text items currently have this field).
maxStrP	Points to a maximum string that is a part of an item's resource specification. (Only text items currently have this field).
focusOutType	Specifies the reason the focus changed from the previous item to the one about to get focus.Possible values for this field are listed at the top of this section and are defined in msdefs.h.
moveDirection	Specifies the direction in which focus is shifting to the next item receiving focus.A value of 1 means forward and - 1 means backward.
nextFocusRiP	Pointer to the Raw Item Header of the item to receive focus as a result of this focus out event.

DITEM_MESSAGE_KEYSTROKE

The DITEM_MESSAGE_KEYSTROKE message is sent when a key is pressed while the item has the input focus. Additional information is included in the keystroke member of the DialogItemMessage union u as follows:

struct
{
    boolean             hookHandled;                            // <= only for hooks,TRUE = handled
    int         moveDirection;                          // <= -1 or 1 indicate next field
    int         keyStroke;                              // <=>
    int rawKeyStroke; // <=>
    int qualifierMask; // =>
    Inputq_element *iqelP; // =>
    int cursorIndex; // => hook only, charIndex
                 //curs before
    boolean isAccelerator; // <=> TRUE = accelerator keystroke
    ULong commandNumber; // <=> Command num for accelerator
    char *unparsedP; // <=> Parm string for cmd function
    char *commandTaskIdP; // <=> Task containing cmd function
} keystroke; // also for POSTKEYSTROKE msgs

Field	Description
hookHandled	Indicates whether the dialog box manager should continue default handling for the keystroke.The item hook function should set this field to TRUE to stop the default handling.
moveDirection	Indicates that the key that was pressed caused the input focus to be moved if hookHandled is TRUE. 1 means that the input focus should be moved forward(later in the dialog item list) to an item that can accept the focus. - 1 means that the input focus should be moved backward(earlier in the dialog item list) to an item that can accept the focus.
keystroke	Contains the keystroke that was just pressed.If the item hook function changes this field, the new value of keystroke will be the value used in the item handler's default keystroke processing (unless hookHandled is set to TRUE).
qualifierMask	Contains the state of the qualifier keys when the keystroke event occurred.The possible qualifier keys are SHIFTKEY, CTRLKEY and ALTKEY.These bitmasks are defined in keys.h.
iqelP	Contains a pointer to the raw input queue element for the keystroke event.See msinputq.h for the declaration of the InputQ_element structure.
cursorIndex	Contains the current cursor position. 0 means that the cursor is in front of the first character.
isAccelerator	A value of TRUE for this field indicates that the current keystroke is being interpreted as a command accelerator.If this field is TRUE, then the three fields describing the command information contain valid data.The hook function may change the value of this field to perform special case handling of keystroke accelerators.
commandNumber	Contains the command number which will be queued to MicroStation after all keystroke processing is completed.This field is only valid of isAccelerator is TRUE.
unparsedP	Contains a pointer to the unparsed character string which will be passed to the command function when the command is executed.This field is only valid of isAccelerator is TRUE.
commandTaskIdP	Contains a pointer to the task ID of the application which implements the command indicated by the commandNumber field.This field is only valid of isAccelerator is TRUE.

DITEM_MESSAGE_POSTKEYSTROKE

The DITEM_MESSAGE_POSTKEYSTROKE message is sent after the item handler's default keystroke handling processes a key. Additional information is included in the keystroke member of the DialogItemMessage union u. See the discussion of the DITEM_MESSAGE_KEYSTROKE message for more information.

Generic item hook function messages

Generic item hook function messages are only sent to item hook functions attached to generic items. See GenericItemFunctions for more information on generic items.

DITEM_MESSAGE_SETLABEL

The DITEM_MESSAGE_SETLABEL message is sent when the item's label needs to be changed. If the item doesn't have a visible label, this message can be ignored. Additional information is included in the setLabel member of the DialogItemMessage union u as follows:

struct
{
    char        *newLabelP;                     // =>
} setLabel; 

Field	Description
newLabelP	Points to the string that should be used as the item's new label.

DITEM_MESSAGE_GETVALUE

The DITEM_MESSAGE_GETVALUE message is sent when the item's internal value is needed. If the item does not have an internal value, this message can be ignored. Additional information is included in the value member of the DialogItemMessage union u. The interpretation of all fields in the value member is the same as the interpretation of fields for the DITEM_MESSAGE_GETSTATE message except that instead of returning the item's state, the item hook function returns the item's internal value.

DITEM_MESSAGE_SETVALUE

The DITEM_MESSAGE_SETVALUE message is sent when the item's internal value will be set. If the item does not have an internal value, this message can be ignored. Additional information is included in the value member of the DialogItemMessage union u. The interpretation of all fields in the value member is the same as the interpretation of the DITEM_MESSAGE_SETSTATE message except that instead of setting the item's state, the item hook function sets the item's internal value.

DITEM_MESSAGE_DRAW

The DITEM_MESSAGE_DRAW message is sent when the item should draw itself. Additional information is included in the draw member of the DialogItemMessage union u as follows:

struct
{
    boolean             eraseFirst;                     // => erase before drawing
    int         nRects;                 // => # of update rects
    Rectangle           *rectList;                      // => update rects (local coords)
} draw; 

Field	Description
eraseFirst	Contains TRUE if the item should be erased first before it is drawn.Use the item's DialogItem rect field to determine where to erase.
nRects	Contains the number of rectangles in the next field.
rectList	Contains an array of rectangles.To optimize drawing(rarely necessary) draw only the item's parts that intersect with a rectangle in this array.

DITEM_MESSAGE_HIGHLIGHT

The DITEM_MESSAGE_HIGHLIGHT message is sent when the item needs to change its highlight state. This message is sent only if a motion function was not specified in response to a mouse down event. While the user keeps the mouse down, a highlight-on message will be sent when the cursor moves into the item's mouse-sensitive area, and a highlight-off message will be sent when it moves out. Additional information is included in the highlight member of the DialogItemMessage union u as follows:

struct
{
    boolean                     highlightOn;
} highlight;

Field	Description
highlightOn	Indicates whether the item should be drawn in its highlighted state. If so, this field is TRUE. Otherwise, the item should be drawn in its unhighlighted state.

DITEM_MESSAGE_MOVE

The DITEM_MESSAGE_MOVE message is sent when the item needs to be moved. Additional information is included in the move member of the DialogItemMessage union u as follows:

struct
{
    Point2d             newPt;          // => new origin of rawItemHdr.itemRect
    boolean             redraw;         // => redraw at new position?
} move; 

Field	Description
newPt	Contains the point where the item's RawItemHdr itemRect.origin should be moved to.
redraw	Indicates whether the item should be erased before it is moved and then drawn in its new location.If so, this field is TRUE.

DITEM_MESSAGE_SETEXTENT

The DITEM_MESSAGE_SETEXTENT message is sent when the item size needs to be changed.Additional information is included in the setExtent member of the DialogItemMessage union u as follows :

struct
{
    // used as if resource extent was respecified (except in pixels)
    Sextent             sextent;                // => 
    boolean             redraw;         // => redraw at new position? 
} setExtent; 

Field	Description
sextent	Contains the item's new extent (in pixels).
redraw	Indicates whether the item should be erased and then drawn in its new size and at its possibly new location.If so, this field is TRUE.

DITEM_MESSAGE_FONTCHANGED

The DITEM_MESSAGE_FONTCHANGED message is sent when the dialog box is moved to a screen that uses a different font size than the screen it was previously on. By default, the dialog box manager will scale the size of each item. If necessary, an item hook function can perform a different resizing operation on the item in response to this message.

Additional information is included in the fontChanged member of the DialogItemMessage union u as follows:

struct
{
    boolean             hookHandled;                            // <= TRUE if handled
    int         newFontHeight;                          // => new font's height
    int         oldFontHeight;                          // => old font's height
} fontChanged;                                  // because dialog now on new screen

Field	Description
hookHandled	Indicates whether the dialog box manager should continue default handling for the font changed message.The item hook function should set this field to TRUE to stop the default handling.
newFontHeight	Specifies the font height that should be used in calculating the new item size.
oldFontHeight	Specifies the height of the dialog box's old font.

DITEM_MESSAGE_SETENABLEDSTATE

The DITEM_MESSAGE_SETENABLEDSTATE message is sent when the item's enabled state is changed. Additional information is included in the setEnabledState member of the DialogItemMessage union u as follows:

struct
{
    boolean             enabled;                // => TRUE = enabled
} setEnabledState;

Field	Description
enabled	Indicates whether the item has been enabled.If so, this field is TRUE.

DITEM_MESSAGE_ACTIVATE

The DITEM_MESSAGE_ACTIVATE message is sent to the dialog item hook function when one of the following occurs:

• The user uses a keyboard accelerator key to activate a specific menu bar menu item.
• The user uses a keyboard mnemonic to activate a specific dialog item.
• An application calls the mdlDialog_pushButtonActivate function to activate a push button item.

If the dialog box containing the item being activated has a hook function, the DIALOG_MESSAGE_ACTIVATE message is sent after this message has been sent to the dialog item.

Additional information is included in the activate member of the DialogItemMessage union u as follows:

struct
{
    ULong               couldSetState;                          // <= if not modal, could set state 
    int                 keystroke;                              // => virtual keystroke
    int         rawKeystroke;                           // => raw keystroke
    int         qualifierMask;                          // => modified key status
    boolean             isAccelerator;                          // => key is accelerator 
    ULong               commandNumber;                          // => accelerator key command
    char                *unparsedP;                             // => accelerator key cmd parms
    char                *commandTaskIdP;                                //=> accelerator key cmd task id
} activate;

Field	Description
couldSetState	This field is unused in this message.
keystroke	Contains the platform independent (virtual) keystroke that was just pressed.
rawKeystroke	Contains the raw, native keystroke just pressed.
qualifierMask	Contains the state of the qualifier keys at the time of the keystroke event. The possible qualifier keys are SHIFTKEY, CTRLKEY and ALTKEY. These bitmasks are defined in keys.h.
isAccelerator	A value of TRUE for this field indicates that the current keystroke is being interpreted as a command accelerator. If this field is TRUE, then the three fields describing the command information contain valid data.
commandNumber	Contains the command number which will be queued to MicroStation after all keystroke processing is completed. This field is only valid of isAccelerator is TRUE.
unparsedP	Contains a pointer to the unparsed character string which will be passed to the command function when the command is executed. This field is only valid of isAccelerator is TRUE.
commandTaskIdP	Contains a pointer to the task ID of the application which implements the command indicated by the commandNumber field. This field is only valid of isAccelerator is TRUE.