Class

# MessageDialog

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Used to design and display customized message dialog boxes.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                                         | Type                                                                   | Read-Only | Shared |
|--------------------------------------------------------------|------------------------------------------------------------------------|-----------|--------|
| `ActionButton<messagedialog.actionbutton>`                   | `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>` |           |        |
| `AlternateActionButton<messagedialog.alternateactionbutton>` | `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>` |           |        |
| `CancelButton<messagedialog.cancelbutton>`                   | `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>` |           |        |
| `Explanation<messagedialog.explanation>`                     | `String</api/data_types/string>`                                       |           |        |
| `IconType<messagedialog.icontype>`                           | `IconTypes<messagedialog.icontypes>`                                   |           |        |
| `Message<messagedialog.message>`                             | `String</api/data_types/string>`                                       |           |        |
| `Title<messagedialog.title>`                                 | `String</api/data_types/string>`                                       |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                 | Parameters                                  | Returns                                                                | Shared |
|--------------------------------------|---------------------------------------------|------------------------------------------------------------------------|--------|
| `Show<messagedialog.show>`           | message As `String</api/data_types/string>` |                                                                        | ✓      |
| `ShowModal<messagedialog.showmodal>` |                                             | `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>` |        |

## Enumerations

<div id="messagedialog.icontypes">

<div class="rst-class">

forsearch

</div>

</div>

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

<div id="messagedialog.actionbutton">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.ActionButton

**ActionButton** As `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>`

> The button that performs the default action.
>
> The ActionButton's Visible property is `True</api/language/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</api/user_interface/desktop/desktopwindow>` class.
>
> ``` xojo
> Var d As New MessageDialog                   ' declare the MessageDialog object
>
> 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."
>
> Var b As MessageDialogButton                 ' for handling the result
>
> 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
> ```

<div id="messagedialog.alternateactionbutton">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.AlternateActionButton

**AlternateActionButton** As `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>`

> The optional button that performs an alternate action.
>
> The AlternateActionButton's Visible property is `False</api/language/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</api/user_interface/desktop/desktopwindow>` class.
>
> ``` xojo
> Var d As New MessageDialog                   ' declare the MessageDialog object
>
> 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."
>
> Var b As MessageDialogButton                 ' for handling the result
>
> 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
> ```

<div id="messagedialog.cancelbutton">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.CancelButton

**CancelButton** As `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>`

> The optional "Cancel" button.
>
> The CancelButton's Visible property is `False</api/language/false>` by default. Its default Caption is "Cancel".
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> 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.
>
> </div>
>
> The following example creates and manages a "Save Changes" dialog box without the need to create an instance of the `Window</api/user_interface/desktop/desktopwindow>` class.
>
> ``` xojo
> Var d As New MessageDialog                   ' declare the MessageDialog object
>
> 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."
>
> Var b As MessageDialogButton                 ' for handling the result
>
> 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
> ```

<div id="messagedialog.explanation">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.Explanation

**Explanation** As `String</api/data_types/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</api/user_interface/desktop/desktopwindow>` class.
>
> ``` xojo
> Var d As New MessageDialog                   ' declare the MessageDialog object
>
> 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."
>
> Var b As MessageDialogButton                 ' for handling the result
>
> 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
> ```

<div id="messagedialog.icontype">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.IconType

**IconType** As `IconTypes<messagedialog.icontypes>`

> Indicates the type of icon to be displayed in the dialog.
>
> Use the `IconTypes<messagedialog.icontypes>` enumeration to specify the icon type.

<div id="messagedialog.message">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.Message

**Message** As `String</api/data_types/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 macOS, 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</api/user_interface/desktop/desktopwindow>` class.
>
> ``` xojo
> Var d As New MessageDialog                   ' declare the MessageDialog object
>
> 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."
>
> Var b As MessageDialogButton                 ' for handling the result
>
> 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
> ```

<div id="messagedialog.title">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.Title

**Title** As `String</api/data_types/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</api/user_interface/desktop/desktopwindow>` class.
>
> ``` xojo
> Var d As New MessageDialog                   ' declare the MessageDialog object
>
> 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."
>
> Var b As MessageDialogButton                 ' for handling the result
>
> 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

<div id="messagedialog.show">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.Show

**Show**(message As `String</api/data_types/string>`)

> Displays the message in a <span class="title-ref">MessageDialog</span> window.
>
> This method is `shared</api/language/shared>`.
>
> For multi-platform compatibility, also look at the `MessageBox</api/user_interface/messagebox>` method.
>
> <div class="warning">
>
> <div class="title">
>
> Warning
>
> </div>
>
> You should avoid using <span class="title-ref">MessageDialog</span>.Show for displaying debugging messages. The displaying of the dialog will alter event order and may give unexpected results. Instead use the `Debugger</getting_started/debugging/debugger_usage>`, `System<system.debuglog>` or your own logging mechanism.
>
> </div>
>
> ``` xojo
> MessageDialog.Show("Hello, World!")
> ```

<div id="messagedialog.showmodal">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MessageDialog.ShowModal

**ShowModal** As `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>`

> Displays the <span class="title-ref">MessageDialog</span> window.
>
> It returns a `MessageDialogButton</api/user_interface/desktop/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</api/user_interface/desktop/desktopwindow>` class:
>
> ``` xojo
> Var d As New MessageDialog                   ' declare the MessageDialog object
>
> 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."
>
> Var b As MessageDialogButton                 ' for handling the result
>
> 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 <span class="title-ref">MessageDialog</span> 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</api/language/true>`. To use any other buttons, you must set their Visible properties to `True</api/language/true>`.

<div class="warning">

<div class="title">

Warning

</div>

You should avoid using <span class="title-ref">MessageDialog</span> for displaying debugging messages. The displaying of the dialog will alter event order and may give unexpected results. Instead use the `Debugger</getting_started/debugging/debugger_usage>`, `System.DebugLog<system.debuglog>` or your own logging mechanism.

</div>

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Icons

The four icons supported by <span class="title-ref">MessageDialog</span> 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 <span class="title-ref">MessageDialog</span>, the ShowModal method returns the `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>` that was pressed. You need to check this against the three types of `MessageDialogButtons</api/user_interface/desktop/messagedialogbutton>` belonging to the <span class="title-ref">MessageDialog</span> 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</api/user_interface/desktop/desktopwindow>` class.

``` xojo
Var d As New MessageDialog                   ' declare the MessageDialog object

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."

Var b As MessageDialogButton                 ' for handling the result

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

|                       |         |
|-----------------------|---------|
| **Project Types**     | Desktop |
| **Operating Systems** | All     |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `MessageDialogButton</api/user_interface/desktop/messagedialogbutton>`, `DesktopWindow</api/user_interface/desktop/desktopwindow>` classes.

</div>