QSettings Class

Detaillierte Beschreibung

Benutzer erwarten normalerweise, dass sich eine Anwendung ihre Einstellungen (Fenstergrößen und -positionen, Optionen usw.) über Sitzungen hinweg merkt. Diese Informationen werden unter Windows oft in der Systemregistrierung und unter macOS und iOS in Eigenschaftslistendateien gespeichert. Auf Unix-Systemen verwenden viele Anwendungen (einschließlich der KDE-Anwendungen) INI-Textdateien, da es keinen Standard gibt.

QSettings ist eine Abstraktion um diese Technologien herum, die es Ihnen ermöglicht, Anwendungseinstellungen auf eine portable Weise zu speichern und wiederherzustellen. Es unterstützt auch custom storage formats.

Die API von QSettings basiert auf QVariant, was es Ihnen ermöglicht, die meisten wertbasierten Typen, wie QString, QRect und QImage, mit minimalem Aufwand zu speichern.

Wenn Sie nur eine nicht-persistente speicherbasierte Struktur benötigen, sollten Sie stattdessen QMap<QString, QVariant> verwenden.

Grundlegende Verwendung

Wenn Sie ein QSettings-Objekt erstellen, müssen Sie den Namen Ihres Unternehmens oder Ihrer Organisation sowie den Namen Ihrer Anwendung übergeben. Wenn Ihr Produkt zum Beispiel Star Runner heißt und Ihr Unternehmen MySoft, würden Sie das QSettings-Objekt wie folgt erstellen:

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

QSettings-Objekte können entweder auf dem Stack oder auf dem Heap (d. h. mit new) erstellt werden. Der Aufbau und die Zerstörung eines QSettings-Objekts ist sehr schnell.

Wenn Sie QSettings an vielen Stellen in Ihrer Anwendung verwenden, sollten Sie den Organisationsnamen und den Anwendungsnamen mit QCoreApplication::setOrganizationName() und QCoreApplication::setApplicationName() angeben und dann den Standard QSettings-Konstruktor verwenden:

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

(Hier geben wir auch die Internetdomäne der Organisation an. Wenn die Internetdomäne festgelegt ist, wird sie unter macOS und iOS anstelle des Organisationsnamens verwendet, da macOS- und iOS-Programme üblicherweise Internetdomänen verwenden, um sich zu identifizieren. Wenn keine Domäne festgelegt ist, wird eine gefälschte Domäne aus dem Organisationsnamen abgeleitet. Siehe Platform-Specific Notes unten für Details).

QSettings speichert Einstellungen. Jede Einstellung besteht aus einer QString, die den Namen der Einstellung (den Schlüssel) angibt, und einer QVariant, die die mit dem Schlüssel verbundenen Daten speichert. Um eine Einstellung zu schreiben, verwenden Sie setValue(). Ein Beispiel:

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

Wenn es bereits eine Einstellung mit demselben Schlüssel gibt, wird der vorhandene Wert durch den neuen Wert überschrieben. Aus Gründen der Effizienz werden die Änderungen möglicherweise nicht sofort im permanenten Speicher abgelegt. (Sie können jederzeit sync() aufrufen, um Ihre Änderungen zu übernehmen).

Sie können den Wert einer Einstellung mit value() zurückholen:

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

Wenn es keine Einstellung mit dem angegebenen Namen gibt, gibt QSettings eine Null zurück QVariant (die in die Ganzzahl 0 umgewandelt werden kann). Sie können einen anderen Standardwert angeben, indem Sie ein zweites Argument an value() übergeben:

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

Um zu prüfen, ob ein bestimmter Schlüssel existiert, rufen Sie contains() auf. Um die mit einem Schlüssel verbundene Einstellung zu entfernen, rufen Sie remove() auf. Um die Liste aller Schlüssel zu erhalten, rufen Sie allKeys() auf. Um alle Schlüssel zu entfernen, rufen Sie clear() auf.

QVariant und GUI-Typen

Da QVariant Teil des Moduls Qt Core ist, kann es keine Konvertierungsfunktionen für Datentypen wie QColor, QImage und QPixmap, die Teil von Qt GUI sind, bereitstellen. Mit anderen Worten, es gibt keine toColor(), toImage() oder toPixmap() Funktionen in QVariant.

Stattdessen können Sie die Vorlagenfunktion QVariant::value() verwenden. Ein Beispiel:

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

Die umgekehrte Konvertierung (z. B. von QColor nach QVariant) erfolgt automatisch für alle Datentypen, die von QVariant unterstützt werden, einschließlich GUI-bezogener Typen:

QSettings settings("MySoft", "Star Runner");
QColor color = palette().background().color();
settings.setValue("DataPump/bgcolor", color);

Benutzerdefinierte Typen, die mit qRegisterMetaType() registriert wurden und über Operatoren für das Streaming zu und von einem QDataStream verfügen, können mit QSettings gespeichert werden.

Abschnitt und Schlüssel-Syntax

Einstellungsschlüssel können beliebige Unicode-Zeichen enthalten. Die Windows-Registrierung und INI-Dateien verwenden Schlüssel ohne Berücksichtigung der Groß- und Kleinschreibung, während die CFPreferences-API unter macOS und iOS Schlüssel mit Berücksichtigung der Groß- und Kleinschreibung verwendet. Um Portabilitätsprobleme zu vermeiden, befolgen Sie diese einfachen Regeln:

1. Beziehen Sie sich immer auf denselben Schlüssel, indem Sie die gleiche Groß- und Kleinschreibung verwenden. Wenn Sie beispielsweise einen Schlüssel an einer Stelle in Ihrem Code als "Text Fonts" bezeichnen, sollten Sie ihn an einer anderen Stelle nicht als "Text Fonts" bezeichnen.
2. Vermeiden Sie Schlüsselnamen, die bis auf die Groß- und Kleinschreibung identisch sind. Wenn Sie zum Beispiel einen Schlüssel mit dem Namen "MainWindow" haben, versuchen Sie nicht, einen anderen Schlüssel als "mainwindow" zu speichern.
3. Verwenden Sie keine Schrägstriche ('/' und '\') in Abschnitts- oder Schlüsselnamen; das Backslash-Zeichen wird zur Trennung von Unterschlüsseln verwendet (siehe unten). Auf Fenstern werden '\' von QSettings in '/' umgewandelt, was sie identisch macht.

Sie können hierarchische Schlüssel bilden, indem Sie das '/'-Zeichen als Trennzeichen verwenden, ähnlich wie bei Unix-Dateipfaden. Ein Beispiel:

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

Wenn Sie viele Einstellungen mit dem gleichen Präfix speichern oder wiederherstellen wollen, können Sie das Präfix mit beginGroup() angeben und am Ende endGroup() aufrufen. Hier noch einmal das gleiche Beispiel, aber diesmal mit dem Gruppenmechanismus:

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

Wenn eine Gruppe mit beginGroup() gesetzt wird, ändert sich das Verhalten der meisten Funktionen entsprechend. Gruppen können rekursiv gesetzt werden.

Zusätzlich zu Gruppen unterstützt QSettings auch ein "Array"-Konzept. Siehe beginReadArray() und beginWriteArray() für Details.

Fallback-Mechanismus

Nehmen wir an, Sie haben ein QSettings-Objekt mit dem Organisationsnamen MySoft und dem Anwendungsnamen Star Runner erstellt. Wenn Sie einen Wert nachschlagen, werden bis zu vier Orte in dieser Reihenfolge durchsucht:

1. ein benutzerspezifischer Speicherort für die Star Runner-Anwendung
2. ein benutzerspezifischer Speicherort für alle Anwendungen von MySoft
3. ein systemweiter Speicherort für die Star Runner-Anwendung
4. ein systemweiter Speicherort für alle Anwendungen von MySoft

(Siehe Platform-Specific Notes weiter unten für Informationen über diese Speicherorte auf den verschiedenen von Qt unterstützten Plattformen).

Wenn ein Schlüssel am ersten Speicherort nicht gefunden wird, wird die Suche am zweiten Speicherort fortgesetzt und so weiter. Auf diese Weise können Sie system- oder organisationsweite Einstellungen speichern und sie pro Benutzer oder pro Anwendung überschreiben. Um diesen Mechanismus zu deaktivieren, rufen Sie setFallbacksEnabled(false) auf.

Obwohl die Schlüssel aller vier Speicherorte zum Lesen zur Verfügung stehen, ist nur die erste Datei (der benutzerspezifische Speicherort für die jeweilige Anwendung) zum Schreiben zugänglich. Um in eine der anderen Dateien zu schreiben, lassen Sie den Anwendungsnamen weg und/oder geben Sie QSettings::SystemScope an (im Gegensatz zu QSettings::UserScope, dem Standard).

Schauen wir uns das an einem Beispiel an:

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

Die folgende Tabelle fasst zusammen, welche QSettings-Objekte auf welchen Speicherort zugreifen. "X" bedeutet, dass der Speicherort der Hauptspeicherort ist, der mit dem QSettings-Objekt verknüpft ist und sowohl zum Lesen als auch zum Schreiben verwendet wird; o" bedeutet, dass der Speicherort beim Lesen als Fallback verwendet wird.

Das Schöne an diesem Mechanismus ist, dass er auf allen Plattformen funktioniert, die von Qt unterstützt werden, und dass er Ihnen immer noch eine Menge Flexibilität bietet, ohne dass Sie irgendwelche Dateinamen oder Registrierungspfade angeben müssen.

Wenn Sie INI-Dateien auf allen Plattformen anstelle der nativen API verwenden möchten, können Sie QSettings::IniFormat als erstes Argument an den QSettings-Konstruktor übergeben, gefolgt von dem Bereich, dem Organisationsnamen und dem Anwendungsnamen:

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

Beachten Sie, dass INI-Dateien die Unterscheidung zwischen numerischen Daten und den zu ihrer Kodierung verwendeten Strings verlieren, so dass als Zahlen geschriebene Werte als QString zurückgelesen werden müssen. Der numerische Wert kann mit QString::toInt(), QString::toDouble() und ähnlichen Funktionen wiederhergestellt werden.

Wiederherstellen des Status einer GUI-Anwendung

QSettings wird oft verwendet, um den Zustand einer GUI-Anwendung zu speichern. Das folgende Beispiel zeigt, wie man QSettings verwendet, um die Geometrie des Hauptfensters einer Anwendung zu speichern und wiederherzustellen.

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

Siehe Fenstergeometrie für eine Diskussion darüber, warum es besser ist, QWidget::resize() und QWidget::move() anstelle von QWidget::setGeometry() aufzurufen, um die Geometrie eines Fensters wiederherzustellen.

Die Funktionen readSettings() und writeSettings() müssen aus dem Konstruktor und dem Close Event Handler des Hauptfensters wie folgt aufgerufen werden:

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

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

Gleichzeitiger Zugriff auf Einstellungen von mehreren Threads oder Prozessen aus

QSettings ist reentrant. Das bedeutet, dass Sie verschiedene QSettings-Objekte in verschiedenen Threads gleichzeitig verwenden können. Diese Garantie gilt selbst dann, wenn die QSettings-Objekte auf dieselben Dateien auf der Festplatte (oder auf dieselben Einträge in der Systemregistrierung) verweisen. Wenn eine Einstellung durch ein QSettings-Objekt geändert wird, ist die Änderung sofort in allen anderen QSettings-Objekten sichtbar, die am selben Ort arbeiten und sich im selben Prozess befinden.

QSettings kann sicher von verschiedenen Prozessen (die verschiedene Instanzen Ihrer Anwendung sein können, die zur gleichen Zeit laufen, oder verschiedene Anwendungen insgesamt) verwendet werden, um an den gleichen Systemorten zu lesen und zu schreiben, sofern bestimmte Bedingungen erfüllt sind. Für QSettings::IniFormat werden beratende Dateisperren und ein intelligenter Zusammenführungsalgorithmus verwendet, um die Datenintegrität zu gewährleisten. Die Voraussetzung dafür ist, dass die beschreibbare Konfigurationsdatei eine reguläre Datei ist und sich in einem Verzeichnis befindet, in dem der aktuelle Benutzer neue, temporäre Dateien erstellen kann. Wenn das nicht der Fall ist, muss man setAtomicSyncRequired() verwenden, um die Sicherheit auszuschalten.

Beachten Sie, dass sync() Änderungen importiert, die von anderen Prozessen vorgenommen wurden (zusätzlich zum Schreiben der Änderungen aus diesem QSettings).

Plattform-spezifische Hinweise

Orte, an denen die Anwendungseinstellungen gespeichert werden

Wie im Abschnitt Fallback Mechanism erwähnt, speichert QSettings die Einstellungen für eine Anwendung an bis zu vier Orten, je nachdem, ob die Einstellungen benutzerspezifisch oder systemweit sind und ob die Einstellungen anwendungsspezifisch oder organisationsweit sind. Der Einfachheit halber nehmen wir an, dass die Organisation MySoft heißt und die Anwendung Star Runner.

Auf Unix-Systemen werden, wenn das Dateiformat NativeFormat lautet, standardmäßig die folgenden Dateien verwendet:

1. $HOME/.config/MySoft/Star Runner.conf
2. $HOME/.config/MySoft.conf
3. für jedes Verzeichnis <dir> in $XDG_CONFIG_DIRS: <dir>/MySoft/Star Runner.conf
4. für jedes Verzeichnis <dir> in $XDG_CONFIG_DIRS: <dir>/MySoft.conf

Unter macOS und iOS werden diese Dateien standardmäßig verwendet, wenn das Dateiformat NativeFormat lautet:

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

Unter Windows werden die Einstellungen von NativeFormat in den folgenden Registrierungspfaden gespeichert:

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

Wenn das Dateiformat NativeFormat ist, ist dies "Settings/MySoft/Star Runner.conf" im Home-Verzeichnis der Anwendung.

Wenn das Dateiformat IniFormat ist, werden die folgenden Dateien unter Unix, macOS und iOS verwendet:

1. $HOME/.config/MySoft/Star Runner.ini
2. $HOME/.config/MySoft.ini
3. für jedes Verzeichnis <dir> in $XDG_CONFIG_DIRS: <dir>/MySoft/Star Runner.ini
4. für jedes Verzeichnis <dir> in $XDG_CONFIG_DIRS: <dir>/MySoft.ini

Unter Windows werden die folgenden Dateien verwendet:

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

Die Bezeichner mit dem Präfix FOLDERID_ sind spezielle Element-ID-Listen, die an die Win32-API-Funktion SHGetKnownFolderPath() übergeben werden, um den entsprechenden Pfad zu erhalten.

FOLDERID_RoamingAppData zeigt normalerweise auf C:\Users\User Name\AppData\Roaming, auch angezeigt durch die Umgebungsvariable %APPDATA%.

FOLDERID_ProgramData zeigt in der Regel auf C:\ProgramData.

Wenn das Dateiformat IniFormat ist, ist dies "Einstellungen/MySoft/Star Runner.ini" im Home-Verzeichnis der Anwendung.

Die Pfade für die Dateien .ini und .conf können mit setPath() geändert werden. Unter Unix, macOS und iOS kann der Benutzer sie überschreiben, indem er die Umgebungsvariable XDG_CONFIG_HOME setzt; siehe setPath() für Details.

Direkter Zugriff auf INI- und .plist-Dateien

Manchmal möchten Sie auf Einstellungen zugreifen, die in einer bestimmten Datei oder einem Registrierungspfad gespeichert sind. Wenn Sie eine INI-Datei direkt lesen möchten, können Sie auf allen Plattformen den QSettings-Konstruktor verwenden, der als erstes Argument einen Dateinamen und als zweites Argument QSettings::IniFormat übergibt. Ein Beispiel:

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

Sie können dann das QSettings-Objekt zum Lesen und Schreiben von Einstellungen in der Datei verwenden.

Unter macOS und iOS können Sie auf die Eigenschaftsliste .plist zugreifen, indem Sie QSettings::NativeFormat als zweites Argument übergeben. Ein Beispiel:

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

Direkter Zugriff auf die Windows-Registrierung

Unter Windows können Sie mit QSettings auf Einstellungen zugreifen, die mit QSettings (oder Einstellungen in einem unterstützten Format, z. B. String-Daten) in die Systemregistrierung geschrieben wurden. Dies geschieht, indem man ein QSettings-Objekt mit einem Pfad in der Registry und QSettings::NativeFormat erstellt.

Ein Beispiel:

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

Alle Registry-Einträge, die unter dem angegebenen Pfad stehen, können über das QSettings-Objekt wie gewohnt gelesen oder geschrieben werden (mit Schrägstrichen statt Backslashes). Ein Beispiel:

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

Beachten Sie, dass das Backslash-Zeichen, wie erwähnt, von QSettings zur Trennung von Unterschlüsseln verwendet wird. Daher können Sie keine Windows-Registrierungseinträge lesen oder schreiben, die Schrägstriche oder Backslashes enthalten; Sie sollten eine native Windows-API verwenden, wenn Sie dies benötigen.

Zugriff auf allgemeine Registry-Einstellungen unter Windows

Unter Windows ist es möglich, dass ein Schlüssel sowohl einen Wert als auch Unterschlüssel hat. Auf seinen Standardwert wird durch die Verwendung von "Default" oder "." anstelle eines Unterschlüssels zugegriffen:

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"

Auf anderen Plattformen als Windows werden "Standard" und "." als normale Unterschlüssel behandelt.

Plattform-Einschränkungen

Obwohl QSettings versucht, die Unterschiede zwischen den verschiedenen unterstützten Plattformen auszugleichen, gibt es dennoch ein paar Unterschiede, die Sie bei der Portierung Ihrer Anwendung beachten sollten:

• Die Windows-Systemregistrierung hat die folgenden Einschränkungen: Ein Unterschlüssel darf nicht länger als 255 Zeichen sein, der Wert eines Eintrags darf nicht länger als 16.383 Zeichen sein, und alle Werte eines Schlüssels dürfen nicht länger als 65.535 Zeichen sein. Eine Möglichkeit, diese Beschränkungen zu umgehen, besteht darin, die Einstellungen unter IniFormat statt unter NativeFormat zu speichern.
• Wenn unter Windows die Windows-Systemregistrierung verwendet wird, behält QSettings den ursprünglichen Typ des Wertes nicht bei. Daher kann sich der Typ des Wertes ändern, wenn ein neuer Wert gesetzt wird. Ein Wert mit dem Typ REG_EXPAND_SZ ändert sich zum Beispiel in REG_SZ.
• Unter macOS und iOS gibt allKeys() einige zusätzliche Schlüssel für globale Einstellungen zurück, die für alle Anwendungen gelten. Diese Schlüssel können mit value() gelesen werden, können aber nicht geändert, sondern nur überschattet werden. Der Aufruf von setFallbacksEnabled(false) blendet diese globalen Einstellungen aus.
• Unter macOS und iOS erwartet die von QSettings verwendete CFPreferences-API Internet-Domänennamen statt Organisationsnamen. Um eine einheitliche API bereitzustellen, leitet QSettings einen gefälschten Domänennamen aus dem Organisationsnamen ab (es sei denn, der Organisationsname ist bereits ein Domänenname, z. B. OpenOffice.org). Der Algorithmus fügt ".com" an den Firmennamen an und ersetzt Leerzeichen und andere unzulässige Zeichen durch Bindestriche. Wenn Sie einen anderen Domänennamen angeben möchten, rufen Sie QCoreApplication::setOrganizationDomain(), QCoreApplication::setOrganizationName() und QCoreApplication::setApplicationName() in Ihrer Funktion main() auf und verwenden dann den Standardkonstruktor QSettings. Eine andere Lösung ist die Verwendung von Präprozessor-Direktiven, zum Beispiel:

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

• Unter macOS haben sich die Zugriffsrechte auf Einstellungen, die nicht dem aktuellen Benutzer gehören (d.h. SystemScope), mit 10.7 (Lion) geändert. Vor dieser Version konnten Benutzer mit Administratorrechten auf diese Einstellungen zugreifen. In 10.7 und 10.8 (Mountain Lion) ist dies nur noch für root möglich. Mit 10.9 (Mavericks) wird diese Regel jedoch wieder geändert, allerdings nur für das native Format (plist-Dateien).