UserGuide

Difference between revisions of "Mobile Message Box"

From Xojo Documentation

Line 7: Line 7:
  
 
== Events ==
 
== Events ==
[[MobileMessageBox.Pressed|Pressed]]
+
[[MobileMessageBox.Pressed|Pressed]] - This event is called when one of the buttons on the Message Box is tapped, with a parameter containing the index of the button that was tapped.
:This event is called when one of the buttons on the Message Box is tapped, with a parameter containing the index of the button that was tapped.
 
  
 
== Properties ==
 
== Properties ==
[[MobileMessageBox.Message|Message]]
+
[[MobileMessageBox.Message|Message]] - This is the message to display in the Message Box. In the sample shown on the right it is the "This is a sample message." text.
:This is the message to display in the Message Box. In the sample shown on the right it is the "This is a sample message." text.
 
  
[[MobileMessageBox.Title|Title]]
+
[[MobileMessageBox.Title|Title]] - This is the title that appears at the top of the Message Box. In the sample shown on the right it is the "Hello" text.
:This is the title that appears at the top of the Message Box. In the sample shown on the right it is the "Hello" text.
 
  
 
== Methods ==
 
== Methods ==
[[MobileMessageBox.Buttons|Buttons]]
+
[[MobileMessageBox.Buttons|Buttons]] - These are the buttons to display.
:These are the buttons to display.
 
  
[[MobileMessageBox.Show|Show]]
+
[[MobileMessageBox.Show|Show]] - This displays the Message Box on the screen.
:This displays the Message Box on the screen.
 
  
 
== Usage ==
 
== Usage ==
 
[[File:iOS Message Box.png|thumb|iOS Message Box]]
 
[[File:iOS Message Box.png|thumb|iOS Message Box]]
 
The easiest way to use a Message Box is to drag it from the Library onto the Layout. The Inspector for a Message Box can be used to change the Message, Title, Left Button and Right Button properties. If you need more than two buttons, you can add them using code. When there are more than two buttons, they display vertically. This example adds three buttons to a Message Box that has been added to the Screen:
 
The easiest way to use a Message Box is to drag it from the Library onto the Layout. The Inspector for a Message Box can be used to change the Message, Title, Left Button and Right Button properties. If you need more than two buttons, you can add them using code. When there are more than two buttons, they display vertically. This example adds three buttons to a Message Box that has been added to the Screen:
<rbcode>Var buttons() As String
+
<rbcode>
 +
Var buttons() As String
 
buttons.AddRow("Yes")
 
buttons.AddRow("Yes")
 
buttons.AddRow("No")
 
buttons.AddRow("No")
Line 34: Line 30:
 
HelloMessage.Buttons = buttons
 
HelloMessage.Buttons = buttons
  
HelloMessage.Show</rbcode>
+
HelloMessage.Show
 +
</rbcode>
  
 
It is important to understand that your code does not pause at the "Show" call to wait for a button to be tapped. A Message Box is asynchronous, which means it displays immediately and your code continues running to the end of the method or event.
 
It is important to understand that your code does not pause at the "Show" call to wait for a button to be tapped. A Message Box is asynchronous, which means it displays immediately and your code continues running to the end of the method or event.
Line 41: Line 38:
  
 
To determine when a button was tapped, you must add the Pressed event handler to the Message Box. This event is called with a parameter containing the index of the button that was tapped. This code displays the index for the tapped button:
 
To determine when a button was tapped, you must add the Pressed event handler to the Message Box. This event is called with a parameter containing the index of the button that was tapped. This code displays the index for the tapped button:
<rbcode>Label1.Text = "You selected button " + buttonIndex.ToString</rbcode>
+
<rbcode>
 +
Label1.Text = "You selected button " + buttonIndex.ToString
 +
</rbcode>
  
 
=== More Advanced Technique ===
 
=== More Advanced Technique ===
 
[[File:iOS Message Box Vertical Buttons.png|thumb|iOS Message Box Vertical Buttons]]
 
[[File:iOS Message Box Vertical Buttons.png|thumb|iOS Message Box Vertical Buttons]]
 
You can also add a Message Box entirely in code, but you'll need to provide a method (on the View) to handle the Pressed event (using [[AddHandler]]). To add a simple Yes/No Message Box, start by adding a property to the Layout:
 
You can also add a Message Box entirely in code, but you'll need to provide a method (on the View) to handle the Pressed event (using [[AddHandler]]). To add a simple Yes/No Message Box, start by adding a property to the Layout:
<rbcode>SampleMessageBox As MobileMessageBox</rbcode>
+
<rbcode>
 +
SampleMessageBox As MobileMessageBox
 +
</rbcode>
  
 
In the code that displays the Message Box, create it and tell it to call a method when the Pressed is called. You might do this on a Button:
 
In the code that displays the Message Box, create it and tell it to call a method when the Pressed is called. You might do this on a Button:
<rbcode>SampleMessageBox = New MobileMessageBox
+
<rbcode>
 +
SampleMessageBox = New MobileMessageBox
 
SampleMessageBox.Title = "Hello"
 
SampleMessageBox.Title = "Hello"
 
SampleMessageBox.Message = "Hello, World!"
 
SampleMessageBox.Message = "Hello, World!"
Line 59: Line 61:
 
AddHandler SampleMessageBox.Pressed, AddressOf SampleButtonPressed
 
AddHandler SampleMessageBox.Pressed, AddressOf SampleButtonPressed
 
    
 
    
SampleMessageBox.Show</rbcode>
+
SampleMessageBox.Show
 +
</rbcode>
  
 
Now add the method to the Screen to perform an action and remove the handler:
 
Now add the method to the Screen to perform an action and remove the handler:
<rbcode>Private Sub SampleButtonPressed(sender As MobileMessageBox, index As Integer)
+
<rbcode>
 +
Private Sub SampleButtonPressed(sender As MobileMessageBox, index As Integer)
 
   OutputLabel.Text = "Button tapped."
 
   OutputLabel.Text = "Button tapped."
 
    
 
    
 
   RemoveHandler SampleMessageBox.ButtonPressed, AddressOf SampleButtonPressed
 
   RemoveHandler SampleMessageBox.ButtonPressed, AddressOf SampleButtonPressed
End Sub</rbcode>
+
End Sub
 +
</rbcode>
  
 
== See Also ==
 
== See Also ==

Revision as of 18:51, 15 February 2021

A MessageBox displays a prompt for the user. Although it is a user interface control, it does not appear on the Layout so when you drag it to your Layout, it is added to the Shelf.

Unlike with desktop a dialog (but similar to a web dialog), the Mobile Message Box is not modal. Your code does not stop executing when the Message Box is displayed. If you have code you want to run after the Message Box is closed, then put it in the Pressed event.

iOS Message Box Library Icon

Below are common events, properties and methods. Refer to MobileMessageBox in the Language Reference for the complete list.

Events

Pressed - This event is called when one of the buttons on the Message Box is tapped, with a parameter containing the index of the button that was tapped.

Properties

Message - This is the message to display in the Message Box. In the sample shown on the right it is the "This is a sample message." text.

Title - This is the title that appears at the top of the Message Box. In the sample shown on the right it is the "Hello" text.

Methods

Buttons - These are the buttons to display.

Show - This displays the Message Box on the screen.

Usage

iOS Message Box

The easiest way to use a Message Box is to drag it from the Library onto the Layout. The Inspector for a Message Box can be used to change the Message, Title, Left Button and Right Button properties. If you need more than two buttons, you can add them using code. When there are more than two buttons, they display vertically. This example adds three buttons to a Message Box that has been added to the Screen:

Var buttons() As String
buttons.AddRow("Yes")
buttons.AddRow("No")
buttons.AddRow("Maybe")

HelloMessage.Buttons = buttons

HelloMessage.Show

It is important to understand that your code does not pause at the "Show" call to wait for a button to be tapped. A Message Box is asynchronous, which means it displays immediately and your code continues running to the end of the method or event.

fa-info-circle-32.png
Calling the Show method does not pause your code until a button is tapped.

To determine when a button was tapped, you must add the Pressed event handler to the Message Box. This event is called with a parameter containing the index of the button that was tapped. This code displays the index for the tapped button:

Label1.Text = "You selected button " + buttonIndex.ToString

More Advanced Technique

iOS Message Box Vertical Buttons

You can also add a Message Box entirely in code, but you'll need to provide a method (on the View) to handle the Pressed event (using AddHandler). To add a simple Yes/No Message Box, start by adding a property to the Layout:

SampleMessageBox As MobileMessageBox

In the code that displays the Message Box, create it and tell it to call a method when the Pressed is called. You might do this on a Button:

SampleMessageBox = New MobileMessageBox
SampleMessageBox.Title = "Hello"
SampleMessageBox.Message = "Hello, World!"

Var buttons() As String
buttons.AddRow("OK")
SampleMessageBox.Buttons = buttons

AddHandler SampleMessageBox.Pressed, AddressOf SampleButtonPressed

SampleMessageBox.Show

Now add the method to the Screen to perform an action and remove the handler:

Private Sub SampleButtonPressed(sender As MobileMessageBox, index As Integer)
OutputLabel.Text = "Button tapped."

RemoveHandler SampleMessageBox.ButtonPressed, AddressOf SampleButtonPressed
End Sub

See Also

MobileMessageBox class; UserGuide:Mobile Dialog Boxes, UserGuide:iOS User Interface Controls topics