Module: Toybox::Background

Overview

Background events are special events that trigger in the background when either certain system events occur, such as when an activity goal has been met, or at certain times (called temporal events). This allows an application to update its data even when the application is not active.

See Also:

Since:

  • 2.3.0

Requires Permission:

  • Background

Defined Under Namespace

Classes: ExitDataSizeLimitException, InvalidBackgroundTimeException, MessageSizeLimitException

Instance Method Summary collapse

Instance Method Details

deleteGoalEvent(goalType) ⇒ Object

Remove the active goal background event of specified type for the application.

Examples:

Background.deleteGoalEvent(GOAL_TYPE_STEPS);

Parameters:

Since:

  • 2.3.0



2699
2700
# File 'Monkeybrains.rb', line 2699

def deleteGoalEvent(goalType)
end

deleteOAuthResponseEventObject

Remove the OAuth response background event.

Since:

  • 2.3.0



2745
2746
# File 'Monkeybrains.rb', line 2745

def deleteOAuthResponseEvent()
end

deleteSleepEventObject

Remove the active sleep background event for the application.

Since:

  • 2.3.0



2647
2648
# File 'Monkeybrains.rb', line 2647

def deleteSleepEvent()
end

deleteStepsEventObject

Remove the active steps background event for the application.

Since:

  • 2.3.0



2721
2722
# File 'Monkeybrains.rb', line 2721

def deleteStepsEvent()
end

deleteTemporalEventObject

Remove the active temporal background event for the application.

Since:

  • 2.3.0



2602
2603
# File 'Monkeybrains.rb', line 2602

def deleteTemporalEvent()
end

deleteWakeEventObject

Remove the active wake background event for the application.

Since:

  • 2.3.0



2666
2667
# File 'Monkeybrains.rb', line 2666

def deleteWakeEvent()
end

exit(backgroundData) ⇒ Object

Terminates the current background process.

All background processes should call this method when they have completed the desired tasks. Data passed to this method will either be passed immediately to the active application if it is running, or will be saved and passed to the application the next time it runs. Data must be one of the following types:

Arrays and Dictionaries may contain null values or any of the above listed types. If no data should be passed to the main process, null may be specified.

This method will exit if called by a background process, but will do nothing if called by the main application process.

Parameters:

Raises:

  • (Toybox::Background::ExitDataSizeLimitException)

    Indicates the data provided exceeds the data size limit (approximately 8 KB). If this exception is caught, the process will not exit and should attempt to call Background.exit() again with less data.

Since:

  • 2.3.0



2790
2791
# File 'Monkeybrains.rb', line 2790

def exit(backgroundData)
end

getBackgroundDataObject

Get data previously saved by a background process.

Data is delivered via AppBase.onBackgroundData(), and is reset to null once data has been delivered to the main process. This method always returns null in the main application's process.

See Also:

Since:

  • 2.3.0



2756
2757
# File 'Monkeybrains.rb', line 2756

def getBackgroundData()
end

getGoalEventRegistered(goalType) ⇒ Toybox::Lang::Boolean

Get whether a background event is registered with registerForGoalEvent().

Parameters:

Returns:

  • (Toybox::Lang::Boolean)

    true if a background event is registered with registerForGoalEvent(), otherwise false

Since:

  • 3.0.0



2688
2689
# File 'Monkeybrains.rb', line 2688

def getGoalEventRegistered(goalType)
end

getLastTemporalEventTimeToybox::Time::Moment

Get the time the last temporal background event was triggered.

This is useful for ensuring new events are not scheduled within the five minute minimum time allowed between temporal events.

Examples:

Register a new temporal background event as soon as allowed

using Toybox.Background;
using Toybox.Time;
const FIVE_MINUTES = new Time.Duration(5 * 60);
var lastTime = Background.getLastTemporalEventTime();
if (lastTime != null) {
    // Events scheduled for a time in the past trigger immediately
    var nextTime = lastTime.add(FIVE_MINUTES);
    Background.registerForTemporalEvent(nextTime);
} else {
    Background.registerForTemporalEvent(Time.now());
}

Returns:

  • (Toybox::Time::Moment)

    The time the last background event was triggered, but may be null if no previous temporal background event has occurred or if the watch-app or widget has been started since the event was last triggered

See Also:

Since:

  • 2.3.0



2628
2629
# File 'Monkeybrains.rb', line 2628

def getLastTemporalEventTime()
end

getOAuthResponseEventRegisteredToybox::Lang::Boolean

Get whether a background event is registered with registerForOAuthResponseEvent()

Returns:

  • (Toybox::Lang::Boolean)

    true if a background event is registered with registerForOAuthResponseEvent(), otherwise false

Since:

  • 3.0.0



2740
2741
# File 'Monkeybrains.rb', line 2740

def getOAuthResponseEventRegistered()
end

getSleepEventRegisteredToybox::Lang::Boolean

Get whether a background event is registered with registerForSleepEvent().

Returns:

  • (Toybox::Lang::Boolean)

    true if a background event is registered with registerForSleepEvent(), otherwise false

Since:

  • 3.0.0



2642
2643
# File 'Monkeybrains.rb', line 2642

def getSleepEventRegistered()
end

getStepsEventRegisteredToybox::Lang::Boolean

Get whether a background event is registered with registerForStepsEvent().

Returns:

  • (Toybox::Lang::Boolean)

    true if a background event is registered with registerForStepsEvent(), otherwise false

Since:

  • 3.0.0



2716
2717
# File 'Monkeybrains.rb', line 2716

def getStepsEventRegistered()
end

getTemporalEventRegisteredTimeToybox::Time::Moment, Toybox::Time::Duration

Get the Moment or Duration with which a background event is registered by registerForTemporalEvent().

Returns:

  • (Toybox::Time::Moment, Toybox::Time::Duration)

    The specific Moment in time at which a background event is registered to trigger, or the interval Duration at which to repeat a background event. May be null if no temporal background event is registered.

See Also:

Since:

  • 3.0.0



2597
2598
# File 'Monkeybrains.rb', line 2597

def getTemporalEventRegisteredTime()
end

getWakeEventRegisteredToybox::Lang::Boolean

Get whether a background event is registered with registerForWakeEvent().

Returns:

  • (Toybox::Lang::Boolean)

    true if a background event is registered with registerForWakeEvent(), otherwise false

Since:

  • 3.0.0



2661
2662
# File 'Monkeybrains.rb', line 2661

def getWakeEventRegistered()
end

registerForGoalEvent(goalType) ⇒ Object

Register a background event that triggers when the user reaches a specified goal.

Examples:

Background.registerForGoalEvent(GOAL_TYPE_STEPS);

Parameters:

Since:

  • 2.3.0



2677
2678
# File 'Monkeybrains.rb', line 2677

def registerForGoalEvent(goalType)
end

registerForOAuthResponseEventObject

Registers a background event that triggers each time an OAuth login request completes and the token becomes available on the system for use.

This event is triggered when a OAuth response is received by the system.

Since:

  • 2.3.0



2732
2733
# File 'Monkeybrains.rb', line 2732

def registerForOAuthResponseEvent()
end

registerForSleepEventObject

Register a background event that triggers at the sleep time configured on the device.

Since:

  • 2.3.0



2634
2635
# File 'Monkeybrains.rb', line 2634

def registerForSleepEvent()
end

registerForStepsEventObject

Registers a background event that triggers each time a multiple of 1000 steps is reached.

This event is triggered only by device-recorded steps, and will not trigger based on synced steps.

Since:

  • 2.3.0



2708
2709
# File 'Monkeybrains.rb', line 2708

def registerForStepsEvent()
end

registerForTemporalEvent(time) ⇒ Object

Register a background event that triggers at a specific time or at a regular interval.

Temporal background events may be registered to run at a specific point in time by providing a Moment at which the event should trigger, or may be registered to run at a periodically by specifying an interval Duration. If a temporal event is scheduled for a time in the past, the event will trigger immediately.

Temporal events cannot be set to occur less than 5 minutes after the last temporal event occurred. For watch-apps and widgets the 5 minute restriction is cleared on application startup if the event was specified using a Moment.

Only one temporal event may be registered at a time. Calling registerForTemporalEvent will overwrite any previously registered temporal events.

Examples:

Schedule a background event to run five minutes from now

using Toybox.Background;
using Toybox.Time;
const FIVE_MINUTES = new Time.Duration(5 * 60);
var eventTime = Time.now().add(FIVE_MINUTES);
Background.registerForTemporalEvent(eventTime);

Parameters:

Raises:

  • (Toybox::Background::InvalidBackgroundTimeException)

    Indicates an application has attempted to schedule a background event which either:

    • Occurs less than five minutes after the last background event occurred

    • Has a duration of less than five minutes

See Also:

Since:

  • 2.3.0



2586
2587
# File 'Monkeybrains.rb', line 2586

def registerForTemporalEvent(time)
end

registerForWakeEventObject

Register a background event that triggers at the wake time configured on the device.

Since:

  • 2.3.0



2653
2654
# File 'Monkeybrains.rb', line 2653

def registerForWakeEvent()
end

requestApplicationWake(message) ⇒ Object

Display a confirmation dialog requesting to launch the application to which the background task belongs.

If the dialog is confirmed, the application will open. If the dialog is declined, the application will not open and the dialog will be dismissed. This request is only valid for widget or watch-app background tasks, and will be ignored by watch face apps. Background.exit() must be called at some point in the background process after this method is invoked because the confirmation dialog will only trigger after the background task exits.

Examples:

using Toybox.Background;
(:background)
class BackgroundServiceDelegate extends System.ServiceDelegate {
    function initialize() {
        ServiceDelegate.initialize();
    }

    function onTemporalEvent() {
        Background.requestApplicationWake("Launch Cool App?");
        Background.exit(null);
    }
}

Parameters:

  • message (Toybox::Lang::String)

    The message to display in the dialog when requesting to launch the app

Raises:

See Also:

Since:

  • 2.3.0



2824
2825
# File 'Monkeybrains.rb', line 2824

def requestApplicationWake(message)
end