Hook Functions

There are two types of hook functions: dialog hook functions and item hook functions. A dialog hook function is attached to a dialog box and receives messages that apply to the dialog box as a whole. An item hook function is attached to an item within a dialog box and receives messages that apply only to that item.

Dialog hook functions are passed a single argument, a pointer to a DialogMessage. Item hook functions are also passed a single argument, but this argument points to a DialogItemMessage.

Both hook function types are of type void. The hook functions respond to messages by setting the msgUnderstood, and other message fields that depend on the message type. Fields used to reply to the dialog box manager will be zero (FALSE) when sent to a hook function. The hook function sets a response field only if it needs to answer a non-zero (TRUE) result.

See Dialog Box Manager Basic Concepts for more information on hook functions and messages.

See Debugging Hook Functions for information on how to have the dialog box manager print detailed information about the messages it sends to dialog and item hook functions. This is the best technique for learning about the type, contents and order of the messages that can be sent to hook functions.

Dialog Hook Functions

A basic dialog hook function should look like the following:

Public void dialogName_dialogHook 
( 
DialogMessage *dmP 
) 
{ 
  dmP->msgUnderstood = TRUE; 
  switch(dmP->messageType) 
  { 
     case DIALOG_MESSAGE_CREATE: 
     { 
        dmP->u.create.interests.updates = TRUE; 
        dmP->u.create.interests.mouses = TRUE; 
        ... 
        break; 
     } 
     case DIALOG_MESSAGE_DESTROY: 
     { 
        ... 
        break; 
     } 
     default: 
     { 
        dmP->msgUnderstood = FALSE; 
        break; 
     } 
  } 
} 

Dialog hook functions are set up as one switch statement that tests for various messages and then handles them.

DialogMessage structure

The dialogmessage structure that is the only argument to a dialog hook function is declared as follows (from dlogitem.h):

typedef struct dialogmessage 
{ 
  boolean msgUnderstood; // <= message understood? 
  int messageType; // => message type
  DialogBox *db; // => dialog box handle
  long dialogId; // => resource id of dialog box
  void *userDataP; / => set by user during CREATE
  union
  {
      // structures that contain information
      //that depend on messageType
   } u;
} DialogMessage;

The structures in the union u will be discussed in the section on the individual dialog messages.

Field	Description
msgUnderstood	Indicates whether the dialog hook function understood the message. The dialog hook function sets this field to TRUE if it understands the message. If the message is not understood, the dialog box manager takes specific action depending on the value of messageType. Some messages also have a hookHandled member. This member indicates that the hook function not only understood the message, but handled it completely and the dialog box manager should not perform any further default processing.
messageType	Specifies the type of dialog message. The individual messages are discussed in the next section.
db	Contains an opaque pointer to the dialog box intended for the message. This pointer is usually just passed on to other dialog box manager functions.
dialogId	Contains the ID of the dialog box the message is intended for.
userDataP	Contains a pointer that can be set up in response to the DIALOG_MESSAGE_CREATE message. This pointer will then be passed to the dialog hook function for all other messages.

• An "opaque" pointer is a pointer that an MDL program can receive from and pass to functions, but should never attempt to reference.

Dialog Hook Function Messages

The messageType field of a dialog message determines the message's type. Based on the field's value, additional information can be present in the u field of the DialogMessage structure. This section discusses each individual dialog message, including any additional information.

The following messages are listed in this section:

Focus Messages	Sent
DIALOG_MESSAGE_CREATE	Before any DITEM_MESSAGE_CREATE messages are sent to the item hook functions.
DIALOG_MESSAGE_INIT	After DITEM_MESSAGE_CREATE messages are sent to all the item hook functions.
DIALOG_MESSAGE_BEFOREDESTROY	Before the dialog items have been sent the DITEM_MESSAGE_DESTROY message and the dialog box has been sent the DIALOG_MESSAGE_HIDE message.
DIALOG_MESSAGE_HIDE	When the dialog box is about to be hidden.
DIALOG_MESSAGE_DESTROY	When the dialog box is about to be destroyed.

Focus Messages	Sent
DIALOG_MESSAGE_FOCUSIN	When the dialog box gains the input focus.
DIALOG_MESSAGE_FOCUSOUT	When the dialog box loses the input focus.
DIALOG_MESSAGE_ITEMFOCUSIN	When an item in the dialog box gains the input focus.
DIALOG_MESSAGE_ITEMFOCUSOUT	When an item in the dialog box loses the input focus.
DIALOG_MESSAGE_KEYSTROKE	When a key is pressed while the dialog box has the input focus.
DIALOG_MESSAGE_ACTIVATE	When a specific menu bar menu item or dialog item is activated.

Size Messages	Sent
DIALOG_MESSAGE_RESIZE	After the dialog box is resized.
DIALOG_MESSAGE_CALCSIZE	When the dialog box manager needs to know what the dialog box's size would be if the dialog font height were changed to a specific value.
DIALOG_MESSAGE_FONTCHANGED	When the dialog box is moved between screens using differing font sizes.
DIALOG_MESSAGE_MINIMIZE	To the dialog hook function when the user presses the minimize button in the dialog title bar or the mdlWindow_minimize function is called.
DIALOG_MESSAGE_MAXIMIZE	To the dialog hook function when the user presses the maximize button in the dialog title bar or the mdlWindow_maximize function is called.
DIALOG_MESSAGE_DOCKEDEXTENT	As the dialog is being dragged into a docking region. This can be used to allow/disallow docking, and to get the dialog's extent when doc ked.
DIALOG_MESSAGE_WINDOWMOVING	Before a resize or move, provides control over minimum/maximum size.

Button Messages	Sent
DIALOG_MESSAGE_PREBUTTON	When a mouse button event occurs.
DIALOG_MESSAGE_BUTTON	Somewhere in the dialog box.
DIALOG_MESSAGE_ACTIONBUTTON	When the user presses and releases an OK, Cancel, Apply, Reset or Default button.

Open & Close Messages	Sent
DIALOG_MESSAGE_CHILDDESTROYED	To a dialog box's parent when the dialog is destroyed.
DIALOG_MESSAGE_ANOTHEROPENED	To all dialogs that set the otherDialogs field of DialogHookInterests to equal TRUE when any dialog is opened.
DIALOG_MESSAGE_ANOTHERCLOSED	To all dialogs that set the otherDialogs field of DialogHookInterests to TRUE when any dialog is destroyed.

Miscellaneous Messages	Sent
DIALOG_MESSAGE_UPDATE	After the dialog box manager has drawn the contents of a dialog box.
DIALOG_MESSAGE_SYNCH	When the dialog box is synched by the mdlDialog_itemsSynch function.
DIALOG_MESSAGE_STATECHANGED	To the dialog hook function after the dialog item state has changed.
DIALOG_MESSAGE_USER	To a dialog hook function with the mdlDialog_hookDialogSendUserMsg function.
DIALOG_MESSAGE_BEFOREUNDOCK	Sent before a dialog is undocked, may be used to disallow undocking.
DIALOG_MESSAGE_SCREENCHANGE	Sent before and after an application screen change.

Non-requested Messages

The following messages, documented in this section, do not have to be requested; they are always sent:

DIALOG_MESSAGE_CREATE 
DIALOG_MESSAGE_INIT 
DIALOG_MESSAGE_BEFOREDESTROY 
DIALOG_MESSAGE_HIDE 
DIALOG_MESSAGE_DESTROY 

DIALOG_MESSAGE_CREATE message

The DIALOG_MESSAGE_CREATE message is sent before any DITEM_MESSAGE_CREATE messages are sent to the item hook functions. Additional information is included in the create member of the DialogMessage union u as follows:

typedef struct dialoghookinterests                                                             // set member TRUE if notification wanted 
{
   ULong  updates : 1;                                 // after an item receives a draw msg 
   ULong  mouses : 1;                                  // on button msgs
   ULong  keystrokes : 1;                                      // on keystroke events
   ULong  dialogFocuses : 1;                                   // when dialog gets/loses focus
   ULong  itemFocuses : 1;                                     // when item get/loses focus
   ULong  synchs : 1;                                  // when item is synchronized
   ULong  resizes : 1;                                 // when dialog resized or moved
   ULong  calcSizes : 1;                                       // when dialog is moved to 2nd screen &
                                       //dialog mgr. needs to know the size
   ULong  fontChanges : 1;                                     // when dialog is moved to 2nd screen &
                                       //the font size will be affected
   ULong  nonDataPoints : 1;                                   // send RESET & TENTATIVE msgs
   ULong  otherDialogs : 1;                                    // another dialog open and close msgs
   ULong  stateChangeds : 1;                                   // after item state changes
   ULong  minimizes : 1;                                       // when dialog is minimized
   ULong  maximizes : 1;                                       // when dialog is maximized
   ULong  activates : 1;                                       // after item is activated
   ULong  preButtons : 1;                                      // before normal BUTTON message
   ULong  unused : 16;
} DialogHookInterests;                                         // CREATE, INIT, HIDE, BEFOREDESTROY and
                                           DESTROY ALWAYS SENT
struct
{
   boolean createFailed;                                               // <= set to TRUE if error
   DialogHookInterests interests;      // <=
   void **userDataPP;                                          // <=
   DialogBoxRsc *dialogBoxRP;                                          // =>
 } create;

Field	Description
createFailed	Indicates whether the dialog 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.
interests	Contains bitfields that the dialog hook function should set to TRUE to indicate which dialog messages are needed. For example, if update messages should be sent to the dialog hook function, the updates bitfield must be set to TRUE. DIALOG_MESSAGE_CREATE, DIALOG_MESSAGE_INIT, DIALOG_MESSAGE_HIDE, DIALOG_MESSAGE_BEFOREDESTROY, DIALOG_MESSAGE_DESTROY and DIALOG_MESSAGE_USER messages will always be sent to dialog hook functions. If any other messages are required, the appropriates bits must be set in the interests field when the function receives the DIALOG_MESSAGE_CREATE message.
userDataPP	Stores a pointer to a user-defined (and allocated) data area. This pointer will be passed back to the dialog hook function in all subsequent messages in the userDataP field. This pointer points to another pointer. To set the pointer, enter a command similar to the following: dmP->u.create.userDataPP = &myData;
dialogBoxRP	Points to the dialog box's loaded resource.

Dialog hook functions will usually want to perform any memory allocations for the entire dialog box in their DIALOG_MESSAGE_CREATE message handling,. They will then store a pointer to the allocated data in the variable pointed at by userDataPP. Remember that at this point, no items have been created so it is illegal (and meaningless) to perform any actions on them.

DIALOG_MESSAGE_INIT message

The DIALOG_MESSAGE_INIT message is sent after DITEM_MESSAGE_CREATE messages are sent to all the item hook functions. Additional information is included in the init member of the DialogMessage union u as follows:

struct 
{ 
boolean initFailed;                                   * <= set to TRUE if error occurred } init;

Field	Description
initFailed	Indicates whether the dialog 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.

Sometimes dialog box-wide initializations cannot be performed until all individual items in the dialog box are created. For this reason, both DIALOG_MESSAGE_CREATE and DIALOG_MESSAGE_INIT messages exist. When the DIALOG_MESSAGE_INIT message is received by a dialog hook function, it serves as a signal that all of the dialog box's items have been created and can be modified.

DIALOG_MESSAGE_BEFOREDESTROY message

The DIALOG_MESSAGE_BEFOREDESTROY message is sent before the dialog items have been sent the DITEM_MESSAGE_DESTROY message and the dialog box has been sent the DIALOG_MESSAGE_HIDE message. This message allows the dialog box hook function to perform additional cleanup prior to the dialog items being destroyed and/or to stop the dialog box from being destroyed. Any dialog item related memory not freed by dialog item hooks should be freed now. Additional information is included in the destroy member of the DialogMessage union u as follows:

struct 
{ 
      boolean stopDestroy;                                    // <= TRUE means stop destroy
  boolean userRequested;                                      // => TRUE means user initiated destroy
                                       //FALSE means program initiated destroy
} beforeDestroy;

Field	Description
stopDestroy	If set to TRUE by the dialog hook function, the destroy processing by MicroStation will be stopped and the dialog box will not be destroyed or hidden.
userRequested	If TRUE, this field indicates that the destroy was initiated by the user rather than by an application program.

DIALOG_MESSAGE_HIDE message

The DIALOG_MESSAGE_HIDE message is sent when the dialog box is about to be hidden. Additional information is included in the hide member of the DialogMessage union u as follows:

struct 
{ 
      int reason;                     // => reason for dialog being hidden
} hide;

Field	Description
reason	Contains a code indicating the reason the dialog is being hidden. Possible values are shown below.

reason Value	Meaning
HIDE_HideWindow	The window has been hidden by an application.
HIDE_ExitingMicroStation	The window is being hidden due to MicroStation being terminated. A DESTROY message will follow the HIDE message in this case.
HIDE_WindowClose	The window is being hidden prior to being closed. A DESTROY message will follow the HIDE message in this case.
HIDE_NoDgnFile	The window is being hidden because there is no open design file.
HIDE_UserClose	The window is being hidden as a result of the user closing the window. A DESTROY message will follow the HIDE message in this case.
HIDE_MdlUnload	The window is being closed as a result of the owning MDL application being unloaded from memory. A DESTROY message will follow the HIDE message in this case.

DIALOG_MESSAGE_DESTROY message

The DIALOG_MESSAGE_DESTROY message is sent when the dialog box is about to be destroyed. All item hook functions have received DITEM_MESSAGE_DESTROY messages. Any generic dialog related memory that was allocated in response to the DIALOG_MESSAGE_CREATE or DIALOG_MESSAGE_INIT message should be freed now. Additional information is included in the destroy member of the DialogMessage union u as follows:

struct
{
  int actionType;                             // =>
} destroy;

Field	Description
actionType	Contains the value last set by a call to the mdlDialog_lastActionTypeSet function. If the standard push button hook function is attached to a push button, this field contains the push button's itemHookArg field (usually an ACTIONBUTTON_ constant).

Focus Messages

The following messages can be sent when the focus changes:

  DIALOG_MESSAGE_FOCUSIN 
  DIALOG_MESSAGE_FOCUSOUT 
  DIALOG_MESSAGE_ITEMFOCUSIN 
  DIALOG_MESSAGE_ITEMFOCUSOUT 
  DIALOG_MESSAGE_KEYSTROKE 
  DIALOG_MESSAGE_ACTIVATE 

The first four of these messages all 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.

DIALOG_MESSAGE_FOCUSIN

The DIALOG_MESSAGE_FOCUSIN message is sent when the dialog box gains the input focus. If the item that will gain the input focus has an item hook function, a DITEM_MESSAGE_FOCUSIN message was already sent. Additional information is included in the focusIn member of the DialogMessage union u as follows:

struct 
{ 
        int             itemIndex;                      // => item about to get focus
    int         focusOutType;                   // => prev item focus out reason
    RawItemHdr *riP;                                    // => item about to get focus
} focusIn;

Field	Description
itemIndex	Specifies the item index (0-based) of the item that just gained the input focus.
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.
riP	Specifies a pointer to the Raw Item Header of the item to receive focus.

DIALOG_MESSAGE_FOCUSOUT

The DIALOG_MESSAGE_FOCUSOUT message is sent when the dialog box loses the input focus. If the item with the input focus has an item hook function, a DITEM_MESSAGE_FOCUSOUT message was already sent. Additional information is included in the focusOut member of the DialogMessage union u as follows:

struct 
      { 
      boolean         outOfRange;                             // <= if current value out of range
  int         itemIndex;                              // => child item that lost focus
  int         focusOutType;                           // => reason for focus out
  int         moveDirection;                          // => 1: forward, -1: backward
  boolean             hookHandled;                            // <= TRUE if handled by hook
  int         nextFocusItemIndex;                             // <=> next item to get focus
  RawItemHdr *nextFocusRiP;                                           // <=> next item to get focus
  RawItemHdr *riP;                                            // => item that just lost focus 
  } focusOut;

Field	Description
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 which 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).
itemIndex	Specifies the item index (0-based) of the item that just lost the input focus.
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	This field is not used for this message.
hookHandled	This field is not used for this message.
nextFocusItemIndex	This field is not used for this message.
nextFocusRiP	This field is not used for this message.
riP	Specifies a pointer to the Raw Item Header of the item losing focus.

DIALOG_MESSAGE_ITEMFOCUSIN

The DIALOG_MESSAGE_ITEMFOCUSIN message is sent when an item in the dialog box gains the input focus. If the item that will gain the input focus has an item hook function, a DITEM_MESSAGE_FOCUSIN message was already sent. Additional information is included in the focusIn member of the DialogMessage union u as follows:

struct 
{ 
    int                 itemIndex;                      // => item about to get focus 
    int                 focusOutType;                   // => prev item focus out reason
    RawItemHdr                  *riP;                   // => item about to get focus
} focusIn; Field  Description

Field	Description
itemIndex	Specifies the item index (0-based) of the item that just gained the input focus.
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.
riP	Specifies a pointer to the Raw Item Header of the item to receive focus.

DIALOG_MESSAGE_ITEMFOCUSOUT

The DIALOG_MESSAGE_ITEMFOCUSOUT message is sent when an item in the dialog box loses the input focus. If the item with the input focus has an item hook function, a DITEM_MESSAGE_FOCUSOUT message was already sent. Additional information is included in the focusOut member of the DialogMessage union u as follows:

struct 
{ 
  boolean             outOfRange;                     // <= if current value out of range
  int         itemIndex;                      // => item just lost focus
  int         focusOutType;                   // => reason for focus out
  int         moveDirection;                  // => 1: forward, -1: backward
  boolean             hookHandled;                    // <= TRUE if handled by hook
  int         nextFocusItemIndex; // <=> next item to get focus
  RawItemHdr *nextFocusRiP;   // <=> next item to get focus
  RawItemHdr                  *riP;           // => item that just lost focus
} focusOut;

Field	Description
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 which case the dialog item 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).
itemIndex	Specifies the item index (0-based) of the item that just lost the input focus.
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 from the current item position in which the focus is shifting. A value of 1 means forward and -1 means backward.
hookHandled	Indicates whether the dialog box manager should continue default handling for the focus out event. The dialog hook function should set this field to TRUE to stop the default handling. In this case, the dialog box manager will validate the nextFocusItemIndex and nextFocusRiP fields to ensure that they point at a valid item, and will set the next input focus item to the proper value if so.
nextFocusItemIndex	Specifies the item index (0-based) of the next dialog item to receive input focus. This field is input-only for this message.
nextFocusRiP	Specifies the pointer to the Raw Item Header of the next item to receive input focus.
riP	Specifies a pointer to the Raw Item Header of the item losing focus.

DIALOG_MESSAGE_KEYSTROKE

The DIALOG_MESSAGE_KEYSTROKE message is sent when a key is pressed while the dialog box has the input focus. This message is sent to the dialog hook function before a DITEM_MESSAGE_KEYSTROKE message is sent to the relevant item hook function to allow the dialog hook function to modify the key. Additional information is included in the keystroke member of the DialogMessage union u as follows:

struct 
{ 
  boolean             hookHandled;                            // <= only for hooks,TRUE = handled
  int         moveDirection;                          // <= -1 or 1 indicate next field
  int         keystroke;                              // <=> key that was pressed
  int         qualifierMask;                          // => shift/ctrl/alt status
  int         itemIndex;                              // => item key WOULD be send to
  Inputq_element                      *iqelP;                 // => source queue element
  boolean             isAccelerator;                          // <=> TRUE = accelerator keystroke
  ULong               commandNumber;                          // <=> Command num for accelerator
  char                *unparsedP;                             // <=> Parm string for cmd function
  char                *commandTaskIdP;                                // <=> Task containing cmd function
  RawItemHdr   *riP;                                  // => Item that would get keystroke
} keystroke;

Field	Description
hookHandled	Indicates whether the dialog box manager should continue default handling for the keystroke. The dialog hook function should set this field to TRUE to stop the default handling. In this case, a DITEM_MESSAGE_KEYSTROKE message will not be sent to the item hook function of the item that currently has the input focus.
moveDirection	Indicates that the key 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 dialog hook function changes this field, the new keystroke value will be the value sent to any relevant item hook function.
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.
itemIndex	Specifies the item that currently has the input focus.
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.
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.
riP	Contains a pointer to the Raw Item Header of the dialog item which would/will receive the keystroke.

DIALOG_MESSAGE_ACTIVATE

The DIALOG_MESSAGE_ACTIVATE message is sent to the dialog 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 mdlDialog_pushButtonActivate to activate a push button item.

If the dialog item being activated has a hook function, the DITEM_MESSAGE_ACTIVATE message has already been sent to the dialog item.

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

struct 
{ 
  ULong               couldSetState;                          // <= if not modal, could set state 
  RawItemHdr *activatedRiP;                                           // => item to be activated
  int         itemIndex;                              // => index of item to be activated
  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.
itemIndex	Specifies the item index (0-based) of the item that just lost the input focus.
activatedRiP	Contains a pointer to the Raw Item Header of the dialog item which is being activated.
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	Standard assignment. This is the most commonly used method.
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.

Size Messages

The following messages, documented in this section, are sent either before or after a dialog or the items in it need to be or are resized.

  DIALOG_MESSAGE_RESIZE 
  DIALOG_MESSAGE_CALCSIZE 
  DIALOG_MESSAGE_FONTCHANGED 
  DIALOG_MESSAGE_MINIMIZE 
  DIALOG_MESSAGE_MAXIMIZE 
  DIALOG_MESSAGE_DOCKEDEXTENT 
  DIALOG_MESSAGE_WINDOWMOVING 

DIALOG_MESSAGE_RESIZE

The DIALOG_MESSAGE_RESIZE message is sent after the dialog box is resized. Additional information is included in the resize member of the DialogMessage union u as follows:

struct 
{ 
  long                whichCorners;                           // => which corners moved 
  Rectangle           oldFrame;                               // => old frame rectangle
  Rectangle           oldContent;                             // => old content rectangle
  Rectangle           newContent;                             // => new content rectangle
  boolean             forceCompleteRedraw; // <= force dialog redraw
} resize;

Field	Description
whichCorners	Specifies which of the dialog boxes corners moved. See the mdlWindow_resize function for a description of possible values.
oldFrame	Contains the old size of the dialog frame.
oldContent	Contains the old size of the dialog content area.
newContent	Contains the new size of the dialog content area in global coordinates.
forceCompleteRedraw	Indicates that the hook function wants the complete contents of the dialog box redrawn aftrer the resize operation is complete. By default, the dialog box is not redrawn if the visible portions of the dialog box do not change and the left and top borders are not moved.

DIALOG_MESSAGE_CALCSIZE

The DIALOG_MESSAGE_CALCSIZE message is sent when the dialog box manager needs to know what the dialog box's size would be if the dialog font height were changed to a specific value. Additional information is included in the calcSize member of the DialogMessage union u as follows:

struct 
{ 
  boolean             hookHandled;                            // <= TRUE if handled 
  int         newWidth;                               // <= calculated width (in pixels)
  int         newHeight;                              // <= calculated height (in pixels)
  int dialogWidth; // <> in dialog coord units
  int dialogHeight; // <> in dialog coord units
  int newFontHeight; // => new font's height
  int oldFontHeight; // => old font's height
} calcSize;

Field	Description
hookHandled	Indicates whether the dialog box manager should continue default handling for calculating the dialog box size. The dialog hook function should set this field to TRUE to stop the default handling. In this case, the dialog hook function must set the newWidth, newHeight, dialogWidth and dialogHeight fields correctly.
newWidth	Contains the height (in pixels) the dialog box will have when the height of the dialog font becomes newFontHeight. The dialog hook function should set this field if hookHandled is set to TRUE.
newHeight	Contains the height (in pixels) the dialog box will have when the height of the dialog font becomes newFontHeight. The dialog hook function should set this field if hookHandled is set to TRUE.
dialogWidth	Contains the width (in dialog coordinate units) the dialog box will have when the height of the dialog font becomes newFontHeight. The dialog hook function should set this field if hookHandled is set to TRUE. dialogWidth is initially the old width of the dialog in dialog coordinate units.
dialogHeight	Contains the height (in dialog coordinate units) the dialog box will have when the height of the dialog font becomes newFontHeight. The dialog hook function should set this field if hookHandled is set to TRUE. dialogHeight is initially the old height of the dialog in dialog coordinate units.
newFontHeight	Specifies the font height that should be used in calculating the new size of the dialog box.
oldFontHeight	Specifies the height of the dialog box's old font.

DIALOG_MESSAGE_FONTCHANGED

The DIALOG_MESSAGE_FONTCHANGED message is sent when the dialog box is moved between screens using differing font sizes. DITEM_MESSAGE_FONTCHANGED messages were already sent to any item hook functions attached to items in the dialog box. The dialog box size was changed to correspond to the new size calculated when the DIALOG_MESSAGE_CALCSIZE message was sent.

Most dialog hook functions ignore this message unless they need to accomplish a task (such as repositioning dialog items) when the dialog font changes.

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

struct 
{ 
      int     newFontHeight;                          // => new font's height
  int oldFontHeight;                          // => old font's height
} fontChanged

Field	Description
newFontHeight	Specifies the font height that should be used in calculating the new size of the dialog box.
oldFontHeight	Specifies the height of the dialog box's old font.

DIALOG_MESSAGE_MINIMIZE

The DIALOG_MESSAGE_MINIMIZE message is sent to the dialog hook function when the user presses the minimize button in the dialog title bar to minimize the dialog box or the mdlWindow_minimize function is called. This message is only generated at minimize time, not when the dialog is restored to it's original size. Additional information is included in the minimize member of the DialogMessage union u as follows:

struct 
{ 
      boolean         hookHandled;                    // <= TRUE if new size returned 
  int         newWidth;                       // <= width of minimized dialog
  int         newHeight;                      // <= height of minimized dialog
} minimize;

Field	Description
hookHandled	Indicates that the dialog hook function has returned new values to be used as the minimized size of the dialog box in pixels.
newWidth	Specifies the minimized width of the dialog box in pixels.
newHeight	Specifies the minimized height of the dialog box in pixels.

DIALOG_MESSAGE_MAXIMIZE

The DIALOG_MESSAGE_MAXIMIZE message is sent to the dialog hook function when the user presses the maximize button in the dialog title bar to maximize the dialog box or the mdlWindow_maximize function is called. This message is only generated at maximize time, not when the dialog is restored to it's original size. Additional information is included in the maximize member of the DialogMessage union u as follows:

struct 
{ 
      boolean         hookHandled;                    // <= TRUE if new size returned
  BSIRect             newRect;                        // <= new content rectangle
} maximize;

Field	Description
hookHandled	Indicates that the dialog hook function has returned new values to be used as the maximized size and location of the dialog box.
newRect	Specifies the new content rectangle for the maximized dialog box in global, pixel coordinates.

DIALOG_MESSAGE_DOCKEDEXTENT

The DIALOG_MESSAGE_DOCKEDEXTENT message is sent to the dialog hook function as the dialog is being dragged into a docking region. The dialog resource must have the DIALOGATTR_DOCKABLE attribute. Additional information is included in the dockedExtent member of the DialogMessage union u as follows:

struct 
{                           // get dialog's extent when docked 
  int      dockPosition;  // <= DOCK_TOP, _LEFT, _BOTTOM, _RIGHT
  int      extentFlag;    // <= DOCKEXTENT_DONTCARE,
                          //_FULLWIDTHORHEIGHT, _SPECIFIED, or _INVALIDREGION
  Point2d  dockExtent;    // <= extent when in docked state
  BoolInt  hookHandled;   // <= TRUE if Dialog Hook handled
} dockedExtent;

Field	Description
dockPosition	Indicates the docking region the dialog is being dragged into.
extentFlag	The hook should set this flag to one of four values: DOCKEXTENT_DONTCARE - uses the undocked width (left and right region) or height (top and bottom region) and FULLWITDTHORHEIGHT, depending on the docking region. DOCKEXTNET_FULLWIDTHORHEIGHT - docked dialog should take up entire width or height of the application area. DOCKEXTENT_SPECIFIED - the dockExtent member has been set to the desired width and height for the docked dialog. DOCKEXTENT_INVALIDREGION - the docking region specified in dockPosition is invalid for this dialog and no docking is allowed.
dockExtent	The x member should be set to the desired width and the y member to the desired height.
hookHandled	Should be set to TRUE if the hook handled the message.

DIALOG_MESSAGE_WINDOWMOVING

The DIALOG_MESSAGE_WINDOWMOVING message is sent to the dialog hook function as the dialog is being moved or resized. The dialog resource must have the DIALOGATTR_GROWABLE attribute. Additional information is included in the windowMoving member of the DialogMessage union u as follows:

struct 
{                           // sent before move/resize occurs 
int      whichCorners;  // => which corners are moving
int      newWidth;      // <> new content width, dialog may change
int      newHeight;     // <> new content hght, dialog may change
BSIRect  oldGlobal;     // => old global rect for window
BSIRect  oldContent;    // => old content rect
byte     percentDone;   // <= set to 100 to halt the message
byte     handled;       // <= set TRUE if window size was changed
} windowMoving;

Field	Description
whichCorners	Indicates which corners are changing: CORNER_UPPERLEFT, CORNER_LOWERLEFT, CORNER_LOWERRIGHT, CORNER_UPPERRIGHT, CORNER_ALL, or CORNER_ALL_RESIZED.
newWidth	Indicates the new width of the dialog. The dialog hook may change this value, resulting in control over minimum or maximum dialog width.
newHeight	Indicates the new height of the dialog. The dialog hook may change this value, resulting in control over minimum or maximum dialog height.
oldGlobal	The old global rectangle of the dialog before resizing.
oldContent	The old content rectangle of the dialog before resizing.
percentDone	For negotiating purposes. This value should not be altered in most cases. Set to 100 to halt the WindowMoving messages.
handled	Set to TRUE if the dialog hook changed either the newWidth or newHeight value.

Button Messages

The following messages, documented in this section, are sent when button events occur:

  DIALOG_MESSAGE_PREBUTTON 
  DIALOG_MESSAGE_BUTTON 
  DIALOG_MESSAGE_ACTIONBUTTON 

DIALOG_MESSAGE_PREBUTTON

DIALOG_MESSAGE_BUTTON

The DIALOG_MESSAGE_PREBUTTON and DIALOG_MESSAGE_BUTTON messages are sent when a mouse button event occurs somewhere in the dialog box. A button event occurs when:

• The mouse button is pressed or released.
  or
• · A button timeout occurs because the mouse button is pressed for an extended period of time or too much time elapses between presses.

When a button down event occurs, a DIALOG_MESSAGE_PREBUTTON message is sent to the dialog hook function. This message allows the hook function to interpret the event in different ways and alter the way MicroStation handles this event. The hook function may redirect the processing o f the button down event to another item in the dialog by placing a pointer to the desired dialog item's raw item header in the buttonRiP field of the button member structure as defined below. This is typically used for opening popup menu items in the dialog box and causes all button events up to and including the subsequent button up event to be sent to this alternate dialog item. A DIALOG_MESSAGE_BUTTON message is sent after the PREBUTTON message to either the item pointed to by the buttonRiP value returned by the dialog hook or item originally receiving the PREBUTTON if this field is NULL.

If the button event occurs with the mouse cursor inside of a dialog item that has an item hook function, a DITEM_MESSAGE_BUTTON message has been sent to that function. Additional information is included in the button member of the DialogMessage union u as follows:

struct 
{ 
        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 means press or drag
    ULong               buttonTime;                             // => time of transition
    Point2d             pt;                             // => location in local coords
    int         itemIndex;                              // => item button already sent to
    Inputq_element                      *iqelP;                 // => source queue element
    void(*motionFunc)();                                // <= for mouse down only
    void                *motionMD;                              // <= for mouse down only
    RawItemHdr  *buttonRiP;                             // <= item to rcv followup msgs
} button;

Field	Description
buttonNumber	Contains the mouse button number. This number will be either DATAPNT, TENTPNT or RESET. These values are defined in msbutton.h.
buttonTrans	Contains the type of button transition that just occurred. The values, listed below in the buttonTrans table, are defined in msdefs.h.
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: BUTTONTIME-OUT_CLICK Indicates that an amount of time equal to half the value of doubleClickTime has elapsed between the time the button last went down, and when it came back up. BUTTONTIME-OUT_DOUBLECLICK-Indicates that an amount of time equal to doubleClickTime has 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.
itemIndex	Specifies the index (0-based) of the item the mouse cursor was on at the time of the button event. -1 means the mouse cursor was not inside a mouse-sensitive item.
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.
motionFunc	Specifies an MDL function to be called by MicroStation to handle cursor motion events while the mouse button is pressed. The motion function will be called every time MicroStation operates on the cursor while the mouse button is down (i.e., every time it moves, the cursor is drawn, or a timeout occurs). The motion function is called with a single parameter, which is a pointer to the structure shown below. typedef struct motionfuncarg { Point2d pt; boolean dragging; } MotionFuncArg; pt - Specifies the location, in global coordinates, of the mouse cursor at the time of the function call. dragging - Specifies whether the cursor has moved while the mouse button is pressed down.

buttonTrans Value	Description
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.

DIALOG_MESSAGE_ACTIONBUTTON

This message is generated by the default MicroStation buttons (OK, Cancel, Apply, Reset and Default) when the user presses and releases the button. Additional information is included in the actionButton member of the DialogMessage union u as follows:

struct 
{ 
      boolean         abortAction;                    // <= TRUE = abort button action
  int         actionType;                     // => OK, CANCEL, APPLY, RESET
} actionButton;

Field	Description
abortAction	Indicates whether the dialog manager should perform the default actions done as a result of the push button being activated. If TRUE, the dialog manager skips all default processing and acts as if the push button was not activated by the user.
actionType	Contains the value last set by a call to the mdlDialog_lastActionTypeSet function. If the standard push button hook function is attached to a push button, this field contains the itemHookArg field of that push button (usually one of the ACTIONBUTTON_ constants).

Open & Close Messages

The following messages, documented in this section, are sent when dialog boxes are created or destroyed:

  DIALOG_MESSAGE_CHILDDESTROYED
  DIALOG_MESSAGE_ANOTHEROPENED
  DIALOG_MESSAGE_ANOTHERCLOSED

DIALOG_MESSAGE_CHILDDESTROYED

The DIALOG_MESSAGE_CHILDDESTROYED message is sent to a dialog box's parent when the dialog is destroyed. The parent dialog box is specified by the parentDialogId field of a dialog box's resource specification. The parentId of a dialog box can also be set with the mdlDialog_parentIdSet function. Additional information is included in the childDestroyed member of the DialogMessage union u as follows:

struct 
{ 
    long        childDialogId;  // => child dialog id
    int actionType;                     // => only if stdAction button used
} childDestroyed;

Field	Description
childDialogIdn	Contains the ID of the dialog box that was just destroyed.
actionType	Contains the value last set by a call to the mdlDialog_lastActionTypeSet function. If the standard push button hook function is attached to a push button, this field contains the itemHookArg field of that push button (usually one of the ACTIONBUTTON_ constants) instead.

DIALOG_MESSAGE_ANOTHEROPENED

The DIALOG_MESSAGE_ANOTHEROPENED message is sent to all dialog boxes that have set the otherDialogs field of DialogHookInterests to equal TRUE when any dialog is opened. Additional information is included in the anotherOpened member of the DialogMessage union u as follows:

struct 
{ 
  DialogBox           *db;                    // => ptr to dialog opened
  ULong               dialogType;                     // => type of dialog opened
   long               dialogId;                       // => id of dialog opened
} anotherOpened;

Field	Description
db	Contains an opaque pointer to the dialog box that was just opened.
dialogType	Contains the type of the dialog box that was just opened.
dialogId	Contains the ID of the dialog box that was just opened.

DIALOG_MESSAGE_ANOTHERCLOSED

When any dialog is destroyed, the DIALOG_MESSAGE_ANOTHERCLOSED message is sent to all dialog boxes that have set the otherDialogs field of DialogHookInterests to TRUE. Additional information is included in the anotherClosed member of the DialogMessage union u as follows:

struct 
{ 
      DialogBox               *db;                    // => pointer to dialog closed
  ULong               dialogType;                     // => type of dialog closed
  long                dialogId;                       // => id of dialog closed
  int         actionType;                         // => only if stdAction button used
} anotherClosed;

Field	Description
db	Contains an opaque pointer to the dialog box that was just destroyed.
dialogType	Contains the type of the dialog box that was just destroyed.
dialogId	Contains the ID of the dialog box that was just destroyed.
actionType	Contains the value last set by a call to the mdlDialog_lastActionTypeSet function. If the standard push button hook function is attached to a push button, this field contains the itemHookArg field of that push button (usually one of the ACTIONBUTTON_ constants).

Miscellaneous Messages

The following messages, documented in this section, are sent when various user interface events occur:

  DIALOG_MESSAGE_UPDATE
  DIALOG_MESSAGE_SYNCH
  DIALOG_MESSAGE_STATECHANGED
  DIALOG_MESSAGE_USER
  DIALOG_MESSAGE_BEFOREUNDOCK
  DIALOG_MESSAGE_SCREENCHANGE

DIALOG_MESSAGE_UPDATE

After the dialog box manager has drawn the contents of a dialog box, it sends the DIALOG_MESSAGE_UPDATE message to the dialog hook function.

DIALOG_MESSAGE_SYNCH

The DIALOG_MESSAGE_SYNCH message is sent when the dialog box is synched by the mdlDialog_itemsSynch function. DITEM_MESSAGE_SYNCHRONIZE messages have already been sent to all item hook functions attached to items in the dialog box.

DIALOG_MESSAGE_STATECHANGED

The DIALOG_MESSAGE_STATECHANGED message is sent to the dialog hook function after the dialog item state has changed. If the dialog item has a hook function, the item hook function has already been sent the DITEM_MESSAGE_STATECHANGED message.

Information about the command is included in the stateChanged member of the DialogMessage union u as follows:

struct
{
  int         itemIndex;                              // => index of item that changed
  boolean             reallyChanged;                  // => if setState noticed difference
  RawItemHdr  *riP;                               // => item that changed
} stateChanged;

Field	Description
itemIndex	Specifies the item index (0-based) of the dialog item which changed.
reallyChanged	Indicates whether the item handler recognized a difference in the state of the item during DITEM_MESSAGE_SETSTATE processing.
riP	Specifies a pointer to the Raw Item Header of the item which changed.

DIALOG_MESSAGE_USER

The DIALOG_MESSAGE_USER message can be sent to a dialog hook function with the mdlDialog_hookDialogSendUserMsg function. This message is useful for setting up a general item hook used for items in different dialog boxes. The item hook sends user messages to each dialog box's dialog hook function. These dialog hook functions are then set up to handle the user messages.

Additional information is included in the user member of the DialogMessage union u as follows:

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

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

DIALOG_MESSAGE_BEFOREUNDOCK

The DIALOG_MESSAGE_BEFOREUNDOCK message is sent to the dialog hook function before a dialog is undocked. The undocking may be disallowed using this message. The dialog resource must have the DIALOGATTR_DOCKABLE attribute. Additional information about the command is included in the beforeUndock member of the DialogMessage union u as follows:

  struct 
  { 
    BoolInt  stopUndock;  /* <= TRUE means stop/disallow undock
* } beforeUndock;
* 

Field	Description
stopUndock	Set to TRUE to disallow undocking.

DIALOG_MESSAGE_SCREENCHANGE

The DIALOG_MESSAGE_SCREENCHANGE message is sent to the dialog hook function before and after a dialog is moved to a different MicroStation application screen using the "Change Screen" system menu item. To remove this menu item and disallow screen changes for a dialog, the dialog resource must have the DIALOGATTRX_NOCHANGESCREEN attribue. Additional information about the command is included in the screenChange member of the DialogMessage union u as follows:

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

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 is the message sent before the screen change, FALSE if this is the message sent after the change.
hookHandled	The hook should set to TRUE if the message is handled.
disallow	If the before member is TRUE, this may be set TRUE to disallow the screen change.

Item Hook Functions

A basic item hook function should look as follows:

Public void dialogBoxName_specificItemtypeHook 
( 
DialogItemMessage *dimP 
) 
{ 
      dimP->msgUnderstood = TRUE; 
      switch (dimP->messageType) 
      { 
              case DITEM_MESSAGE_CREATE: 
              { 
                      ... 
                      break; 
              } 
              case DITEM_MESSAGE_DESTROY: 
              { 
                      ... 
                      break; 
              } 
               
              ... 
              default: 
              { 
                      dimP->msgUnderstood = FALSE; 
                      break; 
              } 
      } 
} 

Item hook functions are set up similarly to dialog hook functions: one switch statement tests for various messages, and then handles them.

DialogItemMessage structure

The DialogItemMessage structure that is the only argument to an item hook function is declared as follows (from dlogitem.h):

typedef struct dialogitemmessage 
{ 
  boolean msgUnderstood;                                              // <= item understood the message 
  int messageType;                                            // => message type
  DialogBox *db;                                              // => dialog box handle
  long dialogId;                                              // => resource id of dialog box
  int itemIndex;                                              // => index of item msg sent to
  DialogItem *dialogItemP;                                            // => dialogItem info for item
  int auxMessageType;                                         // => item specific message type
  void *auxInfoP;                                             // => item specific message info 
  union
  {
  ...
       structures that contain information that
       depends on messageType.
   } u;
  } DialogItemMessage;

Structures that contain information that depends on messageType are discussed in the section on the individual dialog item messages.

Field	Description
msgUnderstood	Indicates whether the item hook function understands the message. If it understands the message, the function sets msgUnderstood to TRUE. If the mesage is not understood, the item handlers take specific actions automatically, depending on the value of messageType. Some messages also have a hookHandled member. This member indicates that the hook function not only understands the message, but it handled it completely and the item handler should not perform any further default processing.
messageType	Type of item message. The individual messages are discussed in the next section.
db	Opaque pointer to the dialog box intended for the message. The pointer is usually passed on to other dialog box manager functions.
dialogId	ID of the dialog box the message is intended for.
itemIndex	Index (0-based) of the item the message is intended for.
dialogItemP	Pointer to the DialogItem field of the item the message is for. The DialogItem declaration is discussed in the next table.
auxMessageType	Type of auxiliary message. This field is used internally by the dialog box manager and can be ignored.
auxInfoP	Additional information needed for auxiliary messages. The dialog box manager uses this field internally and it can be ignored.

DialogItem structure

The header for a dialog item message contains a DialogItem field. Every dialog item in a dialog box can be uniquely identified by a pointer to its DialogItem field. The mdlDialog_itemGetByTypeAndId or mdlDialog_itemGetByIndex functions can be used to obtain a pointer to an item that is different than the one a particular message is directed to.

The DialogItem and associated structures have the following declarations (from dlogitem.h):

typedef struct dialogitemattributes 
{ 
  ULong acceptsKeystrokes:1;                                          // keystroke input possible 
  ULong mouseSensitive : 1;                                           // mouse events possible
  ULong traversable : 1;                                              // kbd navigation possible
  ULong canHaveSynonyms : 1;                                          // synonym resources refs
  ULong enabled : 1;                                          // TRUE = enabled
  ULong hidden : 1;                                           // TRUE = hidden
  ULong hasFocus : 1;                                         // TRUE = has input focus
  ULong updateFlag : 1;                                               // internal use only
  ULong xPosLocked : 1;                                               // internal use only
  ULong yPosLocked : 1;                                               // internal use only
  ULong unused : 6;
  ULong unused2 : 8;
  ULong unused3 : 8;
} DialogItemAttributes;

typedef struct dialogitem
{
  long        type;
  long        id;
  int itemIndex;
  int itemArg;
  Rectangle rect;                             // mouse sensitive/update region of item
  Sextent             extent;         // (in dcoord units) for fontChange msgs
  Point2d             origin;         // for fontChange msgs
  DialogItemAttributes attributes;
  RawItemHdr *rawItemP;
} DialogItem;

Field	Description
type	Specifies the type of the dialog item.
id	Specifies the ID of the dialog item.
itemIndex	Specifies the index (0-based) of the dialog item. This is the item's position within the dialog item list. This field will change if items are inserted or deleted from the dialog box containing the item.
itemArg	Contains the itemArg field that is used in the dialog box's DialogItemRsc item list specification.
rect	Specifies the mouse-sensitive/update region of the item in pixels.
extent	Specifies the mouse-sensitive/update region of the item in dialog coordinate units. This field can be used to handle the DITEM_MESSAGE_FONTCHANGED message.
origin	Specifies the origin that should be used with the extent field. Items can be located relative to an origin different than the upper left corner of a dialog box. This field stores that origin.
attributes	Contains the item's attributes. The attributes for an item are described by the DialogItemAttributes structure. The application program should never set/clear any of the bits in this structure except as may be later described in this section. Changes to information affects the way the dialog manager handles an item.The fields of this structure are described in the attributes table below.
rawItemP	Contains a pointer to the item's RawItemHdr declaration. The RawItemHdr declaration is discussed in the next table.

attributes Value	Meaning
acceptsKeystrokes	Indicates whether the item can accept keystrokes events as input for processing.
mouseSensitive	Indicates whether the item can accept mouse events as input for processing.
traversable	Indicates whether the item can be traversed using keyboard navigation through the dialog box.
canHaveSynonyms	Indicates whether the item can associated with other items through synonym resources.
enabled	Indicates whether the item is ENABLED or DISABLED. ENABLED items are displayed in full intensity and can received user input and focus. DISABLED items are displayed in half intersity and can not be selected by the user.
hidden	Indicates whether the item is displayed in the dialog box. If HIDDEN, an item is not visible to the user and can not receive input focus.
hasFocus	An internal flag not currently used.
updateFlag	An internal flag used to indicate whether the item has been drawn in the dialog box.
xPosLocked	An internal flag used for locking the X position of the item when working with tool palette slamdowns. This attribute should be ignored.
yPosLocked	An internal flag used for locking the Y position of the item when working with tool palette slamdowns. This attribute should be ignored.

RawItemHdr structure

The DialogItem structure contains information specified in the dialog box's DialogItemRsc item list specification. On the other hand, the RawItemHdr structure contains information that is usually specified in an item's resource specification. A field that does not apply to a particular type of item is set to zero.

A pointer to an item's RawItemHdr structure uniquely identifies it, just like a pointer to an item's DialogItem field does. Also, one of these pointers can be obtained from the other. The RawItemHdr structure has the following declaration (from dlogitem.h):

// this structure must be at the beginning of all runtime items
struct rawitemhdr
    {
    void                *userDataP;                                     // for use by itemHooks
    char                *accessStrP;                                    // access str to app variable
    char                *labelP;                                        // items label or NULL
    Point2d             labelPt;                                        // position of label
    Rectangle    itemRect;                                              // item specific rectangle
    ULong               helpInfo;                                       // item help
    ULong               helpSource;                                     // help file indicator
    long                synonymsId;                                     // id of synonyms resource
    UShort              highlightOn : 1;                                        // highlight state
    void                *itemHookMD;                                    // mdl process descrip for hook
    long                itemHookOffset;                                 // mdl hook offset
    long                itemHookArg;                                    // rsc defined arg to hook func
    void                *ownerDialogP;                                  // ptr to owner dialog box
    DialogItem *diP;                                                    // ptr to dialog item struct
    DialogItem *parentDiP;                                                      // ptr to parent dialog item
    long                itemHookId;                                     // mdl hook id 
    int         mnemonic;                                       // keyboard mnemonic
    int         mneIndex;                                       // mnemonic index
    int         nColorPs;                                       // Number of colors settings
    BSIColorDescr **colorsPP;                                                   // colors for each setting
    DialogItemHandlerInfo *itemHandlerP;        // item handler info
    BSIRect              traversalRect;                                 // highlight rectangle
    void                *ownerMD;                                       // owner MDL descriptor
    ULong                commandNumber;                                 // command assoc with item
    char                *commandTaskId;                                 // task owning command
    char                *unparsedP;                                     // command parms
    void                *auxP;                                  // ptr to pulldown menu item
    void                *popupWindP;                                    // ptr to popup window
    RawItemHdr *childFocusRiP;                                                  // child item which has focus
    ArrayObjectHdr *childArrayP;                                                        // array of child items
    };

Field	Description
userDataP	Stores a pointer to user-defined data. The dialog box manager does not store its information in this field.
accessStrP	Points to the item's access string. If this field is NULL, no access string exists.
labelP	Points to the item's label. If this field is NULL, no label exists.
labelPt	Specifies the position of the item's label in pixels.
itemRect	Specifies an item-specific rectangle for the item in pixels. The various item handlers use this field internally, and the field can be ignored.
helpInfo	Contains the value of the helpInfo field that is specified in the item's resource specification.
helpSource	Contains the value of the helpSource field that is specified in the item's resource specification.
synonymsId	Contains the value of the synonymsId field that is specified in the item's resource specification.
highlightOn	Specifies whether the item currently displays in a highlighted state. The various item handlers use this field internally, and the field can be ignored.
itemHookMD	The various item handlers use this field internally, and it should be ignored.
itemHookOffset	The various item handlers use this field internally, and it should be ignored.
itemHookArg	Contains the value of the itemHookArg field that is specified in the item's resource specification.
ownerDialogP	Points to the dialog box that contains the item.
diP	Points to the item's DialogItem field.
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.
itemHookId	The various item handlers use this field internally, and it should be ignored.
mnemonic	The dialog manager uses this field internally, and it should be ignored.
mneIndex	The various item handlers use this field internally, and it should be ignored.
nColorPs	The number of entries in colorsPP (typically set to DITEM_COLORTYPE_NCOLORS). This is an internally used field and should not be modified by the application.
colorsPP	The array of color descriptors for the item. This information in this array is set using mdlDialog_itemSetColor and retrieved using mdlDialog_itemGetColor.
itemHandlerP	The various item handlers use this field internally, and it should be ignored.
traveralRect	The various item handlers use this field internally, and it should be ignored.
ownerMD	Specifies the MDL Descriptor for the owning MDL task.
commandNumber	Command number to be queued when the item is activated.
comamndTaskId	Specifies the owner of the command to be queued.
unparsedP	Pointer to the unparsed character string to be queued along with the command.
auxP	The various item handlers use this field internally, and it should be ignored.
popupWindP	The various item handlers use this field internally, and it should be ignored.
childFocusRiP	The dialog manager uses this field internally, and it should be ignored.
childArrayP	The dialog manager uses this field internally, and it should be ignored.