Watch face

On the SmartWatch 2, you have the ability to customize the watch face to implement your own clock or widget, using the Widget API. Widgets are visual components that can provide information such as weather or number of unread emails. Widgets also include clock support. Clocks are visual components, such as digital or analog clocks or dates, suited for presenting time and dates even when the watch is not connected to a phone.

Widgets can be placed on the SmartWatch 2 watch face by the end user, using the watch face editor included in the SmartWatch 2 host application. Host application versions from 1.4.51 and newer support this functionality.

Watch face editor showing (1) widgets, (2) clock, and (3) watch face.

Watch face editor showing (1) widgets, (2) clock, and (3) watch face.

Widget API

The Widget API allows you to implement your own clock faces or create widgets to show on the watch face, such as battery and date indicators

The basics

To get started with building your own clocks and widgets, perform the following steps:

  1. Register your app.
  2. Update your AndroidManifest.xml.
  3. Include the common classes.
  4. Register your widget classes.
  5. Build your user interface – either a widget or clock UI.
  6. Test your app.

Register your app

First, you need to register your app by extending the RegistrationInformation class in the SmartExtensionUtil Android library. See the Registration guide for more details. Register the Widget API as follows:

@Override public int getRequiredWidgetApiVersion() {
    return 3;
}

Update your AndroidManifest.xml

Next, you need to update your AndroidManifest.xml file. See the Android Manifest guide for more details.

Include the common classes for Smart Extensions

Now, add the common classes for Smart Extensions in your project. See the Common classes guide for more details.

Register your widget classes

You need to return a list of Widget classes to the framework. Do this by overriding getWidgetClasses():

@Override
protected WidgetClassList getWidgetClasses(Context context, String hostAppPackageName, WidgetContainer widget) {
    // Create a list of all widgets to register
    WidgetClassList widgetList = new WidgetClassList();
    widgetList.add(DigitalClockLevelList.class);
    widgetList.add(DigitalClockRoboto.class);
    widgetList.add(AnalogClock.class);
    widgetList.add(AnalogClockLevelList.class);
    widgetList.add(DateWidget.class);
    widgetList.add(WeekAndDayWidget.class);
    return widgetList;
}

Build your user interface

Now you are ready to start defining your layouts to build your UI. Here, the process is slightly different depending on whether you build a widget UI or a build a clock UI.

Build a widget UI

When creating a widget, you’ll need to define the accessory states and layouts.

Define accessory states

When creating a widget, you need to consider what state the SmartWatch 2 can be in. You will be able to adapt to the new state by providing different layouts. You can provide layouts for the following accessory states:

  • DEFAULT  – The SmartWatch 2 backlight is on, the display shows 64K true colors and it is connected to the phone
  • POWERSAVE – The SmartWatch 2 backlight is off, the display only shows 4 grayscale colors and it is connected to the phone

You are required to provide a layout for at least the DEFAULT accessory state. If you do not provide a layout for the POWERSAVE state, the DEFAULT one will be used when the SmartWatch 2 enters the POWERSAVE state.

There is a third state, DISCONNECTED. When the SmartWatch 2 enters the DISCONNECTED state, the widget DEFAULT layout will be used, but grayed out.

When the SmartWatch is in POWERSAVE and DISCONNECTED state, the screen only displays content in 4 grayscale colors. We recommend that SmartWatch 2 apps provide a layout with elements containing high contrast colors when being run in any of these modes.

Define Layouts

See the Layouts section of the Build your app guide for details on how to create a layout.

Build a clock UI

When creating a clock widget, you’ll need to define the accessory states and layouts. Also, you may want to categorize your clock to make it appear in the list of available clocks on the host application.

Clock widgets have the possibility of updating its content even when the SmartWatch 2 is disconnected from the phone. This is done by providing an additional set of layout resources to be displayed in the DISCONNECTED state.

Categorize your clock

During implementation of a clock, you have the option to categorize it by overriding getCategory() in a class that extends BaseWidget to make your clock appear in the list of clocks instead of the default list of widgets in the host application.

@Override
public int getCategory() {
    return Category.CLOCK;
}

Define accessory states

When creating a clock widget, you can provide three layouts for the following states:

  • DEFAULT – The SmartWatch 2 backlight is on, the display shows 64K true colors and it is connected to the phone.
  • POWERSAVE – The SmartWatch 2 backlight is off, the display only shows 4 grayscale colors and it is connected to the phone.
  • DISCONNECTED – The SmartWatch 2 backlight is off, the display only shows 4 grayscale colors and it is disconnected from the phone.

You are required to provide a layout for at least the DEFAULT accessory state.

When the SmartWatch 2 enters the POWERSAVE state, you have the opportunity to update your clock widget providing an alternative layout to adapt to this state. If you do not provide an alternative layout, the SmartWatch 2 will use the DEFAULT layout provided and the layout will in this case be displayed as 4 color grayscale only.

When the SmartWatch 2 enters the DISCONNECTED state, it will use the DISCONNECTED layout provided.

Define level lists

When developing a clock widget, you can choose to let the SmartWatch 2 firmware manage the updating to reflect the current date and time, or you can provide your own defined resources by using a level list. You can choose to define either drawables or strings in the level list to suit your needs:

To define drawables in the level list, use:

<level-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@drawable/digit_0" />
    <item android:drawable="@drawable/digit_1" />
    <item android:drawable="@drawable/digit_2" />
</level-list>

To define strings in the level list, use:

<level-list xmlns:android="http://schemas.android.com/apk/res/android"gt;
    <item android:string="@string/digit_0" /gt;
    <item android:string="@string/digit_1" /gt;
    <item android:string="@string/digit_2" /gt;
</level-listgt;

Define Layouts

You can provide a layout that makes use of newly introduced layout components:

  • TimeLayout
  • TimeView

These layout components are specifically made for updating contents of a clock widget, for example, a minute or hour indicator, also when the SmartWatch 2 is disconnected from the mobile device.

Use the level list in a TimeView, which holds the list as its background. You will also have to define what type the TimeView will be, for example, hours_digit1 or minutes_digit2, using the timeType attribute. See TimeView in the API references for the different available types.

Place the TimeView in a TimeLayout to place the widget according to your needs:

<com.sonyericsson.extras.liveware.aef.widget.TimeLayout
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:layout_weight="0.5"
    widgets:gravity="center"
    android:padding="5px" >

    <com.sonyericsson.extras.liveware.aef.widget.TimeView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:background="@drawable/clock_widget_minutes_msn"
        widgets:timeType="minutes_digit2 />

    <com.sonyericsson.extras.liveware.aef.widget.TimeView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:background="@drawable/clock_widget_minutes_lsn"
        widgets:timeType="minutes_digit1" />
</com.sonyericsson.extras.liveware.aef.widget.TimeLayout>

Reference the layout by overriding the onStartRefresh() method in a class that extends BaseWidget:

@Override
void onStartRefresh() {
    // Prepare a bundle with required resources and the resource
    // id in the layouts that shall be updated.
...
    bundleNoTouchText(Widget.Intents.EXTRA_LAYOUT_REFERENCE,
    R.id.widget_text_box_view_no_touch);
    bundleNoTouchText.putString(Control.Intents.EXTRA_TEXT, mContext.getString(R.string.powersave));
...
    // Connect the bundles to the different states
    showLayout(R.layout.default, R.layout.powersave, R.layout.disconnected);
}

Note that if you only define a single drawable as an android:background in a TimeView when creating an analog clock, the SmartWatch 2 firmware will rotate the resource to represent the time.

Also note that if you only define the widgets:timeType in a TimeView, without providing a graphical resource, the SmartWatch 2 will use built in fonts to represent the time.

Test your app

Test your clock or widget app using your phone with Smart Connect and the SmartWatch 2 Host Application:

  1. Start Smart Connect on your mobile device.
  2. Tap the Devices tab.
  3. Tap SmartWatch 2 in the list.
  4. Tap SmartWatch 2 – Edit settings below the SMART ACCESSORY APPLICATION title.
  5. Tap Edit watch faces below the WATCH FACES title.
  6. Tap the + sign in the upper right corner.
  7. Tap either Clocks or Widgets.
  8. You will be able to find your clock or widget in the scrollable list shown.

Tips when developing clocks and widgets

Take the following tips into consideration as part of your clocks and widgets development:

  • Analog and digital clock implementations – Clocks will often be showing when the device is in POWERSAVE mode and the transflective screen is in 4 color grayscale mode. Because of this, it’s important to check your layouts on actual devices to ensure they render nicely. This especially applies when using analog clocks as they involve blending layers of graphics (for example, the big hand and small hand) which can be more challenging to render in only four colors.
  • One widget vs. multiple widget implementations – When implementing clocks, consider using multiple clock widgets, instead of keeping everything in one single clock widget implementation. When placing a clock widget, the resources used will be copied to the accessory, which will be a long running process if the layout contains a lot of detail and components.
  • Screen refreshing – When a widget is visible on the SmartWatch 2 watch face, you will receive an onStartRefresh() callback. You will now have the possibility to update the screen content for as long as the widget is visible. When a widget is no longer visible, you will receive an onStopRefresh() callback.
  • Touch events – You can receive onObjectClick() callbacks when a user touches a layout object in your widget, if you are using XML based layouts and the view has been set as clickable. You can receive onTouch() callbacks when a user touches your widget. This is supported in both XML-based and bitmap-based layouts.

Clock and widget code example

For the full code example showing how to create a widget that can be placed on the SmartWatch 2 watch face, see the HelloWidget project in the /samples folder of the Sony Add-on SDK.