UserGuide

Desktop Dialog Boxes

From Xojo Documentation

There are several ways you can create dialog boxes in your apps. The easiest way is to use the MsgBox method. The MessageDialog class provides a bit more features. Lastly, you can create your own dialog with its own layout by creating a custom dialog box using a Window.

Message Box

You can display a Message Box to the user with the MsgBox function. This is useful for displaying a brief message to the user in the form of a modal dialog box. Pass the text that you want to display to the MsgBox function. For example, the following message could be shown when a file upload has completed successfully:

MsgBox("File transfer complete!")

This line of code displays a message box with the message and one button that the user can click to dismiss the dialog.

The MsgBox function has two optional parameters that provide some customization. You can pass an integer to display additional buttons, select the default button and display an icon.

If you use the optional parameters, the MsgBox function returns an integer that tells you which button the user clicked. If you display more than the one button, you should examine the value returned by the MsgBox function.

If the string that you pass to MsgBox contains a null character or unprintable characters, you should first filter them out prior to using the MsgBox function. The null character will terminate the string, no matter where it appears.

In general you should avoid using the MsgBox function for anything but the simplest of messages. It is very limited and you will be better served by using a Message Dialog instead.

Message Dialog

A Message Dialog is a much more flexible dialog that you can display to the user. By taking advantage of the MessageDialog class you can have more sophisticated dialog boxes than are possible with the MsgBox function.

With the MessageDialog class, you can present up to three buttons and control their text and functionality. You can also present subordinate explanatory text below the main message.

However, since MessageDialog is a class, you cannot accomplish all of this with a one line function call. You need to declare a variable as type MessageDialog, instantiate it, set its properties, and handle the result returned, which tells you which button the user pressed. This is a little bit more work, but the results are worth it.

A MessageDialog can have up to three buttons: ActionButton, CancelButton, and AlternateActionButton, which each have these properties:

Property Description
Caption The text displayed in the button.
Visible Indicates if the button is displayed. Set to True to show the button.

By default, only the ActionButton is shown, but you can show the others simply by setting their Visible properties to True.

MessageDialog on MacOS

In addition, you can set the text of the message, the subordinate explanation, the type of icon shown in the dialog (no icon, Note, Warning, Stop, or Question), and the title.

Not all of the icons are displayed on MacOS.

You present the customized dialog by calling the ShowModal method of the MessageDialog class.

After the user clicks a button, MessageDialog returns a MessageDialogButton object, which is either an ActionButton, CancelButton, or AlternateActionButton. By determining the type of object that was returned, you learn which button the user pressed. You can also examine the returned object's properties, if necessary.

Here is an example:

Dim dialog As New MessageDialog
dialog.Message = "Do you want to save changes to this document before closing?"
dialog.ActionButton.Caption = "Save"
dialog.CancelButton.Visible = True
dialog.CancelButton.Caption = "Cancel"
dialog.AlternateActionButton.Visible = True
dialog.AlternateActionButton.Caption = "Don't Save"
Dim dialogButton As MessageDialogButton
dialogButton = dialog.ShowModalWithin(Self)
Select Case dialogButton
Case dialog.ActionButton
// Save
Case dialog.AlternateActionButton
// Don't save
Case dialog.CancelButton
// Cancel
End Select

Custom Dialogs

There will be times when you need a more advanced dialog box, perhaps with additional controls or a more sophisticated layout than what MsgBox and MessageDialog offer. In these situations you can use a Modal Window as a dialog box.

To do this, add a Window to your project and set its Type property in the Inspector to one of these values:

  • Movable Modal: A modal dialog box with a title bar that the user can use to drag it around the screen.
  • Modal Dialog: A modal dialog box that cannot be moved around the screen by the user.
  • Sheet Window: Available only on MacOS, a sheet window drops down from the parent window. Because of this you do not see the title bar. On Windows and Linux, a Sheet Window behaves the same as a Movable Modal window.

On MacOS, it is important that you add a way for the dialog to close since there is no close button. Typically you use a button for this and in its Action event handler call Self.Close to close the dialog.

To make a value available for the caller to check, create a public property on the dialog window and set it to the value before you close the dialog.

This code (in the Action event handler of a button on a dialog) gets the selected text from a ListBox, assigns it to the SelectedName property and closes the dialog:

If NameList.ListIndex >= 0 Then
SelectedName = NameList.Text
Self.Close
End If

This is the code that calls the dialog window and assigns the SelectedName to a Label on the window:

Dim dialog As New DialogWindow
dialog.ShowModal
ResultLabel.Text = dialog.SelectedName

By default dialogs display centered on the main screen. You can reposition a dialog by setting its Left and Top properties. This code centers a dialog above its parent window:

Dim dialog As New DialogWindow
// Calculate center of parent (Self)
Dim dLeft As Integer = Self.Left + (Self.Width - dialog.Width) / 2
Dim dTop As Integer = Self.Top + (Self.Height - dialog.Height) / 2

// Change position to new center coordinates and show the dialog
dialog.Left = dLeft
dialog.Top = dTop
dialog.ShowModal

File Dialogs

Use the built-in file dialogs to create file open and save dialogs. They are:

For more information on how to use these, refer to the UserGuide:File Access topic.

See Also

MsgBox function; MessageDialog, Window, OpenDialog, SaveAsDialog, SelectFolderDialog classes