Complicações de mostradores de 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 apps de provedores 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

Apps que disponibilizam 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 disponibilizam dados brutos e não são responsáveis por controlar o modo como as próprias informações são renderizadas em um mostrador do relógio. Para gravar apps que disponibilizem 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.

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 coletar os dados subjacentes. Mostradores de relógio mantêm o controle sobre como os dados são renderizados. Assim, eles podem integrar os dados naturalmente com o próprio 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

Os tipos de complicação definem quais dados podem ser mostrados em uma complicação ou disponibilizados 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 único 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 do 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 disponibilizados (inclusive quais campos opcionais desses tipos serão disponibilizados) e quantos tipos diferentes podem ser aceitos. Por exemplo, um provedor de contagem de passos pode ser compatível com os tipos RANGED_VALUE e SHORT_TEXT, enquanto um provedor de “próximo encontro” pode ser compatível com os tipos SHORT_TEXT e LONG_TEXT.
• Você pode escolher quantas complicações serão incluídas no mostrador do relógio e os tipos de complicação compatíveis. Por exemplo, uma complicação de discagem em um mostrador de relógio pode ser compatível com os tipos SHORT_TEXT, ICON e RANGED_VALUE, enquanto um medidor no mostrador do relógio pode ser compatível apenas com o tipo RANGED_VALUE.

Para saber mais sobre os diferentes tipos de complicação e os campos compatíveis com cada tipo, consulte Usar e testar tipos de complicação.

Resumo da API

Veja abaixo um resumo da API Complications, que faz parte da Biblioteca de Suporte para Wearable. 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, destinado a 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 disponibilizar valores de texto em um 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; prefira ComplicationHelperActivity
• ProviderInfoRetriever
  • Pode ser usado (por atividades de configuração do mostrador do relógio) para recuperar as informações do provedor de dados atual (app, nome do provedor, ícone) para todas as complicações pertencentes a um mostrador de relógio
• ProviderUpdateRequester
  • Pode ser usado por apps de provedores de dados para acionar chamadas para onComplicationUpdated no serviço do provedor para permitir o envio de atualizações
• SystemProviders
  • Lista os provedores de sistema considerados “seguros” por oferecerem apenas as informações que o mostrador do relógio pode coletar 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()
  • Precisa 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 compatíveis
• 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 um ID (como um número inteiro) para um provedor de sistema. Os IDs disponíveis são listados na classe SystemProviders.