Class

MessageDialogButton


Description

A button in a MessageDialog box. There are three possible MessageDialogButtons: ActionButton, CancelButton, and AlternateActionButton.

Properties

Name

Type

Read-Only

Shared

Caption

String

Cancel

Boolean

Default

Boolean

Visible

Boolean

Property descriptions


MessageDialogButton.Caption

Caption As String

The text displayed in the button.

Place a single "&" in front of any character to make it the shortcut key for the button. For example "&Don't Save" makes "D" the shortcut key.

This example sets Captions of the buttons.

Var d As New MessageDialog                       ' declare the MessageDialog object
Var b As MessageDialogButton                     ' for handling the result
d.IconType = MessageDialog.IconTypes.Caution     ' display warning icon

d.ActionButton.Caption = "Save"
d.CancelButton.Visible = True                    ' show the Cancel button
d.AlternateActionButton.Visible = True           ' show the "Don't Save" button
d.AlternateActionButton.Caption = "Don't Save"
d.AlternateActionButton.Cancel = True            ' sets AlternateAction button to cancel
d.Title = "This is the Title (Windows & Linux)"
d.Message = "Do you want to save changes to this document before closing?"
d.Explanation = "If you don't save, your changes will be lost."

b = d.ShowModal(Window1)                         ' display the dialog in the window
Select Case b                                    ' determine which button was pressed.
Case d.ActionButton
  ' user pressed Save
Case d.AlternateActionButton
  ' user pressed Don't Save
Case d.CancelButton
  ' user pressed Cancel
End Select

MessageDialogButton.Cancel

Cancel As Boolean

Set to True to indicate that the button will respond to the Esc key and, on Macintosh, pressing the Command-period sequence.

Only one button can be the Cancel button. Some operating systems do not allow one button to be both the Cancel and Default buttons.

This example shows how to set a button to be the default Cancel button. By default, the CancelButton is the default Cancel button, so this property is often not needed.

Var d As New MessageDialog                       ' declare the MessageDialog object
Var b As MessageDialogButton                     ' for handling the result
d.IconType = MessageDialog.IconTypes.Caution     ' display warning icon

d.ActionButton.Caption = "Save"
d.CancelButton.Visible = True                    ' show the Cancel button
d.AlternateActionButton.Visible = True           ' show the "Don't Save" button
d.AlternateActionButton.Caption = "Don't Save"
d.AlternateActionButton.Cancel = True            ' sets AlternateAction button to cancel
d.Title = "This is the Title (Windows & Linux)"
d.Message = "Do you want to save changes to this document before closing?"
d.Explanation = "If you don't save, your changes will be lost."

b = d.ShowModal(Window1)                         ' display the dialog in the window
Select Case b                                    ' determine which button was pressed.
Case d.ActionButton
  ' user pressed Save
Case d.AlternateActionButton
  ' user pressed Don't Save
Case d.CancelButton
  ' user pressed Cancel
End Select

MessageDialogButton.Default

Default As Boolean

Set to True to highlight the button as the default button in the MessageDialog. By default, the ActionButton's Default property is True.

The Default button will respond to the Enter and Return keys. Only one button can be the Default button. Some operating systems do not allow one button to be both the Default and Cancel buttons.

This example sets the "Don't Save" button as the default button.

Var d As New MessageDialog                       ' declare the MessageDialog object
Var b As MessageDialogButton                     ' for handling the result
d.IconType = MessageDialog.IconTypes.Caution     ' display warning icon

d.ActionButton.Caption = "Save"
d.CancelButton.Visible = True                    ' show the Cancel button
d.AlternateActionButton.Visible = True           ' show the "Don't Save" button
d.AlternateActionButton.Caption = "Don't Save"
d.AlternateActionButton.Default = True           ' Make it the default
d.Title = "This is the Title (Windows & Linux)"
d.Message = "Do you want to save changes to this document before closing?"
d.Explanation = "If you don't save, your changes will be lost."

b = d.ShowModal(Window1)                         ' display the dialog in the window
Select Case b                                    ' determine which button was pressed.
Case d.ActionButton
  ' user pressed Save
Case d.AlternateActionButton
  ' user pressed Don't Save
Case d.CancelButton
  ' user pressed Cancel
End Select

MessageDialogButton.Visible

Visible As Boolean

Set to True to show the button.

Only the ActionButton is shown by default. It has no effect on the ActionButton.

This example uses Visible to display the AlternateActionbutton.

Var d As New MessageDialog                       ' declare the MessageDialog object
Var b As MessageDialogButton                     ' for handling the result
d.IconType = MessageDialog.IconTypes.Caution     ' display warning icon

d.ActionButton.Caption = "Save"
d.CancelButton.Visible = True                    ' show the Cancel button
d.AlternateActionButton.Visible = True           ' show the "Don't Save" button
d.AlternateActionButton.Caption = "Don't Save"
d.AlternateActionButton.Cancel = True            ' sets AlternateAction button to cancel
d.Title = "This is the Title (Windows & Linux)"
d.Message = "Do you want to save changes to this document before closing?"
d.Explanation = "If you don't save, your changes will be lost."

b = d.ShowModal(Window1)                         ' display the dialog in the window
Select Case b                                    ' determine which button was pressed.
Case d.ActionButton
  ' user pressed Save
Case d.AlternateActionButton
  ' user pressed Don't Save
Case d.CancelButton
  ' user pressed Cancel
End Select

Notes

By default, only the ActionButton has its Visible property set to True. To show either of the other buttons in a MessageDialog, set their Visible properties.

Per Microsoft's recommendation, the text in MessageDialogButton.Caption should be limited to 26 characters on Windows. Exceeding this limit can lead to text being cut off or truncated.

Sample code

This example sets Captions of the buttons.

Var d As New MessageDialog                       ' declare the MessageDialog object
Var b As MessageDialogButton                     ' for handling the result
d.IconType = MessageDialog.IconTypes.Caution     ' display warning icon

d.ActionButton.Caption = "Save"
d.CancelButton.Visible = True                    ' show the Cancel button
d.AlternateActionButton.Visible = True           ' show the "Don't Save" button
d.AlternateActionButton.Caption = "Don't Save"
d.AlternateActionButton.Cancel = True            ' sets AlternateAction button to cancel
d.Title = "This is the Title (Windows & Linux)"
d.Message = "Do you want to save changes to this document before closing?"
d.Explanation = "If you don't save, your changes will be lost."

b = d.ShowModal(Window1)                         ' display the dialog in the window
Select Case b                                    ' determine which button was pressed.
Case d.ActionButton
  ' user pressed Save
Case d.AlternateActionButton
  ' user pressed Don't Save
Case d.CancelButton
  ' user pressed Cancel
End Select

Compatibility

All project types on all supported operating systems.

See also

Object parent class; MessageDialog, DesktopWindow classes.