Adicionar complicações à tela do relógio

A complicação de tela do relógio mostra informações de uma fonte de dados. Com a API Complications, os mostradores do relógio podem escolher quais fontes usar para receber dados. Assim, é possível mostrar outras informações além do horário sem precisar de códigos específicos para extrair os dados.

Usar uma classe ComplicationSlotsManager

Para adicionar complicações a uma tela de relógio, use um ComplicationSlotsManager.

O ComplicationSlotsManager define quantas complicações podem ser usadas no mostrador do relógio e onde elas são posicionadas. Para oferecer suporte à mudança do local ou do número de complicações, a classe ComplicationSlotsManager também usa o CurrentUserStyleRepository, conforme mostrado neste exemplo:

 override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager {
        val defaultCanvasComplicationFactory =
            CanvasComplicationFactory { watchState, listener ->
                // ...
            }

        val leftComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 100,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        val rightComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 101,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        return ComplicationSlotsManager(
            listOf(leftComplicationSlot, rightComplicationSlot),
            currentUserStyleRepository
        )
 }

Tipos e campos

A tabela a seguir descreve os tipos e campos do objeto ComplicationData. Se uma tela de relógio solicitar um campo inválido para um tipo de complicação, um valor padrão para esse campo vai ser retornado. Por exemplo, se a tela do relógio tentar acessar o campo LONG_TEXT em um tipo SHORT_TEXT, o valor padrão para o campo LONG_TEXT (null) vai ser retornado.

Tipo Campos obrigatórios Campos opcionais Observações
SHORT_TEXT Texto curto Ícone
Ícone de proteção de pixels
Título curto
Mostra apenas um ícone ou título curto caso um deles ou os dois sejam fornecidos.
ICON Ícone Ícone de proteção de pixels Usado quando nenhum texto é necessário. O ícone precisa ter uma só cor e pode ser colorido pelo mostrador do relógio.
RANGED_VALUE Valor
Valor mínimo
Valor máximo
Ícone
Ícone de proteção de pixels
Texto curto
Título curto
Não há garantias de que os campos opcionais sejam mostrados. Se quiser mostrar a própria barra de progresso, use o método isRangedValueProgressHidden() para ocultar a fornecida pela classe ComplicationDrawable.
LONG_TEXT Texto longo Título longo
Ícone
Ícone de proteção de pixels
Imagem pequena
Mostra o título longo caso ele seja fornecido.
SMALL_IMAGE Imagem pequena Uma imagem pequena tem um destes estilos: de foto ou de ícone. O estilo de foto indica que a imagem preenche um determinado espaço e pode ser cortada. O estilo do ícone indica que ela não pode ser cortada e pode ser preenchida. A variabilidade de imagens pode resultar em uma imagem inadequada para exibição no modo ambiente em dispositivos com proteção de pixels ou com poucos bits. Quando a proteção de pixels ou o modo ambiente de poucos bits estiver ativado, o mostrador do relógio pode usar a imagem pequena com proteção de pixels, porque é seguro fazer isso. Caso contrário, como o mostrador do relógio tem dificuldade para determinar a adequação, nenhuma imagem vai ser mostrada.
LARGE_IMAGE Imagem grande Essa imagem deve ser grande o bastante para preencher a tela do relógio. A variabilidade de imagens pode resultar em uma imagem inadequada para exibição no modo ambiente em dispositivos com proteção de pixels ou com poucos bits. Como o mostrador do relógio tem dificuldade para determinar a adequação ao display, ele não vai mostrar uma imagem no modo ambiente se a proteção de pixels ou o ambiente com poucos bits estiverem ativados.

A tabela abaixo descreve os tipos de complicação para dados vazios que podem ser enviados para qualquer slot de complicação. Eles não têm campos e não precisam ser incluídos em uma lista de tipos com suporte. Eles permitem que as telas de relógio façam a distinção entre estes três casos:

  • Nenhuma fonte foi escolhida.
  • O usuário selecionou "empty" para um slot.
  • A fonte não tem dados para enviar.

As fontes não podem enviar TYPE_EMPTY em resposta a pedidos de atualização. Em vez disso, envie TYPE_NO_DATA.

Tipo de complicação Descrição
TYPE_NOT_CONFIGURED Enviado pelo sistema quando uma complicação é ativada, mas o usuário não selecionou uma fonte e nenhum padrão foi definido.

Não pode ser enviado por fontes.

TYPE_EMPTY Enviado pelo sistema quando uma complicação é ativada e o usuário escolhe "empty" em vez de uma fonte ou quando o mostrador do relógio não escolhe uma fonte e esse tipo é o padrão.

Não pode ser enviado por fontes.

TYPE_NO_DATA Enviado pelo sistema quando uma complicação que tem uma fonte é ativada para limpar a complicação antes que dados reais sejam recebidos da fonte.

Precisa ser enviado por fontes quando elas não têm dados reais para enviar.

Para mais informações, confira o exemplo WatchFace (link em inglês) no GitHub.