Settings QML Type

Proporciona una configuración persistente de la aplicación independiente de la plataforma. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• category : string
• location : url

Métodos

• void setValue(string key, var value)
• void sync()
• var value(string key, var defaultValue)

Descripción detallada

El tipo Settings proporciona configuraciones de aplicación persistentes e independientes de la plataforma.

Normalmente, los usuarios esperan que una aplicación recuerde su configuración (tamaño y posición de las ventanas, opciones, etc.) en todas las sesiones. El tipo Configuración permite guardar y restaurar estos ajustes de la aplicación con el mínimo esfuerzo.

Los valores de configuración individuales se especifican declarando propiedades dentro de un elemento Configuración. Sólo se admiten los tipos de valores reconocidos por QSettings. Se recomienda utilizar alias de propiedades para obtener actualizaciones automáticas de las propiedades en ambos sentidos. El siguiente ejemplo muestra cómo utilizar la 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
    }
}

En el primer inicio de la aplicación, la ventana obtiene unas dimensiones por defecto especificadas como 800x600. Observe que no se especifica ninguna posición por defecto - dejamos que el gestor de ventanas se encargue de ello. Más tarde, cuando la geometría de la ventana cambie, 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, devolviendo la ventana a la posición y tamaño anteriores.

Una sintaxis totalmente declarativa, conseguida mediante el uso de alias de propiedades, tiene el coste de almacenar configuraciones persistentes cada vez que cambian los valores de las propiedades con alias. Las propiedades normales se pueden utilizar para obtener un control más preciso sobre el almacenamiento de la configuración persistente. El siguiente ejemplo ilustra cómo guardar una configuración al destruir 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
    }
}

Observe cómo el valor predeterminado se especifica ahora en la propiedad de configuración persistente, y la propiedad real está vinculada a la 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 la aplicación name, organization y domain, o 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();
}

Suelen especificarse en C++ al principio de main(), pero también pueden controlarse en QML mediante las siguientes propiedades:

• Qt.application.name,
• Qt.application.organization y
• Qt.application.domain.

Categorías

Los ajustes de la aplicación pueden dividirse en categorías lógicas especificando un nombre de categoría mediante la propiedad category. El uso de categorías lógicas no sólo proporciona una estructura de configuración más limpia, sino que también evita posibles conflictos entre las claves de configuración.

Si se necesitan varias categorías, utilice varios objetos Ajustes, 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 tienen nombres únicos, los ajustes se pueden dividir en categorías únicas que pueden contener ajustes con los mismos nombres que se utilizan en otras categorías, sin conflictos.

Configuración singleton

A menudo es útil tener configuraciones disponibles para cada archivo QML como un singleton. Para ver un ejemplo de esto, consulte el ejemplo de la lista de tareas. En concreto, AppSettings.qml es el singleton, y en el archivo CMakeLists.txt, la propiedad QT_QML_SINGLETON_TYPE se establece en TRUE para ese archivo a través de set_source_files_properties.

Notas

La implementación actual se basa en QSettings. Esto impone ciertas limitaciones, como la falta de notificaciones de cambios. Escribir un valor de configuración utilizando una instancia de Configuración no actualiza el valor en otra instancia de Configuración, incluso si se refieren a la misma configuración en 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. Consulte la documentación de QSettings para obtener más detalles.

Véase también QSettings.

Documentación de propiedades

category : string

Esta propiedad contiene el nombre de la categoría de configuración.

Las categorías se pueden utilizar para agrupar configuraciones relacionadas.

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 (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 del ajuste key en value. Si la clave ya existe, se sobrescribe el valor anterior.

Véase también value() y QSettings::setValue.

void sync()

Escribe cualquier cambio no guardado en el almacenamiento permanente, y recarga cualquier configuración que haya sido cambiada mientras tanto por otra aplicación.

Esta función es llamada automáticamente desde el destructor de QSettings y por el bucle de eventos a intervalos regulares, por lo que normalmente no necesitas llamarla tú mismo.

Véase también QSettings::sync.

var value(string key, var defaultValue)

Devuelve el valor de la configuración key. Si el ajuste no existe, devuelve defaultValue.

Véase también setValue() y QSettings::value.