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


13534
13535
# File 'Monkeybrains.rb', line 13534

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


13657
13658
# File 'Monkeybrains.rb', line 13657

def addLayer(layer)
end

clearLayersObject

Clear all layers that are added to the view

Since:

  • 3.1.0


13680
13681
# File 'Monkeybrains.rb', line 13680

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


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

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


13675
13676
# File 'Monkeybrains.rb', line 13675

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


13687
13688
# File 'Monkeybrains.rb', line 13687

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


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

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


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

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


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

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


13583
13584
# File 'Monkeybrains.rb', line 13583

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


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

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


13663
13664
# File 'Monkeybrains.rb', line 13663

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


13645
13646
# File 'Monkeybrains.rb', line 13645

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


13626
13627
# File 'Monkeybrains.rb', line 13626

def setLayout(layout)
end