WatchFaceHostApi.kt

/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.wear.watchface

import android.content.ComponentName
import android.content.Context
import android.os.Handler
import android.support.wearable.complications.ComplicationData
import androidx.annotation.RestrictTo
import androidx.annotation.UiThread
import androidx.wear.complications.SystemProviders.ProviderId
import androidx.wear.watchface.style.data.UserStyleWireFormat

/**
 * The API [WatchFaceImpl] uses to communicate with the system.
 * @hide
 */
@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
public interface WatchFaceHostApi {
    /** Returns the watch face's [Context]. */
    public fun getContext(): Context

    /** Returns the UI thread [Handler]. */
    public fun getUiThreadHandler(): Handler

    /** Returns the Worker thread [Handler]. */
    public fun getBackgroundThreadHandler(): Handler

    /** Returns the initial user style stored by the system if there is one or null otherwise. */
    public fun getInitialUserStyle(): UserStyleWireFormat?

    /**
     * Sets ContentDescriptionLabels for text-to-speech screen readers to make your
     * complications, buttons, and any other text on your watchface accessible.
     *
     * Each label is a region of the screen in absolute coordinates, along with
     * time-dependent text. The regions must not overlap.
     *
     * You must set all labels at the same time; previous labels will be cleared. An empty
     * array clears all labels.
     *
     * In addition to labeling your complications, please include a label that will read the
     * current time. You can use [android.support.wearable.watchface.accessibility
     * .AccessibilityUtils.makeTimeAsComplicationText] to generate the proper
     * [android.support.wearable.complications.ComplicationText].
     *
     * This is a fairly expensive operation so use it sparingly (e.g. do not call it in
     * `onDraw()`).
     */
    public fun updateContentDescriptionLabels()

    /**
     * Sets the complications which are active in the watchface. Complication data will be
     * received for these ids.
     *
     * Any ids not in the provided [watchFaceComplicationIds] will be considered inactive.
     *
     * If providers and complication data types have been configured, the data received will
     * match the type chosen by the user. If no provider has been configured, data of type
     * [ComplicationData.TYPE_NOT_CONFIGURED] will be received.
     *
     * Ids here are chosen by the watch face to represent each complication and can be any
     * integer.
     */
    public fun setActiveComplications(watchFaceComplicationIds: IntArray)

    /**
     * Accepts a list of custom providers to attempt to set as the default provider for the
     * specified watch face complication id. The custom providers are tried in turn, if the
     * first doesn't exist then the next one is tried and so on. If none of them exist then the
     * specified system provider is set as the default instead.
     *
     * This will do nothing if the providers are not installed, or if the specified type is
     * not supported by the providers, or if the user has already selected a provider for the
     * complication.
     *
     * Note that if the watch face has not yet been granted the `RECEIVE_COMPLICATION_DATA`
     * permission, it will not be able to receive data from the provider unless the provider is
     * from the same app package as the watch face, or the provider lists the watch face as a
     * safe watch face. For system providers that may be used before your watch face has the
     * permission, use [setDefaultSystemComplicationProvider] with a safe provider
     * instead.
     *
     * A provider not satisfying the above conditions may still be set as a default using
     * this method, but the watch face will receive placeholder data of type
     * [ComplicationData.TYPE_NO_PERMISSION] until the permission has been granted.
     *
     * @param watchFaceComplicationId The watch face's ID for the complication
     * @param providers The list of non-system providers to try in order before falling back to
     * fallbackSystemProvider. This list may be null.
     * @param fallbackSystemProvider The system provider to use if none of the providers could be
     * used.
     * @param type The type of complication data that should be provided. Must be one of the types
     * defined in [ComplicationData].
     */
    public fun setDefaultComplicationProviderWithFallbacks(
        watchFaceComplicationId: Int,
        providers: List<ComponentName>?,
        @ProviderId fallbackSystemProvider: Int,
        type: Int
    )

    /** Schedules a call to [Renderer.renderInternal] to draw the next frame. */
    @UiThread
    public fun invalidate()
}