QSessionManager Class
La clase QSessionManager permite acceder al gestor de sesiones. Más información...
| Encabezado: | #include <QSessionManager> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Heredado de: | QObject |
Tipos públicos
| enum | RestartHint { RestartIfRunning, RestartAnyway, RestartImmediately, RestartNever } |
Funciones públicas
| bool | allowsErrorInteraction() |
| bool | allowsInteraction() |
| void | cancel() |
| QStringList | discardCommand() const |
| bool | isPhase2() const |
| void | release() |
| void | requestPhase2() |
| QStringList | restartCommand() const |
| QSessionManager::RestartHint | restartHint() const |
| QString | sessionId() const |
| QString | sessionKey() const |
| void | setDiscardCommand(const QStringList &command) |
| void | setManagerProperty(const QString &name, const QStringList &value) |
| void | setManagerProperty(const QString &name, const QString &value) |
| void | setRestartCommand(const QStringList &command) |
| void | setRestartHint(QSessionManager::RestartHint hint) |
Descripción detallada
Un gestor de sesiones en un entorno de escritorio (en el que se ejecutan las aplicaciones de Qt GUI ) realiza un seguimiento de una sesión, que es un grupo de aplicaciones en ejecución, cada una de las cuales tiene un estado concreto. El estado de una aplicación contiene (sobre todo) los documentos que la aplicación tiene abiertos, así como la posición y el tamaño de sus ventanas.
El gestor de sesiones se utiliza para guardar la sesión, por ejemplo, al apagar el equipo, y para restaurarla, por ejemplo, al encenderlo. Recomendamos utilizar ` QSettings ` para guardar la configuración de una aplicación, por ejemplo, las posiciones de las ventanas, los archivos utilizados recientemente, etc. Cuando el gestor de sesiones reinicia la aplicación, se puede restaurar dicha configuración.
QSessionManager proporciona una interfaz entre la aplicación y el gestor de sesiones de la plataforma. En Qt, las solicitudes de acción relacionadas con la gestión de sesiones se gestionan mediante las dos señales QGuiApplication::commitDataRequest() y QGuiApplication::saveStateRequest(). Ambas proporcionan una referencia a un objeto QSessionManager como argumento. Solo se puede acceder al gestor de sesiones en las ranuras invocadas por estas señales.
No es posible ninguna interacción del usuario a menos que la aplicación obtenga permiso explícito del gestor de sesiones. Se solicita permiso llamando a allowsInteraction() o, si es realmente urgente, a allowsErrorInteraction(). Qt no impone esta restricción, pero el gestor de sesiones sí puede hacerlo.
Se puede intentar abortar el proceso de apagado llamando a cancel().
En el caso de los gestores de sesión avanzados disponibles en Unix/X11, QSessionManager ofrece más posibilidades para ajustar con precisión el comportamiento de la gestión de sesiones de una aplicación: ` setRestartCommand()`, ` setDiscardCommand()`, ` setRestartHint()`, ` setProperty()` y ` requestPhase2()`. Consulte las descripciones de las funciones correspondientes para obtener más detalles.
Véase también QGuiApplication y «Gestión de sesiones».
Documentación sobre tipos de miembros
enum QSessionManager::RestartHint
Este tipo de enumeración define las circunstancias en las que esta aplicación desea que el gestor de sesiones la reinicie. Los valores actuales son:
| Constante | Valor | Descripción |
|---|---|---|
QSessionManager::RestartIfRunning | 0 | Si la aplicación sigue ejecutándose cuando se cierra la sesión, desea que se reinicie al inicio de la siguiente sesión. |
QSessionManager::RestartAnyway | 1 | La aplicación desea iniciarse al comienzo de la siguiente sesión, pase lo que pase. (Esto resulta útil para utilidades que se ejecutan justo después del arranque y luego se cierran). |
QSessionManager::RestartImmediately | 2 | La aplicación desea iniciarse inmediatamente siempre que no esté en ejecución. |
QSessionManager::RestartNever | 3 | La aplicación no desea reiniciarse automáticamente. |
La indicación predeterminada es « RestartIfRunning ».
Documentación de funciones de miembro
bool QSessionManager::allowsErrorInteraction()
Devuelve ` true ` si se permite la interacción en caso de error; en caso contrario, devuelve ` false`.
Esto es similar a ` allowsInteraction()`, pero además permite a la aplicación informar al usuario de cualquier error que se produzca. Los gestores de sesión pueden dar mayor prioridad a las solicitudes de interacción en caso de error, lo que significa que es más probable que se permita dicha interacción. Sin embargo, no hay garantía de que el gestor de sesión permita la interacción.
Véanse también allowsInteraction(), release() y cancel().
bool QSessionManager::allowsInteraction()
Solicita permiso al gestor de sesiones para interactuar con el usuario. Devuelve «true» si se permite la interacción; en caso contrario, devuelve « false ».
La razón de ser de este mecanismo es permitir sincronizar la interacción del usuario durante el apagado. Los gestores de sesión avanzados pueden solicitar a todas las aplicaciones simultáneamente que guarden sus datos, lo que se traduce en un apagado mucho más rápido.
Una vez finalizada la interacción, recomendamos encarecidamente liberar el semáforo de interacción con el usuario mediante una llamada a ` release()`. De este modo, otras aplicaciones podrán interactuar con el usuario mientras su aplicación sigue ocupada guardando datos. (El semáforo se libera implícitamente cuando la aplicación se cierra.)
Si el usuario decide cancelar el proceso de apagado durante la fase de interacción, debe informar al gestor de sesiones de que esto ha ocurrido llamando a cancel().
A continuación se muestra un ejemplo de cómo se podría implementar la función ` QGuiApplication::commitDataRequest()` de una aplicación:
MyMainWidget::MyMainWidget(QWidget*parent)
: QWidget(parent)
{
connect(qApp, &QGuiApplication::commitDataRequest,
this, &MyMainWidget::commitData);
}
void MyMainWidget::commitData(QSessionManager& manager)
{
if (manager.allowsInteraction()) {
int ret = QMessageBox::warning(
mainWindow,
tr("Mi aplicación"),
tr("¿Guardar los cambios en el documento?"),
QMessageBox::Guardar | QMessageBox::Descartar | QMessageBox::Cancel);
switch (ret) {
case QMessageBox::Guardar:
gestor.liberar();
si (!guardarDocumento())
gestor.cancelar();
break;
caso QMessageBox::Descartar:
break;
case QMessageBox::Cancelar:
por defecto:
manager.cancel();
}
} else {
// no hemos obtenido permiso para interactuar, entonces
// hacemos algo razonable en su lugar
}
}Si se ha producido un error en la aplicación al guardar sus datos, quizá te interese probar con allowsErrorInteraction() en su lugar.
Véase también QGuiApplication::commitDataRequest(), release() y cancel().
void QSessionManager::cancel()
Indica al gestor de sesiones que cancele el proceso de apagado. Las aplicaciones no deben llamar a esta función sin preguntar primero al usuario.
Véase también allowsInteraction() y allowsErrorInteraction().
QStringList QSessionManager::discardCommand() const
Devuelve el comando de descarte establecido actualmente.
Véase también setDiscardCommand(), restartCommand() y setRestartCommand().
bool QSessionManager::isPhase2() const
Devuelve « true » si el gestor de sesiones está llevando a cabo actualmente una segunda fase de gestión de sesiones; en caso contrario, devuelve « false ».
Véase también requestPhase2().
void QSessionManager::release()
Libera el semáforo de interacción del gestor de sesiones tras una fase de interacción.
Véase también allowsInteraction() y allowsErrorInteraction().
void QSessionManager::requestPhase2()
Solicita una segunda fase de gestión de sesiones para la aplicación. De este modo, la aplicación puede salir inmediatamente de las funciones ` QGuiApplication::commitDataRequest()` o ` QApplication::saveStateRequest()`, y estas se volverán a llamar una vez que la mayoría o todas las demás aplicaciones hayan finalizado su gestión de sesiones.
Las dos fases resultan útiles para aplicaciones como el gestor de ventanas X11, que necesitan almacenar información sobre las ventanas de otras aplicaciones y, por lo tanto, tienen que esperar a que dichas aplicaciones hayan completado sus respectivas tareas de gestión de sesión.
Nota: Si otra aplicación ha solicitado una segunda fase, es posible que esta se active antes, simultáneamente o después de la segunda fase de su aplicación.
Véase también isPhase2().
QStringList QSessionManager::restartCommand() const
Devuelve el comando de reinicio establecido actualmente.
Véase también setRestartCommand() y restartHint().
QSessionManager::RestartHint QSessionManager::restartHint() const
Devuelve la sugerencia de reinicio actual de la aplicación. El valor por defecto es « RestartIfRunning ».
Véase también setRestartHint().
QString QSessionManager::sessionId() const
Devuelve el identificador de la sesión actual.
Si la aplicación se ha restaurado a partir de una sesión anterior, este identificador es el mismo que el de la sesión anterior.
Véase también sessionKey() y QGuiApplication::sessionId().
QString QSessionManager::sessionKey() const
Devuelve la clave de sesión de la sesión actual.
Si la aplicación se ha restaurado a partir de una sesión anterior, esta clave es la misma que había al finalizar la sesión anterior.
La clave de sesión cambia con cada llamada a `commitData()` o `saveState()`.
Véase también sessionId() y QGuiApplication::sessionKey().
void QSessionManager::setDiscardCommand(const QStringList &command)
Establece el comando de descarte en el valor indicado: command.
Véase también discardCommand() y setRestartCommand().
void QSessionManager::setManagerProperty(const QString &name, const QStringList &value)
El acceso de escritura de bajo nivel al registro de identificación y estado de la aplicación se gestiona en el gestor de sesiones.
La propiedad denominada « name » tiene su valor establecido en la lista de cadenas « value ».
void QSessionManager::setManagerProperty(const QString &name, const QString &value)
El acceso de escritura de bajo nivel a los registros de identificación y estado de la aplicación se almacena en el gestor de sesiones.
La propiedad denominada « name » tiene su valor establecido en la cadena « value ».
Se trata de una función sobrecargada.
void QSessionManager::setRestartCommand(const QStringList &command)
Si el gestor de sesiones es capaz de restaurar sesiones, ejecutará el comando « command » para restaurar la aplicación. El valor predeterminado del comando es
appname -session idLa opción « -session » es obligatoria; de lo contrario, « QGuiApplication » no podrá determinar si se ha restaurado o cuál es el identificador de sesión actual. Consulta QGuiApplication::isSessionRestored() y QGuiApplication::sessionId() para obtener más detalles.
Si su aplicación es muy sencilla, es posible que pueda almacenar todo el estado de la aplicación en opciones adicionales de la línea de comandos. Por lo general, esto es una muy mala idea, ya que las líneas de comandos suelen estar limitadas a unos pocos cientos de bytes. En su lugar, utilice QSettings, archivos temporales o una base de datos para este fin. Al marcar los datos con el identificador único sessionId(), podrás restaurar la aplicación en una sesión futura.
Véanse también restartCommand(), setDiscardCommand() y setRestartHint().
void QSessionManager::setRestartHint(QSessionManager::RestartHint hint)
Establece la sugerencia de reinicio de la aplicación en « hint ». Al iniciarse la aplicación, la sugerencia se establece en « RestartIfRunning ».
Nota: Estos indicadores son solo sugerencias; un gestor de sesiones puede tenerlos en cuenta o no.
Recomendamos establecer la indicación de reinicio en ` QGuiApplication::saveStateRequest()` porque la mayoría de los gestores de sesión realizan un punto de control poco después del inicio de la aplicación.
Véase también restartHint().
© 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.