Class

MobileScreen

Description

A screen is a layout of mobile controls.

Methods

Name

Parameters

Returns

Shared

AddConstraint

constraint As iOSLayoutConstraint

AddControl

child As MobileControl

Close

Constraint

name As String

iOSLayoutConstraint

ContentSize

Size

ControlAt

index As Integer

MobileControl

Controls

Iterable

Handle

Ptr

RemoveConstraint

constraint As iOSLayoutConstraint

RemoveControl

child As MobileControl

Show

parent As MobileScreen

ShowModal

parent As MobileScreen, style As ModalPresentationStyles = ModalPresentationStyles.Automatic, animate As Boolean = True

Size

Size

ViewControllerHandle

Ptr

Enumerations

MobileScreen.LargeTitleDisplayModes

LargeTitleDisplayModes

Used to specify how the screen's title should display.

Enum

Description

Automatic

Keep the title bar in whatever state is was for the previous screen.

Always

The title is always displayed large, regardless of the previous screen.

Never

The title never displays in large size.

MobileScreen.ModalPresentationStyles

ModalPresentationStyles

The various ways in which a modal screen can be displayed.

Enum

Description

Automatic

Default style chosen by the system.

CurrentContext

Appears entirely in front of the current screen.

Custom

Can be used with declares or plugins for custom animators.

FormSheet

Appears in front of, but not entirely obscuring, the current screen.

FullScreen

Appears entirely in front of the current screen.

OverCurrentContext

Appears entirely in front of the current screen.

OverFullScreen

Appears entirely in front of the current screen.

PageSheet

Appears in front of, but not entirely obscuring, the current screen.

Popover

Appears in a Popover view (for iPad).

Property descriptions

MobileScreen.BackButtonCaption

BackButtonCaption As String

The caption of the Back button that takes the user back to the current Screen.

The title of the Back button does not appear on the Back button for this Screen, but instead appears on the Back button for any Screens shown by this Screen (using the Show method). It is the caption for the Back button that goes back to this Screen.

Self.BackButtonCaption = "Customers"

MobileScreen.BottomLayoutGuide

BottomLayoutGuide As Object

The bottom layout guide for the Screen.

This property is read-only.

This is used when creating iOSLayoutConstraint.Bottom is the absolute bottom of the View. BottomLayoutGuide is adjusted for things such as a Toolbar or TabBar.

MobileScreen.ControlCount

ControlCount As Integer

The number of controls on the Screen.

This property is read-only.

Get the number of controls on the Screen:

Var count As Integer = Self.ControlCount

MobileScreen.HasNavigationBar

HasNavigationBar As Boolean

Indicates whether the Navigation Bar is visible.

The Navigation Bar must be visible in order to see the Title, LeftNavigationToolbar, RightNavigationToolbar or Back button.

Display the Navigation Bar:

Self.HasNavigationBar = True

MobileScreen.LargeTitleDisplayMode

LargeTitleDisplayMode As LargeTitleDisplayModes

Dictates if and when the screen title should be displayed in a larger size.

// Always display the title in a large font size
Self.LargeTitleDisplayMode = MobileScreen.LargeTitleDisplayModes.Always

MobileScreen.LeftNavigationToolbar

LeftNavigationToolbar As MobileToolbar

The toolbar to display to the left of the Navigation Bar.

This is only visible when HasNavigationBar = True.

Add a button to the left Navigation Bar:

Var cameraButton As New MobileToolbarButton(MobileToolbarButton.Types.Camera)
LeftNavigationToolbar.AddButton(cameraButton)

MobileScreen.ParentSplitScreen

ParentSplitScreen As iOSSplitView

Indicates the split Screen that is the owner of this Screen. It is Nil is there is no split screen.

This property is read-only.

A split screen can only be used on iPad devices. Use this property to determine if a iOSSplitView is displayed. You can then use it to get access to the Master and Detail screens that are displayed.

If a iOSSplitView is used, then populate the detail side, otherwise, push a new screen onto the iOSSplitView:

If Self.ParentSplitScreen <> Nil Then
  // In the SelectionChanged event for a Table on a Master view of the split screen.
  // Gets the Text for the selected row and
  // assigns it to a Label on the DetailScreen of the split screen.
  DetailScreen(Self.ParentSplitScreen.Detail).Label1.Text = Me.RowCellData(row).Text
Else
  // No split screen, so this is a phone.
  // Display the Detail Screen and update the text for its label.
  Var d As New DetailScreen
  d.Label1.Text = Me.RowCellData(row).Text
  d.Show
End If

MobileScreen.ParentTabBar

ParentTabBar As iOSTabBar

Indicates the Tab Bar that is the owner of this Screen. It is Nil if there is no Tab Bar.

This property is read-only.

Add a new View to the Tab Bar:

// This code (on a Screen) adds Screen3 to the Tab Bar
If Self.ParentTabBar <> Nil Then
  Var v As New Screen3
  Self.ParentTabBar.AddTab(v)
End If

MobileScreen.RightNavigationToolbar

RightNavigationToolbar As MobileToolbar

The toolbar to display to the right of the Navigation Bar.

This is only visible when HasNavigationBar = True.

Add a button to the right Navigation Bar:

Var cameraButton As New MobileToolbarButton(MobileToolbarButton.Types.Camera)
RightNavigationToolbar.AddButton(cameraButton)

MobileScreen.TabBarVisible

TabBarVisible As Boolean

If True, the tab bar is visible when the screen is shown. Changing this after the screen is shown has no effect.

MobileScreen.TabIcon

TabIcon As Picture

The icon for the tab upon which this Screen is displayed.

MobileScreen.TintColor

TintColor As ColorGroup

Overrides the default tint color of controls within this screen, for example Button captions, Progress Bars and Slider tracks.

The TintColor can be a ColorGroup created in code or one you have created as a project item.

Because this is a ColorGroup, you can create a Dual-color ColorGroup so that the TintColor will automatically be correct in Dark versus Light mode.

In the Opening event, set the background color to a ColorGroup in the project called MyTheme:

Me.TintColor = MyTheme

MobileScreen.Title

Title As String

The title for the Navigation Bar.

This only appears if HasNavigationBar is True.

Change the title for the Screen:

Self.Title = "Customers"

MobileScreen.Toolbar

Toolbar As MobileToolbar

The toolbar that is displayed in the Screen, typically at the bottom.

Add a button to the Toolbar:

Var button As New MobileToolbarButton(MobileToolbarButton.Types.Camera)
Toolbar.AddButton(button)

MobileScreen.TopLayoutGuide

TopLayoutGuide As Object

The top layout guide for the Screen.

This property is read-only.

This is used when creating iOSLayoutConstraint.Top is the absolute top of the View. TopLayoutGuide is adjusted for things such as a NavigationBar.

Method descriptions

MobileScreen.AddConstraint

AddConstraint(constraint As iOSLayoutConstraint)

Adds the constraint to the Screen.

MobileScreen.AddControl

AddControl(child As MobileControl)

Adds a control to the Screen.

Add a control to the Screen:

Var ctrl As New MobileSwitch
// Send its ValueChanged event to the SwitchValueChanged method on the View
AddHandler ctrl.ValueChanged, AddressOf SwitchValueChanged
Self.AddControl(ctrl)

MobileScreen.Close

Close

For Screens that were displayed using Show or ShowModal, this closes the Screen causing the previous Screen to display.

Since calling Close displays the previous Screen, you can call it to simulate the user pressing a "Back" button on the Screen.

You cannot close the main Screen (the one that is specified as the Content for the iOS Layout), however you can swap in another Screen by using the MobileApplication.CurrentLayout property.

MobileScreen.Constraint

Constraint(name As String) As iOSLayoutConstraint

Gets a reference to a named constraint so that you can modify its settings in code.

Change an existing (and named) constraint of a control on the Screen:

// "TAWidth" is a width constraint for a TextField that has been given
// a name in the auto-layout Inspector properties.
Var c As iOSLayoutConstraint = Self.Constraint("TAWidth")
c.Offset = 200

MobileScreen.ContentSize

ContentSize As Size

The size (in points) of the content area of the Screen. This excludes the Navigation Bar, Tab Bar and Toolbar if they are on the Screen.

Get the content size of the Screen:

Var screenSize As String = Self.ContentSize.Width.ToString + " by " + Self.ContentSize.Height.ToString

MobileScreen.ControlAt

ControlAt(index As Integer) As MobileControl

Gets the control at the index passed.

Get the name of the first control on the Screen:

Var controlName As String = Self.ControlAt(0).Name

MobileScreen.Controls

Controls As Iterable

Used to iterate through the controls on a Screen.

All controls on the Screen are returned as a the MobileControl base type. You can use the IsA operator to check the specific type to see if the control is a MobileButton, MobileLabel, etc.

Loop through all the controls on a Screen and disable only the TextFields:

For Each c As MobileUIControl In Self.Controls
  If c IsA MobileTextField Then
    MobileTextField(c).Enabled = False
  End If
Next

MobileScreen.Handle

Handle As Ptr

The handle to use when creating Declares to the underlying OS object.

On iOS, the underlying OS object is a UIView.

MobileScreen.RemoveConstraint

RemoveConstraint(constraint As iOSLayoutConstraint)

Removes the constraint from the Screen.

MobileScreen.RemoveControl

RemoveControl(child As MobileControl)

Removes the control from the Screen.

MobileScreen.Show

Show(parent As MobileScreen)

Displays the Screen by "pushing" it over the parent Screen passed.

Show displays a new Screen over the current Screen, placing it on the "stack" so that the back functionality of the new Screen can be used to go back to the previous Screen. If you need to just change the current Screen without affecting the stack, you can do so by using the MobileApplication.CurrentLayout property.

Use the Close method to close the new Screen and go back to the previous Screen.

If you using an iOSTabBar or using an iOSSplitView, you'll need to pass as the parent parameter the MobileScreen in front of which you wish the modal dialog to appear.

Displays a new Screen:

Var newScreen As New Screen2
newScreen.Show

MobileScreen.ShowModal

ShowModal(parent As MobileScreen, style As ModalPresentationStyles = ModalPresentationStyles.Automatic, animate As Boolean = True)

Displays the Screen passed as a modal Screen.

A modal Screen has no navigation bar with a back button the user can use to return to the previous screen.

If you using an iOSTabBar or using an iOSSplitView, you'll need to pass as the parent parameter the MobileScreen in front of which you wish the modal dialog to appear.

Show a dialog from the current Screen:

Var login As New LoginDialog
login.ShowModal

MobileScreen.Size

Size As Size

The size (in points) of the entire Screen area.

Get the size of the Screen:

Var screenSize As String = Self.Size.Width.ToString + " by " + Self.Size.Height.ToString

MobileScreen.ViewControllerHandle

ViewControllerHandle As Ptr

The handle to use when creating Declares to the underlying OS object.

On iOS, the underlying OS object is a UIViewController.

Event descriptions

MobileScreen.Activated

Activated

Called when the Screen is activated.

This occurs when: * the screen first opens * the screen reappears after a screen pushed from it is closed

MobileScreen.AppearanceChanged

AppearanceChanged(dark As Boolean)

Called when a user switches between Light and Dark mode.

Use this event to update any graphics or other UI as needed.

MobileScreen.Closing

Closing

Called when the Screen is closed by calling the Close method.

MobileScreen.Deactivated

Deactivated

Called when the Screen is deactivated.

This occurs when:

  • The Screen is closed by calling the Close method or the user tapping the Back button

  • Another Screen is opened (pushed) onto this Screen

MobileScreen.Opening

Opening

Called when the Screen first appears and typically used for initialization.

MobileScreen.OrientationChanged

OrientationChanged

The device has been rotated enough to switch between portrait and landscape orientations. This event also occurs immediately after the Opening event should the app need to make changes based upon device orientation.

MobileScreen.ToolbarButtonPressed

ToolbarButtonPressed(button As MobileToolbarButton)

Called when a button on the left or right Navigation Bar or the Toolbar is pressed.

Check for a button pressed based on its caption:

Select Case button.Caption
  Case "Save"
    // call save code
  Case "Edit"
    // call edit code
End Select

Check for a button pressed based on its name:

Select Case button.Caption
  Case SaveButton
    // call save code
  Case EditButton
    // call edit code
End Select

Check for a button pressed based on its type:

Select Case button.Type
Case MobileToolbarButton.Types.Save
  // call save code
Case MobileToolbarButton.Types.Edit
  // call edit code
End Select

Notes

A Screen is the mobile equivalent of a window for the desktop or a webpage for the web.

Compatibility

Mobile projects on all supported mobile operating systems.

See also

Object parent class; iOSTabBar, MobileToolbar, iOSLayoutConstraint, iOSSplitView classes.