Class: Toybox.Application.AppBase

Inherits:
Toybox.Lang.Object show all

Overview

AppBase is the base class for an app.

All apps inherit from this class and use it's methods to manage the life cycle of an app.

Every AppBase object has access to an object store to persist data.

Example:

Shows basic app life cycle

using Toybox.Application;
class AppLifeCycle extends Application.AppBase {
    // initialize the AppBase class
    function initialize() {
        AppBase.initialize();
    }
    // onStart() is called on application start up
    function onStart(state) {
    }
    // onStop() is called when your application is exiting
    function onStop(state) {
    }
    // Return the initial view of your application here
    function getInitialView() {
        return [new AppLifeCycleView()];
    }
}

Since:

API Level 1.0.0

Direct Known Subclasses

Application.AudioContentProviderApp

Constant Summary

GlanceTheme

Glance color themes for supported devices

Since:

API Level 4.0.0

Name Value Since Description See Also
GLANCE_THEME_DEFAULT 0

API Level 4.0.0

GLANCE_THEME_BLUE 1

API Level 4.0.0

GLANCE_THEME_GOLD 2

API Level 4.0.0

GLANCE_THEME_GREEN 3

API Level 4.0.0

GLANCE_THEME_LIGHT_BLUE 4

API Level 4.0.0

GLANCE_THEME_RED 5

API Level 4.0.0

GLANCE_THEME_WHITE 6

API Level 4.0.0

GLANCE_THEME_PURPLE 7

API Level 4.0.0

Instance Method Summary collapse

Instance Method Details

allowTrialMessage() as Lang.Boolean

Check if application trial messages are allowed.

Returns true if the application should allow the product to push unlock instruction pages for locked apps. Returns true by default.

Returns:

  • Lang.Boolean —

    Returns true if trial messages should be shown, otherwise false.

Since:

API Level 2.3.0

clearProperties() as Void

This has been deprecated

This method may be removed after System 4.

Clear the object store for the application.

Note:

Background processes cannot clear properties.

Supported Devices:

See Also:

Since:

API Level 1.0.0

Throws:

deleteProperty(key as Application.PropertyKeyType) as Void

This has been deprecated

This method may be removed after System 4.

Delete the given key from the object store.

Note:

Background processes cannot delete properties.

Parameters:

Supported Devices:

See Also:

Since:

API Level 1.0.0

Throws:

getGlanceTheme() as AppBase.GlanceTheme

Method to get the glance theme.

Supported Devices:

Since:

API Level 4.0.0

getGlanceView() as [ WatchUi.GlanceView ] or [ WatchUi.GlanceView, WatchUi.GlanceViewDelegate ] or Null

Override to provide the WatchUi.GlanceView and WatchUi.GlanceViewDelegate for the glance preview.

Supported Devices:

Returns:

Since:

API Level 3.1.0

getGoalView(goalType as Application.GoalType) as [ WatchUi.View ] or Null

Override to provide a WatchUi.View for a goal that has triggered within a watch face.

  • If a goal is reached when a watch face is running, this function will be triggered.

  • The type of goal that was met will be provided, and the AppBase should return a View that displays a goal reached message and/or animations for that goal.

  • If a View is returned from this function, the main watch face view will be shutdown, and then new View will pushed.

  • If this method is not overridden in the AppBase, or if it returns null, the native goal screens will be shown.

Parameters:

  • goalType — (Application.GoalType) —

    The goal type that has triggered. The goalType will be from the GOAL_TYPE_* enumeration.

Returns:

Since:

API Level 1.3.0

getInitialView() as [ WatchUi.Views ] or [ WatchUi.Views, WatchUi.InputDelegates ]

Override to provide the initial View and Input Delegate of the application.

Note:

This method must be overridden in derived classes. If called, this function will cause the application to crash.

Returns:

Since:

API Level 1.0.0

getProperty(key as Application.PropertyKeyType) as Application.PropertyValueType

This has been deprecated

This method may be removed after System 4.

Get the data associated with a given key from the object store.

Properties must first be set with setProperty() before they are can be obtained with getProperty.

Note:

Symbols can change from build to build and are not to be used for for Keys or Values.

Parameters:

  • key —

    The key of the value to retrieve from the object store (cannot be a Symbol)

Supported Devices:

Returns:

  • Lang.Object —

    The content associated with the key, or null if the key is not in the object store

See Also:

Since:

API Level 1.0.0

getServiceDelegate() as [ System.ServiceDelegate ]

Get a ServiceDelegate to run background tasks for this app.

When a ServiceDelegate is retrieved, the following will occur:

  • The method triggered within the ServiceDelegate will be run

  • The background task will exit using Background.exit() or System.exit()

  • The background task will be automatically terminated after 30 seconds if it is not exited by these methods

Returns:

See Also:

Since:

API Level 2.3.0

getSettingsView() as [ WatchUi.Views ] or [ WatchUi.Views, WatchUi.InputDelegates ] or Null

Override to provide the settings View and Input Delegate of the application.

  • This function is only applicable to watch faces and data fields.

Supported Devices:

Returns:

Since:

API Level 3.2.0

getSyncDelegate() as Communications.SyncDelegate or Null

Get a SyncDelegate object that communicates sync status to the system for syncing content to the device.

Supported Devices:

Returns:

Since:

API Level 3.1.0

getTrialDaysRemaining() as Lang.Number or Null

Override to return the number of days remaining in the trial

If a developer wishes to implement time-based app trials, they will need to override this function to return the number of days remaining in the trial. This function will be called on app startup to determine if a trial is active and push a notice to the user of how many days remain in the trial. Note that if allowTrialMessage() is overridden to return false, no notifications will be displayed.

Returns:

  • Lang.Number —

    A Number object indicating the number of days remaining in the trial, or null if no timed trial is active.

Since:

API Level 2.3.0

isActive() as Lang.Boolean

return true if app is currently in active state, otherwise false.

Supported Devices:

Since:

API Level 4.2.3

isTrial() as Lang.Boolean

Check if the application is in trial mode.

This will always return true for development build apps. If the app has been signed by the store it will return the current unlock state of the app. This method should not be overridden or your trial mode functionality could cease to function correctly.

Returns:

  • Lang.Boolean —

    Return true if the app is "locked" and considered to be in trial mode, otherwise false if the app has been unlocked.

Since:

API Level 2.3.0

loadProperties() as Void

This has been deprecated

This method may be removed after System 4.

Load the properties for the application

Supported Devices:

Since:

API Level 1.0.0

onActive(state as Lang.Dictionary or Null) as Void

Invoked when app enters active mode, i.e. occupying screen in the foreground.

Parameters:

Supported Devices:

Since:

API Level 4.2.3

onAppInstall() as Void

The callback method that is triggered in the background when the app is installed. Requires the Background permission to be enabled and your application class to carry the :background annotation.

Since:

API Level 3.0.0

onAppUpdate() as Void

The callback method that is triggered in the background when the app is updated Requires the Background permission to be enabled and your application class to carry the :background annotation.

Since:

API Level 3.0.0

onAuthenticationRequest() as Void

Called when an Application requests to run code on demand, during an authentication process.

Since:

API Level 3.3.0

onBackgroundData(data as Application.PersistableType) as Void

Handle data passed from a ServiceDelegate to the application.

When the Background process terminates, a data payload may be available. If the main application is active when this occurs, the data will be passed directly to the application's onBackgroundData() method. If the main application is not active, the data will be saved until the next time the application is launched and will be passed to the application after the onStart() method completes.

Parameters:

  • data — (Lang.Object) —

    The data passed from the background process.

See Also:

Since:

API Level 2.3.0

onDisplayModeChanged() as Void

The display mode has changed, only available in AMOLED or LCD screen products.

This method is called when the system changes the display mode. Use the System.getDisplayMode() to get the current state.

Supported Devices:

Since:

API Level 5.0.0

onEnhancedReadabilityModeChanged() as Void

The font mode has changed

This method is called when the system changes to or from Enhanced Readability Mode. Use the Toybox::System::DeviceSettings#isEnhancedReadabilityModeEnabled field to get the current state.

Supported Devices:

Since:

API Level 4.2.3

onInactive(state as Lang.Dictionary or Null) as Void

Invoked when app enters inactive mode, i.e. hidden by system and not occupying screen. Access to certain system resources will be limited, such as GPS, ANT, Alerts (Vibs tones, flashlight).

Parameters:

Supported Devices:

Since:

API Level 4.2.3

onNightModeChanged() as Void

The display mode has changed

This method is called when the system changes to or from night mode. Use the Toybox::System::DeviceSettings#isNightModeEnabled field to get the current state.

Supported Devices:

Since:

API Level 4.1.2

onSettingsChanged() as Void

Called when the application settings have been changed by Garmin Connect Mobile (GCM) while while the app is running. Override this method to change app behavior when settings change. This is typically used to call for an update to the WatchUi.requestUpdate()

Example:

function onSettingsChanged() { // triggered by settings change in GCM
    _mainView.handleSettingUpdate();
    WatchUi.requestUpdate();   // update the view to reflect changes
}

See Also:

Since:

API Level 1.2.0

onStart(state as Lang.Dictionary or Null) as Void

Method called at startup to allow handling of app initialization.

Before the initial WatchUi.View is retrieved, onStart() is called. Application level settings can be initialized or retrieved from the object store before the initial View is created. This method must be overridden to handle your own app initialization.

Note:

the suspension state can be cleared in the event of reboot or app update.

Parameters:

  • state — (Lang.Dictionary) —

    Required. If an Intent is not used to launch the application, then an empty "state" Dictionary is used. If an Intent is used to start the application the Dictionary contains the arguments from the Intent.

    • :resume — (Lang.Boolean) —

      If true, indicating app has been resumed from suspension, restore the previously saved app state if needed.

    • :launchedFromGlance — (Lang.Boolean) —

      If true, indicating the app is started from glance list as opposed to the the app list.

    • :launchedFromComplication — (Lang.Number) —

      If presented, indicating the complication index the app was launched from.

Example:

onStart() used with Intent

function onStart(state) {
    if (state != null) {
        infoString = "Args:" + state.toString();
    }
}

See Also:

Since:

API Level 1.0.0

onStop(state as Lang.Dictionary or Null) as Void

Override to handle application cleanup upon termination.

If the application needs to save data to the object store it should be done in this function. Once the function is complete, the application will terminate.

Note:

the suspension state can be cleared in the event of reboot or app update.

Parameters:

  • state — (Lang.Dictionary) —

    Required. If an Intent is not used to launch an application on stop of the current application an empty "state" Dictionary is used. If an Intent is used to start another application, then the Dictionary contains the arguments from the Intent.

    • :suspend — (Lang.Boolean) —

      If true, the app has been suspended and the current state can be resumed at a later time.

See Also:

Since:

API Level 1.0.0

onStorageChanged() as Void

Called when Application storage is changed by the other running instance, of the app i.e Background Process while the CIQ app is running or vice-versa. Override this function to receive a callback when the storage is updated. Use this function to reload storage data from the application storage.

Since:

API Level 3.2.0

onValidateProperty(key as Lang.String, value as Application.PropertyValueType) as Lang.Boolean or Lang.String

Called when a property needs to be validated by the application.

Returns:

  • true if the property is valid, return an error message otherwise. Returning false causes a generic error to be displayed on settings configuration app

Since:

API Level 4.1.0

openAppSettingsEditor() as Void

Function to open application settings editor

Since:

API Level 4.1.0

saveProperties() as Void

This has been deprecated

This method may be removed after System 4.

Save the properties for the application

Supported Devices:

Since:

API Level 1.0.0

setProperty(key as Application.PropertyKeyType, value as Application.PropertyValueType) as Void

This has been deprecated

This method may be removed after System 4.

Store the given data in the object.

Keys can be of the following types:

Values can be of the following types:

Array and Dictionary values may contain null values or any of the above listed types. There is a limit on the size of the Properties of 32 KB. If this limit is reached, the properties will not be saved or reloaded.

Note:

Background processes cannot save properties.

Note:

Symbols can change from build to build and are not to be used for for Keys or Values.

Parameters:

  • key —

    The key used to store and retrieve the value from the object store (cannot be a Symbol)

  • value —

    The value to put into the object store

Example:

using Toybox.Application;
var app = Application.getApp();

app.setProperty("number", 2);               // set value for "number" key
app.setProperty("float", 3.14);             // set value for "float" key
app.setProperty("string", "Hello World!");  // set value for "string" key
app.setProperty("boolean", true);           // set value for "boolean" key

var int = app.getProperty("number");          // get value for "number" key
var float = app.getProperty("float");         // get value for "float" key
var string = app.getProperty("string");       // get value for "string" key
var boolean = app.getProperty("boolean");     // get value for "boolean" key

Supported Devices:

See Also:

Since:

API Level 1.0.0

Throws:

validateProperty(key as Application.PropertyKeyType, value as Application.PropertyValueType) as Void

Validate a property being stored.

Since:

API Level 1.0.0

Generated Sep 23, 2024, 3:32:48 PM