MessageDialog

From Xojo Documentation

Revision as of 18:55, 19 November 2009 by WikiSysop (talk) (1 revision)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Description

Used to design and display customized message dialog boxes. Similar to the MsgBox function but the MessageDialog class is much more flexible.


Super Class

Object

Properties

Name Type Description
ActionButton 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.

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

CancelButton MessageDialogButton The optional "cancel" button.

The CancelButton's Visible property is False by default. Its default Caption is "Cancel" or the equivalent in the language used by the application. To be safe, you should set the Caption property explicitly. If clicked, its Cancel property is set to True.

Explanation String The text of a secondary message.

On Macintosh only it appears in a smaller font size below Message. 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.

Icon Integer Number indicating the type of icon to be displayed in the dialog box.

These icons are supplied by the host operating system. You can use the following class constants to specify the icon: -1 - GraphicNone 0 - GraphicNote (The application icon on Mac OS X) 1 - GraphicCaution triangle (On Mac OS X, the application icon superimposed on the caution triangle) 2 - GraphicStop (On Mac OS X 10.3 and above, the application icon) 3 - GraphicQuestion icon (On Mac OS X 10.3 and above, it is the same as 0) See the Notes section in the pdf version of the Language Reference for screen shots of these icons on each platform. If the value of Icon is out of range, an OutOfBoundsException occurs.

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

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


Methods

Name Parameters Return Type Description
ShowModal 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.

ShowModalWithin
Introduced 2005r1
Parent as Window MessageDialogButton Displays the MessageDialog window as a sheet window (Mac OS X only) for the passed Window.

On other platforms, it displays the MessageDialog as a modal dialog (same as ShowModal). 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.


Class Constants

The following class constants are used to specify the value of the Icon property.

Class Constant Description
GraphicNone No icon.
GraphicNote The OS's Note icon or the application icon on Mac OS X
GraphicCaution The OS's Caution icon. On Mac OS X, the application icon superimposed on the Caution icon.
GraphicStop The OS's Stop icon. On Mac OS X 10.3 and above, the application icon.
GraphicQuestion The OS's Question icon. On Mac OS X 10.3 and above, the application icon.


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.


Icons

The four icons supported by MessageDialog are not the same on all platforms. In particular, Mac OS X shows the application icon for the values of 0, 2, and 3.


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.


Examples

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

Dim d as New MessageDialog //declare the MessageDialog object
Dim b as MessageDialogButton //for handling the result
d.icon=MessageDialog.GraphicCaution //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


See Also

MsgBox function, MessageDialogButton, Window classes.