Settings QML Type

Permet de définir des paramètres d'application persistants et indépendants de la plateforme. En savoir plus...

• 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 « Paramètres » permet de définir des paramètres d'application persistants et indépendants de la plateforme.

Les utilisateurs s'attendent généralement à ce qu'une application mémorise ses paramètres (tailles et positions des fenêtres, options, etc.) d'une session à l'autre. Le type « Settings » vous permet d'enregistrer et de restaurer ces paramètres d'application avec un minimum d'effort.

Les valeurs de chaque paramètre sont spécifiées en déclarant des propriétés au sein 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é afin de bénéficier de mises à jour automatiques des propriétés dans les deux sens. L’exemple suivant montre comment utiliser « Settings » pour enregistrer 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, la fenêtre se voit attribuer des dimensions par défaut de 800x600. Notez qu’aucune position par défaut n’est spécifiée : nous laissons le gestionnaire de fenêtres s’en charger. Par la suite, lorsque la géométrie de la fenêtre changera, les nouvelles valeurs seront automatiquement enregistrées dans les paramètres persistants. Lors du deuxième lancement de l’application, les valeurs initiales seront récupérées à partir des paramètres persistants, ce qui ramènera la fenêtre à sa position et à sa taille précédentes.

Une syntaxe entièrement déclarative, obtenue grâce à l’utilisation d’alias de propriétés, implique de sauvegarder les 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 bénéficier d’un contrôle plus fin sur la sauvegarde des paramètres persistants. L’exemple suivant illustre comment enregistrer 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
    }
}

Notez que la valeur par défaut est désormais spécifiée dans la propriété de paramètre persistant, et que la propriété réelle est liée à ce paramètre afin de récupérer la valeur initiale à partir des paramètres persistants.

Identifiants d’application

Les paramètres spécifiques à l’application sont identifiés en fournissant l’ name, organization et domain de l’application, 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();
}

Ces identifiants 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 de l’application peuvent être répartis 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ètres plus claire, mais aussi d’éviter d’éventuels conflits entre les clés de paramètres.

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 veiller à ce que tous les paramètres de l’application aient des noms uniques, ceux-ci peuvent être répartis dans des catégories distinctes pouvant alors contenir des paramètres portant les mêmes noms que ceux utilisés dans d’autres catégories, sans qu’il y ait de conflit.

Singleton de paramètres

Il est souvent utile de disposer de paramètres accessibles à tous les fichiers QML sous la forme d’un singleton. Pour un exemple concret, consultez l’exemple « To Do List ». Plus précisément, AppSettings.qml fait office de singleton, et dans le fichier CMakeLists.txt, la propriété QT_QML_SINGLETON_TYPE est définie sur TRUE pour ce fichier via set_source_files_properties.

Remarques

L’implémentation actuelle repose sur QSettings. Cela impose certaines limitations, telles que l’absence de notifications de modification. L’écriture d’une valeur de paramètre à l’aide d’une instance de Settings ne met pas à jour la valeur dans une autre instance de Settings, même si celles-ci font référence au même paramètre dans la même catégorie.

Les informations sont stockées dans le registre système sous Windows, et dans des fichiers de préférences XML sous macOS. Sur les autres systèmes Unix, en l’absence de norme, des fichiers texte INI sont utilisés. Consultez la documentation de 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 permettent de regrouper des paramètres apparentés.

Voir également QSettings::group.

location : url

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

Si cette propriété est vide (valeur par défaut), la valeur « QSettings::defaultFormat » () sera utilisée. Sinon, la valeur « QSettings::IniFormat » sera utilisée.

Voir également QSettings::fileName, QSettings::defaultFormat et QSettings::IniFormat.

Documentation de la méthode

void setValue(string key, var value)

Définit la valeur de la clé « key » sur « value ». Si la clé existe déjà, la valeur précédente est écrasée.

Voir également value() et QSettings::setValue.

void sync()

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

Cette fonction est appelée automatiquement depuis le destructeur de ` QSettings` et par la boucle d'événements à intervalles réguliers ; vous n'avez donc généralement pas besoin de l'appeler vous-même.

Voir également QSettings::sync.

var value(string key, var defaultValue)

Renvoie la valeur associée au paramètre key. Si ce paramètre n'existe pas, renvoie defaultValue.

Voir également setValue() et QSettings::value.