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 InputDelegate or BehaviorDelegate or ConfirmationDelegate or MenuInputDelegate or NumberPickerDelegate or PickerDelegate or TextPickerDelegate or WatchFaceDelegate or Menu2InputDelegate

typedef Resource as Array or Dictionary or String or AnimationResource or BitmapResource or FontResource or BitmapReference or FontReference

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

Instance Method Summary collapse

Instance Method Details

animate(object, property as Symbol, type as AnimationType, start as Numeric, stop as Numeric, period as Numeric, callback as Null or 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.

Parameters:

  • object(Object)

    The object to animate

  • property(Symbol)

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

  • type(Number)

    A WatchUi.ANIM_TYPE_* value

  • start(Number)

    The starting value of the property

  • stop(Number)

    The ending value of the property

  • period(Float)

    The duration of the animation in seconds

  • callback(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

getSubscreen() as BoundingBox or Null

Get the subscreen area in the display.

Returns:

  • BoundingBox object or null is no subscreen is present

Since:

API Level 3.3.0

loadResource(resource as Symbol) as 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(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 SlideType) as Void

    Pop the current View from the View stack.

    Parameters:

    • transition(Number)

      A WatchUi.SLIDE_* value

    Since:

    API Level 1.0.0

    Throws:

    • (OperationNotAllowedException)

      Raised if popView is called on the base page of a widget or if switchToView is used to switch to a native view from the base page of a widget

    pushView(view as Views, delegate as InputDelegates or Null, transition as SlideType) as 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 Views, delegate as InputDelegates, transition as 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 pushed View.

    Parameters:

    • view(View)

      The View object to push

    • delegate(BehaviorDelegate, InputDelegate)

      The input delegate to handle input for the View

    • transition(Number)

      A WatchUi.SLIDE_* value

    Since:

    API Level 1.0.0


    Generated Apr 22, 2021 10:10:32 AM