The push button item activates commands when the data button is pressed and then released while the cursor is on the push button. A push button can also be activated by pressing the enter key if a user has given focus to that button by moving via the tab key.
The DialogItemRsc field extent specifies the location of the push button. If width is 0 the width of the label, plus an extra character on each side, is used. Since all buttons in a given dialog should have the same width, the width usually needs to be specified. BUTTON_STDWIDTH can be used for buttons with labels that have only five or six characters. Height should be 0. This height lets the push button item handler set a height that is the same for all push buttons.
The type field should contain PushButton.
The ID determines the DItem_PushButtonRsc instance to load.
The attributes field can be ON or OFF and optionally combined with HIDDEN. It will usually be ON.
The itemArg field is unused and should usually be set to 0.
The label field can override the label contained in the DItem_PushButtonRsc instance.
The auxInfo field is not used with push button items.
The following is an example of a push button item list specification:
The push button item is defined in a resource file with the following structure:
The DItem_PushButtonRsc structure has the following unique fields.See CommonItemResourceFields for a description of any field not in this table.
|isDefault||Indicates whether the push button is a dialog box's default button. Possible values are listed in the isDefault table below.|
|itemHookArg||When the standard push button item hook function is invoked by declaring HOOKITEMID_Button_StandardAction in the itemHookId field, itemHookArg specifies the actionType for the push button. |
actionType determines the behavior of push buttons in modal dialogs. It is sent to a dialog hook function as part of the DIALOG_MESSAGE_DESTROY message.
The values of itemHookArg listed in the itemHookArg table below have special meanings when the standard push button item hook function is attached to a push button in a modal dialog.
The following table lists possible values for the isDefault field (described above) and the meaning of those values:
|DEFAULT_BUTTON||The push button is a dialog box's default button. The push button is outlined with a recessed rectangle. The button will automatically be activated if the user presses the <Enter> key. |
In some situations, a double-click in a dialog box should also activate the default button. This action must be implemented manually by calling mdlDialog_pushButtonActivate.
In any dialog box there should be only one default push button.
|NOT_DEFAULT_BUTTON||The button is not a dialog box's default button.|
|CANCEL_BUTTON||The push button is a dialog box's cancel button. This type of push button is automatically activated if the user presses the <Esc> key and typically means that the operations to be performed by the dialog box should be aborted (cancelled). |
A dialog box should never contain more than one cancel button.
|PBUTATTR_ALIGNCENTER||This attribute automatically centers the push button label in the push button display rectangle. This is the default attribute.|
|PBUTATTR_ALIGNLEFT||This attribute causes the push button label text to be left aligned in the push button display rectangle.|
|PBUTATTR_ALIGNRIGHT||This attribute causes the push button label text to be right aligned in the push button display rectangle.|
The following table lists possible values for the itemHookArg field (described above) and the meaning of those values:
|ACTIONBUTTON_APPLY||When the push button is activated, the mdlDialog_itemSetState function will be called for each item in the dialog box. The dialog box will not be closed.|
|ACTIONBUTTON_RESET||When the push button is activated, the mdlDialog_itemSynch function is called for each item in the dialog box. The dialog box will not be closed.|
|ACTIONBUTTON_OK||When the pushbutton is activated, the mdlDialog_itemSetState function will be called for each item in the dialog box. The dialog box will then be closed.|
|ACTIONBUTTON_CANCEL||When the push button is activated, the dialog box will then be closed.|
Multi-lined push button items can be displayed by placing newline characters `\n' in the push button item label.
The following are examples of push button item resources:
The following messages are sent to item hook functions that are attached to push button items:
DITEM_MESSAGE_CREATE DITEM_MESSAGE_DESTROY DITEM_MESSAGE_BUTTON DITEM_MESSAGE_SYNCHRONIZE DITEM_MESSAGE_QUEUECOMMAND
|mdlDialog_pushButtonActivate||produces the same result as pressing the data button and then releasing it while the cursor is in the indicated push button. Thus, button and queue command messages are sent to any attached item hook function. If the hook function does not handle the DITEM_MESSAGE_QUEUECOMMAND message or if no hook function exists, the push button's non-zero commandNumber is placed at the end of MicroStation's input queue.|
|mdlDialog_pushButtonSetDefault||dynamically changes the default button in a dialog box.|
|mdlDialog_pushButtonSetCancel||dynamically changes the cancel button in a dialog box.|
|mdlDialog_pushButtonGetInfo||retrieves detailed information about a push button.|
|mdlDialog_pushButtonSetInfo||sets various aspects of a push button.|
Several default push buttons, are provided with MicroStation, and included in MicroStation's resource file. These may be included in dialogs by including in the DialogItemList Resource specification and optionally, overriding their labels in the label entry of the dialog item list entry. These are, (see Dlogids.h):
|PUSHBUTTONID_YesToAll||-12||Yes to All|