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


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

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


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

def deleteGoalEvent(goalType)
end

deleteOAuthResponseEventObject

Remove the OAuth response background event.

Since:

  • 2.3.0


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

def deleteOAuthResponseEvent()
end

deletePushNotificationEventObject

Stops the application from receiving silent and actionable push notifications.

Since:

  • 3.0.10


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

def deletePushNotificationEvent()
end

deleteSleepEventObject

Remove the active sleep background event for the application.

Since:

  • 2.3.0


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

def deleteSleepEvent()
end

deleteStepsEventObject

Remove the active steps background event for the application.

Since:

  • 2.3.0


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

def deleteStepsEvent()
end

deleteTemporalEventObject

Remove the active temporal background event for the application.

Since:

  • 2.3.0


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

def deleteTemporalEvent()
end

deleteWakeEventObject

Remove the active wake background event for the application.

Since:

  • 2.3.0


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

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


2880
2881
# File 'Monkeybrains.rb', line 2880

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


2989
2990
# File 'Monkeybrains.rb', line 2989

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


2846
2847
# File 'Monkeybrains.rb', line 2846

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


2778
2779
# File 'Monkeybrains.rb', line 2778

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


2718
2719
# File 'Monkeybrains.rb', line 2718

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


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

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


2971
2972
# File 'Monkeybrains.rb', line 2971

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


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

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


2806
2807
# File 'Monkeybrains.rb', line 2806

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


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

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


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

def getWakeEventRegistered()
end

registerForActivityCompletedEventObject

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

Since:

  • 3.0.10


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

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


2767
2768
# File 'Monkeybrains.rb', line 2767

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


2822
2823
# File 'Monkeybrains.rb', line 2822

def registerForOAuthResponseEvent()
end

registerForPushNotificationEventObject

Registers the application to receive silent and actionable push notifications.

Since:

  • 3.0.10


2958
2959
# File 'Monkeybrains.rb', line 2958

def registerForPushNotificationEvent()
end

registerForSleepEventObject

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

Since:

  • 2.3.0


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

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


2798
2799
# File 'Monkeybrains.rb', line 2798

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


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

def registerForTemporalEvent(time)
end

registerForWakeEventObject

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

Since:

  • 2.3.0


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

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


2914
2915
# File 'Monkeybrains.rb', line 2914

def requestApplicationWake(message)
end