Class

MobileApplication

Description

The base class for mobile applications.

Methods

Name

Parameters

Returns

Shared

AddShortcut

type As String, title As String, subtitle As String, bundleIconName As String, userinfo As Dictionary

RemoveAllShortcuts

Events

Name

Parameters

Returns

Activated

Closing

Deactivating

HandleBackgroundURL

identifier As String

HandleShortcut

identifier As String, userInfo As String

Boolean

HandleURL

url As String, identifier As String, annotation As String, openInPlace As Boolean

Boolean

LaunchOptions

launchOptions As Ptr

Boolean

LowMemoryWarning

Opening

SignificantTimeChange

UnhandledException

exc As RuntimeException

Boolean

Property descriptions

MobileApplication.AndroidContextHandle

AndroidContextHandle As Ptr

Returns a Ptr that can be passed to libraries that require it.

This property is read-only.

Important

This property is supported for Android only.

MobileApplication.BugVersion

BugVersion As Integer

The version you increment when the release of your application is only to fix critical and unexpected bugs in the previous release.

This property is read-only.

This can only be set in the IDE, but you can read the value in your code.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Puts all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = app.MajorVersion.ToString + "." + app.MinorVersion.ToString + "." _
  + app.BugVersion.ToString + "." + app.NonReleaseVersion.ToString

MobileApplication.BuildDateTime

BuildDateTime As DateTime

Contains the date and time when the application was built.

This property is read-only.

Important

This property is supported for iOS only.

You can also access the CreationDateTime property of the application's FolderItem by calling App.ExecutableFile.CreationDate.

The following code gets the build date/time and displays it in a Label.

Var d As DateTime
d = App.BuildDateTime

Label1.Text = d.ToString

MobileApplication.CurrentLayout

CurrentLayout As iOSLayout

The currently displayed layout. You can use this property to access the current layout so that you can change its content.

This property is read-only.

The layout is typically the base (first) screen that was displayed in a phone app. It may also refer to a Split screen or a Tab screen.

In most cases you will want to use the MobileScreen method to display a new screen over the initial screen. This retains the screen hierarchy and allows the back button to go back to the previous screen.

There may be times when you need to replace the entire screen/layout and do not want the screen hierarchy. For example, you may have an initial login screen that is displayed but after the user successfully logs in and you want to replace that screen with another screen so that the back button does not return the user to the login screen.

Important

This property is supported for iOS only.

You can directly change the layout content like this to swap in a new screen:

Var myNewScreen As New MyScreen
App.CurrentLayout.Content = myNewScreen

Use the same technique to swap in a new MobileScreen, iOSLayout, iOSSplitView or iOSTabBar. For example, this swaps in a new screen:

Var s As New MySpecialScreen
App.CurrentLayout.Content = s.Content

MobileApplication.CurrentScreen

CurrentScreen As MobileScreen

The currently displayed screen. You can use this property to access the current screen so that you can change its content.

This property is read-only.

The screen is typically the base (first) screen that was displayed in a phone app. It may also refer to a Split screen or a Tab screen.

In most cases you will want to use the MobileScreen method to display a new screen over the initial screen. This retains the screen hierarchy and allows the back button to go back to the previous screen.

There may be times when you need to replace the entire screen and do not want the screen hierarchy. For example, you may have an initial login screen that is displayed but after the user successfully logs in and you want to replace that screen with another screen so that the back button does not return the user to the login screen.

Important

This property is supported for Android only.

You can directly change the current screen to swap in a new screen:

Var myNewScreen As New MyScreen
App.CurrentScreen = myNewScreen

MobileApplication.DefaultiPadScreen

DefaultiPadScreen As iOSLayout

Set to the default screen to use when the app is launched on an iPad-sized device.

This property is read-only.

Important

This property is supported for iOS only.

If no DefaultiPadScreen is specified, the app will still run on an iPad but will use the DefaultiPhoneScreen, running it in "scaled" mode.

One or both of DefaultiPhoneScreen and DefaultiPadScreen must be specified.

By specifying separate screens for DefaultiPhoneScreen and DefaultiPadScreen, you can have completely different layouts for each type of device.

MobileApplication.DefaultiPhoneScreen

DefaultiPhoneScreen As iOSLayout

Set to the default screen to use when the app is launched on an iPhone-sized device.

This property is read-only.

Important

This property is supported for iOS only.

If you do not specify a DefaultiPhoneScreen, then the app will not run on iPhone-sized devices.

One or both of DefaultiPhoneScreen and DefaultiPadScreen must be specified.

By specifying separate screens for DefaultiPhoneScreen and DefaultiPadScreen, you can have completely different layouts for each type of device.

MobileApplication.IconBadgeNumber

IconBadgeNumber As Integer

The number that appears in the badge on the application's icon.

A badge will only appear if the value is greater than 0.

Important

This property is supported for iOS only.

When building with Xojo 2021r3 and later versions, your app will be required to get permission to update the badge from the Notification Center.

App.IconBadgeNumber = App.IconBadgeNumber + 1

MobileApplication.MajorVersion

MajorVersion As Integer

The version to be incremented when the release includes many large new features.

This property is read-only.

This can only be set in the IDE, but you can read the value in your code.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Puts all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = App.MajorVersion.ToString + "." + App.MinorVersion.ToString + "." _
  + App.BugVersion.ToString + "." + App.NonReleaseVersion.ToString

MobileApplication.MinorVersion

MinorVersion As Integer

The version you increment when the release is does not add any major features.

This property is read-only.

This can only be set in the IDE, but you can read the value in your code.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Puts all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = app.MajorVersion.ToString + "." + app.MinorVersion.ToString + "." _
  + app.BugVersion.ToString + "." + app.NonReleaseVersion.ToString.

MobileApplication.NonReleaseVersion

NonReleaseVersion As Integer

The version you increment each time you build your project.

This property is read-only.

This can only be set in the IDE, but you can read the value in your code.

Some platforms also refer to this as the build or revision number.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

If AutoIncrementVersionInformation is checked, the IDE increases NonReleaseVersion by one each time you build your project, but not when you run it.

If your app is rejected by the Apple App Store for something minor, you can resolve it then increment this number to sufficiently distinguish it from the version you previously submitted.

Puts all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = app.MajorVersion.ToString + "." + app.MinorVersion.ToString + "." _
  + app.BugVersion.ToString + "." + app.NonReleaseVersion.ToString.

MobileApplication.StageCode

StageCode As Integer

Stage Code of the application, corresponding to the version information.

This property is read-only.

Important

This property is supported for iOS only.

Use the four Application class constants to set/get the Stage. Stage can be set only in the IDE.

Value

Description

0

Development

1

Alpha

2

Beta

3

Final

MobileApplication.TintColor

TintColor As ColorGroup

The default tint color for the controls in the application.

Important

This property is supported for iOS only.

MobileApplication.Version

Version As String

The version of the application.

This property is read-only.

Method descriptions

MobileApplication.AddShortcut

AddShortcut(type As String, title As String, subtitle As String, bundleIconName As String, userinfo As Dictionary)

Adds a shortcut to the app's shortcut menu.

Important

This method is supported for iOS only.

The shortcut menu is accessed by the user performing a long-press on the application's icon.

If you're going to add shortcuts via code, you should add all of your shortcuts in the Opening event.

Shortcuts can also be added using the Xojo IDE's visual editor. Click on iOS under Build Settings in the Navigator, choose the Advanced tab and then click on the Options button next to Shortcut Items in the Inspector.

Var credentials As New Dictionary
d.Value("username") = user.Name
d.Value("passwordHash") = user.PasswordHash
App.AddShortcut("userlogin", "Login", "Connect to your account", "person-badge", credentials)

MobileApplication.RemoveAllShortcuts

RemoveAllShortcuts

Removes all shortcuts from the application's shortcut menu.

Important

This method is supported for iOS only.

app.RemoveAllShortcuts

Event descriptions

MobileApplication.Activated

Activated

The app is now frontmost.

MobileApplication.Closing

Closing

The app is being closed by the OS.

The OS will close an app if the device is running low on memory. If can also occur if the user force quits the application.

The idea that an app quits on a mobile device is not one the user should be aware of. This means that in the Closing event, your app should store in a file any information about its current state so that when the app is relaunched, in the Opening event, you can restore the app to its previous state. Keep in mind that the amount of time the OS will give you to store your current state in the Closing event will be very limited.

MobileApplication.Deactivating

Deactivating

The app is being sent to the background.

MobileApplication.HandleBackgroundURL

HandleBackgroundURL(identifier As String)

Called when the app is passed a URL and is not in the foreground.

Important

This event is supported for iOS only.

MobileApplication.HandleShortcut

HandleShortcut(identifier As String, userInfo As String) As Boolean

Called when the user has chosen an item from the app's shortcut menu.

The shortcut menu is displayed when the user performs a long-press on the application's icon.

Important

This event is supported for iOS only.

MobileApplication.HandleURL

HandleURL(url As String, identifier As String, annotation As String, openInPlace As Boolean) As Boolean

Called when your app is passed a URL.

To add a URL scheme to your app, click on iOS under Build Settings in the Navigator then click on the Advanced tab in the Inspector. Enable Custom URL Schemes then click the Options button to add one. The scheme is the portion of the URL before the colon. For example, to add a scheme called feedback using with createcase as the path, enter feedback://createcase.

Important

This event is supported for iOS only.

MobileApplication.LaunchOptions

LaunchOptions(launchOptions As Ptr) As Boolean

Called when the app is launched.

The launchOptions parameter points to a NSDictionary provided by iOS. Use Declares to read this information. More information on this NSDictionary can be found in Apple's documentation.

If your app is being called to handle a URL, a background URL or a shortcut, implement those events instead.

If you are implementing this event to handle something else, return True if your app will handle the request and False if it will not.

Important

This event is supported for iOS only.

MobileApplication.LowMemoryWarning

LowMemoryWarning

Called when the OS reports a low-memory situation. Apps should attempt to free up objects and other resources when this event is raised. If the low-memory situation persists, the OS may kill your app.

Your implementation of this method should free up as much memory as possible by purging cached data objects that can be recreated (or reloaded from disk) later. It is strongly recommended that you implement this method. If your app does not release enough memory during low-memory conditions, the system may terminate it outright.

MobileApplication.Opening

Opening

Called when the app is first launched.

MobileApplication.SignificantTimeChange

SignificantTimeChange

Called when the device's clock has made a significant time change.

Significant time changes include each night at midnight, the change to/from Daylight Savings Time (in areas that recognize it), carrier updates and when the device moves from one time zone to another.

Important

This event is supported for iOS only.

MobileApplication.UnhandledException

UnhandledException(exc As RuntimeException) As Boolean

Called if the app had an exception and did not handle it. If the event is not implemented or the event handler returns False, the application will terminate.

Note

On Android, nothing that displays user interface (such as MessageBox) is supported for this event.

Notes

Changing your app name via code at build time

You can change the iOS App Name using an IDE Script like this:

PropertyValue("App.iOSAppName") = "MyApp"

Accepting files shared via other apps

To accept files shared with your app from other iOS apps, make sure you have defined a file type you wish to be able to receive. When the user shares a file with your app (via the Files app or the Sharing Panel), the HandleURL event will fire with the file will be passed as a file URL.

Compatibility

Mobile projects on all supported mobile operating systems.

See also

Object parent class; iOSLayout, iOSSplitView, iOSTabBar