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.