Push Button Item

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.

v8pushbutton.jpg

Item list specification

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:

PUSHBUTTONID_Precision, ON, 0, "", ""}

Item resource specification

The push button item is defined in a resource file with the following structure:

typedef struct ditem_pushbuttonrsc
{
char isDefault; // TRUE if this is default button
ULong helpInfo;
ULong helpSource;
long itemHookId;
long itemHookArg;
ULong commandNumber;
ULong commandSource;
#if defined (resource)
char unparsed[];
char label[];
#else
long unparsedLength;
char unparsed[1];
#endif
} DItem_PushButtonRsc;

The DItem_PushButtonRsc structure has the following unique fields.See CommonItemResourceFields for a description of any field not in this table.

Field Description
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:

isDefault Value Meaning
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:

itemHookArg Value Meaning
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:

DItem_PushButtonRsc PUSHBUTTONID_Precision=
{
NOHOOK, NOARG, CMD_POINT_DEFAULT, MCMD, "", "Apply"
}
DItem_PushButtonRsc PUSHBUTTONID_MultiLineLeft=
{
NOARG, CMD_POINT_DEFAULT, MCMD, "", "Left\nAligned\nMultilined"
}

Item hook function messages

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

Push button item functions

Funtion Description
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):

Name ID Default Label
PUSHBUTTONID_Apply -1 Apply
PUSHBUTTONID_Reset -2 Reset
PUSHBUTTONID_OK -3 Ok
PUSHBUTTONID_Cancel -4 Cancel
PUSHBUTTONID_Default -5 Default
PUSHBUTTONID_OKNotDefault -6 Ok
PUSHBUTTONID_Yes -7 Yes
PUSHBUTTONID_No -8 No
PUSHBUTTONID_Retry -9 Retry
PUSHBUTTONID_Stop -10 Stop
PUSHBUTTONID_Help -11 Help
PUSHBUTTONID_YesToAll -12 Yes to All

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.