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

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.

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 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.