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


2878
2879
# File 'Monkeybrains.rb', line 2878

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


2704
2705
# File 'Monkeybrains.rb', line 2704

def deleteGoalEvent(goalType)
end

deleteOAuthResponseEventObject

Remove the OAuth response background event.

Since:

  • 2.3.0


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

def deleteOAuthResponseEvent()
end

deleteSleepEventObject

Remove the active sleep background event for the application.

Since:

  • 2.3.0


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

def deleteSleepEvent()
end

deleteStepsEventObject

Remove the active steps background event for the application.

Since:

  • 2.3.0


2726
2727
# File 'Monkeybrains.rb', line 2726

def deleteStepsEvent()
end

deleteTemporalEventObject

Remove the active temporal background event for the application.

Since:

  • 2.3.0


2607
2608
# File 'Monkeybrains.rb', line 2607

def deleteTemporalEvent()
end

deleteWakeEventObject

Remove the active wake background event for the application.

Since:

  • 2.3.0


2671
2672
# File 'Monkeybrains.rb', line 2671

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

def getWakeEventRegistered()
end

registerForActivityCompletedEventObject

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

Since:

  • 3.0.10


2873
2874
# File 'Monkeybrains.rb', line 2873

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


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

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


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

def registerForOAuthResponseEvent()
end

registerForSleepEventObject

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

Since:

  • 2.3.0


2639
2640
# File 'Monkeybrains.rb', line 2639

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


2713
2714
# File 'Monkeybrains.rb', line 2713

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


2591
2592
# File 'Monkeybrains.rb', line 2591

def registerForTemporalEvent(time)
end

registerForWakeEventObject

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

Since:

  • 2.3.0


2658
2659
# File 'Monkeybrains.rb', line 2658

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


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

def requestApplicationWake(message)
end