Complicaciones de caras de reloj

Una complicación es cualquier característica que se muestra en una cara de reloj además de la hora. Por ejemplo, un indicador de carga de batería es una complicación. La API de Complications sirve tanto para caras de reloj como para apps de proveedores de datos.

En el resto de este documento, se describen proveedores de datos, caras de reloj y tipos de complicaciones.

Proveedores de datos de complicaciones

Las apps que proporcionan datos (como el nivel de batería, el estado del tiempo o el conteo de pasos) a las caras de reloj para las complicaciones se denominan "proveedores de datos de complicaciones". Esos proveedores proporcionan datos sin procesar y no se encargan de controlar la forma en que se representan sus datos en una cara de reloj. Para las apps de escritura que proporcionan datos a las caras de reloj, consulta Cómo exponer datos a complicaciones.

Como se muestra en el siguiente diagrama, Wear OS by Google actúa como intermediario en el flujo de datos de los proveedores a las caras de reloj.

Complicaciones en caras de reloj

Las caras de reloj reciben datos de proveedores de datos de complicaciones, lo que les permite incluir complicaciones sin la necesidad de usar código para obtener los datos subyacentes. Las caras de reloj controlan la forma en que se representan los datos, por lo que pueden integrar datos naturalmente con su diseño; consulta los patrones de diseño para complicaciones.

Para obtener más información sobre cómo agregar complicaciones a una cara de reloj, consulta Cómo agregar complicaciones a una cara de reloj.

Tipos de complicaciones

Los tipos de complicaciones definen el tipo de datos que puede mostrar una complicación o que puede proporcionar un proveedor de datos. Por ejemplo, el tipo SHORT_TEXT se usa cuando los datos consisten principalmente en una cadena corta. Un objeto ComplicationData siempre tendrá un solo tipo de complicación que define los campos obligatorios y opcionales. Generalmente, un campo obligatorio representa los datos más importantes; la mayoría de los tipos toman su nombre del campo obligatorio.

Los proveedores de datos usan estos tipos de complicaciones de forma diferente en comparación con las caras de reloj:

• Un proveedor de datos selecciona los tipos de datos de complicaciones que proporcionará (incluidos los campos opcionales de esos tipos que proporcionará) y la cantidad de tipos diferentes que se pueden admitir. Por ejemplo, un proveedor de conteo de pasos podría admitir los tipos RANGED_VALUE y SHORT_TEXT, mientras que un proveedor de "próxima reunión" podría admitir los tipos SHORT_TEXT y LONG_TEXT.
• Puedes seleccionar la cantidad de complicaciones que incluirás en tu cara de reloj y los tipos de complicaciones que admitirás. Por ejemplo, una complicación de cuadrante en una cara de reloj podría admitir los tipos SHORT_TEXT, ICON y RANGED_VALUE, mientras que un medidor podría admitir solo RANGED_VALUE.

Para obtener más información sobre los diferentes tipos de complicaciones y los campos admitidos por cada tipo, consulta Cómo usar y probar tipos de complicaciones.

Resumen de la API

A continuación, se incluye un resumen de la API de Complications. La API forma parte de la biblioteca de compatibilidad con dispositivos wearables; consulta la Referencia de la API de Wear.

• ComplicationData
  • Es divisible (usando un Bundle a nivel interno); inmutable.
  • Representa todos los tipos de datos de complicación.
  • Incluye un Builder para la creación de instancias.
• ComplicationDrawable
  • Permite representar una complicación completa en un lienzo.
• ComplicationHelperActivity
  • Se usa para solicitar el siguiente permiso:
    com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
  • Se usa en lugar de ProviderChooserIntent para iniciar el selector en la mayoría de los casos.
• ComplicationManager
  • Wrapper para el servicio administrado de complicaciones, para que lo usen los proveedores.
  • Permite a los proveedores enviar datos de complicación al sistema.
• ComplicationProviderService
  • Extiende Service e incluye métodos de devolución de llamada para responder al sistema de complicaciones.
  • Se llama a todos los métodos de devolución de llamada en el subproceso principal.
• ComplicationText
  • Se usa para proporcionar valores basados en texto en un objeto ComplicationData.
  • Incluye opciones para valores que dependen del tiempo, en los que el valor del texto depende de la hora actual.
• ProviderChooserIntent
  • Clase de utilidad que no admite la creación de instancias y no se usa comúnmente; en su lugar, usa ComplicationHelperActivity.
• ProviderInfoRetriever
  • La pueden usar las actividades de configuración de la cara de reloj a fin de obtener la información del proveedor de datos actual (app, nombre del proveedor e ícono) para todas las complicaciones que pertenecen a una cara de reloj.
• ProviderUpdateRequester
  • La pueden usar las apps del proveedor de datos a fin de activar llamadas a onComplicationUpdated en su servicio del proveedor para habilitar la inserción de actualizaciones.
• SystemProviders
  • Incluye los proveedores de sistemas que se consideran "seguros", ya que solo proporcionan información que la cara de reloj pudo obtener por sí misma.
• TextRenderer
  • Facilita el diseño de texto en un lienzo.

Además, la clase WatchFaceService.Engine contiene los siguientes métodos:

• setActiveComplications()
  • La cara de reloj debe llamar a esta clase para indicar al objeto ComplicationManager cuáles son las ranuras de complicaciones disponibles y los tipos admitidos.
• onComplicationDataUpdate()
  • Recibe llamadas del objeto ComplicationManager para enviar datos de la complicación a la cara de reloj.
• setDefaultSystemComplicationProvider()
  • Establece un proveedor de sistemas predeterminado para una complicación. Este método toma un ID (como un valor entero) para un proveedor de sistemas. Los ID disponibles se indican en la clase SystemProviders.