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

MobileUIControl

Controls

Iterable

Handle

Ptr

Objects

Iterable

RemoveConstraint

constraint As iOSLayoutConstraint

RemoveControl

child As MobileControl

Show

parent As MobileScreen

makeCurrent As Boolean = False

ShowModal

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

ShowPopover

parentControl As MobileToolbarButton

parent As MobileUIControl

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.

Important

This is supported for iOS only.

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.

Important

This is supported for iOS only.

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

HasBackButton As Boolean

If True the Back button appears in the navigation bar.

This property is design time only.

Important

This property is only supported for Android.

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.

Important

This is supported for iOS only.

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

Important

This is supported for iOS only.

Add a button to the left Navigation Bar:

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

MobileScreen.Modal

Modal As Boolean

If True the screen will be displayed as a modal screen.

Important

This is supported for Android only.

MobileScreen.NavigationBarHeight

NavigationBarHeight As Integer

The height (in points) of the navigation bar.

Important

This is supported for Android only.

MobileScreen.NavigationToolbar

NavigationToolbar As MobileToolbar

The screen's toolbar.

Important

This is supported for Android only.

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.

Important

This is supported for iOS only.

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.

Important

This is supported for iOS 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.

Important

This is supported for iOS only.

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.

Important

This is supported for iOS only.

MobileScreen.TabIcon

TabIcon As Picture

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

Important

This is supported for iOS only.

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.

Important

This is supported for iOS only.

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.

Important

This is supported for iOS 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.

Important

This is supported for iOS only.

MobileScreen.AddControl

AddControl(child As MobileUIControl)

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.

Important

This is supported for iOS only.

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 MobileUIControl

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.

Note

This does not include non-control object instances. For that, use the Objects method.

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

Objects As Iterable

Allows you to iterate through all the non-control object instances on the MobileScreen.

Note

This does not include controls. For that, use the Controls method.

MobileScreen.RemoveConstraint

RemoveConstraint(constraint As iOSLayoutConstraint)

Removes the constraint from the Screen.

Important

This is supported for iOS only.

MobileScreen.RemoveControl

RemoveControl(child As MobileControl)

Removes the relationship between the child control and the its parent. It does not remove the control itself.

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.

Important

This signature is supported for iOS only.

Displays a new Screen:

Var newScreen As New Screen2
newScreen.Show

MobileScreen.Show

Show(makeCurrent As Boolean = False)

Displays the Screen by pushing it over the current screen such that pressing the Back button will take the user back to the previous screen.

If makeCurrent is True then the current screen is replaced by this screen and as such, the Back button will not take the user back to the previous screen.

Important

This signature is supported for Android only.

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.

Important

This is supported for iOS only. For Android, use the Modal property instead.

Show a dialog from the current Screen:

Var login As New LoginDialog
login.ShowModal

MobileScreen.ShowPopover

ShowPopover(parentControl As MobileToolbarButton)

Displays the screen as a popover below the parentControl.

ShowPopover(parentControl As MobileUIControl)

Displays the screen as a popover on top of the parentControl's screen.

This example from a button's Pressed event displays the screen named MyPopover:

Var c As New MyPopover
c.ShowPopover(Me)

Important

This method is not currently supported for Android.

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.

Important

This is supported for iOS only.

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.

Important

This is supported for iOS only.

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

KeyDown(key As String) As Boolean

The passed key has been pressed and not handled by a control on the MobileScreen. For example, The tab key is never sent to any control. It is instead handled by the MobileScreen itself. If the MobileScreen has no controls that can receive the focus, any keys that are pressed will generate KeyDown events for the MobileScreen. This event handler is passed a parameter that tells you which key was pressed.

Returns a Boolean. Returning True means that no further processing is to be done with the Key, although the KeyUp event is still called.

Important

This is supported for iOS only.

MobileScreen.KeyUp

KeyUp(key As String)

Fires when the passed key is released and no other control on the MobileScreen has captured the event. It is not guaranteed to be the same key that received the KeyDown event.

Important

This is supported for iOS only.

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

Resized

The screen's size has changed.

Important

This is supported for iOS only.

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

Interfaces

This class implements the iOSLayoutContent, iOSSplitContent, iOSTabContent and the iOSViewController class interfaces on iOS.

Compatibility

Mobile projects on all supported mobile operating systems.

See also

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