O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Criar um serviço para mostradores de relógio

Um mostrador do relógio é um serviço empacotado em um app para Wear OS. Quando o usuário seleciona uma opção disponível, o mostrador do relógio é exibido e os métodos de callback de serviço são invocados.

Quando o usuário instala um app para Wear OS que possui mostradores de relógio, os mostradores ficam disponíveis no relógio por meio de um seletor. Opcionalmente, o usuário pode selecionar um mostrador de relógio de um app complementar no smartphone pareado.

Esta página descreve como configurar um projeto do Wear OS para incluir mostradores de relógio e como implementar um serviço de mostrador do relógio.

Criar um projeto de mostrador do relógio

Para criar um projeto no Android Studio para o mostrador do relógio:

  1. Clique em Studio > New > New project.
  2. Na janela Create Android Project, aceite os valores padrão e clique em Next.
  3. Na janela Target Android Devices, selecione somente a opção Wear e, na lista de versões do SDK, selecione a versão mais recente disponível. Clique em Next.
  4. Na janela Add an Activity to Wear, selecione Watch Face e clique em Next.
  5. Na janela Configure Activity, aceite os valores padrão e clique em Finish.

O Android Studio cria um projeto com um módulo app para o serviço de mostrador do relógio. Para mais informações sobre projetos no Android Studio, consulte Criar um projeto.

Dependências

A Biblioteca de Suporte para Wearables disponibiliza as classes necessárias que você estende para criar implementações de mostrador do relógio. As bibliotecas de cliente do Google Play Services (play-services e play-services-wearable) são necessárias para sincronizar itens de dados entre o dispositivo associado e o wearable com a API Wearable Data Layer.

O Android Studio acrescenta automaticamente as entradas necessárias nos arquivos build.gradle quando você cria o projeto nas instruções acima.

Referência de API da biblioteca de suporte para Wearables

A documentação de referência traz informações detalhadas sobre as classes que você usa para implementar mostradores de relógio. Navegue pela documentação de referência da API da Biblioteca de Suporte para Wearables.

Observação: recomendamos o uso do Android Studio para o desenvolvimento para o Wear OS, uma vez que ele oferece configuração de projetos, inclusão de bibliotecas e facilidades no empacotamento.

Declarar permissões

O mostrador do relógio requer a permissão WAKE_LOCK. Adicione a seguinte permissão aos arquivos de manifesto do app para Wear OS (app para wearable) e do app para dispositivos móveis (smartphone) no elemento manifest:

    <manifest ...>
        <uses-permission
            android:name="android.permission.WAKE_LOCK" />

        <!-- Required for complications to receive complication data and open the provider chooser. -->
        <uses-permission
            android:name="com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA"/>
        ...
    </manifest>
    

Cuidado: o app para dispositivos portáteis precisa incluir todas as permissões declaradas no app para wearable.

Implementar o serviço e métodos de callback

Os mostradores de relógio no Wear OS são implementados como serviços. Quando o mostrador do relógio está ativo, o sistema invoca os métodos no próprio serviço quando a hora muda ou quando ocorre um evento importante (como a mudança para o modo ambiente ou o recebimento de uma nova notificação). Em seguida, a implementação do serviço desenha o mostrador do relógio na tela usando a hora atualizada e todos os outros dados relevantes.

Para implementar um mostrador de relógio, estenda CanvasWatchFaceService e CanvasWatchFaceService.Engine e, em seguida, modifique os métodos de callback na classe CanvasWatchFaceService.Engine. Essas classes estão incluídas na Biblioteca de Suporte para Wearables.

O snippet a seguir descreve os principais métodos que você precisa implementar:

Kotlin

    class AnalogWatchFaceService : CanvasWatchFaceService() {

        override fun onCreateEngine(): Engine {
            /* provide your watch face implementation */
            return Engine()
        }

        /* implement service callback methods */
        inner class Engine : CanvasWatchFaceService.Engine() {

            override fun onCreate(holder: SurfaceHolder) {
                super.onCreate(holder)
                /* initialize your watch face */
            }

            override fun onPropertiesChanged(properties: Bundle?) {
                super.onPropertiesChanged(properties)
                /* get device features (burn-in, low-bit ambient) */
            }

            override fun onTimeTick() {
                super.onTimeTick()
                /* the time changed */
            }

            override fun onAmbientModeChanged(inAmbientMode: Boolean) {
                super.onAmbientModeChanged(inAmbientMode)
                /* the wearable switched between modes */
            }

            override fun onDraw(canvas: Canvas, bounds: Rect) {
                /* draw your watch face */
            }

            override fun onVisibilityChanged(visible: Boolean) {
                super.onVisibilityChanged(visible)
                /* the watch face became visible or invisible */
            }
        }
    }
    

Java

    public class AnalogWatchFaceService extends CanvasWatchFaceService {

        @Override
        public Engine onCreateEngine() {
            /* provide your watch face implementation */
            return new Engine();
        }

        /* implement service callback methods */
        private class Engine extends CanvasWatchFaceService.Engine {

            @Override
            public void onCreate(SurfaceHolder holder) {
                super.onCreate(holder);
                /* initialize your watch face */
            }

            @Override
            public void onPropertiesChanged(Bundle properties) {
                super.onPropertiesChanged(properties);
                /* get device features (burn-in, low-bit ambient) */
            }

            @Override
            public void onTimeTick() {
                super.onTimeTick();
                /* the time changed */
            }

            @Override
            public void onAmbientModeChanged(boolean inAmbientMode) {
                super.onAmbientModeChanged(inAmbientMode);
                /* the wearable switched between modes */
            }

            @Override
            public void onDraw(Canvas canvas, Rect bounds) {
                /* draw your watch face */
            }

            @Override
            public void onVisibilityChanged(boolean visible) {
                super.onVisibilityChanged(visible);
                /* the watch face became visible or invisible */
            }
        }
    }
    

A classe CanvasWatchFaceService fornece um mecanismo de invalidação semelhante ao método View.invalidate(). Você pode chamar o método invalidate() em toda a implementação quando quiser que o sistema redesenhe o mostrador do relógio. Só é possível usar o método invalidate() na linha de execução de IU principal. Para invalidar a tela de outra linha de execução, chame o método postInvalidate().

Para mais informações sobre como implementar os métodos na classe CanvasWatchFaceService.Engine, consulte Desenhar mostradores de relógio.

Registrar o serviço de mostrador do relógio

Depois de implementar o serviço de mostrador do relógio, registre a implementação no arquivo de manifesto do app para wearable. Quando os usuários instalam esse app, o sistema usa as informações sobre o serviço para disponibilizar o mostrador do relógio no app associado do Wear OS e no seletor de mostradores no dispositivo wearable.

O snippet a seguir mostra como registrar uma implementação de mostrador do relógio no elemento application:

    <service
        android:name=".AnalogWatchFaceService"
        android:label="@string/analog_name"
        android:permission="android.permission.BIND_WALLPAPER" >
        <meta-data
            android:name="android.service.wallpaper"
            android:resource="@xml/watch_face" />
        <meta-data
            android:name="com.google.android.wearable.watchface.preview"
            android:resource="@drawable/preview_analog" />
        <meta-data
            android:name="com.google.android.wearable.watchface.preview_circular"
            android:resource="@drawable/preview_analog_circular" />
        <intent-filter>
            <action android:name="android.service.wallpaper.WallpaperService" />
            <category
                android:name=
                "com.google.android.wearable.watchface.category.WATCH_FACE" />
        </intent-filter>
    </service>
    

O app associado do Wear OS e o seletor de mostradores do relógio no wearable usam a imagem de visualização definida pela entrada de metadados com.google.android.wearable.watchface.preview ao apresentar aos usuários todos os mostradores do relógio instalados no dispositivo. Para gerar esse drawable, execute o mostrador do relógio no dispositivo Wear OS ou em uma instância de emulador e faça uma captura de tela. Em dispositivos Wear OS com telas hdpi, a imagem de visualização normalmente tem 320 x 320 pixels.

Os mostradores de relógio que têm aparência significativamente diferente em dispositivos redondos podem oferecer tanto imagens de visualização redondas quanto quadradas. Para especificar uma imagem de visualização arredondada, use a entrada de metadados com.google.android.wearable.watchface.preview_circular. Se o mostrador do relógio incluir ambas as imagens de visualização, o app associado e o seletor de mostradores do relógio no wearable mostrarão a opção adequada de acordo com o formato do relógio. Se não houver uma imagem de visualização redonda incluída, a opção quadrada será usada igualmente em dispositivos quadrados e redondos. Nos dispositivos redondos, uma imagem de visualização quadrada é cortada por meio de uma forma circular.

A entrada de metadados android.service.wallpaper especifica o arquivo de recurso watch_face.xml, que contém um elemento wallpaper:

    <?xml version="1.0" encoding="UTF-8"?>
    <wallpaper xmlns:android="http://schemas.android.com/apk/res/android" />
    

Seu app para wearable pode conter mais de um mostrador de relógio. É necessário adicionar uma entrada de serviço ao arquivo de manifesto do app para wearable para cada implementação de mostrador do relógio.