Class: Toybox.WatchUi.View

Inherits:

Toybox.Lang.Object

• Toybox.Lang.Object
• Toybox.WatchUi.View

Overview

A View is an object that represents a page within an app.

An app may have multiple View objects representing things like menus and other app states. Each View contains a Layout, which in turn contain Drawable objects, such as Bitmaps and Text. View objects also handle the life cycle of each app, which varies depending on the app type:

Widgets and Watch Apps

onLayout() → onShow() → onUpdate() → onHide()

Watch Faces

onLayout() → onShow() → onUpdate()

Data Fields

onLayout() → onShow() → onUpdate()

If the size of the data field has changed since the last onUpdate(), onLayout() will be called prior to onUpdate(). However, onLayout(), onShow(), and onUpdate() are not called for SimpleDataField objects.

See Also:

• Toybox.WatchUi.Drawable

Example:

A basic widget View class definition

using Toybox.WatchUi;

class MyWidgetView extends WatchUi.View {
    function initialize() {
        View.initialize();
    }

    // Resources are loaded here
    function onLayout(dc) {
        setLayout(Rez.Layouts.MainLayout(dc));
    }

    // onShow() is called when this View is brought to the foreground
    function onShow() {
    }

    // onUpdate() is called periodically to update the View
    function onUpdate(dc) {
        View.onUpdate(dc);
    }

    // onHide() is called when this View is removed from the screen
    function onHide() {
    }
}

Since:

API Level 1.0.0

Direct Known Subclasses

WatchUi.DataField, WatchUi.DataFieldAlert, WatchUi.GlanceView, WatchUi.MapView, WatchUi.Menu2, WatchUi.Picker, WatchUi.WatchFace

Typedef Summary

• ControlBarOptions as { :leftButton as WatchUi.ControlBarLeftButton, :title as Lang.String, :rightButton as WatchUi.ControlBarRightButton }

Instance Method Summary

• addLayer(layer as WatchUi.Layer) as Void

  Add a WatchUi.Layer on the top of view's layer stack.

• clearLayers() as Void

  Clear all layers that are added to the view.

• findDrawableById(identifier as Lang.Object) as WatchUi.Drawable or Null

  Find a Drawable by its ID.

• getLayerIndex(layer as WatchUi.Layer) as Lang.Number

  Return the index of the layer from the bottom of the view layer stack.

• getLayers() as Lang.Array<WatchUi.Layer> or Null

  Get a copy of the layer stack currently added to the view, sorted by the drawing order, i.e.

• initialize()

  Constructor.

• insertLayer(layer as WatchUi.Layer, idx as Lang.Number) as Void

  Insert the layer at the given index in the layer stack, this will stop animation playback.

• onHide() as Void

  Hide the View.

• onLayout(dc as Graphics.Dc) as Void

  The entry point for the View.

• onShow() as Void

  Show the View.

• onUpdate(dc as Graphics.Dc) as Void

  Update the View.

• removeLayer(layer as WatchUi.Layer) as Lang.Boolean

  Remove a layer from the view layer stack, this will stop animation playback.

• setClockHandPosition(options as { :clockState as WatchUi.AnalogClockState, :hour as Lang.Number or Null, :minute as Lang.Number or Null }) as Lang.Boolean

  Set the clock hands position.

• setControlBar(options as View.ControlBarOptions) as Void

  Set control bar options for this view.

• setKeyToSelectableInteraction(enable as Lang.Boolean) as Void

  Enter Selectable interaction mode.

• setLayout(layout as Lang.Array<WatchUi.Drawable> or Null) as Void

  Set the layout for the View.

Instance Method Details

addLayer(layer as WatchUi.Layer) as Void

Add a WatchUi.Layer on the top of view's layer stack. Users do not need to draw the layer on the screen manually, instead, once a layer is added to the view, the system will draw all layers during screen updates which include View update (e.g. onUpdate/onPartialUpdate) and animation playback.

Disabled for DataFiled and Background Apps

Parameters:

• layer — (WatchUi.Layer) —

  a WatchUi.Layer object to add

Since:

API Level 3.1.0

Throws:

• (Lang.UnexpectedTypeException) —

  Thrown if the layer is not a WatchUi.Layer

clearLayers() as Void

Clear all layers that are added to the view

Since:

API Level 3.1.0

findDrawableById(identifier as Lang.Object) as WatchUi.Drawable or Null

Find a Drawable by its ID.

A common use for this method is to get layout information to format dynamic content, such as a string that updates at runtime.

Parameters:

• identifier — (Lang.Object) —

  The identifier of the Drawable to find

Example:

Formatting the clock time as centered, blue text

// The layout.xml file contents:
// <layout id="WatchFace">
//      <label id="TimeLabel" x="center" y="center" font="Graphics.FONT_LARGE" justification="Graphics.TEXT_JUSTIFY_CENTER" color="Graphics.COLOR_BLUE" />
// </layout>

using Toybox.Graphics;
using Toybox.Lang;
using Toybox.System;
using Toybox.WatchUi.View;

var clockTime = System.getClockTime();
var timeString = Lang.format(
    "$1$:$2$",
    [clockTime.hour, clockTime.min.format("%02d")]
);
var view = View.findDrawableById("TimeLabel");
view.setText(timeString);

Returns:

• WatchUi.Drawable —

  A Drawable if found, otherwise null

See Also:

• System.getClockTime()

Since:

API Level 1.0.0

getLayerIndex(layer as WatchUi.Layer) as Lang.Number

Return the index of the layer from the bottom of the view layer stack

Parameters:

• layer —

  a WatchUi.Layer a layer object

Returns:

• Lang.Number —

  index of the layer from the bottom of the layer stack

Since:

API Level 3.1.0

getLayers() as Lang.Array<WatchUi.Layer> or Null

Get a copy of the layer stack currently added to the view, sorted by the drawing order, i.e. from the bottom to the top.

Returns:

• Lang.Array —

  an array of WatchUi.Layer or null

Since:

API Level 3.1.0

initialize()

Constructor

Since:

API Level 2.1.0

insertLayer(layer as WatchUi.Layer, idx as Lang.Number) as Void

Insert the layer at the given index in the layer stack, this will stop animation playback.

Parameters:

• layer — (WatchUi.Layer) —

  a layer to insert.

• idx — (Lang.Number) —

  position in the layer stack to insert layer.

Since:

API Level 3.1.0

onHide() as Void

Hide the View.

This is called before the View is removed from the foreground. This occurs when a new View object is pushed on top of the current one, when the current View is popped, or when the app is closed. Resources should be freed from memory at this point if the current View will be left on the page stack.

Since:

API Level 1.0.0

onLayout(dc as Graphics.Dc) as Void

The entry point for the View.

onLayout() is called before the View is shown to load resources and set up the layout of the View.

Parameters:

• dc — (Graphics.Dc) —

  The device context

Since:

API Level 1.0.0

onShow() as Void

Show the View.

This is called when the View is brought into the foreground. Resources should be loaded into system memory for use in the View at this point.

Since:

API Level 1.0.0

onUpdate(dc as Graphics.Dc) as Void

Update the View.

This is called when a View is brought to the foreground, after the call to onShow(). While a View is active, this method is generally used to update dynamic content in the View. There are also some special cases when it will be invoked:

• On WatchUi.requestUpdate() calls within Widgets and Watch Apps

• Once per minute in Watch Faces when in low power mode

• Once per second in Watch Faces when in high power mode

• Once per second in Data Fields

• At an increased rate while an animation is active

• More than one call to onUpdate() may occur during View transitions

If a class that extends View does not implement this function then any Drawable objects contained in the View will automatically be drawn.

Parameters:

• dc — (Graphics.Dc) —

  The device context

See Also:

• WatchFace.onPartialUpdate()

Since:

API Level 1.0.0

removeLayer(layer as WatchUi.Layer) as Lang.Boolean

Remove a layer from the view layer stack, this will stop animation playback.

Parameters:

• layer —

  a WatchUi.Layer to remove from the layer stack.

Returns:

• Lang.Boolean —

  true, if layer is removed successfully, otherwise false

Since:

API Level 3.1.0

setClockHandPosition(options as { :clockState as WatchUi.AnalogClockState, :hour as Lang.Number or Null, :minute as Lang.Number or Null }) as Lang.Boolean

Set the clock hands position.

Parameters:

• options — (Lang.Dictionary) —

  Options for setting the analog clock state.

  • :clockState — (WatchUi.AnalogClockState) —

    An ANALOG_CLOCK_STATE_* value for the clock state

  • :hour — (Lang.Number) —

    Position for the hour hand in degrees clockwise from the 12 o'clock position

  • :minute — (Lang.Number) —

    Position for the minute hand in degrees clockwise from the 12 o'clock position

Supported Devices:

• Instinct® Crossover

Returns:

• Lang.Boolean —

  true if the request to change the analog hands was successful, false otherwise.

Since:

API Level 3.3.0

Throws:

• (Lang.InvalidValueException) —

  Thrown if invalid or no value is passed in for :clockState.

• (Lang.InvalidValueException) —

  Thrown if no :hour and :minute values are specified for the :clockState value of ANALOG_CLOCK_STATE_HOLDING.

setControlBar(options as View.ControlBarOptions) as Void

Set control bar options for this view.

Use of this method has many restrictions.

With View, the control bar can be hidden by passing null. If options is non-null, the :leftButton option must be provided. All values for CONTROL_BAR_RIGHT_BUTTON_* and CONTROL_BAR_RIGHT_BUTTON_* are allowed.

With Menu2 and CustomMenu, the options parameter cannot be null; the control bar is always shown. The :leftButton option must be set to CONTROL_BAR_LEFT_BUTTON_BACK. The :rightButton option may be null, for no button, or CONTROL_BAR_RIGHT_BUTTON_ACCEPT.

Attempting to call this method on any other class derived from View, or with an unsupported option for the given view type, will result in an exception.

Note:

Control bar visibility changes made from onLayout or onUpdate will result in an exception.

Parameters:

• options — (Lang.Dictionary) —

  Optional parameters for control bar. If null, the control bar will be hidden.

  • :leftButton — (WatchUi.ControlBarLeftButton) —

    The icon to use for the left button. Must be a CONTROL_BAR_LEFT_BUTTON_* value.

  • :rightButton — (WatchUi.ControlBarRightButton) —

    The icon to use for the right button. Must be a CONTROL_BAR_RIGHT_BUTTON_* value. If the value is null or not provided, no button will be shown.

  • :title — (Lang.String) —

    The title to display in the control bar. If the view is of type Menu2, the Menu2 title will be given priority and will be displayed in the control bar. If no title is specified, the application name will be used.

Supported Devices:

• Edge® 1040 / 1040 Solar
• Edge® 1050
• Edge® 540 / 540 Solar
• Edge® 840 / 840 Solar
• Edge® Explore 2

Since:

API Level 4.1.2

Throws:

• (Lang.OperationNotAllowedException) —

  Thrown if called on a view type that does not support control bar changes, or if called from onLayout or onUpdate.

• (Lang.InvalidValueException) —

  Thrown if one or more of the specified options is not valid for the view type.

setKeyToSelectableInteraction(enable as Lang.Boolean) as Void

Enter Selectable interaction mode.

When enabled, physical buttons may be used to cycle through on-screen Selectable objects. The first registered Selectable in the current layout will be highlighted initially.

Parameters:

• enable — (Lang.Boolean) —

  Set to true if the mode should be enabled, otherwise false

Example:

Toggle the Selectable interaction mode with the Menu button

var selectableMode = false;
function onMenu() {
    selectableMode = !selectableMode;
    // currentView is a View containing Selectable objects
    currentView.setKeyToSelectableInteraction(selectableMode);
    return true;
}

Since:

API Level 2.1.0

Throws:

• (Lang.SymbolNotAllowedException) —

  Thrown if called from a data field app

setLayout(layout as Lang.Array<WatchUi.Drawable> or Null) as Void

Set the layout for the View.

Set the array of Drawable objects to be managed by this View. The specified Drawables will be:

• Drawn automatically via calls to onUpdate()

• Searched via calls to findDrawableById()

Parameters:

• layout — (Lang.Array) —

  An array of Drawables or null.

Since:

API Level 1.0.0