Settings QML Type

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

Ce type est obsolète depuis la version 6.5 de Qt.labs.settings. Nous déconseillons fortement de l'utiliser dans du 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 » disponible sur Qt Qml Core.

Le type Settings fournit 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 individuelles des paramètres sont spécifiées en déclarant des propriétés au sein d’un élément « Settings ». Tous les types de valeurs sont pris en charge. L’approche recommandée consiste à utiliser des alias de propriétés 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 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, 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 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
    }
}

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 les identifiants d’ 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();
}

Ces identifiants sont généralement définis en C++ au début du fichier ` 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 risque de conflit.

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 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 permettent de regrouper des paramètres apparentés.

fileName : string [since Qt 5.12]

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

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

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

Documentation des méthodes

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

Définit la valeur de l'option « key » sur « 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 é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 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 ce paramètre n'existe pas, renvoie « defaultValue ».

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

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