Class

MessageDialog

Description

Used to design and display customized message dialog boxes.

Methods

Name

Parameters

Returns

Shared

Show

message As String

✓

ShowModal

MessageDialogButton

Enumerations

MessageDialog.IconTypes

IconTypes

The types of icons that can be displayed (None, Caution, Note, Question, Stop).

Enum

Description

None

Do not display an icon (macOS always displays the apps icon).

Caution

Displays a caution icon. On macOS, the app icon is overlaid on the caution icon.

Note

Displays a note icon. On macOS, only the app icon is displayed.

Question

Displays a question icon. On macOS, only the app icon is displayed.

Stop

Displays a stop icon. On macOS, only the app icon is displayed.

Property descriptions

MessageDialog.ActionButton

ActionButton As MessageDialogButton

The button that performs the default action.

The ActionButton's Visible property is True by default. By default, its caption is "OK" or an equivalent in the language used by the application. To be safe, you should set the caption property explicitly.

The following example creates and manages a "Save Changes" dialog box without the need to create an instance of the Window class.

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.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                              ' display the dialog
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

MessageDialog.AlternateActionButton

AlternateActionButton As MessageDialogButton

The optional button that performs an alternate action.

The AlternateActionButton's Visible property is False by default. It has no default text; if you display it, you should specify its caption.

The following example creates and manages a "Save Changes" dialog box without the need to create an instance of the Window class.

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.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                              ' display the dialog
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

MessageDialog.CancelButton

CancelButton As MessageDialogButton

The optional "Cancel" button.

The CancelButton's Visible property is False by default. Its default Caption is "Cancel".

Note: Be aware that the default caption may not appear localized on non-English systems. Therefore, if your application is localized for other languages, be sure to set this caption explicitly to the equivalent translation.

The following example creates and manages a "Save Changes" dialog box without the need to create an instance of the Window class.

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.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                              ' display the dialog
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

MessageDialog.Explanation

Explanation As String

The text of a secondary message.

This appears in a smaller font size below Message only on macOS. On other platforms it appears in the same font size as Message. Use this text to provide a fuller description of the situation, its consequences, and how to get out of it. For example, a warning that an action cannot be undone is an appropriate use of explanation text.

The following example creates and manages a "Save Changes" dialog box without the need to create an instance of the Window class.

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.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                              ' display the dialog
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

MessageDialog.IconType

IconType As IconTypes

Indicates the type of icon to be displayed in the dialog.

Use the IconTypes enumeration to specify the icon type.

MessageDialog.Message

Message As String

The text of the message to be displayed.

Use this property to present a short summary of the error, condition, or choice. Often, the message is posed as a question. On Macintosh, the text is emphasized in a bold font. Use the Explanation property for a more detailed message.

The following example creates and manages a "Save Changes" dialog box without the need to create an instance of the Window class.

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.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                              ' display the dialog
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

MessageDialog.Title

Title As String

Text to be displayed in the Title bar (Windows and Linux only).

The following example creates and manages a "Save Changes" dialog box without the need to create an instance of the Window class.

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.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                              ' display the dialog
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

Method descriptions

MessageDialog.Show

Show(message As String)

Displays the message in a MessageDialog window.

This method is shared.

For multi-platform compatibility, also look at the MessageBox method.

Warning

You should avoid using MessageDialog.Show for displaying debugging messages. The displaying of the dialog will alter event order and may give unexpected results. Instead use the Debugger, System or your own logging mechanism.

MessageDialog.Show("Hello, World!")

MessageDialog.ShowModal

ShowModal As MessageDialogButton

Displays the MessageDialog window.

It returns a MessageDialogButton, which indicates which button was pressed. To find out which button was pressed, compare it to the button instances in the dialog.

If a parentWindow is passed, the window being displayed will be modal to the parent window on macOS.

The following code creates and manages a "Save Changes" dialog box without the need to create an instance of the Window class:

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.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                              ' display the dialog
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

A MessageDialog dialog can have up to three buttons, an icon, and main and subordinate text. On Windows and Linux, it can also have text in its title bar. By default, only the ActionButton's Visible property is True. To use any other buttons, you must set their Visible properties to True.

Warning

You should avoid using MessageDialog for displaying debugging messages. The displaying of the dialog will alter event order and may give unexpected results. Instead use the Debugger, System.DebugLog or your own logging mechanism.

Icons

The four icons supported by MessageDialog are not the same on all platforms. In particular, macOS shows the generic application icon for the values None, Note, and Question.

Handling the button click

After the user has clicked a button in the MessageDialog, the ShowModal method returns the MessageDialogButton that was pressed. You need to check this against the three types of MessageDialogButtons belonging to the MessageDialog to determine which button the user clicked. See the example.

Sample code

The following code creates and manages a Save Changes dialog box without the need to create an instance of the Window class.

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.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                              ' display the dialog
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; MessageDialogButton, DesktopWindow classes.