Settings QML Type

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

Este tipo está obsoleto desde Qt.labs.settings 6.5. Desaconsejamos su uso en código nuevo.

• Lista de todos los miembros, incluyendo los heredados

Propiedades

• category : string
• fileName : string (since Qt 5.12)

Métodos

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

Descripción detallada

Utilice Settings de Qt Qml Core en su lugar.

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 Settings permite guardar y restaurar la configuración 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. Se admiten todas las propiedades de tipo valor. 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 QtQuick.Window
import Qt.labs.settings

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 tiene unas dimensiones por defecto especificadas de 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 QtQuick
import Qt.labs.settings

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 fileName.

#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 pueden dividirse en categorías únicas que pueden contener ajustes con los mismos nombres que se utilizan en otras categorías, sin conflictos.

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 más detalles.

Véase también Settings y 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 ajustes relacionados.

fileName : string [since Qt 5.12]

Esta propiedad contiene la ruta al archivo de configuración. Si el archivo no existe, se crea.

Esta propiedad se introdujo en Qt 5.12.

Véase también QSettings::fileName y QSettings::IniFormat.

Documentación del método

[since Qt 5.12] 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.

Este método se introdujo en Qt 5.12.

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.

[since Qt 5.12] var value(string key, var defaultValue)

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

Este método se introdujo en Qt 5.12.

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