Widgets on EPD

Widgets for EPD are the same with widgets on Front screen. Same Android SDK is used, same classes, same everything. This means that creating widgets for EPD is almost the same process as creating standard widgets for Front screen.

If you are new to widgets in Android please refer to Android documentation here: App Widgets.

How to create a widget?

EPD widgets are essentially the same with Front Screen widgets, but there are some peculiarities.

1. You need to create XML with EPD widget settings: size and preview layouts.

2. There are some events which can happen:

   – Widget's theme changing (white or black)

   – Widget's visibility changing (whether it is visible for user or not)

onAppWidgetOptionsChanged method tracks them and gets the new widgets' parameters and values, and then you only need to update widget according to these new parameters.

Declaring EPD widget

Declaring widget for EPD is the same as declaring normal widget for Front screen, with the only difference that you also have to add EPD-specific meta-data. EPD-specific values should be located at file specified in "com.yotadevices.epd_provider" meta-data. Please see example below.

AndroidManifest.xml

    <receiver
         android:name="com.yotadevices.api.sample.epd.widgetprovider" >
         <intent-filter>
            <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
         </intent-filter>
         <!-- Front screen widget settings -->
         <meta-data
            android:name="android.appwidget.provider"
            android:resource="@xml/fs_widget_info" />
         <!-- Epd widget settings -->
         <meta-data
            android:name="com.yotadevices.epd_provider"        
            android:resource="@xml/epd_widget_info" />
    </receiver>

Widget sizes

There is a list of widget sizes on the scheme.

– Fullscreen (full_screen) - 540x960

– XL (extra_large) - 476x672

– L (large) - 476×448

– M (medium) - 168×476

– S (small) - 112×476

The indents between the widgets are regulated by YotaHub and cannot be changed.

In the EPD widget file (@xml/epd_widget_info in our example) developers should specify supported widget sizes. Generally, widget can support several sizes.

    <epd-widget-provider
        xmlns:sdk="http://schemas.android.com/apk/com.yotadevices.sdk"
        sdk:size="medium"/>

Configuration file for the Front Screen should be specified in corresponding Front screen file (fs_widget_info.xml in our example)

    <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
        android:initialLayout="@layout/fs_widget"
        android:minHeight="10dp"
        android:minWidth="10dp"
        android:resizeMode="vertical|horizontal"
        android:updatePeriodMillis="60000"
        android:widgetCategory="home_screen">
    </appwidget-provider>

An important note: if it is necessary to hide widget from the default launcher, developers need to specify android:widgetCategory=“”.

Widget Previews

Widget previews are displayed when user select a new widget from the widgets' list.

https://yotaphone.com/media/5_widgets+on+epd_1.png

It is possible to make EPD widget's preview as a standard Android layout. It means that all resources qualifiers apply as they should, so you can use localized resources (values-ru/, values-en/...).

You can define layouts in the widget's XML file with the previewBlack and previewWhite attributes for black and white theme respectively.

For example:

    <?xml version="1.0" encoding="utf-8"?>
    <epd-widget-provider
            xmlns:sdk="http://schemas.android.com/apk/com.yotadevices.sdk"
            sdk:size="medium"
            sdk:previewBlack="@layout/preview_layout_black"
            sdk:previewWhite="@layout/preview_layout_white"/>

If you include it in your code, widget preview will be taken from @layout/preview_layout_black or @layout/preview_layout_white depending on the selected theme.

White/Black theme

If a widget doesn’t support white theme natively, it can make himself invertible. If a widget is invertible, YotaHub will invert colors on White device.

    <epd-widget-provider
        xmlns:sdk="http://schemas.android.com/apk/com.yotadevices.sdk"
        sdk:size="medium"
        sdk:invertable="medium" 
        sdk:previewBlack="@layout/preview_layout_black"
        sdk:previewWhite="@layout/preview_layout_white"/>

Implement onAppWidgetOptionsChanged method and make manual updates:

    // we have to make manual invert for this size
    int size = appWidgetOptions.getInt(EpdConstants.EpdLauncherConstants.OPTION_WIDGET_SIZE, -1);
    int display = appWidgetOptions.getInt(EpdConstants.EpdLauncherConstants.OPTION_WIDGET_THEME, -1);
    if (size == EpdConstants.EpdLauncherConstants.WIDGET_SIZE_LARGE) {
        if (display == EpdConstants.EpdLauncherConstants.WIDGET_THEME_WHITE) {
            remoteViews.setTextColor(R.id.textView, context.getResources().getColor(android.R.color.black));
        }
            }