Register now for Android Dev Summit 2019!

Complicações do mostrador do relógio

Uma complicação é qualquer recurso do mostrador do relógio que é exibido além do horário. Por exemplo, o indicador de bateria é uma complicação. A API Complications é destinada a mostradores de relógio e a aplicativos de fornecimento de dados.

O restante deste documento descreve provedores de dados, mostradores de relógio e tipos de complicações.

Provedores de dados de complicação

Aplicativos que fornecem dados (como o nível da bateria, o clima ou dados de contagem de passos) a mostradores de relógio são chamados de “provedores de dados de complicação”. Esses provedores de dados fornecem dados brutos e não são responsáveis por controlar como suas informções são renderizadas em um mostrador do relógio. Para gravar aplicativos que forneçam dados a mostradores de relógio, consulte Expor dados a complicações.

Conforme mostrado no diagrama abaixo, o Wear OS by Google media o fluxo de dados dos provedores aos mostradores de relógio.

Fluxo de dados de complicação

Complicações em mostradores de relógio

Mostradores de relógios recebem dados de provedores de dados de complicação, o que permite que eles incluam complicações sem precisar de código para obter os dados subjacentes. Mostradores de relógio mantêm o controle sobre como os dados são renderizados, portanto, eles podem integrar os dados naturalmente com o design; confira os padrões de design para complicações.

Para saber como adicionar complicações a um mostrador do relógio, consulte Adicionar complicações a um mostrador de relógio.

Tipos de complicação

Tipos de complicação definem os tipos de dados que podem ser mostrados em uma complicação ou fornecidos por um provedor de dados. Por exemplo, o tipo SHORT_TEXT é usado quando os dados consistem principalmente em uma string curta. Um objeto ComplicationData sempre terá um só tipo de complicação que define os campos obrigatórios e opcionais. Geralmente, um campo obrigatório representa os dados principais; a maioria dos tipos adota o nome de seu campo obrigatório.

Provedores de dados usam esses tipos de complicação de forma diferente dos mostradores de relógio:

  • Um provedor de dados escolhe os tipos de dados de complicação a serem fornecidos (incluindo quais campos opcionais fornecer dentre esses tipos) e quantos tipos diferentes podem ser suportados. Por exemplo, um provedor de contagem de passos pode oferecer suporte aos tipos RANGED_VALUE e SHORT_TEXT, enquanto um provedor de “próximo encontro” pode oferecer suporte aos tipos SHORT_TEXT e LONG_TEXT.
  • Você pode escolher quantas complicações deseja incluir no mostrador do relógio e a quais tipos oferecer suporte. Por exemplo, uma complicação de discagem em um mostrador de relógio pode oferecer suporte aos tipos SHORT_TEXT, ICON e RANGED_VALUE, enquanto um medidor no mostrador do relógio pode oferecer suporte apenas ao tipo RANGED_VALUE.

Para saber mais sobre os diferentes tipos de complicação e os campos suportados por cada tipo, consulte Usar e testar tipos de complicação.

Resumo da API

Veja a seguir um resumo da API Complications. A API faz parte da Biblioteca de suporte de wearables; consulte a Referência da API Wear.

  • ComplicationData
    • Analisável (usando um Bundle internamente); imutável
    • Representa todos os tipos de dados de complicação
    • Inclui um Builder para criação de instâncias
  • ComplicationDrawable
    • Permite que você renderize uma complicação inteira em um canvas
  • ComplicationHelperActivity
    • Usado para solicitar a seguinte permissão:
      com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
    • Usado em vez de ProviderChooserIntent para iniciar o seletor em quase todos os casos
  • ComplicationManager
    • Um wrapper para o serviço de gerenciamento de complicações, para uso dos provedores
    • Permite que os provedores enviem dados de complicação para o sistema
  • ComplicationProviderService
    • Estende Service e inclui métodos de callback para responder ao sistema de complicações
    • Métodos de callback são chamados no thread principal
  • ComplicationText
    • Usado para fornecer valores de texto em objeto ComplicationData
    • Inclui opções para valores que dependem do horário atual
  • ProviderChooserIntent
    • Classe de utilitário não instanciável que não é comumente usada; use ComplicationHelperActivity no lugar
  • ProviderInfoRetriever
    • Pode ser usado (por atividades de configuração do mostrador do relógio) para recuperar as informações do provedor de dados atual (aplicativo, nome do provedor, ícone) para todas as complicações que pertencem a um mostrador de relógio
  • ProviderUpdateRequester
    • Pode ser usado por aplicativos de provedores de dados para acionar chamadas para onComplicationUpdated no serviço do provedor, para permitir o envio de atualizações
  • SystemProviders
    • Lita os provedores de sistema que são considerados “seguros”, pois eles apenas fornecem as informações que o mostrador do relógio pode obter por conta própria
  • TextRenderer
    • Facilita o desenho de texto em um canvas

Além disso, a classe WatchFaceService.Engine contém os seguintes métodos:

  • setActiveComplications()
    • Deve ser chamado pelo mostrador do relógio para informar o objeto ComplicationManager sobre quais slots de complicação estão disponíveis e quais tipos são suportados
  • onComplicationDataUpdate()
    • Chamado pelo objeto ComplicationManager para enviar dados de complicação para o mostrador do relógio
  • setDefaultSystemComplicationProvider()
    • Define o provedor de sistema padrão para uma complicação. Esse método aceita uma ID (como um número inteiro) para um provedor de sistema. As IDs disponíveis são listadas na classe SystemProviders.