Settings QML Type

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

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

Propriétés

• category : string
• location : url

Méthodes

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

Description détaillée

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 Paramètres vous permet d'enregistrer 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 Settings. Seuls les types de valeurs reconnus par QSettings sont pris 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 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
    }
}

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

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 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();
}

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 ensuite contenir des paramètres utilisant les mêmes noms que ceux utilisés dans d'autres catégories - sans conflit.

Paramètres singleton

Il est souvent utile d'avoir des paramètres disponibles pour chaque fichier QML en tant que singleton. L'exemple de la liste des choses à faire en est un exemple. Spécifiquement, AppSettings.qml est le singleton, et dans le fichier CMakeLists.txt, la propriété QT_QML_SINGLETON_TYPE est définie à TRUE pour ce fichier via set_source_files_properties.

Notes

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

Voir aussi QSettings::group.

location : url

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

Si cette propriété est vide (par défaut), c'est QSettings::defaultFormat() qui sera utilisé. Sinon, c'est QSettings::IniFormat qui sera utilisé.

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

Documentation de la méthode

void setValue(string key, var value)

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

Voir également 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.

var value(string key, var defaultValue)

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

Voir aussi setValue() et QSettings::value.