Cómo funciona Qt para Android
Si eres desarrollador y buscas una visión general de alto nivel sobre cómo Qt es compatible con la plataforma Android, esta página es para ti.
Inicio de la aplicación Qt
Al igual que en las aplicaciones nativas de Android, el método onCreate() de la actividad principal de Qt se invoca al inicio de la aplicación, cuando se crea la actividad. Es ahí donde tiene lugar la mayor parte de la inicialización de la abstracción de la plataforma Qt para Android (QPA). Las partes más importantes son:
- Carga de Qt y de las bibliotecas de la aplicación principal.
- Inicialización de los delegados, que se encargan de inicializar las superficies de renderizado y el diseño de nivel superior, así como de registrar diversos oyentes, como los de entrada, visualización y controladores táctiles, entre otros.
Al cargar las bibliotecas de Qt, la JavaVM se almacena en caché mientras se carga por primera vez QtCore. Esto se lleva a cabo mediante la función JNI_OnLoad(), que se invoca de forma sincrónica cuando se carga una biblioteca mediante la llamada System.load(). Cada módulo de Qt puede tener una implementación de esta función para realizar alguna inicialización específica del módulo, como el registro de métodos JNI nativos.
Una vez cargadas todas las bibliotecas de los módulos de Qt, Qt carga el complemento QPA de Android y la biblioteca principal de la aplicación. Una vez que el diseño de nivel superior de QtLayout ha terminado de inflar su contenido, se localiza e invoca el identificador main() de la aplicación Qt. Esto iniciará la aplicación Qt en C++ y, por lo general, pondrá en marcha el bucle de eventos principal.
El QPA de Android
El QPA de Android se encarga de unir el lado de Android (Java/Kotlin) con el lado nativo de Qt (C++). Se encarga de la propagación de diversos eventos y señales tanto hacia como desde Qt a Android. Esa responsabilidad abarca la gestión de señales, los eventos táctiles, los elementos de la interfaz de usuario y el renderizado, entre otros. Esta capa también se encarga de la inicialización al inicio de la aplicación y de la limpieza al salir de la aplicación o al destruirse.
Hilos
En las aplicaciones Qt para Android, Qt suele tener dos subprocesos de interés. El primero es el ` QtThread ` que inicia Qt. El segundo es el subproceso de la interfaz de usuario de Android.
QtThread
Este hilo es implementado e iniciado por la aplicación Qt antes de, por ejemplo, cargar las bibliotecas. Este hilo se denomina « qtMainLoopThread ». Todas las operaciones siguientes se ejecutan en este hilo:
- Carga de las bibliotecas de Qt.
- Operaciones realizadas dentro de JNI_OnLoad().
- Inicio de la aplicación nativa.
- La ejecución de `
main()`.
Hilo de la interfaz de usuario de Android
Al igual que en las aplicaciones de Android, se espera que las operaciones que afectan a la interfaz de usuario se ejecuten en el hilo de la interfaz de usuario. Qt se encarga de ello de forma interna para cualquier llamada interna que deba ejecutarse en la interfaz de usuario. Además, Qt ofrece una API ` runOnAndroidMainThread()` para ejecutar operaciones en este hilo desde código C++. Mediante 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 de Qt
En las siguientes secciones se repasan las distintas clases de Qt para Android, así como su funcionalidad y su papel en las aplicaciones Qt.
Los enlaces públicos de Java
Estas son clases públicas que encapsulan los detalles de implementación interna de las clases orientadas al usuario, como `Activity`, `Service` y `Application`. Estas clases se utilizan de forma predeterminada en las aplicaciones Qt para Android y se mencionan en el archivo de manifiesto de Android. El sistema de compilación y las herramientas de implementación se encargan de incluirlas en la compilación.
Los usuarios pueden utilizar estas clases para modificar o ampliar el comportamiento predeterminado. Por ejemplo, QtActivity extiende Activity e implementa la lógica necesaria para cargar las bibliotecas de Qt o gestionar eventos y llamadas nativas entre Android y Qt.
Por lo general, es necesario extender ` QtActivity ` si se requiere la implementación de Qt para diversos eventos y llamadas entre Qt y Android. De lo contrario, debería bastar con extender ` Activity `.
Para añadir lógica personalizada definida por el usuario en ` onCreate()`, puedes utilizar 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
}
}Nota: Debes editar el archivo AndroidManifest.xml para utilizar tu Activity o clase de enlace personalizadas; de lo contrario, se seguirá utilizando la predeterminada.
Configuración de un tema
Al extender QtActivity, puedes establecer un tema específico de Android mediante setTheme(). Sin embargo, esa llamada debe preceder a la llamada a onCreate() de la clase padre para que surta efecto, ya que Qt establece el tema de forma predeterminada. Por ejemplo, puedes utilizar:
@Override
protected void onCreate(Bundle bundle)
{
setTheme(android.R.style.Theme_DeviceDefault_DayNight);
super.onCreate(bundle);
}De forma predeterminada, para Android 10 y versiones 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 adicional —es decir, un argumento que se pasa a la función ` (main()) ` de la aplicación desde Java/Kotlin—, puedes hacer lo siguiente tras extender `QtActivity`:
@Override
protected void onCreate(Bundle bundle)
{
appendApplicationParameters("--flag value");
super.onCreate(bundle);
}Esto es similar a utilizar directamente la variable de CMake QT_ANDROID_APPLICATION_ARGUMENTS. Los parámetros pasados mediante cualquiera de los dos métodos aceptan espacios o tabulaciones como separadores, y la lista final de parámetros pasados a la aplicación se analiza mediante QProcess::splitCommand.
Carga de bibliotecas Qt con QtLoader
Toda aplicación de Qt para Android debe asegurarse de que todas las bibliotecas nativas de Qt o de terceros se carguen primero antes de invocar cualquier funcionalidad de dichos módulos. El sistema de compilación mantiene una lista de las diversas dependencias de bibliotecas de Qt, el complemento QPA, la biblioteca principal de la aplicación y cualquier biblioteca de terceros en el archivo de recursos libs.xml de la aplicación. Una vez completados todos los pasos previos mencionados en las secciones siguientes, las bibliotecas se cargan mediante System.load().
El cargador de clases
El objeto cargador de clases lo establece desde el principio el « QtLoader » antes de cargar las bibliotecas de 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 la aplicación
Antes de cargar las bibliotecas, Qt debe asegurarse de que las variables de entorno se pasen como metadatos en el manifiesto de Android para su configuración. Este paso permite la inicialización de algunos módulos en función de los indicadores de configuración establecidos como metadatos del manifiesto. Parte de estos metadatos también se propaga a la lista de parámetros de la aplicación que se pasa a la aplicación al iniciarse.
setActivity(), setContext() y setService()
Es posible que varios módulos de Qt necesiten realizar tareas de inicialización desde el lado de Java que requieran disponer del contexto de la actividad o del servicio. Dichos módulos implementan entonces un método estático que toma una actividad, un servicio o un contexto como parámetro:
void setActivity(Activity activity)
{
m_activity = activity;
// Other logic
}A continuación, el « QtLoader » invoca estos métodos con el contexto padre del cargador justo antes de cargar las bibliotecas compartidas nativas.
Cómo gestiona Qt para Android el ciclo de vida de las actividades de Android
Qt para Android no proporciona una API para gestionar directamente las llamadas de retorno del ciclo de vida de las actividades de Android, como onCreate(), onStart(), onResume(), onPause(), onStop() y onDestroy(). En su lugar, se encarga de gestionarlas de forma interna por el usuario. El comportamiento se describe en las secciones siguientes.
Nota: Estos eventos del ciclo de vida se traducen a la señal ` QGuiApplication::applicationStateChanged `.
Gestión del contexto
QAndroidApplication puede proporcionar el contexto de Android como un ` 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 solo hay servicios, será el servicio iniciado más recientemente.
Nota: Qt para Android no admite múltiples actividades.
Llamadas de retorno
La clase `QtActivityBase` está diseñada para mantener privados, dentro del paquete Qt para Android, los detalles de implementación de las diversas funcionalidades de una actividad. Esta clase actúa como mediadora entre el ciclo de vida de Android y el marco de trabajo de Qt, traduciendo las llamadas de retorno 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 bibliotecas 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. Garantiza que se gestionen todas las inicializaciones necesarias específicas de la actividad.
onStart()
Llama a Activity.OnStart() de Android.
onResume()
Cuando la actividad pasa a primer plano, QtActivityBase reanuda la aplicación Qt. Garantiza que los procesos u operaciones en pausa continúen y que la aplicación vuelva a estar lista para la interacción del usuario. Volverá a registrar el oyente del gestor de pantalla detenido por onPause().
onPause()
Si otra actividad oculta parcialmente la actividad, QtActivityBase pausa la aplicación Qt. Guardará el estado de la aplicación o liberará los recursos que no sean necesarios 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 más exhaustivo del estado y la liberación de recursos, preparando la aplicación para su posible destrucción.
Nota: El QtThread queda suspendido en este momento.
onDestroy()
Si la actividad ha finalizado o está siendo destruida por el sistema, QtActivityBase libera todos los recursos asociados a la aplicación Qt. Garantiza un apagado correcto y que se realicen todas las operaciones de limpieza necesarias.
Esta integración permite a los desarrolladores centrarse en crear su aplicación Qt sin preocuparse por las complejidades del ciclo de vida de Android, ya que QtActivityBase gestiona estas complejidades en segundo plano.
Gestión de la pantalla de inicio
QAndroidApplication Permite ocultar la pantalla de inicio con un efecto de desvanecimiento, que puede sincronizarse con la secuencia de inicio de la aplicación, normalmente después de onCreate().
Más información sobre Qt para Android
El vídeo de la Qt World Summit 2021 ofrece una visión general de Qt para Android.
«Imagen de un programa que enlaza con un vídeo de YouTube»
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.