Difference between revisions of "MessageDialog"

From Xojo Documentation

m (1 revision)
 
 
(41 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 +
{{SupportedPlatforms | type=d}}
 +
{{ClassBox
 +
| super=[[Object]]
 +
| platform=all
 +
| scope=global
 +
}}
 +
{{Description
 +
|text = Used to design and display customized message dialog boxes.}}
  
 +
<dynamicTable id="Properties" class="propertyTable" title="Properties" columns="3">
 +
{{Property | name=ActionButton | type=MessageDialogButton | platform=all | description=( MessageDialogButton)&nbsp;&nbsp;The button that performs the default action.  }}
 +
{{Property | name=AlternateActionButton | type=MessageDialogButton | platform=all | description=( MessageDialogButton)&nbsp;&nbsp;The optional button that performs an alternate action.  }}
 +
{{Property | name=CancelButton | type=MessageDialogButton | platform=all | description=( MessageDialogButton)&nbsp;&nbsp;The optional "cancel" button.  }}
 +
{{Property | name=Explanation | type=String | platform=all | description=( String)&nbsp;&nbsp;The text of a secondary message.  }}
 +
{{Property | name=IconType | description=( IconTypes)&nbsp;&nbspIndicates the type of icon to be displayed in the dialog box. }}
 +
{{Property | name=Message | type=String | platform=all | description=( String)&nbsp;&nbsp;The text of the message to be displayed.  }}
 +
{{Property | name=Title | type=String | platform=all | description=( String)&nbsp;&nbsp;Text to be displayed in the Title bar (Windows and Linux only). }}
 +
</dynamicTable>
  
−
=='''Description'''==
+
<dynamicTable id="Methods" class="methodTable" title="Methods" columns="3">
−
Used to design and display customized message dialog boxes. Similar to the [[MsgBox|MsgBox]] function but the '''MessageDialog''' class is much more flexible.
+
{{Method | name=ShowModal | returntype=[[MessageDialogButton]] | description=ShowModal() as MessageDialogButton&#x0A;Displays the MessageDialog window. }}
 +
{{Method | name=ShowModalWithin | params=Parent as [[Window]] | returntype=[[MessageDialogButton]] | newinversion=2005r1 | description=ShowModalWithin(Parent as Window) as MessageDialogButton&#x0A;Displays the MessageDialog window as a sheet window (macOS only) for the passed Window }}
 +
</dynamicTable>
  
 +
<dynamicTable id="Shared Methods" class="methodTable" title="Shared Methods" columns="3">
 +
{{Method | name=Show | description=Show(message As String)&#x0A;Displays the MessageDialog window with the passed message.}}
 +
</dynamicTable>
  
 +
<dynamicTable id="Enumerations" class="methodTable" title="Enumerations" columns="3">
 +
{{Enum | name=IconTypes | description=The types of icons that can be displayed (None, Caution, Note, Question, Stop).}}
 +
</dynamicTable>
  
−
=='''Super Class'''==
+
==Notes==
−
[[Object|Object]]
+
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]].
−
 
 
−
=='''Properties'''==
 
−
 
 
−
{| cellpadding="8" cellspacing="0" border="1"
 
−
 
 
−
! width=10%  style="background-color:#e0e0e0" | Name
 
−
 
 
−
! width=15%  style="background-color:#e0e0e0" | Type
 
−
 
 
−
! width=55%  style="background-color:#e0e0e0" | Description
 
−
|-
 
−
|ActionButton
 
−
 
 
−
|[[MessageDialogButton|MessageDialogButton]]
 
−
|The button that performs the default action.
 
−
The ActionButton's Visible property is [[True|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|MessageDialogButton]]
 
−
|The optional button that performs an alternate action.
 
−
The AlternateActionButton's Visible property is [[False|False]] by default. It has no default text; if you display it, you should specify its caption.
 
−
 
 
−
|-
 
−
|CancelButton
 
−
 
 
−
|[[MessageDialogButton|MessageDialogButton]]
 
−
|The optional "cancel" button.
 
−
The CancelButton's Visible property is [[False|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|True]].
 
−
 
 
−
|-
 
−
|Explanation
 
−
 
 
−
|[[String|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|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|OutOfBoundsException]] occurs.
 
−
 
 
−
|-
 
−
|Message
 
−
 
 
−
|[[String|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|String]]
 
−
|Text to be displayed in the Title bar (Windows and Linux only).
 
−
 
 
−
|-
 
−
|}
 
−
 
 
−
 
 
−
=='''Methods'''==
 
−
 
 
−
{| cellpadding="8" cellspacing="0" border="1"
 
−
 
 
−
! width=10%  style="background-color:#e0e0e0" | Name
 
−
 
 
−
! width=20%  style="background-color:#e0e0e0" | Parameters
 
−
 
 
−
! width=25%  style="background-color:#e0e0e0" | Return Type
 
−
 
 
−
! width=55%  style="background-color:#e0e0e0" | Description
 
−
|-
 
−
|ShowModal
 
−
 
 
−
|
 
−
|[[MessageDialogButton|MessageDialogButton]]
 
−
|Displays the '''MessageDialog''' window.
 
−
It returns a [[MessageDialogButton|MessageDialogButton]], which indicates which button was pressed. To find out which button was pressed, compare it to the button instances in the dialog.
 
−
 
 
−
|-
 
−
|ShowModalWithin
 
−
<div style="font-style:italic; color:green;">Introduced 2005r1</div>
 
−
|Parent as [[WindowClass|Window]]
 
−
|[[MessageDialogButton|MessageDialogButton]]
 
−
|Displays the '''MessageDialog''' window as a sheet window (Mac OS X only) for the passed [[WindowClass|Window]].
 
−
On other platforms, it displays the MessageDialog as a modal dialog (same as ShowModal). Returns a [[MessageDialogButton|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.
 
−
{| cellpadding="8" cellspacing="0" border="1"
 
−
 
 
−
! width=25%  style="background-color:#e0e0e0" | Class Constant
 
−
 
 
−
! width=55%  style="background-color:#e0e0e0" | 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|True]]. To use any other buttons, you must set their Visible properties to [[True|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 [[UserGuide:Debugger_Usage|Debugger]], [[System.DebugLog]] or your own logging mechanism.}}
  
 
===Icons===
 
===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.
+
The four icons supported by MessageDialog are not the same on all platforms. In particular, macOS shows the generic 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|MessageDialogButton]] that was pressed. You need to check this against the three types of [[MessageDialogButton|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 [[WindowClass|Window]] class.
 
−
{| cellpadding="8" cellspacing="0" border="1"
 
−
|<div style="width:100%; background-color:#d0d0d0; padding-left:30px">[[Dim|Dim]] d as [[New|New]] '''MessageDialog'''  //declare the MessageDialog object
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">[[Dim|Dim]] b as [[MessageDialogButton|MessageDialogButton]] //for handling the result
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">d.icon=MessageDialog.GraphicCaution  //display warning icon
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">d.ActionButton.Caption="Save"
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">d.CancelButton.Visible=[[True|True]]     //show the Cancel button
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">d.AlternateActionButton.Visible=[[True|True]]   //show the "Don't Save" button
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">d.AlternateActionButton.Caption="Don't Save"
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">d.Message="Do you want to save changes to this document"[[_|_]]        +" before closing?"
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">d.Explanation="If you don't save, your changes will be lost. "
 
−
<br /></div>
 
−
<br />
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">b=d.ShowModal    //display the dialog
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">[[Select|Select Case]] b //determine which button was pressed.
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">&#xA0;Case d.ActionButton
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">&#xA0;&#xA0;//user pressed Save
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">&#xA0;Case d.AlternateActionButton
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">&#xA0;&#xA0;//user pressed Don't Save
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">&#xA0;Case d.CancelButton
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">&#xA0;&#xA0;//user pressed Cancel
 
−
<br /></div>
 
−
<div style="width:100%; background-color:#d0d0d0; padding-left:30px">End select
 
−
<br /></div>
 
  
−
|-
+
===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 [[MessageDialogButton|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.
 +
<rbcode>
 +
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. "
  
−
=='''See Also'''==
+
b = d.ShowModal                            // display the dialog
−
[[MsgBox|MsgBox]] function, [[MessageDialogButton|MessageDialogButton]], [[WindowClass|Window]] classes.
+
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
 +
</rbcode>
  
 +
==See Also==
 +
[[MessageDialogButton]], [[Window]] classes.
  
−
[[Category:Windows]]
+
[[Category:Desktop]]
−
[[Category:Classes]]
 

Latest revision as of 01:56, 30 January 2021
Supported Platforms
Project Types: Desktop     Platforms: macOS, Windows, Linux

Class (inherits from Object)

Used to design and display customized message dialog boxes.

Properties
ActionButton Explanation Title
AlternateActionButton IconType
CancelButton Message
Methods
ShowModal ShowModalWithin
Shared Methods
Show
Enumerations
IconTypes

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.

fa-exclamation-circle-32.png
 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 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.

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

See Also

MessageDialogButton, Window classes.

Retrieved from "http://docs.xojo.com/index.php?title=MessageDialog&oldid=76910"