Difference between revisions of "MessageDialog"

From Xojo Documentation

(Notes)
 
(3 intermediate revisions by 2 users not shown)
Line 13: Line 13:
 
{{Property | name=CancelButton | type=MessageDialogButton | platform=all | description=( MessageDialogButton)  The optional "cancel" button.  }}
 
{{Property | name=CancelButton | type=MessageDialogButton | platform=all | description=( MessageDialogButton)  The optional "cancel" button.  }}
 
{{Property | name=Explanation | type=String | platform=all | description=( String)  The text of a secondary message.  }}
 
{{Property | name=Explanation | type=String | platform=all | description=( String)  The text of a secondary message.  }}
{{Property | name=Icon | type=Integer | platform=all | description=( Integer)  Number indicating the type of icon to be displayed in the dialog box. }}
+
{{Property | name=IconType | description=( IconTypes) &nbspIndicates the type of icon to be displayed in the dialog box. }}
 
{{Property | name=Message | type=String | platform=all | description=( String)  The text of the message to be displayed.  }}
 
{{Property | name=Message | type=String | platform=all | description=( String)  The text of the message to be displayed.  }}
 
{{Property | name=Title | type=String | platform=all | description=( String)  Text to be displayed in the Title bar (Windows and Linux only). }}
 
{{Property | name=Title | type=String | platform=all | description=( String)  Text to be displayed in the Title bar (Windows and Linux only). }}
 
</dynamicTable>
 
</dynamicTable>
 
  
 
<dynamicTable id="Methods" class="methodTable" title="Methods" columns="3">
 
<dynamicTable id="Methods" class="methodTable" title="Methods" columns="3">
 
{{Method | name=ShowModal | returntype=[[MessageDialogButton]] | description=ShowModal() as MessageDialogButton&#x0A;Displays the MessageDialog window. }}
 
{{Method | name=ShowModal | returntype=[[MessageDialogButton]] | description=ShowModal() as MessageDialogButton&#x0A;Displays the MessageDialog window. }}
{{Method | name=ShowModalWithin | params=Parent as [[WindowClass|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>
  
<dynamicTable id="Shared Methods" class="methodTable" title="Shared Methods" columns="2">
+
<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.}}
 
{{Method | name=Show | description=Show(message As String)&#x0A;Displays the MessageDialog window with the passed message.}}
 
</dynamicTable>
 
</dynamicTable>
  
==Class Constants==
+
<dynamicTable id="Enumerations" class="methodTable" title="Enumerations" columns="3">
The following class constants are used to specify the value of the Icon property.
+
{{Enum | name=IconTypes | description=The types of icons that can be displayed (None, Caution, Note, Question, Stop).}}
{| class="genericTable"
+
</dynamicTable>
 
 
! width=15% | Class Constant
 
 
 
! width=55% | Description
 
|-
 
|GraphicNone
 
 
 
|No icon
 
 
 
|-
 
|GraphicNote
 
 
 
|The OS's Note icon or the application icon on macOS
 
 
 
|-
 
|GraphicCaution
 
 
 
|The OS's Caution icon. On macOS, the application icon superimposed on the Caution icon.
 
 
 
|-
 
|GraphicStop
 
 
 
|The OS's Stop icon. On macOS, the application icon.
 
 
 
|-
 
|GraphicQuestion
 
 
 
|The OS's Question icon. On macOS, the application icon.
 
 
 
|-
 
|}
 
  
 
==Notes==
 
==Notes==
Line 71: Line 38:
 
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.
 
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.
  
The following series of screenshot shows the icons on the three platforms.
+
===Handling the Button Click===
 
 
{| cellpadding="8" cellspacing="0" border="1"
 
|+
 
! width="100" style="background-color:#e0e0e0" |
 
! width="100" style="background-color:#e0e0e0" | Note
 
! width="100" style="background-color:#e0e0e0" | Caution
 
! width="100"  style="background-color:#e0e0e0"| Stop
 
! width="100" style="background-color:#e0e0e0" | Question
 
|- style="height:100px"
 
! Windows
 
| [[File:Windows_Note.jpg|center]] || [[File:Windows_Caution.jpg|center]] || [[File:Windows_Stop.jpg|center]] || width="100" | [[File:Windows_question.jpg|center]]
 
|- style="height:100px"
 
! macOS
 
| [[File:Mac_note.jpg|center]] || [[File:Mac_Caution.jpg|center]] || [[File:Mac_note.jpg|center]] || [[File:Mac_note.jpg|center]]
 
|- style="height:100px"
 
! Linux
 
| [[File:NoteIcon.jpg|center]] || [[File:CautionIcon.jpg|center]] || [[File:StopIcon.jpg|center]] || [[File:QuestionIcon.jpg|center]]
 
|}
 
 
 
===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.
 
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.
  
==Example==
+
==Sample Code==
The following example creates and manages a &ldquo;Save Changes&rdquo; dialog box without the need to create an instance of the [[Window]] class.
+
The following code creates and manages a Save Changes dialog box without the need to create an instance of the [[Window]] class.
 
 
 
<rbcode>
 
<rbcode>
 
Var d As New MessageDialog                  // declare the MessageDialog object
 
Var d As New MessageDialog                  // declare the MessageDialog object
 
Var b As MessageDialogButton                // for handling the result
 
Var b As MessageDialogButton                // for handling the result
d.Icon = MessageDialog.GraphicCaution       // display warning icon
+
d.IconType = MessageDialog.IconTypes.Caution       // display warning icon
 
d.ActionButton.Caption = "Save"
 
d.ActionButton.Caption = "Save"
 
d.CancelButton.Visible = True              // show the Cancel button
 
d.CancelButton.Visible = True              // show the Cancel button
Line 120: Line 66:
  
 
==See Also==
 
==See Also==
[[MessageDialogButton]], [[Window]] classes.
+
[[MessageDialogButton]], [[DesktopWindow]] classes.
  
 
[[Category:Desktop]]
 
[[Category:Desktop]]

Latest revision as of 13:57, 21 September 2021

Class (inherits from Object)

Used to design and display customized message dialog boxes.

Properties
ActionButton Explanation Title
AlternateActionButton IconType
CancelButton Message
Methods
ShowModal
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, DesktopWindow classes.