Settings QML Type
Proporciona una configuración de la aplicación persistente e independiente de la plataforma. Más...
| Import Statement: | import QtCore |
| Since: | Qt 6.5 |
| Inherits: |
Propiedades
Métodos
Descripción detallada
El tipo «Configuración» proporciona ajustes de aplicación persistentes e independientes de la plataforma.
Normalmente, los usuarios esperan que una aplicación recuerde su configuración (tamaños y posiciones de ventanas, opciones, etc.) entre sesiones. El tipo «Settings» te permite guardar y restaurar dicha configuración de la aplicación con el mínimo esfuerzo.
Los valores de cada configuración se especifican declarando propiedades dentro de un elemento «Configuración». Solo se admiten los tipos de valor reconocidos por QSettings. Se recomienda utilizar alias de propiedades para obtener actualizaciones automáticas de las mismas en ambos sentidos. El siguiente ejemplo muestra cómo utilizar «Configuración» para almacenar y restaurar la geometría de una ventana.
import QtCore
import QtQuick
Window {
id: window
width: 800
height: 600
Settings {
property alias x: window.x
property alias y: window.y
property alias width: window.width
property alias height: window.height
}
}Al iniciar la aplicación por primera vez, la ventana adquiere unas dimensiones predeterminadas de 800x600. Obsérvese que no se especifica ninguna posición por defecto: dejamos que el gestor de ventanas se encargue de ello. Más adelante, cuando cambie la geometría de la ventana, los nuevos valores se almacenarán automáticamente en la configuración persistente. La segunda ejecución de la aplicación obtendrá los valores iniciales de la configuración persistente, lo que devolverá a la ventana a su posición y tamaño anteriores.
Una sintaxis totalmente declarativa, que se consigue mediante el uso de alias de propiedades, conlleva el coste de almacenar la configuración persistente cada vez que cambian los valores de las propiedades con alias. Se pueden utilizar propiedades normales para obtener un control más detallado sobre el almacenamiento de la configuración persistente. El siguiente ejemplo ilustra cómo guardar una configuración al destruirse un componente.
import QtCore
import QtQuick
Item {
id: page
state: settings.state
states: [
State {
name: "active"
// ...
},
State {
name: "inactive"
// ...
}
]
Settings {
id: settings
property string state: "active"
}
Component.onDestruction: {
settings.state = page.state
}
}Fíjate en cómo ahora el valor por defecto se especifica en la propiedad de configuración persistente, y la propiedad real está vinculada a dicha configuración para obtener el valor inicial de la configuración persistente.
Identificadores de aplicación
Los ajustes específicos de la aplicación se identifican proporcionando name, organization y domain, o bien especificando location.
#include <QGuiApplication>
#include <QQmlApplicationEngine>
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
app.setOrganizationName("Some Company");
app.setOrganizationDomain("somecompany.com");
app.setApplicationName("Amazing Application");
QQmlApplicationEngine engine("main.qml");
return app.exec();
}Normalmente se especifican en C++ al principio de main(), pero también se pueden controlar en QML mediante las siguientes propiedades:
Categorías
La configuración de la aplicación se puede dividir en categorías lógicas especificando un nombre de categoría mediante la propiedad category. El uso de categorías lógicas no solo proporciona una estructura de configuración más clara, sino que también evita posibles conflictos entre las claves de configuración.
Si se necesitan varias categorías, utilice varios objetos `Settings`, cada uno con su propia categoría:
Item {
id: panel
visible: true
Settings {
category: "OutputPanel"
property alias visible: panel.visible
// ...
}
Settings {
category: "General"
property alias fontSize: fontSizeSpinBox.value
// ...
}
}En lugar de asegurarse de que todos los ajustes de la aplicación tengan nombres únicos, los ajustes se pueden dividir en categorías únicas que, a su vez, pueden contener ajustes con los mismos nombres que se utilizan en otras categorías, sin que se produzca ningún conflicto.
Singleton de configuración
A menudo resulta útil disponer de una configuración accesible para todos los archivos QML como un singleton. Para ver un ejemplo de esto, consulta el ejemplo «Lista de tareas pendientes». Concretamente, AppSettings.qml es el singleton y, en el archivo CMakeLists.txt, la propiedad ` QT_QML_SINGLETON_TYPE ` se establece en ` TRUE ` para ese archivo mediante ` set_source_files_properties`.
Notas
La implementación actual se basa en QSettings. Esto impone ciertas limitaciones, como la ausencia de notificaciones de cambios. Al escribir un valor de configuración utilizando una instancia de Settings, no se actualiza el valor en otra instancia de Settings, incluso si ambas hacen referencia a la misma configuración dentro de la misma categoría.
La información se almacena en el registro del sistema en Windows y en archivos de preferencias XML en macOS. En otros sistemas Unix, a falta de un estándar, se utilizan archivos de texto INI. Consulta la documentación de QSettings para obtener más detalles.
Véase también QSettings.
Documentación sobre propiedades
category : string
Esta propiedad contiene el nombre de la categoría de configuración.
Las categorías se pueden utilizar para agrupar ajustes relacionados.
Véase también QSettings::group.
location : url
Esta propiedad contiene la ruta al archivo de configuración. Si el archivo aún no existe, se creará.
Si esta propiedad está vacía (valor por defecto), se utilizará QSettings::defaultFormat(). En caso contrario, se utilizará QSettings::IniFormat.
Véase también QSettings::fileName, QSettings::defaultFormat y QSettings::IniFormat.
Documentación del método
void setValue(string key, var value)
Establece el valor de la configuración « key » en « value ». Si la clave ya existe, se sobrescribe el valor anterior.
Véase también value() y QSettings::setValue.
void sync()
Guarda en el almacenamiento permanente cualquier cambio no guardado y vuelve a cargar cualquier configuración que haya sido modificada entretanto por otra aplicación.
Esta función se invoca automáticamente desde el destructor de QSettings y mediante el bucle de eventos a intervalos regulares, por lo que normalmente no es necesario que la invoques tú mismo.
Véase también QSettings::sync.
var value(string key, var defaultValue)
Devuelve el valor de la configuración « key ». Si la configuración no existe, devuelve « defaultValue ».
Véase también setValue() y QSettings::value.
© 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.