Class: Toybox::Application::AppBase

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

Examples:

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:

  • 1.0.0

Direct Known Subclasses

AudioContentProviderApp

Direct Known Subclasses

AudioContentProviderApp

Instance Method Summary collapse

Methods inherited from Lang::Object

equals, hashCode, method, toString, weak

Instance Method Details

allowTrialMessageToybox::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:

Since:

  • 2.3.0



1826
1827
# File 'Monkeybrains.rb', line 1826

def allowTrialMessage()
end

clearPropertiesObject

Deprecated.

This method will be dropped in Connect IQ 4.0.0

Note:

Background processes cannot clear properties.

Clear the object store for the application.

Raises:

See Also:

Since:

  • 1.0.0



2078
2079
# File 'Monkeybrains.rb', line 2078

def clearProperties()
end

deleteProperty(key) ⇒ Object

Deprecated.

This method will be dropped in Connect IQ 4.0.0

Note:

Background processes cannot delete properties.

Delete the given key from the object store.

Parameters:

Raises:

See Also:

Since:

  • 1.0.0



2067
2068
# File 'Monkeybrains.rb', line 2067

def deleteProperty(key)
end

getGoalView(goalType) ⇒ Toybox::Lang::Array

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 (Toybox::Lang::Number)

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

Returns:

Since:

  • 1.3.0



1875
1876
# File 'Monkeybrains.rb', line 1875

def getGoalView(goalType)
end

getInitialViewToybox::Lang::Array

Override to provide the initial WatchUi.View and WatchUi.InputDelegate of the application.

  • Providing a WatchUi.InputDelegate is optional for widgets and watch-apps.

  • For watch faces and data fields, an Array containing just a WatchUi.View should be returned as input is not available for these app types.

Returns:

Since:

  • 1.0.0



1861
1862
# File 'Monkeybrains.rb', line 1861

def getInitialView()
end

getProperty(key) ⇒ Toybox::Lang::Object

Note:

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

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.

Parameters:

  • key

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

Returns:

  • (Toybox::Lang::Object)

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

See Also:

Since:

  • 1.0.0



1998
1999
# File 'Monkeybrains.rb', line 1998

def getProperty(key)
end

getServiceDelegateToybox::Lang::Array

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:

  • 2.3.0



1918
1919
# File 'Monkeybrains.rb', line 1918

def getServiceDelegate()
end

getTrialDaysRemainingToybox::Lang::Number

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:

  • (Toybox::Lang::Number)

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

Since:

  • 2.3.0



1890
1891
# File 'Monkeybrains.rb', line 1890

def getTrialDaysRemaining()
end

isTrialToybox::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:

  • (Toybox::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:

  • 2.3.0



1904
1905
# File 'Monkeybrains.rb', line 1904

def isTrial()
end

loadPropertiesObject

Deprecated.

loadProperties() will be removed in Connect IQ 3.0.0

Load the properties for the application

Since:

  • 1.0.0



2084
2085
# File 'Monkeybrains.rb', line 2084

def loadProperties()
end

onAppInstallObject

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:

  • 3.0.0



1972
1973
# File 'Monkeybrains.rb', line 1972

def onAppInstall()
end

onAppUpdateObject

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:

  • 3.0.0



1979
1980
# File 'Monkeybrains.rb', line 1979

def onAppUpdate()
end

onBackgroundData(data) ⇒ Object

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:

See Also:

Since:

  • 2.3.0



1950
1951
# File 'Monkeybrains.rb', line 1950

def onBackgroundData(data)
end

onSettingsChangedObject

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()

Examples:

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

See Also:

Since:

  • 1.2.0



1934
1935
# File 'Monkeybrains.rb', line 1934

def onSettingsChanged()
end

onStart(state) ⇒ Object

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.

Examples:

onStart() used with Intent

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

Parameters:

  • state (Toybox::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.

See Also:

Since:

  • 1.0.0



1848
1849
# File 'Monkeybrains.rb', line 1848

def onStart(state)
end

onStop(state) ⇒ Object

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.

Parameters:

  • state (Toybox::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.

See Also:

Since:

  • 1.0.0



1965
1966
# File 'Monkeybrains.rb', line 1965

def onStop(state)
end

savePropertiesObject

Deprecated.

saveProperties() will be removed in Connect IQ 3.0.0

Save the properties for the application

Since:

  • 1.0.0



2090
2091
# File 'Monkeybrains.rb', line 2090

def saveProperties()
end

setProperty(key, value) ⇒ Object

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.

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 8KB. If this limit is reached, the properties will not be saved or reloaded.

Examples:

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

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

Raises:

See Also:

Since:

  • 1.0.0



2055
2056
# File 'Monkeybrains.rb', line 2055

def setProperty(key, value)
end

validateProperty(key, value) ⇒ Object

Validate a property being stored.

Since:

  • 1.0.0



2095
2096
# File 'Monkeybrains.rb', line 2095

def validateProperty(key, value)
end