Funcionamiento de Qt para Android

Si eres un desarrollador que busca una visión general de alto nivel de cómo Qt soporta la plataforma Android, esta página es para ti.

Inicio de la aplicación Qt

Al igual que en las aplicaciones nativas de Android, la función onCreate() de la Actividad principal de Qt se ejecuta al principio, cuando se inicia la aplicación y se crea la Actividad. Ahí es donde tiene lugar la mayor parte de la inicialización de la Abstracción de la Plataforma Qt (QPA) de Android. Las partes más importantes son:

• Cargar Qt y las librerías de la aplicación principal.
• Inicialización de los delegados, que se encarga de inicializar las superficies de renderizado y el diseño de nivel superior, así como de registrar varios listeners como input, display, touch handlers, entre otros.

Al cargar las librerías Qt, la JavaVM se almacena en caché mientras QtCore se carga por primera vez. Esto se hace bajo la función JNI_OnLoad(), que es llamada sincrónicamente cuando una librería es cargada usando la llamada System.load(). Cada módulo Qt puede tener una implementación para esta función para hacer alguna inicialización específica del módulo, como registrar métodos JNI nativos.

Una vez cargadas todas las librerías de los módulos Qt, Qt carga el plugin QPA de Android y la librería principal de la aplicación. Después de que el diseño de nivel superior QtLayout haya terminado de inflar su contenido, el manejador main() de la aplicación Qt es localizado e invocado. Esto iniciará la aplicación C++ Qt y normalmente iniciará el bucle de eventos principal.

El QPA de Android

El Android Q PA es responsable de unir el lado Android (Java/Kotlin) con el lado nativo Qt (C++). Se encarga de la propagación de eventos y señales tanto desde Qt como desde Android. Esta responsabilidad abarca el manejo de señales, eventos táctiles, elementos UI, renderizado, etc. Esta capa también es responsable de la inicialización del arranque de la aplicación y de la limpieza al salir o destruir la aplicación.

Hilos

Con Qt para aplicaciones Android, Qt normalmente tiene dos hilos de interés. El primero es el QtThread que Qt inicia. El segundo es el hilo Android UI.

QtThread

Este hilo es implementado e iniciado por la aplicación Qt antes de, por ejemplo, cargar las librerías. Este hilo se llama qtMainLoopThread. Todas las operaciones siguientes se ejecutan bajo este hilo:

• Carga de librerías Qt.
• Operaciones realizadas dentro de JNI_OnLoad().
• Inicio de la aplicación nativa.
• La ejecución de main().

Hilo UI Android

Al igual que en las aplicaciones Android, se espera que las operaciones que afectan a la interfaz de usuario se ejecuten en el subproceso de interfaz de usuario. Qt hace eso bajo el capó para cualquier llamada interna que se espera que se ejecute en la UI. Además, Qt ofrece una API runOnAndroidMainThread() para ejecutar operaciones bajo este hilo desde código C++. Usando esta API, Qt gestiona cuándo las llamadas se envían directamente al hilo si la aplicación está activa, o se ponen en cola si la aplicación está en pausa o en segundo plano.

Arquitectura

Clases Qt

Las siguientes secciones repasan las distintas clases de Qt para Android y su funcionalidad y papel en las aplicaciones Qt.

Los enlaces Java públicos

Estas clases son clases públicas que envuelven los detalles de implementación interna de las clases orientadas al usuario como Activity, Service y Application. Estas clases se utilizan por defecto para aplicaciones Qt Android y se hace referencia a ellas en el archivo de manifiesto de Android. El sistema de compilación y las herramientas de despliegue se encargan de incluirlas en la compilación.

Los usuarios pueden utilizar estas clases para cambiar o ampliar el comportamiento por defecto. Por ejemplo, QtActivity extiende Activity e implementa la lógica necesaria para cargar las librerías Qt o manejar eventos y llamadas nativas entre Android y Qt.

Extender QtActivity es generalmente necesario si necesitas tener la implementación de Qt para varios eventos y llamadas entre Qt y Android. De lo contrario, extender Activity debería funcionar.

Para añadir lógica personalizada definida por el usuario bajo onCreate(), puedes usar lo siguiente:

public class MyActivity extends QtActivity
{
    @Override
    protected void onCreate(Bundle bundle)
    {
        // code before Qt is initialized
        super.onCreate(bundle);
        // code after Qt is initialized
    }
}

Establecer un Tema

Al extender QtActivity, puedes establecer un tema específico de Android usando setTheme(). Sin embargo, esa llamada debe preceder a la llamada a onCreate() de la clase padre para que tenga efecto, ya que Qt establece el tema por defecto. Por ejemplo, puedes usar:

@Override
protected void onCreate(Bundle bundle)
{
    setTheme(android.R.style.Theme_DeviceDefault_DayNight);
    super.onCreate(bundle);
}

Por defecto, para Android 10 y posteriores, Qt establece el tema Theme_DeviceDefault_DayNight Style, y Theme_Holo_Light Style para versiones anteriores.

Añadir un parámetro de aplicación

Para añadir un parámetro de aplicación extra, que es un argumento que se pasa a la función (main()) de la aplicación desde Java/Kotlin, puedes hacer lo siguiente después de extender QtActivity:

@Override
protected void onCreate(Bundle bundle)
{
    appendApplicationParameters("--flag value");
    super.onCreate(bundle);
}

Esto es similar a usar la variable CMake QT_ANDROID_APPLICATION_ARGUMENTS directamente. Los parámetros pasados usando cualquiera de los dos métodos aceptan espacios o tabuladores como separadores, y la lista final de parámetros pasados a la aplicación se analizan usando QProcess::splitCommand.

Cargando Bibliotecas Qt con QtLoader

Cada aplicación Qt para Android necesita asegurarse de que cada librería nativa Qt o de terceros se carga primero antes de invocar cualquier funcionalidad de esos módulos. El sistema de compilación mantiene una lista de varias dependencias de librerías Qt, el plugin QPA, la librería principal de la aplicación, y cualquier librería de terceros bajo el archivo de recursos libs.xml de la aplicación. Una vez realizados todos los pasos previos mencionados en las secciones siguientes, las librerías se cargan utilizando System.load().

El cargador de clases

El objeto cargador de clases se establece en QtLoader antes de cargar las librerías Qt o inicializar los delegados. Esto se debe a que el cargador de clases es utilizado por QJniObject para encontrar clases Java y es necesario para realizar cualquier llamada JNI con QJniObject.

Configuración de variables de entorno y parámetros de aplicación

Antes de cargar las librerías, Qt tiene que asegurarse de que las variables de entorno se pasan como metadatos en el manifiesto de Android para configurarlas. Este paso permite la inicialización de algunos módulos basados en las banderas de configuración establecidas como meta-datos del manifiesto. Algunos de estos meta-datos también se propagan a la lista de parámetros de la aplicación que se pasa a la aplicación cuando se inicia.

setActivity(), setContext() y setService()

Varios módulos Qt pueden necesitar hacer algún trabajo de inicialización desde el lado Java que requiera tener el contexto de la Actividad o Servicio. Estos módulos implementan un método estático que toma una Actividad, Servicio o Contexto como parámetro:

void setActivity(Activity activity)
{
    m_activity = activity;
    // Other logic
}

Entonces, el QtLoader invoca estos métodos con el contexto padre del cargador justo antes de cargar las librerías nativas compartidas.

Cómo Qt para Android maneja el ciclo de vida de la actividad Android

Qt para Android no proporciona una API para manejar directamente las llamadas de retorno del ciclo de vida de la actividad de Android como onCreate(), onStart(), onResume(), onPause(), onStop(), y onDestroy(). En su lugar, se encarga de estos procesos para el usuario. El comportamiento se describe en las siguientes secciones.

Manejo del Contexto

QAndroidApplication puede proporcionar el Contexto Android como QJniObject, esencial para interactuar con el sistema Android. Este contexto puede ser una Actividad o un Servicio. Si hay una Actividad, será la Actividad iniciada más recientemente, independientemente de si hay Servicios. Si sólo hay Servicios, será el Servicio iniciado más recientemente.

Llamadas de retorno

La clase QtActivityBase está diseñada para mantener los detalles de implementación de las diversas funcionalidades de una Actividad privada dentro del paquete Qt para Android. Esta clase es un mediador entre el ciclo de vida de Android y el framework Qt, traduciendo los callbacks del ciclo de vida de Android en señales y operaciones a las que la aplicación Qt puede responder.

onCreate()

Cuando se crea la actividad, QtActivityBase inicializa el entorno Qt. Esto incluye cargar las librerías Qt, configurar el cargador de clases que utiliza QJniObject, analizar los metadatos de la aplicación, y preparar la aplicación Qt para su ejecución. Asegura que toda la inicialización necesaria específica para la Actividad sea manejada.

onStart()

Llama al Activity.OnStart() de Android.

onResume()

Cuando la Actividad se mueve al primer plano, QtActivityBase reanuda la aplicación Qt. Se asegura de que los procesos u operaciones pausados continúan y la aplicación está de nuevo lista para la interacción del usuario. Volverá a registrar la escucha del gestor de pantalla detenida por onPause().

onPause()

Si otra actividad oscurece parcialmente la Activity, QtActivityBase pausa la aplicación Qt. Guardará el estado de la aplicación o liberará los recursos que no se necesiten mientras la aplicación no esté en primer plano.

onStop()

Cuando la Actividad ya no es visible, QtActivityBase detiene la aplicación Qt, lo que implica un guardado de estado y liberación de recursos más extensos, preparando la aplicación para su potencial destrucción.

onDestroy()

Si la Actividad ha terminado o está siendo destruida por el sistema, QtActivityBase limpia todos los recursos asociados con la aplicación Qt. Asegura un cierre correcto y que se realicen todas las operaciones de limpieza necesarias.

Esta integración permite a los desarrolladores centrarse en la construcción de su aplicación Qt sin preocuparse por las complejidades del ciclo de vida de Android, ya que QtActivityBase gestiona estas complejidades bajo el capó.

Gestión de la pantalla de bienvenida

QAndroidApplication QtActivityBase puede ocultar la pantalla de inicio con un efecto de fundido, que puede ser programado con la secuencia de inicio de la aplicación, por lo general después de onCreate().

Más información sobre Qt para Android

El vídeo de la Cumbre Mundial de Qt de 2021 ofrece una visión general de Qt para Android.

"Una imagen de una agenda que enlaza con un vídeo de YouTube"