Class
MobileApplication
Description
The base class for mobile applications.
Properties
Name |
Type |
Read-Only |
Shared |
---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
DefaultPhoneScreen |
|||
DefaultTabletScreen |
|||
IconBadgeNumber |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
type As String, title As String, subtitle As String, bundleIconName As String, userinfo As Dictionary |
|||
Events
Name |
Parameters |
Returns |
---|---|---|
identifier As String |
||
url As String, identifier As String, annotation As String, openInPlace As Boolean |
||
launchOptions As Ptr |
||
exc As RuntimeException |
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.
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.DefaultPhoneScreen
DefaultPhoneScreen As MobileScreen
Set to the default screen to use when the app is launched on a phone-sized device.
This property is read-only.
Important
This property is supported for Android only.
By specifying separate screens for DefaultPhoneScreen and DefaultTabletScreen, you can have completely different layouts for each type of device.
MobileApplication.DefaultTabletScreen
DefaultTabletScreen As MobileScreen
Set to the default screen to use when the app is launched on an tablet-sized device.
This property is read-only.
Important
This property is supported for Android only.
By specifying separate screens for DefaultPhoneScreen and DefaultTabletScreen, 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.
Note
For Android applications submitted to the Google Play Store, the NonReleaseVersion must always be a higher value than it was the last time the application was submitted.
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"
Compatibility
Mobile projects on all supported mobile operating systems.
See also
Object parent class; iOSLayout, iOSSplitView, iOSTabBar