Class: Toybox.WatchUi.View

Inherits:
Toybox.Lang.Object show all

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:

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

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

Since:

API Level 1.0.0

Instance Method Summary collapse

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:

Since:

API Level 3.1.0

Throws:

clearLayers() as Void

Clear all layers that are added to the view

Since:

API Level 3.1.0

findDrawableById(identifier as Lang.String) 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.String)

    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:

See Also:

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:

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:

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:

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:

See Also:

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:

Returns:

  • Lang.Boolean

    true, if layer is removed successfully, otherwise false

Since:

API Level 3.1.0

setClockHandPosition(hour as Lang.Number, minute as Lang.Number, options as Lang.Dictionary or Null)

Set the clock hands position.

Note:

0 degrees indicate 12 o' clock, 180 degrees indicate 6 o'clock and 360 degrees indicate 12 o' clock.

Note:

Passing in null value as argument for hour and minute will set the hand to resting position. At resting position the clock hands will align themselves at horizontal position at 9:15.

Parameters:

  • hour

    value ranging from 0-360 in degrees to set the hour hand position

  • minute

    value ranging from 0-360 in degrees to set the minute hand position

  • options

    Reserved. Additional options related to clock hands position.

Since:

API Level 3.3.0

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.

Supported Devices:

Since:

API Level 4.1.2

Throws:

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:

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:

Parameters:

  • layout(Lang.Array)

    An array of Drawables or null.

Since:

API Level 1.0.0


Generated Sep 1, 2022 11:27:04 AM