Settings QML Type

Fournit des paramètres d'application persistants et indépendants de la plate-forme. Plus...

Ce type est obsolète depuis Qt.labs.settings 6.5. Il est fortement déconseillé de l'utiliser dans un nouveau code.

• Liste de tous les membres, y compris les membres hérités

Propriétés

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

Méthodes

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

Description détaillée

Utilisez plutôt Settings de Qt Qml Core.

Le type Settings fournit des paramètres d'application persistants et indépendants de la plate-forme.

Les utilisateurs s'attendent normalement à ce qu'une application se souvienne de ses paramètres (taille et position des fenêtres, options, etc.) d'une session à l'autre. Le type Settings vous permet de sauvegarder et de restaurer ces paramètres d'application avec un minimum d'effort.

Les valeurs des paramètres individuels sont spécifiées en déclarant des propriétés à l'intérieur d'un élément Paramètres. Toutes les propriétés de type valeur sont prises en charge. Il est recommandé d'utiliser des alias de propriétés afin d'obtenir des mises à jour automatiques des propriétés dans les deux sens. L'exemple suivant montre comment utiliser les paramètres pour stocker et restaurer la géométrie d'une fenêtre.

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
    }
}

Au premier démarrage de l'application, les dimensions par défaut de la fenêtre sont fixées à 800x600. Notez qu'aucune position par défaut n'est spécifiée - nous laissons le gestionnaire de fenêtres s'en charger. Plus tard, lorsque la géométrie de la fenêtre changera, les nouvelles valeurs seront automatiquement stockées dans les paramètres persistants. Lors de la deuxième exécution de l'application, les valeurs initiales seront récupérées dans les paramètres persistants, ce qui ramènera la fenêtre à la position et à la taille précédentes.

Une syntaxe entièrement déclarative, obtenue grâce à l'utilisation d'alias de propriétés, a pour contrepartie le stockage de paramètres persistants chaque fois que les valeurs des propriétés aliasées changent. Les propriétés normales peuvent être utilisées pour obtenir un contrôle plus fin sur le stockage des paramètres persistants. L'exemple suivant illustre la sauvegarde d'un paramètre lors de la destruction d'un composant.

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
    }
}

Remarquez que la valeur par défaut est maintenant spécifiée dans la propriété du paramètre persistant, et que la propriété réelle est liée au paramètre afin d'obtenir la valeur initiale à partir des paramètres persistants.

Identifiants d'application

Les paramètres spécifiques à une application sont identifiés en fournissant les applications name, organization et domain, ou en spécifiant 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();
}

Ils sont généralement spécifiés en C++ au début de main(), mais peuvent également être contrôlés en QML via les propriétés suivantes :

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

Catégories

Les paramètres d'application peuvent être divisés en catégories logiques en spécifiant un nom de catégorie via la propriété category. L'utilisation de catégories logiques permet non seulement d'obtenir une structure de paramétrage plus propre, mais aussi d'éviter les conflits éventuels entre les clés de paramétrage.

Si plusieurs catégories sont nécessaires, utilisez plusieurs objets Settings, chacun avec sa propre catégorie :

Item {
    id: panel

    visible: true

    Settings {
        category: "OutputPanel"
        property alias visible: panel.visible
        // ...
    }

    Settings {
        category: "General"
        property alias fontSize: fontSizeSpinBox.value
        // ...
    }
}

Au lieu de s'assurer que tous les paramètres de l'application ont des noms uniques, les paramètres peuvent être divisés en catégories uniques qui peuvent alors contenir des paramètres utilisant les mêmes noms que ceux utilisés dans d'autres catégories - sans conflit.

Remarques

L'implémentation actuelle est basée sur QSettings. Cela impose certaines limitations, telles que l'absence de notifications de changement. L'écriture d'une valeur de paramètre à l'aide d'une instance de Paramètres ne met pas à jour la valeur dans une autre instance de Paramètres, même si elles se réfèrent au même paramètre dans la même catégorie.

Les informations sont stockées dans le registre du système sous Windows et dans les fichiers de préférences XML sous macOS. Sur d'autres systèmes Unix, en l'absence de norme, des fichiers texte INI sont utilisés. Voir la documentation QSettings pour plus de détails.

Voir également Settings et QSettings.

Documentation sur les propriétés

category : string

Cette propriété contient le nom de la catégorie de paramètres.

Les catégories peuvent être utilisées pour regrouper des paramètres apparentés.

fileName : string [since Qt 5.12]

Cette propriété contient le chemin d'accès au fichier de configuration. Si le fichier n'existe pas encore, il est créé.

Cette propriété a été introduite dans Qt 5.12.

Voir aussi QSettings::fileName et QSettings::IniFormat.

Documentation de la méthode

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

Fixe la valeur du paramètre key à value. Si la clé existe déjà, la valeur précédente est écrasée.

Cette méthode a été introduite dans Qt 5.12.

Voir aussi value() et QSettings::setValue.

void sync()

Écrit toutes les modifications non enregistrées dans la mémoire permanente et recharge tous les paramètres qui ont été modifiés entre-temps par une autre application.

Cette fonction est appelée automatiquement par le destructeur de QSettings et par la boucle d'événements à intervalles réguliers, de sorte que vous n'avez normalement pas besoin de l'appeler vous-même.

Voir également QSettings::sync.

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

Renvoie la valeur du paramètre key. Si le paramètre n'existe pas, elle renvoie defaultValue.

Cette méthode a été introduite dans Qt 5.12.

Voir aussi setValue() et QSettings::value.