Connect IQ/APIメモ/Toybox/Application/AppBase - api_programming @ ウィキ

Index (A) » Toybox » Application » AppBase

Class: Toybox::Application::AppBase

Inherits:

   Lang::Object
   show all

Overview

AppBase is the base class for an app.

すべてのアプリケーションは、このクラスを継承し、その method を継承してアプリケーションのライフサイクルを管理する。
実装としては、このくらいをオーバーライドして、エントリポイントを提供し、次のメソッドでアプリケーションを操作する。

• onStart()
• getInitialView()
• getGoalView()
• getServiceDelegate()
• onSettingsChanged()
• onStop()

"widgets" と "watch-apps" では、次の順番で実行される。

• onStart()
• getInitialView()
• onStop()

For watch faces and data fields, only getInitialView() is called.

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

Instance Method Summary

collapse

   allowTrialMessage ⇒ Toybox::Lang::Boolean

   Check if application trial messages are allowed.
   clearProperties ⇒ Object deprecated Deprecated.

   This method will be dropped in [[Connect IQ]] 4.0.0
   deleteProperty(key) ⇒ Object deprecated Deprecated.

   This method will be dropped in Connect IQ 4.0.0
   getGoalView(goalType) ⇒ Toybox::Lang::Array

   Override to provide a WatchUi.View for a goal that has triggered within a watch face.
   getInitialView ⇒ Toybox::Lang::Array

   Override to provide the initial WatchUi.View and WatchUi.InputDelegate of the application.
   getProperty(key) ⇒ Toybox::Lang::Object

   Get the data associated with a given key from the object store.
   getServiceDelegate ⇒ Toybox::Lang::Array

   Get a ServiceDelegate to run background tasks for this app.
   getTrialDaysRemaining ⇒ Toybox::Lang::Number

   Override to return the number of days remaining in the trial.
   isTrial ⇒ Toybox::Lang::Boolean

   Check if the application is in trial mode.
   loadProperties ⇒ Object deprecated Deprecated.

   loadProperties() will be removed in Connect IQ 3.0.0
   onBackgroundData(data) ⇒ Object

   Handle data passed from a ServiceDelegate to the application.
   onSettingsChanged ⇒ Object

   Called when the application settings have been changed by Garmin Connect Mobile (GCM) while while the app is running.
   onStart(state) ⇒ Object

   Method called at startup to allow handling of app initialization.
   onStop(state) ⇒ Object

   Override to handle application cleanup upon termination.
   saveProperties ⇒ Object deprecated Deprecated.

   saveProperties() will be removed in Connect IQ 3.0.0
   setProperty(key, value) ⇒ Object

   Store the given data in the object.
   validateProperty(key, value) ⇒ Object

   Validate a property being stored.

Methods inherited from Lang::Object

equals, hashCode, method, toString, weak
Instance Method Details
allowTrialMessage ⇒ Toybox::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:

   (Toybox::Lang::Boolean) —

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

Since:

   2.3.0

clearProperties ⇒ Object
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:

   (Toybox::Application::ObjectStoreAccessException) —

   Thrown if clearProperties() is called from a Background process

See Also:

   Storage

Since:

   1.0.0

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:

   key (Toybox::Lang::Object) —

   The key to delete

Raises:

   (Toybox::Application::ObjectStoreAccessException) —

   Thrown if deleteProperty() is called from a Background process

See Also:

   Storage

Since:

   1.0.0

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:

   (Toybox::Lang::Array) —

   An Array containing a WatchUi.View

Since:

   1.3.0

getInitialView ⇒ Toybox::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:

   (Toybox::Lang::Array) —

   An Array containing a WatchUi.View and an optional WatchUi.InputDelegate

Since:

   1.0.0

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:

   setProperty()
   Background
   Properties
   Storage

Since:

   1.0.0

getServiceDelegate ⇒ Toybox::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:

   (Toybox::Lang::Array) —

   An Array containing a System.ServiceDelegate

See Also:

   Background

Since:

   2.3.0

getTrialDaysRemaining ⇒ Toybox::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

isTrial ⇒ Toybox::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

loadProperties ⇒ Object
Deprecated.

loadProperties() will be removed in Connect IQ 3.0.0

Load the properties for the application

Since:

   1.0.0

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:

   data (Toybox::Lang::Object) —

   The data passed from the background process.

See Also:

   Background

Since:

   2.3.0

onSettingsChanged ⇒ Object

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:

   WatchUi.requestUpdate() for more details

Since:

   1.2.0

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:

   Intent API Documentation

Since:

   1.0.0

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:

   Intent API Documentation

Since:

   1.0.0

saveProperties ⇒ Object
Deprecated.

saveProperties() will be removed in Connect IQ 3.0.0

Save the properties for the application

Since:

   1.0.0

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:

   String

   Number

   Float

   Boolean

   Char

   Long

   Double

Values can be of the following types:

   String

   Number

   Float

   Boolean

   Char

   Long

   Double

   null

Values can also be of type Array or Dictionary containing the above listed types. There is a limit on the size of the Properties of 8KB. If you reach this limit, 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:

   (Toybox::Application::ObjectStoreAccessException) —

   Thrown if setProperty() is called from a Background process (data should be passed back to the main application from background processes with Background.exit())
   (Toybox::Lang::UnexpectedTypeException) —

   Thrown if setProperty() is called with a key or value of a disallowed type

See Also:

   getProperty()
   Background
   Programmer's Guide - Data Storage
   Properties
   Storage

Since:

   1.0.0

validateProperty(key, value) ⇒ Object

Validate a property being stored.

Since:

   1.0.0