Class: Toybox::WatchUi::View

Inherits:
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.

Examples:

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() {
    }
}

See Also:

Since:

  • 1.0.0

Direct Known Subclasses

DataField, GlanceView, MapView, Menu2, Picker, WatchFace

Direct Known Subclasses

DataField, GlanceView, MapView, Menu2, Picker, WatchFace

Instance Method Summary collapse

Methods inherited from Lang::Object

equals, hashCode, method, toString, weak

Constructor Details

initializeView

Returns a new instance of View

Since:

  • 2.1.0


13524
13525
# File 'Monkeybrains.rb', line 13524

def initialize()
end

Instance Method Details

addLayer(layer) ⇒ Object

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 anmation playback.

Disabled for DataFiled and Background Apps

Parameters:

Raises:

Since:

  • 1.0.0


13647
13648
# File 'Monkeybrains.rb', line 13647

def addLayer(layer)
end

clearLayersObject

Clear all layers that are added to the view

Since:

  • 3.1.0


13670
13671
# File 'Monkeybrains.rb', line 13670

def clearLayers()
end

findDrawableById(identifier) ⇒ Toybox::WatchUi::Drawable

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.

Examples:

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);

Parameters:

Returns:

See Also:

Since:

  • 1.0.0


13554
13555
# File 'Monkeybrains.rb', line 13554

def findDrawableById(identifier)
end

getLayerIndex(layer) ⇒ Toybox::Lang::Number

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

Parameters:

Returns:

Since:

  • 1.0.0


13665
13666
# File 'Monkeybrains.rb', line 13665

def getLayerIndex(layer)
end

getLayersToybox::Lang::Array

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:

  • 3.1.0


13677
13678
# File 'Monkeybrains.rb', line 13677

def getLayers()
end

insertLayer(layer, idx) ⇒ Object

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

Parameters:

  • layer

    a WatchUi.Layer a layer to insert.

  • idx

    a [Toybox::Lang::Number] index in the layer stack to insert at

Since:

  • 1.0.0


13659
13660
# File 'Monkeybrains.rb', line 13659

def insertLayer(layer, idx)
end

onHideObject

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:

  • 1.0.0


13605
13606
# File 'Monkeybrains.rb', line 13605

def onHide()
end

onLayout(dc) ⇒ Toybox::Lang::Boolean

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:

Returns:

Since:

  • 1.0.0


13564
13565
# File 'Monkeybrains.rb', line 13564

def onLayout(dc)
end

onShowToybox::Lang::Boolean

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.

Returns:

Since:

  • 1.0.0


13573
13574
# File 'Monkeybrains.rb', line 13573

def onShow()
end

onUpdate(dc) ⇒ Toybox::Lang::Boolean

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:

Returns:

See Also:

Since:

  • 1.0.0


13594
13595
# File 'Monkeybrains.rb', line 13594

def onUpdate(dc)
end

removeLayer(layer) ⇒ Toybox::Lang::Boolean

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

Parameters:

Returns:

Since:

  • 1.0.0


13653
13654
# File 'Monkeybrains.rb', line 13653

def removeLayer(layer)
end

setKeyToSelectableInteraction(enable) ⇒ Object

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.

Examples:

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;
}

Parameters:

Since:

  • 2.1.0


13635
13636
# File 'Monkeybrains.rb', line 13635

def setKeyToSelectableInteraction(enable)
end

setLayout(layout) ⇒ Object

Set the layout for the View.

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

Parameters:

Since:

  • 1.0.0


13616
13617
# File 'Monkeybrains.rb', line 13616

def setLayout(layout)
end