QSettings Class

Description détaillée

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. Ces informations sont souvent stockées dans le registre système sous Windows, et dans des fichiers de liste de propriétés sous macOS et iOS. Sur les systèmes Unix, en l'absence de norme, de nombreuses applications (y compris celles de KDE) utilisent des fichiers texte INI.

QSettings est une abstraction de ces technologies, vous permettant d'enregistrer et de restaurer les paramètres d'une application de manière portable. Il prend également en charge custom storage formats.

L’API de QSettings repose sur QVariant, ce qui vous permet d’enregistrer la plupart des types basés sur des valeurs, tels que QString, QRect et QImage, avec un minimum d’effort.

Si vous n'avez besoin que d'une structure en mémoire non persistante, envisagez plutôt d'utiliser QMap<QString, QVariant>.

Utilisation de base

Lors de la création d’un objet QSettings, vous devez passer le nom de votre entreprise ou organisation ainsi que le nom de votre application. Par exemple, si votre produit s’appelle Star Runner et que votre entreprise s’appelle MySoft, vous construirez l’objet QSettings comme suit :

    QSettings settings("MySoft", "Star Runner");

Les objets QSettings peuvent être créés soit sur la pile, soit sur le tas (c'est-à-dire à l'aide de ` new`). La création et la destruction d'un objet QSettings sont très rapides.

Si vous utilisez QSettings à plusieurs endroits dans votre application, vous pouvez spécifier le nom de l’organisation et celui de l’application à l’aide de ` QCoreApplication::setOrganizationName()` et ` QCoreApplication::setApplicationName()`, puis utiliser le constructeur par défaut de QSettings :

    QCoreApplication::setOrganizationName("MySoft");
    QCoreApplication::setOrganizationDomain("mysoft.com");
    QCoreApplication::setApplicationName("Star Runner");
    ...
    QSettings settings;

(Ici, nous spécifions également le domaine Internet de l’organisation. Lorsque le domaine Internet est défini, il est utilisé sous macOS et iOS à la place du nom de l’organisation, car les applications macOS et iOS utilisent traditionnellement les domaines Internet pour s’identifier. Si aucun domaine n’est défini, un faux domaine est dérivé du nom de l’organisation. Voir l’ Platform-Specific Notes ci-dessous pour plus de détails.)

QSettings stocke les paramètres. Chaque paramètre est constitué d’une paire « clé-valeur » ( QString ) qui spécifie le nom du paramètre (la clé) et d’une valeur ( QVariant ) qui stocke les données associées à la clé. Pour écrire un paramètre, utilisez ` setValue()`. Par exemple :

    settings.setValue("editor/wrapMargin", 68);

Si un paramètre portant la même clé existe déjà, la valeur existante est écrasée par la nouvelle valeur. Pour des raisons d'efficacité, les modifications peuvent ne pas être immédiatement enregistrées dans le stockage permanent. (Vous pouvez à tout moment appeler sync() pour valider vos modifications.)

Vous pouvez récupérer la valeur d’un paramètre à l’aide de ` value()` :

    int margin = settings.value("editor/wrapMargin").toInt();

S’il n’existe aucun paramètre portant le nom spécifié, QSettings renvoie une valeur nulle QVariant (qui peut être convertie en entier 0). Vous pouvez spécifier une autre valeur par défaut en passant un deuxième argument à value() :

    int margin = settings.value("editor/wrapMargin", 80).toInt();

Pour vérifier si une clé donnée existe, appelez ` contains()`. Pour supprimer le paramètre associé à une clé, appelez ` remove()`. Pour obtenir la liste de toutes les clés, appelez ` allKeys()`. Pour supprimer toutes les clés, appelez ` clear()`.

QVariant et types d’interface graphique

QVariant faisant partie du module Qt Core, il ne peut pas fournir de fonctions de conversion vers des types de données tels que QColor, QImage et QPixmap, qui font partie de Qt GUI. En d’autres termes, il n’existe pas de fonctions toColor(), toImage() ou toPixmap() dans QVariant.

À la place, vous pouvez utiliser la fonction modèle QVariant::value(). Par exemple :

QSettings settings("MySoft", "Star Runner");
QColor color = settings.value("DataPump/bgcolor").value<QColor>();

La conversion inverse (par exemple, de QColor vers QVariant) est automatique pour tous les types de données pris en charge par QVariant, y compris les types liés à l’interface graphique :

QSettings settings("MySoft", "Star Runner");
QColor color = QColor(Qt::blue);
settings.setValue("DataPump/bgcolor", color);

Les types personnalisés enregistrés à l’aide de ` qRegisterMetaType()` et disposant d’opérateurs permettant la transmission vers et depuis un ` QDataStream ` peuvent être stockés à l’aide de `QSettings`.

Syntaxe des sections et des clés

Les clés de paramètres peuvent contenir n'importe quel caractère Unicode. Le format de fichier et le système d'exploitation déterminent si elles sont sensibles à la casse ou non. Sous Windows, le registre et les fichiers INI utilisent des clés insensibles à la casse, tandis que les formats définis par l'utilisateur et enregistrés via ` registerFormat()` peuvent être sensibles ou insensibles à la casse. Sur les systèmes Unix, les clés sont toujours sensibles à la casse.

Pour éviter les problèmes de portabilité, respectez ces règles simples :

1. Faites toujours référence à la même clé en utilisant la même casse. Par exemple, si vous faites référence à une clé sous le nom « text fonts » à un endroit de votre code, ne l'appelez pas « Text Fonts » ailleurs.
2. Évitez les noms de clés identiques à l'exception de la casse. Par exemple, si vous avez une clé nommée « MainWindow », n'essayez pas d'enregistrer une autre clé sous le nom « mainwindow ».
3. N’utilisez pas de barres obliques (« / » et « \ ») dans les noms de sections ou de clés ; le caractère « \ » sert à séparer les sous-clés (voir ci-dessous). Sous Windows, les « \ » sont convertis par QSettings en « / », ce qui les rend identiques.

Vous pouvez créer des clés hiérarchiques en utilisant le caractère « / » comme séparateur, à l’instar des chemins d’accès aux fichiers sous Unix. Par exemple :

    settings.setValue("mainwindow/size", win->size());
    settings.setValue("mainwindow/fullScreen", win->isFullScreen());
    settings.setValue("outputpanel/visible", panel->isVisible());

Si vous souhaitez enregistrer ou restaurer de nombreux paramètres avec le même préfixe, vous pouvez spécifier ce préfixe à l’aide de ` beginGroup()` et appeler ` endGroup()` à la fin. Voici à nouveau le même exemple, mais cette fois en utilisant le mécanisme de groupe :

    settings.beginGroup("mainwindow");
    settings.setValue("size", win->size());
    settings.setValue("fullScreen", win->isFullScreen());
    settings.endGroup();

    settings.beginGroup("outputpanel");
    settings.setValue("visible", panel->isVisible());
    settings.endGroup();

Si un groupe est défini à l’aide de beginGroup(), le comportement de la plupart des fonctions change en conséquence. Les groupes peuvent être définis de manière récursive.

Outre les groupes, QSettings prend également en charge le concept de « tableau ». Voir beginReadArray() et beginWriteArray() pour plus de détails.

Mécanisme de repli

Supposons que vous ayez créé un objet QSettings avec le nom d’organisation MySoft et le nom d’application Star Runner. Lorsque vous recherchez une valeur, jusqu’à quatre emplacements sont parcourus dans cet ordre :

1. un emplacement spécifique à l’utilisateur pour l’application Star Runner
2. un emplacement spécifique à l’utilisateur pour toutes les applications de MySoft
3. un emplacement à l'échelle du système pour l'application Star Runner
4. un emplacement système pour toutes les applications de MySoft

(Consultez la section « Platform-Specific Notes » ci-dessous pour savoir où se trouvent ces emplacements sur les différentes plateformes prises en charge par Qt.)

Si une clé est introuvable dans le premier emplacement, la recherche se poursuit dans le deuxième emplacement, et ainsi de suite. Cela vous permet de stocker des paramètres à l’échelle du système ou de l’organisation et de les remplacer au cas par cas, par utilisateur ou par application. Pour désactiver ce mécanisme, appelez setFallbacksEnabled(false).

Bien que les clés des quatre emplacements soient accessibles en lecture, seul le premier fichier (l’emplacement spécifique à l’utilisateur pour l’application en question) est accessible en écriture. Pour écrire dans l’un des autres fichiers, omettez le nom de l’application et/ou spécifiez QSettings::SystemScope (par opposition à QSettings::UserScope, la valeur par défaut).

Voyons cela avec un exemple :

    QSettings obj1("MySoft", "Star Runner");
    QSettings obj2("MySoft");
    QSettings obj3(QSettings::SystemScope, "MySoft", "Star Runner");
    QSettings obj4(QSettings::SystemScope, "MySoft");

Le tableau ci-dessous récapitule quels objets QSettings accèdent à quel emplacement. «X » signifie que l’emplacement est l’emplacement principal associé à l’objet QSettings et qu’il est utilisé à la fois pour la lecture et pour l’écriture ; « o » signifie que l’emplacement est utilisé comme solution de secours lors de la lecture.

L'intérêt de ce mécanisme réside dans le fait qu'il fonctionne sur toutes les plateformes prises en charge par Qt et qu'il vous offre une grande flexibilité, sans que vous ayez à spécifier de noms de fichiers ni de chemins d'accès au registre.

Si vous souhaitez utiliser des fichiers INI sur toutes les plateformes plutôt que l'API native, vous pouvez passer QSettings::IniFormat en premier argument au constructeur de QSettings, suivi de la portée, du nom de l'organisation et du nom de l'application :

    QSettings settings(QSettings::IniFormat, QSettings::UserScope,
                       "MySoft", "Star Runner");

Notez que les fichiers INI ne font pas la distinction entre les données numériques et les chaînes de caractères utilisées pour les encoder ; ainsi, les valeurs écrites sous forme de nombres seront lues comme des chaînes de caractères ( QString). La valeur numérique peut être récupérée à l’aide des fonctions QString::toInt(), QString::toDouble() et des fonctions associées.

Restauration de l’état d’une application GUI

QSettings est souvent utilisé pour stocker l’état d’une application GUI. L’exemple suivant illustre comment utiliser QSettings pour enregistrer et restaurer la géométrie de la fenêtre principale d’une application.

void MainWindow::writeSettings()
{
    QSettings settings("Moose Soft", "Clipper");

    settings.beginGroup("MainWindow");
    settings.setValue("geometry", saveGeometry());
    settings.endGroup();
}

void MainWindow::readSettings()
{
    QSettings settings("Moose Soft", "Clipper");

    settings.beginGroup("MainWindow");
    const auto geometry = settings.value("geometry", QByteArray()).toByteArray();
    if (geometry.isEmpty())
        setGeometry(200, 200, 400, 400);
    else
        restoreGeometry(geometry);
    settings.endGroup();
}

Consultez la section Géométrie des fenêtres pour comprendre pourquoi il est préférable d’appeler QWidget::resize() et QWidget::move() plutôt que QWidget::setGeometry() pour restaurer la géométrie d’une fenêtre.

Les fonctions readSettings() et writeSettings() doivent être appelées depuis le constructeur de la fenêtre principale et le gestionnaire d'événement close comme suit :

MainWindow::MainWindow()
{
    ...
    readSettings();
}

void MainWindow::closeEvent(QCloseEvent *event)
{
    if (userReallyWantsToQuit()) {
        writeSettings();
        event->accept();
    } else {
        event->ignore();
    }
}

Accès simultané aux paramètres depuis plusieurs threads ou processus

QSettings est réentrant. Cela signifie que vous pouvez utiliser simultanément des objets QSettings distincts dans différents threads. Cette garantie s'applique même lorsque les objets QSettings font référence aux mêmes fichiers sur le disque (ou aux mêmes entrées dans le registre système). Si un paramètre est modifié via un objet QSettings, la modification sera immédiatement visible dans tous les autres objets QSettings qui opèrent sur le même emplacement et qui résident dans le même processus.

QSettings peut être utilisé en toute sécurité depuis différents processus (qui peuvent être différentes instances de votre application s'exécutant simultanément ou des applications totalement différentes) pour lire et écrire dans les mêmes emplacements système, à condition que certaines conditions soient remplies. Pour ` QSettings::IniFormat`, il utilise un verrouillage consultatif des fichiers et un algorithme de fusion intelligent afin de garantir l’intégrité des données. Pour que cela fonctionne, le fichier de configuration accessible en écriture doit être un fichier ordinaire et se trouver dans un répertoire où l’utilisateur actuel peut créer de nouveaux fichiers temporaires. Si ce n’est pas le cas, il faut utiliser ` setAtomicSyncRequired()` pour désactiver cette mesure de sécurité.

Notez que la fonction ` sync()` importe les modifications apportées par d’autres processus (en plus d’enregistrer les modifications issues de ce `QSettings`).

Remarques spécifiques à la plateforme

Emplacements de stockage des paramètres de l’application

Comme mentionné dans la section Fallback Mechanism, QSettings stocke les paramètres d’une application dans un maximum de quatre emplacements, selon que ces paramètres sont spécifiques à l’utilisateur ou à l’ensemble du système, et qu’ils concernent une application en particulier ou l’ensemble de l’organisation. Par souci de simplicité, nous supposons que l’organisation s’appelle MySoft et que l’application s’appelle Star Runner.

Sur les systèmes Unix, si le format de fichier est NativeFormat, les fichiers suivants sont utilisés par défaut :

1. $HOME/.config/MySoft/Star Runner.conf
2. $HOME/.config/MySoft.conf
3. pour chaque répertoire <dir> dans $XDG_CONFIG_DIRS : <dir>/MySoft/Star Runner.conf
4. pour chaque répertoire <dir> présent dans $XDG_CONFIG_DIRS : <dir>/MySoft.conf

Sous macOS et iOS, si le format de fichier est NativeFormat, ces fichiers sont utilisés par défaut :

1. $HOME/Library/Preferences/com.MySoft.Star Runner.plist
2. $HOME/Library/Preferences/com.MySoft.plist
3. /Library/Preferences/com.MySoft.Star Runner.plist
4. /Library/Preferences/com.MySoft.plist

Sous Windows, les paramètres d'NativeFormat sont stockés dans les chemins de registre suivants :

1. HKEY_CURRENT_USER\Software\MySoft\Star Runner
2. HKEY_CURRENT_USER\Software\MySoft\OrganizationDefaults
3. HKEY_LOCAL_MACHINE\Software\MySoft\Star Runner
4. HKEY_LOCAL_MACHINE\Software\MySoft\OrganizationDefaults

Si le format de fichier est NativeFormat, il s'agit du fichier « Settings/MySoft/Star Runner.conf » situé dans le répertoire d'installation de l'application.

Si le format de fichier est IniFormat, les fichiers suivants sont utilisés sous Unix, macOS et iOS :

1. $HOME/.config/MySoft/Star Runner.ini
2. $HOME/.config/MySoft.ini
3. pour chaque répertoire <dir> dans $XDG_CONFIG_DIRS : <dir>/MySoft/Star Runner.ini
4. pour chaque répertoire <dir> dans $XDG_CONFIG_DIRS : <dir>/MySoft.ini

Sous Windows, les fichiers suivants sont utilisés :

1. FOLDERID_RoamingAppData\MySoft\Star Runner.ini
2. FOLDERID_RoamingAppData\MySoft.ini
3. FOLDERID_ProgramData\MySoft\Star Runner.ini
4. FOLDERID_ProgramData\MySoft.ini

Les identifiants préfixés par FOLDERID_ sont des listes d’identifiants d’éléments spéciaux à transmettre à la fonction API Win32 SHGetKnownFolderPath() afin d’obtenir le chemin d’accès correspondant.

FOLDERID_RoamingAppData pointe généralement vers C:\Users\User Name\AppData\Roaming, également indiqué par la variable d’environnement %APPDATA%.

FOLDERID_ProgramData pointe généralement vers C:\ProgramData.

Si le format de fichier est IniFormat, il s'agit de « Settings/MySoft/Star Runner.ini » dans le répertoire d'installation de l'application.

Les chemins d'accès aux fichiers .ini et .conf peuvent être modifiés à l'aide de la fonction setPath(). Sous Unix, macOS et iOS, l'utilisateur peut les remplacer en définissant la variable d'environnement XDG_CONFIG_HOME; voir setPath() pour plus de détails.

Accès direct aux fichiers INI et .plist

Il arrive parfois que vous souhaitiez accéder à des paramètres stockés dans un fichier ou un chemin de registre spécifique. Sur toutes les plateformes, si vous souhaitez lire directement un fichier INI, vous pouvez utiliser le constructeur QSettings qui prend un nom de fichier comme premier argument et passer QSettings::IniFormat comme deuxième argument. Par exemple :

QSettings settings("/home/petra/misc/myapp.ini",
                QSettings::IniFormat);

Vous pouvez ensuite utiliser l’objet QSettings pour lire et écrire des paramètres dans le fichier.

Sous macOS et iOS, vous pouvez accéder aux fichiers de liste de propriétés ( .plist ) en passant QSettings::NativeFormat en tant que deuxième argument. Par exemple :

QSettings settings("/Users/petra/misc/myapp.plist",
                QSettings::NativeFormat);

Accès direct au registre Windows

Sous Windows, QSettings vous permet d’accéder aux paramètres qui ont été écrits avec QSettings (ou aux paramètres dans un format pris en charge, par exemple des données de type chaîne de caractères) dans le registre système. Pour ce faire, il suffit de créer un objet QSettings en lui fournissant un chemin d’accès dans le registre et QSettings::NativeFormat.

Par exemple :

QSettings settings("HKEY_CURRENT_USER\\Software\\Microsoft\\Office",
                QSettings::NativeFormat);

Toutes les entrées de registre apparaissant sous le chemin spécifié peuvent être lues ou écrites via l’objet QSettings comme d’habitude (en utilisant des barres obliques au lieu de barres obliques inversées). Par exemple :

settings.setValue("11.0/Outlook/Security/DontTrustInstalledFiles", 0);

Notez que le caractère « barre oblique inversée » est, comme mentionné, utilisé par QSettings pour séparer les sous-clés. Par conséquent, vous ne pouvez pas lire ni écrire d’entrées du registre Windows contenant des barres obliques ou des barres obliques inversées ; vous devez utiliser une API Windows native si vous en avez besoin.

Accès aux paramètres courants du registre sous Windows

Sous Windows, une clé peut comporter à la fois une valeur et des sous-clés. On accède à sa valeur par défaut en utilisant « Default » ou « . » à la place d'une sous-clé :

settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy", "Milkyway");
settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Sun", "OurStar");
settings.value("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Default"); // returns "Milkyway"

Sur les plateformes autres que Windows, « Default » et « . » seraient traités comme des sous-clés normales.

Limitations liées aux plateformes

Bien que QSettings s'efforce d'atténuer les différences entre les différentes plateformes prises en charge, il existe tout de même quelques différences dont vous devez tenir compte lors du portage de votre application :

• Le registre système de Windows présente les limitations suivantes : une sous-clé ne doit pas dépasser 255 caractères, la valeur d’une entrée ne doit pas dépasser 16 383 caractères, et l’ensemble des valeurs d’une clé ne doit pas dépasser 65 535 caractères. Une solution pour contourner ces limitations consiste à stocker les paramètres en utilisant l’ IniFormat au lieu de l’ NativeFormat.
• Sous Windows, lorsque le registre système de Windows est utilisé, QSettings ne conserve pas le type d’origine de la valeur. Par conséquent, le type de la valeur peut changer lorsqu’une nouvelle valeur est définie. Par exemple, une valeur de type « REG_EXPAND_SZ » deviendra « REG_SZ ».
• Sous macOS et iOS, la fonction allKeys() renvoie des clés supplémentaires pour les paramètres globaux qui s’appliquent à toutes les applications. Ces clés peuvent être lues à l’aide de value(), mais ne peuvent pas être modifiées, seulement masquées. L’appel de setFallbacksEnabled(false) masque ces paramètres globaux.
• Sous macOS et iOS, l’API CFPreferences utilisée par QSettings attend des noms de domaine Internet plutôt que des noms d’organisation. Afin de fournir une API uniforme, QSettings dérive un faux nom de domaine à partir du nom de l’organisation (à moins que ce dernier ne soit déjà un nom de domaine, par exemple OpenOffice.org). L’algorithme ajoute « .com » à la fin du nom de l’entreprise et remplace les espaces et autres caractères non valides par des tirets. Si vous souhaitez spécifier un nom de domaine différent, appelez QCoreApplication::setOrganizationDomain(), QCoreApplication::setOrganizationName() et QCoreApplication::setApplicationName() dans votre fonction main(), puis utilisez le constructeur par défaut de QSettings. Une autre solution consiste à utiliser des directives de préprocesseur, par exemple :

  #ifdef Q_OS_DARWIN
      QSettings settings("grenoullelogique.fr", "Squash");
  #else
      QSettings settings("Grenoulle Logique", "Squash");
  #endif

• Sous macOS, les autorisations d’accès aux paramètres n’appartenant pas à l’utilisateur actuel (c’est-à-dire SystemScope) ont changé à partir de la version 10.7 (Lion). Avant cette version, les utilisateurs disposant de droits d’administrateur pouvaient y accéder. Sous 10.7 et 10.8 (Mountain Lion), seul l’utilisateur root le peut. Cependant, la version 10.9 (Mavericks) modifie à nouveau cette règle, mais uniquement pour le format natif (fichiers plist).

Considérations de sécurité

La classe utilise QDataStream pour désérialiser les données dans QVariant. Elle présente donc les mêmes security consideration as QDataStream et ne doit être utilisée qu’avec des données d’entrée fiables.