Module: Toybox.WatchUi

Overview

The WatchUi module contains user interface elements available within apps.

WatchUi provides several classes that represent Views, or what is displayed on the screen of a device. Also available are UI elements like on-screen menus, progress bars, buttons, and various pickers. More abstract classes represent all drawable objects, such as bitmaps and text.

Note:

All keys in the key types enum listed after EXTENDED_KEYS (16) were added after ConnectIQ version 1.1.2. Before evaluating these keys, check for the availability of these keys with a has check: if (Toybox.WatchUi has :EXTENDED_KEYS) ...

Since:

API Level 1.0.0

App Types:

  • Watch App

  • Audio Content Provider

  • Data Field

  • Watch Face

  • Widget

Classes Under Namespace

Classes: AnimationDelegate, AnimationLayer, AnimationResource, BehaviorDelegate, Bitmap, BitmapResource, Button, CheckboxMenu, CheckboxMenuItem, ClickEvent, Confirmation, ConfirmationDelegate, CustomMenu, CustomMenuItem, DataField, DataFieldAlert, Drawable, FontResource, GlanceView, GlanceViewDelegate, IconMenuItem, InputDelegate, InvalidMenuItemTypeException, InvalidPointException, InvalidSelectableStateException, KeyEvent, Layer, MapMarker, MapPolyline, MapTrackView, MapView, Menu, Menu2, Menu2InputDelegate, MenuInputDelegate, MenuItem, NumberPicker, NumberPickerDelegate, Picker, PickerDelegate, PickerFactory, ProgressBar, Selectable, SelectableEvent, SimpleDataField, SwipeEvent, Text, TextArea, TextPicker, TextPickerDelegate, ToggleMenuItem, View, WatchFace, WatchFaceDelegate, WatchFacePowerInfo

Constant Summary

Key

Name Value Since Description
KEY_POWER 0

API Level 1.0.0

The power key

KEY_LIGHT 1

API Level 1.0.0

The light key

KEY_ZIN 2

API Level 1.0.0

The zoom in key

KEY_ZOUT 3

API Level 1.0.0

The zoom out key

KEY_ENTER 4

API Level 1.0.0

The enter key

KEY_ESC 5

API Level 1.0.0

The escape key

KEY_FIND 6

API Level 1.0.0

The find key

KEY_MENU 7

API Level 1.0.0

The menu key

KEY_DOWN 8

API Level 1.0.0

The down key

KEY_DOWN_LEFT 9

API Level 1.0.0

The down left key

KEY_DOWN_RIGHT 10

API Level 1.0.0

The down key

KEY_LEFT 11

API Level 1.0.0

The left key

KEY_RIGHT 12

API Level 1.0.0

The right key

KEY_UP 13

API Level 1.0.0

The up key

KEY_UP_LEFT 14

API Level 1.0.0

The up-left

KEY_UP_RIGHT 15

API Level 1.0.0

The up-right key

EXTENDED_KEYS 16

API Level 1.1.2

Indicates extended key support

KEY_PAGE 17

API Level 1.1.2

The page key

KEY_START 18

API Level 1.1.2

The start key

KEY_LAP 19

API Level 1.1.2

The lap key

KEY_RESET 20

API Level 1.1.2

The reset key

KEY_SPORT 21

API Level 1.1.2

The sport key

KEY_CLOCK 22

API Level 1.1.2

The clock key

KEY_MODE 23

API Level 1.1.2

The mode key

AnimationType

Name Value Since Description
ANIM_TYPE_LINEAR 0

API Level 1.0.0

Animation with a constant speed

ANIM_TYPE_EASE_IN 1

API Level 1.0.0

Animation that increases in speed from start to end

ANIM_TYPE_EASE_OUT 2

API Level 1.0.0

Animation that decreases in speed from start to end

ANIM_TYPE_EASE_IN_OUT 3

API Level 1.0.0

Animation that increases in speed from the start, then decreases in speed toward the end

KeyPressType

Name Value Since Description
PRESS_TYPE_DOWN 0

API Level 1.1.2

The key is pressed down

PRESS_TYPE_UP 1

API Level 1.1.2

The key is released

PRESS_TYPE_ACTION 2

API Level 1.1.2

The key's action is performed

ClickType

Name Value Since Description
CLICK_TYPE_TAP 0

API Level 1.0.0

A tap on the screen

CLICK_TYPE_HOLD 1

API Level 1.0.0

A press and hold on the screen

CLICK_TYPE_RELEASE 2

API Level 1.0.0

A release of a hold on the screen

MapMarkerIcon

Name Value Since Description
MAP_MARKER_ICON_PIN 0

API Level 3.0.0

The default Garmin map marker pin icon

MapMode

Name Value Since Description
MAP_MODE_PREVIEW 0

API Level 3.0.0

The preview mode for a MapView

MAP_MODE_BROWSE 1

API Level 3.0.0

The browse mode for a MapView

SwipeDirection

Name Value Since Description
SWIPE_UP 0

API Level 1.0.0

A swipe in the upward direction

SWIPE_RIGHT 1

API Level 1.0.0

A swipe towards the right

SWIPE_DOWN 2

API Level 1.0.0

A swipe in the downward direction

SWIPE_LEFT 3

API Level 1.0.0

A swipe towards the left

Confirm

Name Value Since Description
CONFIRM_NO 0

API Level 1.0.0

CONFIRM_YES 1

API Level 1.0.0

NumberPickerMode

Name Value Since Description
NUMBER_PICKER_DISTANCE 0

API Level 1.0.0

A Float in meters (m)

NUMBER_PICKER_TIME 1

API Level 1.0.0

A Duration

NUMBER_PICKER_TIME_MIN_SEC 2

API Level 1.0.0

A Duration

NUMBER_PICKER_TIME_OF_DAY 3

API Level 1.0.0

A Duration representing the number of seconds since midnight

NUMBER_PICKER_WEIGHT 4

API Level 1.0.0

A Float in kilograms (kg)

NUMBER_PICKER_HEIGHT 5

API Level 1.0.0

A Float in meters (m)

NUMBER_PICKER_CALORIES 6

API Level 1.0.0

A Number

NUMBER_PICKER_BIRTH_YEAR 7

API Level 1.0.0

A Number

SlideType

Name Value Since Description
SLIDE_IMMEDIATE 0

API Level 1.0.0

No transition.

SLIDE_LEFT 1

API Level 1.0.0

The View slides to the left.

SLIDE_RIGHT 2

API Level 1.0.0

The View slides to the right.

SLIDE_DOWN 3

API Level 1.0.0

The View slides down.

SLIDE_UP 4

API Level 1.0.0

The View slides up.

SLIDE_BLINK 5

API Level 3.1.0

The View fades in.

LayoutVerticalAlignment

Name Value Since Description
LAYOUT_VALIGN_TOP -0x7FFFFFFF

API Level 1.2.0

Set a Drawable object's locY property to this to align it to the top edge of the device context (Dc).

LAYOUT_VALIGN_BOTTOM -0x7FFFFFFE

API Level 1.2.0

Set a Drawable object's locY property to this to align it to the bottom edge of the device context (Dc).

LAYOUT_VALIGN_CENTER -0x7FFFFFFD

API Level 1.2.0

Set a Drawable object's locY property to this to center it vertically in the device context (Dc).

LAYOUT_VALIGN_START -0x7FFFFFFC

API Level 1.2.0

Set a Drawable object's locY property to this to make it equal to its parent's locY property.

LayoutHorizontalAlignment

Name Value Since Description
LAYOUT_HALIGN_LEFT -0x7FFFFFFF

API Level 1.2.0

Set a Drawable object's locX property to this to align it along the left edge of the device context (Dc).

LAYOUT_HALIGN_RIGHT -0x7FFFFFFE

API Level 1.2.0

Set a Drawable object's locX property to this to align it along the right edge of the device context (Dc).

LAYOUT_HALIGN_CENTER -0x7FFFFFFD

API Level 1.2.0

Set a Drawable object's locX property to this to center it horizontally in the device context (Dc).

LAYOUT_HALIGN_START -0x7FFFFFFC

API Level 1.2.0

Set a Drawable object's locX property to this to make it equal to its parent's locX property.

AnimationEvent

Name Value Since Description
ANIMATION_EVENT_COMPLETE 0

API Level 3.1.0

Indicates the completion of an animation.

ANIMATION_EVENT_CANCELED 1

API Level 3.1.0

Indicates the cancel of the animation playback

Typedef Summary

typedef InputDelegates as WatchUi.InputDelegate or WatchUi.BehaviorDelegate or WatchUi.ConfirmationDelegate or WatchUi.MenuInputDelegate or WatchUi.NumberPickerDelegate or WatchUi.PickerDelegate or WatchUi.TextPickerDelegate or WatchUi.WatchFaceDelegate or WatchUi.Menu2InputDelegate

typedef Resource as Lang.Array or Lang.Dictionary or Lang.String or WatchUi.AnimationResource or WatchUi.BitmapResource or WatchUi.FontResource or Graphics.BitmapReference or Graphics.FontReference

typedef Views as WatchUi.View or WatchUi.Menu or WatchUi.TextPicker or WatchUi.ProgressBar or WatchUi.Confirmation or WatchUi.NumberPicker

Instance Method Summary collapse

Instance Method Details

animate(object, property as Lang.Symbol, type as WatchUi.AnimationType, start as Lang.Numeric, stop as Lang.Numeric, period as Lang.Numeric, callback as Null or Lang.Method() as Void)

Animate an Object.

Animate works by changing an object property over time, such as the x-position of a Drawable. The animation starts after the call and runs the length of the specified period. During this time, the View object's onUpdate() method will be invoked at an increased rate to facilitate animation.

Note:

Will cause an app crash if called from background or data field app, or from watch face while in low power mode

Parameters:

  • object(Lang.Object)

    The object to animate

  • property(Lang.Symbol)

    The Symbol of the object's property to animate (e.g. :locX, :locY, etc.)

  • type(Lang.Number)

    A WatchUi.ANIM_TYPE_* value

  • start(Lang.Number)

    The starting value of the property

  • stop(Lang.Number)

    The ending value of the property

  • period(Lang.Float)

    The duration of the animation in seconds

  • callback(Lang.Method)

    A Method to call when the animation is complete; this can be null

Example:

Move a bitmap across the screen from left to right

using System.WatchUi;

square = new Ui.Bitmap({
    :rezId=>Rez.Drawables.square,
    :locX=>10,
    :locY=>30
});
WatchUi.animate(square, :locX, Ui.ANIM_TYPE_LINEAR, 10, 200, 10, null);

See Also:

Since:

API Level 1.0.0

cancelAllAnimations() as Void

Cancel animations started with WatchUi.animate()

Stop all animations that were started with WatchUi.animate(). This will leave all animations at their final frame, as if WatchUi.animate() ran to completion.

See Also:

Since:

API Level 3.1.7

loadResource(resource as Lang.Symbol) as WatchUi.Resource

Load a resource from the executable.

Note:
Toybox::Graphics::BitmapReference
  • in CIQ 4.0.0 and later.

  • Note:
    Toybox::Graphics::FontReference
  • in CIQ 4.0.0 and later.

  • Parameters:

    • resource(Lang.Symbol)

      An identifier for a resource defined in the project's resources.xml file

    Example:

    Loading a String resource

    // The resources.xml file contents:
    // <resources>
    //     <string id="AppName">APEELingApp</string>
    // </resources>
    using Toybox.WatchUi;
    
    var banana = WatchUi.loadResource(Rez.Strings.AppName);
    

    Returns:

    Since:

    API Level 1.0.0

    popView(transition as WatchUi.SlideType) as Void

    Pop the current View from the View stack.

    Parameters:

    • transition(Lang.Number)

      A WatchUi.SLIDE_* value

    Since:

    API Level 1.0.0

    Throws:

    pushView(view as WatchUi.Views, delegate as WatchUi.InputDelegates or Null, transition as WatchUi.SlideType) as Lang.Boolean

    Push a View onto the View stack.

    Parameters:

    Since:

    API Level 1.0.0

    Throws:

    requestUpdate() as Void

    Request a call to the onUpdate() method for the current View.

    See Also:

    Since:

    API Level 1.0.0

    switchToView(view as WatchUi.Views, delegate as WatchUi.InputDelegates, transition as WatchUi.SlideType) as Void

    Pop the current View from the View stack and push a new one.

    Note:

    Prior to ConnectIQ 3.1, this method only supported switching to user-defined View objects, and would only accept InputDelegate or BehaviorDelegate objects as delegates for the given View.

    Parameters:

    Since:

    API Level 1.0.0

    Throws:


    Generated Nov 29, 2021 1:34:36 PM