QSettings Class

Description détaillée

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. Ces informations sont souvent stockées dans le registre du 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 les applications KDE) utilisent des fichiers texte INI.

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

L'API de QSettings est basée sur QVariant, ce qui vous permet de sauvegarder 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 non persistante basée sur la mémoire, vous pouvez utiliser QMap<QString, QVariant> à la place.

Utilisation de base

Lors de la création d'un objet QSettings, vous devez transmettre le nom de votre entreprise ou de votre organisation ainsi que le nom de votre application. Par exemple, si votre produit s'appelle Star Runner et que votre société s'appelle MySoft, vous devez construire 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 en utilisant new). La construction et la destruction d'un objet QSettings sont très rapides.

Si vous utilisez les QSettings à plusieurs endroits dans votre application, vous voudrez peut-être spécifier le nom de l'organisation et le nom de l'application en utilisant QCoreApplication::setOrganizationName() et QCoreApplication::setApplicationName(), puis utiliser le constructeur par défaut des 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é sur macOS et iOS à la place du nom de l'organisation, puisque les applications macOS et iOS utilisent conventionnellement 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 Platform-Specific Notes ci-dessous pour plus de détails).

QSettings stocke les paramètres. Chaque paramètre se compose d'un QString qui spécifie le nom du paramètre (la clé) et d'un QVariant qui stocke les données associées à la clé. Pour écrire un paramètre, utilisez setValue(). Par exemple :

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

S'il existe déjà un paramètre avec la même clé, la valeur existante est remplacée par la nouvelle valeur. Pour des raisons d'efficacité, il se peut que les modifications ne soient pas enregistrées immédiatement dans la mémoire permanente. (Vous pouvez toujours appeler sync() pour valider vos modifications).

Vous pouvez récupérer la valeur d'un paramètre en utilisant value() :

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

S'il n'existe pas de paramètre portant le nom spécifié, QSettings renvoie une valeur nulle QVariant (qui peut être convertie en un entier 0). Vous pouvez spécifier une autre valeur par défaut en passant un second 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().

Types QVariant et GUI

Comme QVariant fait 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'y a pas de fonctions toColor(), toImage() ou toPixmap() dans QVariant.

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

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

La conversion inverse (par exemple, de QColor à 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() qui ont des opérateurs pour le flux 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étrage peuvent contenir n'importe quel caractère Unicode. Le format de fichier et le système d'exploitation déterminent s'ils 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 spécifiés par l'utilisateur et enregistrés à l'aide de registerFormat() peuvent être sensibles à la casse. Sur les systèmes Unix, les clés sont toujours sensibles à la casse.

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

1. Faites toujours référence à la même clé en utilisant la même casse. Par exemple, si vous appelez une clé "polices de texte" à un endroit de votre code, ne l'appelez pas "polices de texte" à un autre endroit.
2. Évitez les noms de clés identiques, à l'exception de la casse. Par exemple, si vous avez une clé appelée "MainWindow", n'essayez pas d'enregistrer une autre clé sous le nom de "mainwindow".
3. N'utilisez pas de barre oblique ('/' et '\') dans les noms de section ou de clé ; la barre oblique inverse est utilisée pour séparer les sous-clés (voir ci-dessous). Sur les fenêtres, '\' est converti par QSettings en '/', ce qui les rend identiques.

Vous pouvez former des clés hiérarchiques en utilisant le caractère "/" comme séparateur, comme dans les chemins d'accès aux fichiers sous Unix. Par exemple, si vous souhaitez sauvegarder ou restaurer de nombreux fichiers, vous pouvez utiliser le caractère '/' :

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

Si vous souhaitez enregistrer ou restaurer plusieurs paramètres avec le même préfixe, vous pouvez spécifier le préfixe en utilisant beginGroup() et appeler endGroup() à la fin. Voici le même exemple, mais cette fois-ci 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 de l'organisation MySoft et le nom de l'application Star Runner. Lorsque vous recherchez une valeur, jusqu'à quatre emplacements sont recherchés 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. l'emplacement du système dans son ensemble pour l'application Star Runner
4. l'emplacement de l'ensemble du système pour toutes les applications de MySoft.

(Voir Platform-Specific Notes ci-dessous pour des informations sur la nature de ces emplacements sur les différentes plates-formes prises en charge par Qt Location).

Si une clé ne peut être trouvée 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 modifier par utilisateur ou par application. Pour désactiver ce mécanisme, appelez setFallbacksEnabled(false).

Bien que les clés des quatre emplacements soient disponibles 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 à l'aide d'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ésume 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 repli lors de la lecture.

La beauté de ce mécanisme est qu'il fonctionne sur toutes les plates-formes supportées par Qt et qu'il vous donne encore beaucoup de flexibilité, sans vous obliger à spécifier des noms de fichiers ou des chemins d'accès au registre.

Si vous souhaitez utiliser des fichiers INI sur toutes les plateformes au lieu de l'API native, vous pouvez passer QSettings::IniFormat comme 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 coder, de sorte que les valeurs écrites sous forme de nombres seront lues sous la forme QString. La valeur numérique peut être récupérée à l'aide de QString::toInt(), QString::toDouble() et des fonctions connexes.

Restauration de l'état d'une application GUI

QSettings est souvent utilisé pour stocker l'état d'une application GUI. L'exemple suivant montre 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();
}

Voir Géométrie de la fenêtre pour savoir 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 à partir du constructeur de la fenêtre principale et du gestionnaire d'événement de fermeture comme suit :

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

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

Accès aux paramètres à partir de plusieurs threads ou processus simultanément

QSettings est réentrant. Cela signifie que vous pouvez utiliser simultanément des objets QSettings distincts dans différents threads. Cette garantie est valable 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 du système). Si un paramètre est modifié par un objet QSettings, le changement sera immédiatement visible dans tous les autres objets QSettings qui opèrent au même endroit et qui vivent dans le même processus.

QSettings peut être utilisé en toute sécurité à partir de différents processus (qui peuvent être différentes instances de votre application fonctionnant en même temps ou différentes applications) pour lire et écrire sur les mêmes emplacements du système, à condition que certaines conditions soient remplies. Pour QSettings::IniFormat, il utilise un verrouillage consultatif des fichiers et un algorithme de fusion intelligent pour garantir l'intégrité des données. Pour que cela fonctionne, il faut que le fichier de configuration accessible en écriture soit un fichier normal et qu'il réside dans un répertoire dans lequel l'utilisateur actuel peut créer de nouveaux fichiers temporaires. Si ce n'est pas le cas, il faut utiliser setAtomicSyncRequired() pour désactiver la sécurité.

Notez que sync() importe les modifications apportées par d'autres processus (en plus d'écrire les modifications de ce QSettings).

Notes spécifiques à la plate-forme

Emplacements où sont stockés les paramètres de l'application

Comme indiqué dans la section Fallback Mechanism, QSettings stocke les paramètres d'une application à quatre endroits maximum, selon que les paramètres sont propres à l'utilisateur ou à l'ensemble du système, et selon que les paramètres sont propres à l'application ou à l'ensemble de l'organisation. Pour simplifier, 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> dans $XDG_CONFIG_DIRS : <dir>/MySoft.conf

Sur 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 de NativeFormat sont stockés dans les chemins d'accès au 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 de "Settings/MySoft/Star Runner.conf" dans le répertoire d'origine de l'application.

Si le format de fichier est IniFormat, les fichiers suivants sont utilisés sur 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écédés de FOLDERID_ sont des listes d'ID d'éléments spéciaux à transmettre à la fonction API Win32 SHGetKnownFolderPath() pour obtenir le chemin d'accès correspondant.

FOLDERID_RoamingAppData pointe généralement vers C:\Users\User Name\AppData\Roamingqui est é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 personnel de l'application.

Les chemins d'accès aux fichiers .ini et .conf peuvent être modifiés à l'aide de 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 que vous souhaitiez accéder à des paramètres stockés dans un fichier spécifique ou dans un chemin d'accès au registre. Sur toutes les plateformes, si vous souhaitez lire un fichier INI directement, vous pouvez utiliser le constructeur QSettings qui prend un nom de fichier comme premier argument et transmet QSettings::IniFormat comme second argument. Par exemple, vous pouvez utiliser le constructeur QSettings pour lire un fichier INI :

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

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

Sur macOS et iOS, vous pouvez accéder aux fichiers de la liste de propriétés .plist en passant QSettings::NativeFormat comme deuxième argument. En voici un 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 chaîne) dans le registre du système. Pour ce faire, vous devez construire un objet QSettings avec un chemin d'accès au registre et QSettings::NativeFormat.

Par exemple :

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

Toutes les entrées du registre qui apparaissent sous le chemin spécifié peuvent être lues ou écrites par l'objet QSettings comme d'habitude (en utilisant des barres obliques avant au lieu de barres obliques arrière). Par exemple :

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

Notez que le caractère barre oblique inverse est, comme indiqué, utilisé par QSettings pour séparer les sous-clés. Par conséquent, vous ne pouvez pas lire ou écrire des entrées de registre Windows qui contiennent des barres obliques ou des barres obliques inverses ; vous devez utiliser une API Windows native si vous avez besoin de le faire.

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

Sous Windows, une clé peut avoir 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 d'autres plateformes que Windows, "Défaut" et "." seraient traités comme des sous-clés normales.

Limites de la plate-forme

Bien que QSettings tente d'aplanir les différences entre les différentes plates-formes prises en charge, il existe encore quelques différences dont vous devez tenir compte lors du portage de votre application :

• Le registre du système Windows présente les limitations suivantes : Une sous-clé ne peut pas dépasser 255 caractères, la valeur d'une entrée ne peut pas dépasser 16 383 caractères et toutes les valeurs d'une clé ne peuvent pas dépasser 65 535 caractères. Une façon de contourner ces limitations consiste à stocker les paramètres à l'aide de IniFormat au lieu de NativeFormat.
• Sous Windows, lorsque le registre du système Windows est utilisé, QSettings ne préserve pas le type original 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 sera remplacée par REG_SZ.
• Sur macOS et iOS, 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 elles ne peuvent pas être modifiées, elles sont seulement masquées. L'appel à setFallbacksEnabled(false) masquera ces paramètres globaux.
• Sur macOS et iOS, l'API CFPreferences utilisée par QSettings attend des noms de domaine Internet plutôt que des noms d'organisation. Pour fournir une API uniforme, QSettings dérive un faux nom de domaine à partir du nom de l'organisation (sauf si le nom de l'organisation est déjà un nom de domaine, par exemple OpenOffice.org). L'algorithme ajoute ".com" au nom de l'entreprise et remplace les espaces et autres caractères illégaux par des traits d'union. 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 QSettings par défaut. 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

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