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

deleteActivityCompletedEventObject

Stops the application from receiving activity completed events.

Since:

  • 3.0.10


2987
2988
# File 'Monkeybrains.rb', line 2987

def deleteActivityCompletedEvent()
end

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


2795
2796
# File 'Monkeybrains.rb', line 2795

def deleteGoalEvent(goalType)
end

deleteOAuthResponseEventObject

Remove the OAuth response background event.

Since:

  • 2.3.0


2841
2842
# File 'Monkeybrains.rb', line 2841

def deleteOAuthResponseEvent()
end

deletePushNotificationEventObject

Stops the application from receiving silent and actionable push notifications.

Since:

  • 3.0.10


2969
2970
# File 'Monkeybrains.rb', line 2969

def deletePushNotificationEvent()
end

deleteSleepEventObject

Remove the active sleep background event for the application.

Since:

  • 2.3.0


2743
2744
# File 'Monkeybrains.rb', line 2743

def deleteSleepEvent()
end

deleteStepsEventObject

Remove the active steps background event for the application.

Since:

  • 2.3.0


2817
2818
# File 'Monkeybrains.rb', line 2817

def deleteStepsEvent()
end

deleteTemporalEventObject

Remove the active temporal background event for the application.

Since:

  • 2.3.0


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

def deleteTemporalEvent()
end

deleteWakeEventObject

Remove the active wake background event for the application.

Since:

  • 2.3.0


2762
2763
# File 'Monkeybrains.rb', line 2762

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


2886
2887
# File 'Monkeybrains.rb', line 2886

def exit(backgroundData)
end

getActivityCompletedEventRegisteredToybox::Lang::Boolean

Get whether a background event is registered with registerForActivityCompletedEvent()

Returns:

  • (Toybox::Lang::Boolean)

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

Since:

  • 3.0.10


2995
2996
# File 'Monkeybrains.rb', line 2995

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


2852
2853
# File 'Monkeybrains.rb', line 2852

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


2784
2785
# File 'Monkeybrains.rb', line 2784

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 device app or widget has been started since the event was last triggered

See Also:

Since:

  • 2.3.0


2724
2725
# File 'Monkeybrains.rb', line 2724

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


2836
2837
# File 'Monkeybrains.rb', line 2836

def getOAuthResponseEventRegistered()
end

getPushNotificationEventRegisteredToybox::Lang::Boolean

Get whether a background event is registered with registerForPushNotificationEvent()

Returns:

  • (Toybox::Lang::Boolean)

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

Since:

  • 3.0.10


2977
2978
# File 'Monkeybrains.rb', line 2977

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


2738
2739
# File 'Monkeybrains.rb', line 2738

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


2812
2813
# File 'Monkeybrains.rb', line 2812

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


2693
2694
# File 'Monkeybrains.rb', line 2693

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


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

def getWakeEventRegistered()
end

registerForActivityCompletedEventObject

Registers the application to receive an event whenever an activity is completed.

Since:

  • 3.0.10


2982
2983
# File 'Monkeybrains.rb', line 2982

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


2773
2774
# File 'Monkeybrains.rb', line 2773

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


2828
2829
# File 'Monkeybrains.rb', line 2828

def registerForOAuthResponseEvent()
end

registerForPushNotificationEventObject

Registers the application to receive silent and actionable push notifications.

Since:

  • 3.0.10


2964
2965
# File 'Monkeybrains.rb', line 2964

def registerForPushNotificationEvent()
end

registerForSleepEventObject

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

Since:

  • 2.3.0


2730
2731
# File 'Monkeybrains.rb', line 2730

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


2804
2805
# File 'Monkeybrains.rb', line 2804

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


2682
2683
# File 'Monkeybrains.rb', line 2682

def registerForTemporalEvent(time)
end

registerForWakeEventObject

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

Since:

  • 2.3.0


2749
2750
# File 'Monkeybrains.rb', line 2749

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 device 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


2920
2921
# File 'Monkeybrains.rb', line 2920

def requestApplicationWake(message)
end