Ajouter des complications à un cadran

Une complication de cadran affiche les données issues d'une source de données. Avec l'API Complications, les cadrans peuvent choisir les sources de données qu'ils souhaitent utiliser pour obtenir les données sous-jacentes. Cela permet aux cadrans d'afficher des informations au-delà de l'heure de la journée sans avoir besoin de code pour les obtenir.

Utiliser un ComplicationSlotsManager

Pour ajouter des complications à un cadran, utilisez un ComplicationSlotsManager.

Le ComplicationSlotsManager définit le nombre de complications acceptées par un cadran et leur position sur l'écran. Pour permettre la modification de l'emplacement ou du nombre de complications, le ComplicationSlotsManager utilise également CurrentUserStyleRepository, comme illustré dans l'exemple suivant :

 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
        )
 }

Types et champs

Le tableau suivant décrit les types et les champs de l'objet ComplicationData. Si un cadran demande un champ non valide pour un type de complication, une valeur par défaut du champ est renvoyée. Par exemple, si un cadran tente d'accéder à un champ LONG_TEXT dans un type SHORT_TEXT, la valeur par défaut du champ LONG_TEXT, null, est renvoyée.

Type	Champs obligatoires	Champs facultatifs	Notes
`SHORT_TEXT`	Texte court	Icône Icône de protection contre les brûlures d'écran Titre court	Affiche une seule icône ou un titre court s'ils sont fournis.
`ICON`	Icône	Icône de protection contre les brûlures d'écran	Utilisée lorsque le texte n'est pas nécessaire. L'icône doit être de couleur unie et peut être teintée par le cadran.
`RANGED_VALUE`	Valeur Valeur minimale Valeur maximale	Icône Icône de protection contre les brûlures d'écran Texte court Titre court	L'affichage des champs facultatifs n'est pas garanti. Si vous souhaitez dessiner votre propre barre de progression, vous pouvez utiliser la méthode `isRangedValueProgressHidden()` pour masquer la barre de progression fournie par la classe `ComplicationDrawable`.
`LONG_TEXT`	Texte long	Titre long Icône Icône de protection contre les brûlures d'écran Petite image	Affiche le titre long s'il est fourni.
`SMALL_IMAGE`	Petite image		Une petite image présente l'un des deux styles suivants : style photo ou style icône. Le style de photo signifie que cette image est censée occuper tout l'espace et peut être recadrée. Le style d'icône signifie qu'elle ne peut pas être recadrée, mais qu'elle peut avoir une marge intérieure. La variabilité des images peut entraîner l'affichage d'une image inappropriée en mode Veille sur les appareils dotés d'une protection contre les brûlures ou du mode Veille à faible vitesse de transmission. Lorsque la protection contre les brûlures d'écran et le mode Veille à faible vitesse de transmission sont activés, le cadran peut utiliser la petite image de protection contre les brûlures d'écran, car elle est sans risque. Dans le cas contraire, comme un cadran peut difficilement déterminer l'adéquation d'une image, aucune image ne s'affiche.
`LARGE_IMAGE`	Grande image		Cette image doit être suffisamment grande pour remplir le cadran. La variabilité des images peut entraîner l'affichage d'une image inappropriée en mode Veille sur les appareils dotés d'une protection contre les brûlures ou du mode Veille à faible vitesse de transmission. Étant donné qu'un cadran peut difficilement déterminer si une image est adaptée, celui-ci n'affiche pas d'image en mode Veille si la protection contre les brûlures ou le mode Veille à faible vitesse de transmission sont activés.

Le tableau suivant décrit les types de complications correspondant aux données vides pouvant être envoyées pour n'importe quel emplacement de complication. Ces types n'ont pas de champ et n'ont pas besoin d'être inclus dans une liste de types compatibles. Ils permettent aux cadrans de se différencier dans les trois cas suivants :

Aucune source n'a été choisie.
L'utilisateur a sélectionné "Vide" pour un emplacement.
Une source n'a aucune donnée à envoyer.

Les sources ne peuvent pas envoyer TYPE_EMPTY en réponse à des requêtes de mise à jour. Envoyez plutôt TYPE_NO_DATA.

Type de complication	Description
`TYPE_NOT_CONFIGURED`	Envoyé par le système lorsqu'une complication s'active, mais que l'utilisateur n'a pas sélectionné de source et qu'aucune valeur par défaut n'a été définie. Ne peut pas être envoyé par des sources.
`TYPE_EMPTY`	Envoyé par le système lorsqu'une complication s'active et que l'utilisateur choisit "vide" au lieu d'une source, ou lorsque le cadran ne sélectionne aucune source et ce type de complication par défaut. Ne peut pas être envoyé par des sources.
`TYPE_NO_DATA`	Envoyé par le système lorsqu'une complication (qui a une source) s'active pour effacer la complication avant que des données réelles ne soient reçues de la source. Peut être envoyé par des sources si elles n'ont pas de données réelles à envoyer.

Pour en savoir plus, consultez l'exemple WatchFace sur GitHub.