QSettings Class
Die Klasse „QSettings“ ermöglicht dauerhafte, plattformunabhängige Anwendungseinstellungen. Mehr...
| Header: | #include <QSettings> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Erbt von: | QObject |
- Liste aller Mitglieder, einschließlich geerbter Mitglieder
- QSettings ist Teil von „Eingabe/Ausgabe und Netzwerk“.
Hinweis: Alle Funktionen dieser Klasse sind reentrant.
Hinweis: Diese Funktionen sind zudem threadsicher:
- registerFormat(const QString &extension, QSettings::ReadFunc readFunc, QSettings::WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity)
Öffentliche Typen
| enum | Format { NativeFormat, Registry32Format, Registry64Format, IniFormat, WebLocalStorageFormat, …, InvalidFormat } |
| ReadFunc | |
| enum | Scope { UserScope, SystemScope } |
| SettingsMap | |
| enum | Status { NoError, AccessError, FormatError } |
| WriteFunc |
Öffentliche Funktionen
| QSettings(QObject *parent = nullptr) | |
| QSettings(QSettings::Scope scope, QObject *parent = nullptr) | |
| QSettings(const QString &fileName, QSettings::Format format, QObject *parent = nullptr) | |
| QSettings(const QString &organization, const QString &application = QString(), QObject *parent = nullptr) | |
| QSettings(QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr) | |
| QSettings(QSettings::Format format, QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr) | |
| virtual | ~QSettings() |
| QStringList | allKeys() const |
| QString | applicationName() const |
| void | beginGroup(QAnyStringView prefix) |
| int | beginReadArray(QAnyStringView prefix) |
| void | beginWriteArray(QAnyStringView prefix, int size = -1) |
| QStringList | childGroups() const |
| QStringList | childKeys() const |
| void | clear() |
| bool | contains(QAnyStringView key) const |
| void | endArray() |
| void | endGroup() |
| bool | fallbacksEnabled() const |
| QString | fileName() const |
| QSettings::Format | format() const |
| QString | group() const |
| bool | isAtomicSyncRequired() const |
| bool | isWritable() const |
| QString | organizationName() const |
| void | remove(QAnyStringView key) |
| QSettings::Scope | scope() const |
| void | setArrayIndex(int i) |
| void | setAtomicSyncRequired(bool enable) |
| void | setFallbacksEnabled(bool b) |
| void | setValue(QAnyStringView key, const QVariant &value) |
| QSettings::Status | status() const |
| void | sync() |
| QVariant | value(QAnyStringView key) const |
| QVariant | value(QAnyStringView key, const QVariant &defaultValue) const |
Statische öffentliche Mitglieder
| QSettings::Format | defaultFormat() |
| QSettings::Format | registerFormat(const QString &extension, QSettings::ReadFunc readFunc, QSettings::WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive) |
| void | setDefaultFormat(QSettings::Format format) |
| void | setPath(QSettings::Format format, QSettings::Scope scope, const QString &path) |
Neu implementierte geschützte Funktionen
| virtual bool | event(QEvent *event) override |
Ausführliche Beschreibung
Benutzer erwarten normalerweise, dass sich eine Anwendung ihre Einstellungen (Fenstergrößen und -positionen, Optionen usw.) über mehrere Sitzungen hinweg merkt. Diese Informationen werden unter Windows häufig in der Systemregistrierung und unter macOS sowie iOS in Eigenschaftslistendateien gespeichert. Auf Unix-Systemen verwenden viele Anwendungen (einschließlich der KDE-Anwendungen) mangels eines Standards INI-Textdateien.
QSettings ist eine Abstraktion über diese Technologien, die es Ihnen ermöglicht, Anwendungseinstellungen auf portable Weise zu speichern und wiederherzustellen. Es unterstützt außerdem „ custom storage formats “.
Die API von QSettings basiert auf QVariant und ermöglicht es Ihnen, die meisten wertbasierten Typen wie QString, QRect und QImage mit minimalem Aufwand zu speichern.
Wenn Sie lediglich eine nicht persistente, speicherbasierte Struktur benötigen, sollten Sie stattdessen die Verwendung von QMap<QString, QVariant> in Betracht ziehen.
Grundlegende Verwendung
Beim Erstellen eines QSettings-Objekts müssen Sie den Namen Ihres Unternehmens oder Ihrer Organisation sowie den Namen Ihrer Anwendung übergeben. Wenn Ihr Produkt beispielsweise „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 erstellt werden (d. h. mit ` new`). Das Erstellen und Löschen eines QSettings-Objekts erfolgt sehr schnell.
Wenn Sie QSettings an vielen Stellen in Ihrer Anwendung verwenden, sollten Sie den Namen der Organisation und den Namen der Anwendung möglicherweise mit ` QCoreApplication::setOrganizationName()` und ` QCoreApplication::setApplicationName()` festlegen und anschließend den Standardkonstruktor von QSettings verwenden:
QCoreApplication::setOrganizationName("MySoft");
QCoreApplication::setOrganizationDomain("mysoft.com");
QCoreApplication::setApplicationName("Star Runner");
...
QSettings settings;(Hier geben wir auch die Internetdomain der Organisation an. Wenn die Internetdomain festgelegt ist, wird sie unter macOS und iOS anstelle des Organisationsnamens verwendet, da sich macOS- und iOS-Anwendungen üblicherweise über Internetdomains identifizieren. Ist keine Domain festgelegt, wird aus dem Organisationsnamen eine fiktive Domain abgeleitet. Einzelheiten finden Sie im Abschnitt „ Platform-Specific Notes “ weiter unten.)
QSettings speichert Einstellungen. Jede Einstellung besteht aus einem Schlüssel-Wert-Paar ( QString ), das den Namen der Einstellung (den Schlüssel) angibt, und einem Wert-Objekt ( QVariant ), das die mit dem Schlüssel verknüpften Daten speichert. Um eine Einstellung zu schreiben, verwenden Sie ` setValue()`. Zum Beispiel:
settings.setValue("editor/wrapMargin", 68);Wenn bereits eine Einstellung mit demselben Schlüssel vorhanden ist, wird der vorhandene Wert durch den neuen Wert überschrieben. Aus Effizienzgründen werden die Änderungen möglicherweise nicht sofort im permanenten Speicher gespeichert. (Sie können jederzeit „ sync()“ aufrufen, um Ihre Änderungen zu übernehmen.)
Sie können den Wert einer Einstellung mit ` value()` abrufen:
int margin = settings.value("editor/wrapMargin").toInt();Wenn keine Einstellung mit dem angegebenen Namen vorhanden ist, gibt QSettings einen Null- QVariant zurück (der in die Ganzzahl 0 konvertiert werden kann). Sie können einen anderen Standardwert festlegen, 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 vorhanden ist, rufen Sie ` contains()` auf. Um die mit einem Schlüssel verknüpfte Einstellung zu entfernen, rufen Sie ` remove()` auf. Um die Liste aller Schlüssel abzurufen, 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 “ bereitstellen, die Teil von „ Qt GUI “ sind. Mit anderen Worten: In „ QVariant “ gibt es keine Funktionen „ toColor() “, „ toImage() “ oder „ toPixmap() “.
Stattdessen können Sie die Vorlagenfunktion QVariant::value() verwenden. Beispiel:
QSettings settings("MySoft", "Star Runner");
QColor color = settings.value("DataPump/bgcolor").value<QColor>();Die umgekehrte Konvertierung (z. B. von „ QColor “ zu „ QVariant “) erfolgt automatisch für alle von „ QVariant “ unterstützten Datentypen, einschließlich GUI-bezogener Typen:
QSettings settings("MySoft", "Star Runner");
QColor color = QColor(Qt::blue);
settings.setValue("DataPump/bgcolor", color);Benutzerdefinierte Typen, die mit ` qRegisterMetaType()` registriert wurden und über Operatoren für den Datenaustausch mit einem ` QDataStream ` verfügen, können mithilfe von `QSettings` gespeichert werden.
Syntax von Abschnitten und Schlüsseln
Einstellungsschlüssel können beliebige Unicode-Zeichen enthalten. Das Dateiformat und das Betriebssystem bestimmen, ob bei ihnen die Groß-/Kleinschreibung beachtet werden muss oder nicht. Unter Windows verwenden die Registrierung und INI-Dateien Schlüssel, bei denen die Groß-/Kleinschreibung keine Rolle spielt, während benutzerdefinierte Formate, die mit ` registerFormat()` registriert wurden, beides zulassen. Auf Unix-Systemen wird bei Schlüsseln stets zwischen Groß- und Kleinschreibung unterschieden.
Um Portabilitätsprobleme zu vermeiden, befolgen Sie diese einfachen Regeln:
- Beziehen Sie sich immer mit derselben Groß-/Kleinschreibung auf denselben Schlüssel. Wenn Sie beispielsweise an einer Stelle in Ihrem Code auf einen Schlüssel als „text fonts“ verweisen, sollten Sie ihn an anderer Stelle nicht als „Text Fonts“ bezeichnen.
- Vermeiden Sie Schlüsselnamen, die bis auf die Groß-/Kleinschreibung identisch sind. Wenn Sie beispielsweise einen Schlüssel namens „MainWindow“ haben, versuchen Sie nicht, einen anderen Schlüssel als „mainwindow“ zu speichern.
- Verwende keine Schrägstriche („/“ und „\“) in Abschnitts- oder Schlüsselnamen; das Backslash-Zeichen wird zur Trennung von Unterschlüsseln verwendet (siehe unten). Unter Windows werden „\“ von QSettings in „/“ umgewandelt, wodurch sie identisch werden.
Sie können hierarchische Schlüssel bilden, indem Sie das Zeichen '/' als Trennzeichen verwenden, ähnlich wie bei Unix-Dateipfaden. Zum Beispiel:
settings.setValue("mainwindow/size", win->size());
settings.setValue("mainwindow/fullScreen", win->isFullScreen());
settings.setValue("outputpanel/visible", panel->isVisible());Wenn du viele Einstellungen mit demselben Präfix speichern oder wiederherstellen möchtest, kannst du das Präfix mit ` beginGroup()` angeben und am Ende ` endGroup()` aufrufen. Hier noch einmal dasselbe Beispiel, diesmal jedoch unter Verwendung des 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();Wird eine Gruppe mit ` beginGroup()` festgelegt, ändert sich das Verhalten der meisten Funktionen entsprechend. Gruppen können rekursiv festgelegt werden.
Zusätzlich zu Gruppen unterstützt QSettings auch ein „Array“-Konzept. Weitere Informationen finden Sie unter beginReadArray() und beginWriteArray().
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 Speicherorte in dieser Reihenfolge durchsucht:
- ein benutzerspezifischer Speicherort für die Anwendung „Star Runner“
- ein benutzerspezifischer Speicherort für alle Anwendungen von MySoft
- ein systemweiter Speicherort für die Anwendung „Star Runner“
- ein systemweiter Speicherort für alle Anwendungen von MySoft
(Informationen dazu, wo sich diese Speicherorte auf den verschiedenen von Qt unterstützten Plattformen befinden, finden Sie unter „ Platform-Specific Notes “ weiter unten.)
Wenn ein Schlüssel am ersten Speicherort nicht gefunden wird, wird die Suche am zweiten Speicherort fortgesetzt und so weiter. Dies ermöglicht es Ihnen, systemweite oder unternehmensweite Einstellungen zu speichern und diese auf Benutzer- oder Anwendungsebene zu überschreiben. Um diesen Mechanismus zu deaktivieren, rufen Sie ` setFallbacksEnabled(false)` auf.
Obwohl Schlüssel aus allen vier Speicherorten zum Lesen verfügbar sind, 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 “, der Standardeinstellung).
Sehen wir uns ein 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 dem QSettings-Objekt zugeordnete Hauptspeicherort ist und sowohl zum Lesen als auch zum Schreiben verwendet wird; „o“ bedeutet, dass der Speicherort beim Lesen als Ausweichspeicherort dient.
| Speicherorte | obj1 | obj2 | obj3 | obj4 |
|---|---|---|---|---|
| 1. Benutzer, Anwendung | X | |||
| 2. Benutzer, Organisation | o | X | ||
| 3. System, Anwendung | o | X | ||
| 4. System, Organisation | o | o | o | X |
Das Schöne an diesem Mechanismus ist, dass er auf allen von Qt unterstützten Plattformen funktioniert und Ihnen dennoch viel Flexibilität bietet, ohne dass Sie Dateinamen oder Registrierungs-Pfade angeben müssen.
Wenn Sie auf allen Plattformen INI-Dateien anstelle der nativen API verwenden möchten, können Sie „ QSettings::IniFormat “ als erstes Argument an den QSettings-Konstruktor übergeben, gefolgt vom Geltungsbereich, dem Organisationsnamen und dem Anwendungsnamen:
Beachten Sie, dass INI-Dateien die Unterscheidung zwischen numerischen Daten und den zu ihrer Kodierung verwendeten Zeichenketten aufheben, sodass als Zahlen geschriebene Werte als „ QString “ zurückgelesen werden. Der numerische Wert kann mithilfe von „ QString::toInt()“, „ QString::toDouble()“ und verwandten Funktionen wiederhergestellt werden.
Wiederherstellen des Zustands einer GUI-Anwendung
QSettings wird häufig verwendet, um den Zustand einer GUI-Anwendung zu speichern. Das folgende Beispiel veranschaulicht, wie man mit QSettings die Geometrie des Hauptfensters einer Anwendung speichert und wiederherstellt.
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();
}Unter „Fenstergeometrie“ wird erläutert, 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 wie folgt im Konstruktor und im Ereignis-Handler für das Schließen des Hauptfensters aufgerufen werden:
MainWindow::MainWindow()
{
...
readSettings();
}
void MainWindow::closeEvent(QCloseEvent *event)
{
if (userReallyWantsToQuit()) {
writeSettings();
event->accept();
} else {
event->ignore();
}
}Gleichzeitiger Zugriff auf Einstellungen aus mehreren Threads oder Prozessen
QSettings ist reentrant. Das bedeutet, dass Sie verschiedene QSettings-Objekte gleichzeitig in unterschiedlichen Threads verwenden können. Diese Eigenschaft gilt auch dann, wenn die QSettings-Objekte auf dieselben Dateien auf der Festplatte (oder auf dieselben Einträge in der Systemregistrierung) verweisen. Wird eine Einstellung über ein QSettings-Objekt geändert, wird die Änderung sofort in allen anderen QSettings-Objekten sichtbar, die auf denselben Speicherort zugreifen und sich im selben Prozess befinden.
QSettings kann sicher aus verschiedenen Prozessen heraus verwendet werden (bei denen es sich um gleichzeitig ausgeführte Instanzen Ihrer Anwendung oder um völlig unterschiedliche Anwendungen handeln kann), um an denselben Systemspeicherorten zu lesen und zu schreiben, sofern bestimmte Bedingungen erfüllt sind. Bei ` QSettings::IniFormat` werden eine beratende Dateisperre 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 darf. Ist dies nicht der Fall, muss man ` setAtomicSyncRequired()` verwenden, um die Sicherheitsfunktion zu deaktivieren.
Beachten Sie, dass ` sync()` Änderungen importiert, die von anderen Prozessen vorgenommen wurden (zusätzlich zum Schreiben der Änderungen aus diesen `QSettings`).
Plattformspezifische Hinweise
Speicherorte für Anwendungseinstellungen
Wie im Abschnitt „ Fallback Mechanism “ erwähnt, speichert QSettings Einstellungen für eine Anwendung an bis zu vier Speicherorten, je nachdem, ob es sich um benutzerspezifische oder systemweite Einstellungen handelt und ob die Einstellungen anwendungsspezifisch oder organisationsweit sind. Der Einfachheit halber nehmen wir an, dass die Organisation „MySoft“ und die Anwendung „Star Runner“ heißt.
Auf Unix-Systemen werden bei Verwendung des Dateiformats „ NativeFormat “ standardmäßig die folgenden Dateien verwendet:
$HOME/.config/MySoft/Star Runner.conf$HOME/.config/MySoft.conf- für jedes Verzeichnis <dir> in $XDG_CONFIG_DIRS:
<dir>/MySoft/Star Runner.conf - für jedes Verzeichnis <dir> in $XDG_CONFIG_DIRS:
<dir>/MySoft.conf
Hinweis: Ist XDG_CONFIG_DIRS nicht gesetzt, wird der Standardwert „ /etc/xdg “ verwendet.
Unter macOS und iOS werden bei dem Dateiformat „ NativeFormat “ standardmäßig folgende Dateien verwendet:
$HOME/Library/Preferences/com.MySoft.Star Runner.plist$HOME/Library/Preferences/com.MySoft.plist/Library/Preferences/com.MySoft.Star Runner.plist/Library/Preferences/com.MySoft.plist
Unter Windows werden die Einstellungen für „ NativeFormat “ in den folgenden Registrierungsschlüsseln gespeichert:
HKEY_CURRENT_USER\Software\MySoft\Star RunnerHKEY_CURRENT_USER\Software\MySoft\OrganizationDefaultsHKEY_LOCAL_MACHINE\Software\MySoft\Star RunnerHKEY_LOCAL_MACHINE\Software\MySoft\OrganizationDefaults
Hinweis: Unter Windows werden für 32-Bit-Programme, die im WOW64-Modus ausgeführt werden, die Einstellungen unter folgendem Registrierungsschlüssel gespeichert: „ HKEY_LOCAL_MACHINE\Software\WOW6432node “.
Wenn das Dateiformat „ NativeFormat “ ist, befindet sich die Datei „Settings/MySoft/Star Runner.conf“ im Stammverzeichnis der Anwendung.
Wenn das Dateiformat „ IniFormat “ lautet, werden unter Unix, macOS und iOS die folgenden Dateien verwendet:
$HOME/.config/MySoft/Star Runner.ini$HOME/.config/MySoft.ini- für jedes Verzeichnis <dir> in $XDG_CONFIG_DIRS:
<dir>/MySoft/Star Runner.ini - für jedes Verzeichnis <dir> in $XDG_CONFIG_DIRS:
<dir>/MySoft.ini
Hinweis: Wenn XDG_CONFIG_DIRS nicht gesetzt ist, wird der Standardwert „ /etc/xdg “ verwendet.
Unter Windows werden die folgenden Dateien verwendet:
FOLDERID_RoamingAppData\MySoft\Star Runner.iniFOLDERID_RoamingAppData\MySoft.iniFOLDERID_ProgramData\MySoft\Star Runner.iniFOLDERID_ProgramData\MySoft.ini
Die Bezeichner mit dem Präfix „ FOLDERID_ “ sind spezielle Listen von Element-IDs, die an die Win32-API-Funktion „ SHGetKnownFolderPath() “ übergeben werden, um den entsprechenden Pfad zu erhalten.
FOLDERID_RoamingAppData verweist in der Regel auf C:\Users\User Name\AppData\Roaming, was auch durch die Umgebungsvariable „ %APPDATA% “ angezeigt wird.
FOLDERID_ProgramData verweist in der Regel auf C:\ProgramData.
Wenn das Dateiformat „ IniFormat “ lautet, ist dies „Settings/MySoft/Star Runner.ini“ im Stammverzeichnis der Anwendung.
Die Pfade für die Dateien „ .ini “ und „ .conf “ können mit der Funktion „ setPath()“ geändert werden. Unter Unix, macOS und iOS kann der Benutzer diese durch Setzen der Umgebungsvariablen „ XDG_CONFIG_HOME “ überschreiben; Einzelheiten finden Sie unter „ setPath()“.
Direkter Zugriff auf INI- und .plist-Dateien
Manchmal möchten Sie auf Einstellungen zugreifen, die in einer bestimmten Datei oder unter einem bestimmten Registrierungspfad gespeichert sind. Wenn Sie auf allen Plattformen eine INI-Datei direkt lesen möchten, können Sie den QSettings-Konstruktor verwenden, der einen Dateinamen als erstes Argument entgegennimmt, und als zweites Argument ` QSettings::IniFormat ` übergeben. Zum Beispiel:
Anschließend können Sie das QSettings-Objekt verwenden, um Einstellungen in der Datei zu lesen und zu schreiben.
Unter macOS und iOS können Sie auf Property-List- .plist -Dateien zugreifen, indem Sie „ QSettings::NativeFormat “ als zweites Argument übergeben. Beispiel:
Direkter Zugriff auf die Windows-Registrierung
Unter Windows ermöglicht QSettings den Zugriff auf Einstellungen, die mit QSettings (oder in einem unterstützten Format, z. B. als Zeichenkettendaten) in die Systemregistrierung geschrieben wurden. Dazu erstellen Sie ein QSettings-Objekt mit einem Pfad in der Registrierung und „ QSettings::NativeFormat “.
Beispiel:
Alle Registrierungseinträge, die unter dem angegebenen Pfad erscheinen, können wie gewohnt über das QSettings-Objekt gelesen oder geschrieben werden (wobei Schrägstriche anstelle von Backslashes verwendet werden). Zum Beispiel:
settings.setValue("11.0/Outlook/Security/DontTrustInstalledFiles", 0);Beachten Sie, dass das Backslash-Zeichen, wie bereits 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; in diesem Fall sollten Sie eine native Windows-API verwenden.
Zugriff auf allgemeine Registrierungseinstellungen unter Windows
Unter Windows kann ein Schlüssel sowohl einen Wert als auch Unterschlüssel haben. Der Zugriff auf seinen Standardwert erfolgt durch die Verwendung von „Default“ oder „.“ anstelle eines Unterschlüssels:
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 würden „Default“ und „.“ als normale Unterschlüssel behandelt.
Plattformspezifische Einschränkungen
Obwohl QSettings versucht, die Unterschiede zwischen den verschiedenen unterstützten Plattformen auszugleichen, gibt es dennoch einige Unterschiede, die Sie bei der Portierung Ihrer Anwendung beachten sollten:
- Die Windows-Systemregistrierung weist folgende Einschränkungen auf: Ein Unterschlüssel darf 255 Zeichen nicht überschreiten, der Wert eines Eintrags darf 16.383 Zeichen nicht überschreiten und die Summe aller Werte eines Schlüssels darf 65.535 Zeichen nicht überschreiten. Eine Möglichkeit, diese Einschränkungen zu umgehen, besteht darin, die Einstellungen über die „ IniFormat “ statt über die „ NativeFormat “ zu speichern.
- Unter Windows behält QSettings bei Verwendung der Windows-Systemregistrierung den ursprünglichen Typ des Werts nicht bei. Daher kann sich der Typ des Werts ändern, wenn ein neuer Wert festgelegt wird. Beispielsweise ändert sich ein Wert vom Typ „
REG_EXPAND_SZ“ 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, jedoch nicht geändert, sondern nur überschrieben werden. Der Aufruf von ` setFallbacksEnabled(false)` blendet diese globalen Einstellungen aus.
- Unter macOS und iOS erwartet die von QSettings verwendete CFPreferences-API Internet-Domainnamen anstelle von Organisationsnamen. Um eine einheitliche API bereitzustellen, leitet QSettings einen fiktiven Domainnamen aus dem Organisationsnamen ab (es sei denn, der Organisationsname ist bereits ein Domainname, z. B. OpenOffice.org). Der Algorithmus hängt „.com“ an den Firmennamen an und ersetzt Leerzeichen und andere unzulässige Zeichen durch Bindestriche. Wenn Sie einen anderen Domainnamen angeben möchten, rufen Sie in Ihrer Funktion „
main()“ die Methoden „ QCoreApplication::setOrganizationDomain()“, „ QCoreApplication::setOrganizationName()“ und „ QCoreApplication::setApplicationName()“ auf und verwenden Sie anschließend den Standardkonstruktor von QSettings. Eine weitere Lösung besteht darin, Präprozessor-Direktiven zu verwenden, zum Beispiel: - Unter macOS haben sich die Berechtigungen für den Zugriff auf Einstellungen, die nicht dem aktuellen Benutzer gehören (d. h. SystemScope), mit Version 10.7 (Lion) geändert. Vor dieser Version konnten Benutzer mit Administratorrechten darauf zugreifen. Unter 10.7 und 10.8 (Mountain Lion) ist dies nur noch für „root“ möglich. Unter 10.9 (Mavericks) ändert sich diese Regel jedoch erneut, allerdings nur für das native Format (plist-Dateien).
Sicherheitsaspekte
Die Klasse verwendet ` QDataStream `, um Daten in ` QVariant` zu deserialisieren. Daher weist sie denselben ` security consideration as QDataStream` auf und sollte nur für vertrauenswürdige Eingaben verwendet werden.
Siehe auch „ QVariant “ und „ QSessionManager “.
Dokumentation zu Mitgliedstypen
enum QSettings::Format
Dieser Enum-Typ legt das von QSettings verwendete Speicherformat fest.
| Konstante | Wert | Beschreibung |
|---|---|---|
QSettings::NativeFormat | 0 | Speichern Sie die Einstellungen im für die jeweilige Plattform am besten geeigneten Speicherformat. Unter Windows ist dies die Systemregistrierung; unter macOS und iOS ist dies die CFPreferences-API; unter Unix sind dies textbasierte Konfigurationsdateien im INI-Format. |
QSettings::Registry32Format | 2 | Nur Windows: Greift explizit auf die 32-Bit-Systemregistrierung von einer 64-Bit-Anwendung aus zu, die unter 64-Bit-Windows läuft. Unter 32-Bit-Windows oder von einer 32-Bit-Anwendung unter 64-Bit-Windows funktioniert dies genauso wie die Angabe von „NativeFormat“. Dieser Enum-Wert wurde in Qt 5.7 hinzugefügt. |
QSettings::Registry64Format | 3 | Nur Windows: Greift explizit auf die 64-Bit-Systemregistrierung von einer 32-Bit-Anwendung aus zu, die unter 64-Bit-Windows läuft. Unter 32-Bit-Windows oder von einer 64-Bit-Anwendung unter 64-Bit-Windows funktioniert dies genauso wie die Angabe von „NativeFormat“. Dieser Enum-Wert wurde in Qt 5.7 hinzugefügt. |
QSettings::IniFormat | 1 | Speichert die Einstellungen in INI-Dateien. Beachten Sie, dass INI-Dateien nicht zwischen numerischen Daten und den zu ihrer Kodierung verwendeten Zeichenketten unterscheiden; daher werden als Zahlen geschriebene Werte als „ QString “ zurückgelesen. |
QSettings::WebLocalStorageFormat | 4 | Nur WASM: Speichere die Einstellungen in „window.localStorage“ für die aktuelle Herkunft. Wenn Cookies nicht zulässig sind, wird auf das INI-Format zurückgegriffen. Dies bietet bis zu 5 MiB Speicherplatz pro Herkunft, der Zugriff erfolgt jedoch synchron und JSPI ist nicht erforderlich. |
QSettings::WebIndexedDBFormat | 5 | Nur WASM: Speichert die Einstellungen in einer IndexedDB für den aktuellen Ursprung. Sind Cookies nicht zulässig, wird auf das INI-Format zurückgegriffen. Dies erfordert JSPI, bietet jedoch mehr Speicherplatz als WebLocalStorageFormat. |
QSettings::InvalidFormat | 16 | Von ` registerFormat()` zurückgegebener Sonderwert. |
Unter Unix haben „NativeFormat“ und „IniFormat“ dieselbe Bedeutung, abgesehen von der unterschiedlichen Dateiendung (.conf für „NativeFormat“, .ini für „IniFormat“).
Das INI-Dateiformat ist ein Windows-Dateiformat, das Qt auf allen Plattformen unterstützt. Da es keinen INI-Standard gibt, versuchen wir, uns an die Vorgehensweise von Microsoft zu halten, mit folgenden Ausnahmen:
- Wenn Sie Typen speichern, die QVariant nicht in QString konvertieren kann (z. B. QPoint, QRect und QSize), verwendet Qt eine auf
@basierende Syntax, um den Typ zu kodieren. Zum Beispiel:pos = @QPoint(100 100)Um Kompatibilitätsprobleme zu minimieren, wird jede „
@“, die nicht an erster Stelle im Wert steht oder auf die kein Qt-Typ folgt (Point,Rect,Sizeusw.), als normales Zeichen behandelt. - Obwohl der Backslash in INI-Dateien ein Sonderzeichen ist, führen die meisten Windows-Anwendungen keine Escape-Zeichen für Backslashes (
\) in Dateipfaden durch:windir = C:\WindowsQSettings behandelt den Backslash immer als Sonderzeichen und bietet keine API zum Lesen oder Schreiben solcher Einträge.
- Das INI-Dateiformat unterliegt strengen Einschränkungen hinsichtlich der Syntax eines Schlüssels. Qt umgeht dies, indem es „
%“ als Escape-Zeichen in Schlüsseln verwendet. Wenn Sie zudem eine Einstellung auf oberster Ebene speichern (einen Schlüssel ohne Schrägstriche, z. B. „someKey“), erscheint diese im Abschnitt „General“ der INI-Datei. Um das Überschreiben anderer Schlüssel zu vermeiden, wird der Schlüssel, wenn Sie etwas unter einem Schlüssel wie „General/someKey“ speichern, im Abschnitt „%General“ und nicht im Abschnitt „General“ abgelegt. - Entsprechend den meisten heutigen Implementierungen geht „ QSettings “ davon aus, dass Werte in der INI-Datei UTF-8-kodiert sind. Das bedeutet, dass Werte als UTF-8-kodierte Einträge dekodiert und als UTF-8 zurückgeschrieben werden. Um die Abwärtskompatibilität mit älteren Qt-Versionen zu gewährleisten, werden Schlüssel in der INI-Datei im %-kodierten Format geschrieben, können jedoch sowohl im %-kodierten als auch im UTF-8-Format gelesen werden.
Kompatibilität mit älteren Qt-Versionen
Bitte beachten Sie, dass sich dieses Verhalten von dem unterscheidet, wie sich „ QSettings “ in Qt-Versionen vor Qt 6 verhielt. Mit Qt 5 oder früher erstellte INI-Dateien sind jedoch für eine auf Qt 6 basierende Anwendung vollständig lesbar (es sei denn, es wurde ein anderer INI-Codec als „utf8“ festgelegt). Mit Qt 6 erstellte INI-Dateien sind jedoch nur dann von älteren Qt-Versionen lesbar, wenn Sie „iniCodec“ auf einen UTF-8-Textcodec setzen.
Siehe auch registerFormat() und setPath().
QSettings::ReadFunc
Typedef für einen Zeiger auf eine Funktion mit folgender Signatur:
ReadFunc wird in registerFormat() als Zeiger auf eine Funktion verwendet, die eine Reihe von Schlüssel-Wert-Paaren ausliest. ReadFunc sollte alle Optionen in einem Durchgang auslesen und alle Einstellungen im Container SettingsMap zurückgeben, der anfangs leer ist.
Siehe auch WriteFunc und registerFormat().
enum QSettings::Scope
Diese Enumeration gibt an, ob Einstellungen benutzerspezifisch sind oder von allen Benutzern desselben Systems gemeinsam genutzt werden.
| Konstante | Wert | Beschreibung |
|---|---|---|
QSettings::UserScope | 0 | Speichert Einstellungen an einem für den aktuellen Benutzer spezifischen Speicherort (z. B. im Home-Verzeichnis des Benutzers). |
QSettings::SystemScope | 1 | Speichert Einstellungen an einem globalen Speicherort, sodass alle Benutzer auf demselben Rechner auf denselben Satz von Einstellungen zugreifen können. |
Siehe auch setPath().
QSettings::SettingsMap
Typedef für QMap<QString, QVariant>.
Siehe auch registerFormat().
enum QSettings::Status
Folgende Statuswerte sind möglich:
| Konstant | Wert | Beschreibung |
|---|---|---|
QSettings::NoError | 0 | Es ist kein Fehler aufgetreten. |
QSettings::AccessError | 1 | Es ist ein Zugriffsfehler aufgetreten (z. B. beim Versuch, in eine schreibgeschützte Datei zu schreiben). |
QSettings::FormatError | 2 | Es ist ein Formatfehler aufgetreten (z. B. beim Laden einer fehlerhaften INI-Datei). |
Siehe auch ` status()`.
QSettings::WriteFunc
Typedef für einen Zeiger auf eine Funktion mit folgender Signatur:
WriteFunc wird in registerFormat() als Zeiger auf eine Funktion verwendet, die eine Reihe von Schlüssel-Wert-Paaren schreibt. WriteFunc wird nur einmal aufgerufen, daher müssen Sie die Einstellungen in einem Durchgang ausgeben.
Siehe auch „ ReadFunc “ und „ registerFormat()“.
Dokumentation zu Member-Funktionen
[explicit] QSettings::QSettings(QObject *parent = nullptr)
Erstellt ein QSettings-Objekt für den Zugriff auf die Einstellungen der Anwendung und der Organisation, die zuvor mit einem Aufruf von ` QCoreApplication::setOrganizationName()`, ` QCoreApplication::setOrganizationDomain()` und ` QCoreApplication::setApplicationName()` festgelegt wurden.
Der Gültigkeitsbereich ist „ QSettings::UserScope “ und das Format ist „ defaultFormat “ (standardmäßig „QSettings::NativeFormat “). Verwenden Sie „ setDefaultFormat “ vor dem Aufruf dieses Konstruktors, um das von diesem Konstruktor verwendete Standardformat zu ändern.
Der Code
QSettings settings("Moose Soft", "Facturo-Pro");entspricht
QCoreApplication::setOrganizationName("Moose Soft");
QCoreApplication::setApplicationName("Facturo-Pro");
QSettings settings;Wenn QCoreApplication::setOrganizationName() und QCoreApplication::setApplicationName() zuvor nicht aufgerufen wurden, kann das QSettings-Objekt keine Einstellungen lesen oder schreiben, und status() gibt AccessError zurück.
Sie sollten sowohl die Domäne (Standard unter macOS und iOS) als auch den Namen (Standard auf anderen Plattformen) angeben, obwohl der Code auch mit nur einer Angabe zurechtkommt; diese wird dann (auf allen Plattformen) verwendet, was jedoch im Widerspruch zur üblichen Benennung der Datei auf Plattformen steht, auf denen dies nicht der Standard ist.
Siehe auch QCoreApplication::setOrganizationName(), QCoreApplication::setOrganizationDomain(), QCoreApplication::setApplicationName() und setDefaultFormat().
[explicit] QSettings::QSettings(QSettings::Scope scope, QObject *parent = nullptr)
Erstellt ein QSettings-Objekt auf dieselbe Weise wie QSettings(QObject *parent), jedoch mit dem angegebenen scope.
Siehe auch ` QSettings(QObject *parent)`.
QSettings::QSettings(const QString &fileName, QSettings::Format format, QObject *parent = nullptr)
Erstellt ein QSettings-Objekt für den Zugriff auf die Einstellungen, die in der Datei „ fileName “ gespeichert sind, deren übergeordnete Datei „ parent “ ist. Falls die Datei noch nicht existiert, wird sie angelegt.
Wenn „ format “ gleich „ QSettings::NativeFormat “ ist, hängt die Bedeutung von „ fileName “ von der Plattform ab. Unter Unix ist „ fileName “ der Name einer INI-Datei. Unter macOS und iOS ist „ fileName “ der Name einer „ .plist “-Datei. Unter Windows ist „ fileName “ ein Pfad in der Systemregistrierung.
Wenn format gleich QSettings::IniFormat ist, ist fileName der Name einer INI-Datei.
Warnung: Diese Funktion dient der Benutzerfreundlichkeit. Sie funktioniert gut für den Zugriff auf von Qt generierte INI- oder „ .plist “-Dateien, kann jedoch bei bestimmten Syntaxen in solchen Dateien, die von anderen Programmen stammen, fehlschlagen. Beachten Sie insbesondere die folgenden Einschränkungen:
- QSettings bietet keine Möglichkeit, INI-„Pfad“-Einträge zu lesen, d. h. Einträge mit nicht maskierten Schrägstrichen. (Dies liegt daran, dass diese Einträge mehrdeutig sind und nicht automatisch aufgelöst werden können.)
- In INI-Dateien verwendet QSettings das Zeichen „
@“ in bestimmten Kontexten als Metazeichen, um Qt-spezifische Datentypen zu kodieren (z. B. `@Rect`), und könnte es daher falsch interpretieren, wenn es in reinen INI-Dateien vorkommt.
Siehe auch ` fileName()`.
[explicit] QSettings::QSettings(const QString &organization, const QString &application = QString(), QObject *parent = nullptr)
Erstellt ein QSettings-Objekt für den Zugriff auf die Einstellungen der Anwendung „ application “ aus der Organisation „ organization “ mit dem übergeordneten Element „ parent “.
Beispiel:
QSettings settings("Moose Tech", "Facturo-Pro");Der Geltungsbereich ist auf „ QSettings::UserScope “ festgelegt, und das Format ist auf „ QSettings::NativeFormat “ festgelegt (d. h., der Aufruf von „ setDefaultFormat()“ vor dem Aufruf dieses Konstruktors hat keine Auswirkungen).
Siehe auch setDefaultFormat() und Fallback Mechanism.
QSettings::QSettings(QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr)
Erstellt ein QSettings-Objekt für den Zugriff auf die Einstellungen der Anwendung „ application “ aus der Organisation „ organization “ mit dem übergeordneten Element „ parent “.
Wenn „ scope “ gleich „ QSettings::UserScope “ ist, durchsucht das QSettings-Objekt zunächst benutzerspezifische Einstellungen, bevor es als Ausweichlösung systemweite Einstellungen durchsucht. Wenn „ scope “ gleich „ QSettings::SystemScope “ ist, ignoriert das QSettings-Objekt benutzerspezifische Einstellungen und bietet Zugriff auf systemweite Einstellungen.
Das Speicherformat ist auf „ QSettings::NativeFormat “ festgelegt (d. h., der Aufruf von „ setDefaultFormat()“ vor dem Aufruf dieses Konstruktors hat keine Auswirkung).
Wird kein Anwendungsname angegeben, greift das QSettings-Objekt ausschließlich auf die organisationsweite „ locations “ zu.
Siehe auch ` setDefaultFormat()`.
QSettings::QSettings(QSettings::Format format, QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr)
Erstellt ein QSettings-Objekt für den Zugriff auf die Einstellungen der Anwendung „ application “ aus der Organisation „ organization “ mit dem übergeordneten Objekt „ parent “.
Wenn scope gleich QSettings::UserScope ist, durchsucht das QSettings-Objekt zunächst benutzerspezifische Einstellungen, bevor es als Ausweichlösung systemweite Einstellungen durchsucht. Wenn scope gleich QSettings::SystemScope ist, ignoriert das QSettings-Objekt benutzerspezifische Einstellungen und bietet Zugriff auf systemweite Einstellungen.
Wenn format gleich QSettings::NativeFormat ist, wird die native API zum Speichern von Einstellungen verwendet. Wenn format gleich QSettings::IniFormat ist, wird das INI-Format verwendet.
Wird kein Anwendungsname angegeben, greift das QSettings-Objekt ausschließlich auf die organisationsweite „ locations “ zu.
[virtual noexcept] QSettings::~QSettings()
Löscht das Objekt „ QSettings “.
Alle nicht gespeicherten Änderungen werden schließlich in den permanenten Speicher geschrieben.
Siehe auch sync().
QStringList QSettings::allKeys() const
Gibt eine Liste aller Schlüssel, einschließlich Unterschlüssel, zurück, die mithilfe des Objekts „ QSettings “ gelesen werden können.
Beispiel:
QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);
QStringList keys = settings.allKeys();
// keys: ["fridge/color", "fridge/size", "sofa", "tv"]Wenn eine Gruppe mit ` beginGroup()` festgelegt wird, werden nur die Schlüssel in der Gruppe ohne das Gruppenpräfix zurückgegeben:
settings.beginGroup("fridge");
keys = settings.allKeys();
// keys: ["color", "size"]Siehe auch „ childGroups()“ und „ childKeys()“.
QString QSettings::applicationName() const
Gibt den Anwendungsnamen zurück, der zum Speichern der Einstellungen verwendet wird.
Siehe auch QCoreApplication::applicationName(), format(), scope() und organizationName().
void QSettings::beginGroup(QAnyStringView prefix)
Fügt „ prefix “ zur aktuellen Gruppe hinzu.
Die aktuelle Gruppe wird automatisch allen in „ QSettings “ angegebenen Schlüsseln vorangestellt. Darüber hinaus basieren Abfragefunktionen wie „ childGroups()“, „ childKeys()“ und „ allKeys()“ auf der Gruppe. Standardmäßig ist keine Gruppe festgelegt.
Gruppen sind nützlich, um zu vermeiden, dass dieselben Einstellungs-Pfade immer wieder eingegeben werden müssen. Zum Beispiel:
settings.beginGroup("mainwindow");
settings.setValue("size", win->size());
settings.setValue("active", win->isActive());
settings.endGroup();
settings.beginGroup("outputpanel");
settings.setValue("visible", panel->isVisible());
settings.endGroup();Damit werden die Werte von drei Einstellungen festgelegt:
mainwindow/sizemainwindow/activeoutputpanel/visible
Rufen Sie ` endGroup()` auf, um die aktuelle Gruppe auf den Zustand zurückzusetzen, in dem sie sich vor dem entsprechenden Aufruf von `beginGroup()` befand. Gruppen können verschachtelt werden.
Hinweis: In Qt-Versionen vor 6.4 nahm diese Funktion „ QString “ als Argument entgegen, nicht „ QAnyStringView “.
Siehe auch ` endGroup()` und ` group()`.
int QSettings::beginReadArray(QAnyStringView prefix)
Fügt „ prefix “ zur aktuellen Gruppe hinzu und beginnt mit dem Einlesen aus einem Array. Gibt die Größe des Arrays zurück.
Beispiel:
struct Login {
QString userName;
QString password;
};
QList<Login> logins;
//...
void some_function()
{
//...
QSettings settings;
int size = settings.beginReadArray("logins");
for (int i = 0; i < size; ++i) {
settings.setArrayIndex(i);
Login login;
login.userName = settings.value("userName").toString();
login.password = settings.value("password").toString();
logins.append(login);
}
settings.endArray();
//...
}Verwenden Sie zunächst „ beginWriteArray()“, um das Array zu schreiben.
Hinweis: In Qt-Versionen vor 6.4 nahm diese Funktion „ QString “ entgegen, nicht „ QAnyStringView “.
Siehe auch ` beginWriteArray()`, ` endArray()` und ` setArrayIndex()`.
void QSettings::beginWriteArray(QAnyStringView prefix, int size = -1)
Fügt „ prefix “ zur aktuellen Gruppe hinzu und beginnt mit dem Schreiben eines Arrays der Größe „ size “. Ist „ size “ gleich -1 (Standardwert), wird die Größe automatisch anhand der Indizes der geschriebenen Einträge ermittelt.
Wenn eine bestimmte Gruppe von Schlüsseln häufig vorkommt, können Sie Arrays verwenden, um sich die Arbeit zu erleichtern. Nehmen wir zum Beispiel an, Sie möchten eine Liste von Benutzernamen und Passwörtern mit variabler Länge speichern. Dann könnten Sie Folgendes schreiben:
struct Login {
QString userName;
QString password;
};
QList<Login> logins;
//...
void some_function()
{
//...
QSettings settings;
settings.beginWriteArray("logins");
for (qsizetype i = 0; i < logins.size(); ++i) {
settings.setArrayIndex(i);
settings.setValue("userName", logins.at(i).userName);
settings.setValue("password", logins.at(i).password);
}
settings.endArray();
//...
}Die generierten Schlüssel haben die Form
logins/sizelogins/1/userNamelogins/1/passwordlogins/2/userNamelogins/2/passwordlogins/3/userNamelogins/3/password- ...
Um ein Array wieder auszulesen, verwenden Sie ` beginReadArray()`.
Hinweis: In Qt-Versionen vor 6.4 nahm diese Funktion ` QString` entgegen, nicht ` QAnyStringView`.
Siehe auch beginReadArray(), endArray() und setArrayIndex().
QStringList QSettings::childGroups() const
Gibt eine Liste aller Schlüsselgruppen der obersten Ebene zurück, die Schlüssel enthalten, die mithilfe des Objekts „ QSettings “ gelesen werden können.
Beispiel:
QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);
QStringList groups = settings.childGroups();
// groups: ["fridge"]Wird eine Gruppe mit ` beginGroup()` festgelegt, werden die Schlüssel der ersten Ebene in dieser Gruppe ohne das Gruppenpräfix zurückgegeben.
settings.beginGroup("fridge");
groups = settings.childGroups();
// groups: []Sie können mithilfe von „ childKeys()“ und „childGroups()“ rekursiv durch die gesamte Einstellungshierarchie navigieren.
Siehe auch „ childKeys()“ und „ allKeys()“.
QStringList QSettings::childKeys() const
Gibt eine Liste aller Schlüssel der obersten Ebene zurück, die mithilfe des Objekts „ QSettings “ gelesen werden können.
Beispiel:
QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);
QStringList keys = settings.childKeys();
// keys: ["sofa", "tv"]Wenn eine Gruppe mit ` beginGroup()` festgelegt wird, werden die Schlüssel der obersten Ebene in dieser Gruppe ohne das Gruppenpräfix zurückgegeben:
settings.beginGroup("fridge");
keys = settings.childKeys();
// keys: ["color", "size"]Mit `childKeys()` und ` childGroups()` können Sie rekursiv durch die gesamte Einstellungshierarchie navigieren.
Siehe auch „ childGroups()“ und „ allKeys()“.
void QSettings::clear()
Entfernt alle Einträge am primären Speicherort, die mit diesem „ QSettings “-Objekt verknüpft sind.
Einträge in Ausweichspeicherorten werden nicht entfernt.
Wenn Sie nur die Einträge im aktuellen „ group()“ entfernen möchten, verwenden Sie stattdessen „remove("")“.
Siehe auch „ remove()“ und „ setFallbacksEnabled()“.
bool QSettings::contains(QAnyStringView key) const
Gibt „ true “ zurück, wenn eine Einstellung namens „ key “ vorhanden ist; andernfalls wird „false“ zurückgegeben.
Wenn eine Gruppe mit ` beginGroup()` festgelegt wird, wird ` key ` als relativ zu dieser Gruppe betrachtet.
Die Suche nach Schlüsseln erfolgt je nach Dateiformat und Betriebssystem entweder groß- und kleinschreibungsabhängig oder groß- und kleinschreibungsunabhängig. Um Portabilitätsprobleme zu vermeiden, beachten Sie die Regeln für „ Section and Key Syntax “.
Hinweis: In Qt-Versionen vor 6.4 nahm diese Funktion „ QString “ und nicht „ QAnyStringView “ entgegen.
Siehe auch ` value()` und ` setValue()`.
[static] QSettings::Format QSettings::defaultFormat()
Gibt das Standarddateiformat zurück, das zum Speichern der Einstellungen für den Konstruktor „ QSettings “ (QObject *) verwendet wird. Wenn kein Standardformat festgelegt ist, wird „ QSettings::NativeFormat “ verwendet.
Siehe auch „ setDefaultFormat()“ und „ format()“.
void QSettings::endArray()
Schließt das Array, das mit „ beginReadArray()“ oder „ beginWriteArray()“ angelegt wurde.
Siehe auch beginReadArray() und beginWriteArray().
void QSettings::endGroup()
Setzt die Gruppe auf den Zustand zurück, den sie vor dem entsprechenden Aufruf von ` beginGroup()` hatte.
Beispiel:
settings.beginGroup("alpha");
// settings.group() == "alpha"
settings.beginGroup("beta");
// settings.group() == "alpha/beta"
settings.endGroup();
// settings.group() == "alpha"
settings.endGroup();
// settings.group() == ""Siehe auch beginGroup() und group().
[override virtual protected] bool QSettings::event(QEvent *event)
Umsetzt: ` QObject::event(QEvent *e)`.
bool QSettings::fallbacksEnabled() const
Gibt „ true “ zurück, wenn Fallbacks aktiviert sind; andernfalls „ false “.
Standardmäßig sind Fallbacks aktiviert.
Siehe auch setFallbacksEnabled().
QString QSettings::fileName() const
Gibt den Pfad zurück, unter dem die mit diesem „ QSettings “-Objekt geschriebenen Einstellungen gespeichert sind.
Unter Windows ist der Rückgabewert bei dem Format „ QSettings::NativeFormat “ ein Pfad zur Systemregistrierung und kein Dateipfad.
Siehe auch „ isWritable()“ und „ format()“.
QSettings::Format QSettings::format() const
Gibt das Format zurück, das zum Speichern der Einstellungen verwendet wird.
Siehe auch defaultFormat(), fileName(), scope(), organizationName() und applicationName().
QString QSettings::group() const
Gibt die aktuelle Gruppe zurück.
Siehe auch beginGroup() und endGroup().
bool QSettings::isAtomicSyncRequired() const
Gibt „ true “ zurück, wenn „ QSettings “ nur das atomare Speichern und Laden (Synchronisierung) der Einstellungen durchführen darf. Gibt „ false “ zurück, wenn der Inhalt der Einstellungen direkt in die Konfigurationsdatei gespeichert werden darf.
Der Standardwert ist „ true “.
Siehe auch „ setAtomicSyncRequired()“ und „ QSaveFile “.
bool QSettings::isWritable() const
Gibt „ true “ zurück, wenn Einstellungen mithilfe dieses „ QSettings “-Objekts geschrieben werden können; andernfalls wird „ false “ zurückgegeben.
Ein Grund, warum `isWritable()` möglicherweise `false` zurückgibt, ist, dass ` QSettings ` auf eine schreibgeschützte Datei zugreift.
Warnung: Diese Funktion ist nicht absolut zuverlässig, da sich die Dateiberechtigungen jederzeit ändern können.
Siehe auch fileName(), status() und sync().
QString QSettings::organizationName() const
Gibt den Namen der Organisation zurück, der zum Speichern der Einstellungen verwendet wird.
Siehe auch QCoreApplication::organizationName(), format(), scope() und applicationName().
[static] QSettings::Format QSettings::registerFormat(const QString &extension, QSettings::ReadFunc readFunc, QSettings::WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive)
Registriert ein benutzerdefiniertes Speicherformat. Bei Erfolg wird ein spezieller „Format“-Wert zurückgegeben, der anschließend an den Konstruktor von „ QSettings “ übergeben werden kann. Bei einem Fehler wird „ InvalidFormat “ zurückgegeben.
„ extension “ ist die mit dem Format verknüpfte Dateiendung (ohne den Punkt „.“).
Die Parameter „ readFunc “ und „ writeFunc “ sind Zeiger auf Funktionen, die eine Reihe von Schlüssel-Wert-Paaren lesen und schreiben. Der Parameter „ QIODevice “ der Lese- und Schreibfunktionen wird immer im Binärmodus geöffnet (d. h. ohne das Flag „ QIODeviceBase::Text “).
Der Parameter „ caseSensitivity “ legt fest, ob bei Schlüsseln die Groß-/Kleinschreibung beachtet wird oder nicht. Dies spielt eine Rolle, wenn Werte mit „ QSettings “ gesucht werden. Standardmäßig wird die Groß-/Kleinschreibung beachtet. Auf Unix-Systemen muss der Parameter „ Qt::CaseSensitive “ lauten.
Standardmäßig werden bei Verwendung eines der Konstruktoren, die mit einem Organisations- und einem Anwendungsnamen arbeiten, dieselben Dateisystempfade wie bei „ IniFormat “ verwendet. Verwenden Sie „ setPath()“, um andere Pfade anzugeben.
Beispiel:
bool readXmlFile(QIODevice &device, QSettings::SettingsMap &map);
bool writeXmlFile(QIODevice &device, const QSettings::SettingsMap &map);
int main(int argc, char *argv[])
{
const QSettings::Format XmlFormat =
QSettings::registerFormat("xml", readXmlFile, writeXmlFile);
QSettings settings(XmlFormat, QSettings::UserScope, "MySoft",
"Star Runner");
//...
}Hinweis: Diese Funktion ist threadsicher.
Siehe auch ` setPath()`.
void QSettings::remove(QAnyStringView key)
Entfernt die Einstellung „ key “ sowie alle Untereinstellungen von „ key “.
Beispiel:
QSettings settings;
settings.setValue("ape", 0);
settings.setValue("monkey", 1);
settings.setValue("monkey/sea", 2);
settings.setValue("monkey/doe", 4);
settings.remove("monkey");
QStringList keys = settings.allKeys();
// keys: ["ape"]Beachten Sie, dass, falls einer der Fallback-Speicherorte eine Einstellung mit demselben Schlüssel enthält, diese Einstellung nach dem Aufruf von `remove()` weiterhin sichtbar ist.
Ist „ key “ eine leere Zeichenkette, werden alle Schlüssel im aktuellen „ group “ () entfernt. Beispiel:
QSettings settings;
settings.setValue("ape", 0);
settings.setValue("monkey", 1);
settings.setValue("monkey/sea", 2);
settings.setValue("monkey/doe", 4);
settings.beginGroup("monkey");
settings.remove("");
settings.endGroup();
QStringList keys = settings.allKeys();
// keys: ["ape"]Die Suche nach Schlüsseln erfolgt je nach Dateiformat und Betriebssystem entweder groß-/kleinschreibungsabhängig oder -unabhängig. Um Portabilitätsprobleme zu vermeiden, beachten Sie die Regeln für „ Section and Key Syntax “.
Hinweis: In Qt-Versionen vor 6.4 nahm diese Funktion ` QString` und nicht ` QAnyStringView` entgegen.
Siehe auch setValue(), value() und contains().
QSettings::Scope QSettings::scope() const
Gibt den Bereich zurück, der zum Speichern der Einstellungen verwendet wird.
Siehe auch format(), organizationName() und applicationName().
void QSettings::setArrayIndex(int i)
Setzt den aktuellen Array-Index auf i. Aufrufe von Funktionen wie setValue(), value(), remove() und contains() wirken sich auf den Array-Eintrag an diesem Index aus.
Sie müssen zunächst „ beginReadArray()“ oder „ beginWriteArray()“ aufrufen, bevor Sie diese Funktion aufrufen können.
void QSettings::setAtomicSyncRequired(bool enable)
Legt fest, ob QSettings für das atomare Speichern und Wiederladen (Synchronisieren) der Einstellungen erforderlich ist. Wenn das Argument „ enable “ auf „ true “ gesetzt ist (Standardeinstellung), führt sync() nur atomare Synchronisierungsvorgänge durch. Ist dies nicht möglich, schlägt sync() fehl und status() führt zu einem Fehler.
Wird diese Eigenschaft auf „ false “ gesetzt, kann „ QSettings “ direkt in die Konfigurationsdatei schreiben und ignoriert dabei etwaige Fehler beim Versuch, die Datei vor anderen Prozessen zu sperren, die gleichzeitig schreiben möchten. Aufgrund der Gefahr von Datenbeschädigungen sollte diese Option mit Bedacht eingesetzt werden, ist jedoch unter bestimmten Umständen erforderlich, beispielsweise bei einer Konfigurationsdatei „ QSettings::IniFormat “, die sich in einem ansonsten nicht beschreibbaren Verzeichnis befindet, oder bei NTFS-Alternate-Data-Streams.
Weitere Informationen zu dieser Funktion finden Sie unter QSaveFile.
Siehe auch isAtomicSyncRequired() und QSaveFile.
[static] void QSettings::setDefaultFormat(QSettings::Format format)
Legt das Standarddateiformat auf das angegebene „ format “ fest, das zum Speichern der Einstellungen für den Konstruktor „ QSettings “ (QObject *) verwendet wird.
Wenn kein Standardformat festgelegt ist, wird ` QSettings::NativeFormat ` verwendet. Lesen Sie die Dokumentation zum von Ihnen verwendeten ` QSettings `-Konstruktor, um zu prüfen, ob dieser Konstruktor diese Funktion ignoriert.
Siehe auch defaultFormat() und format().
void QSettings::setFallbacksEnabled(bool b)
Legt fest, ob Fallbacks für „ b “ aktiviert sind.
Standardmäßig sind Fallbacks aktiviert.
Siehe auch fallbacksEnabled().
[static] void QSettings::setPath(QSettings::Format format, QSettings::Scope scope, const QString &path)
Legt den Pfad fest, unter dem die Einstellungen für die angegebenen „ format “ und „ scope “ gespeichert werden, und zwar unter „ path “. Das Format „ format “ kann individuell angepasst werden.
Die folgende Tabelle fasst die Standardwerte zusammen:
| Plattform | Format | Gültigkeitsbereich | Pfad |
|---|---|---|---|
| Windows | IniFormat | UserScope | FOLDERID_RoamingAppData |
| SystemScope | FOLDERID_ProgramData | ||
| Unix | NativeFormat, IniFormat | UserScope | $HOME/.config ($XDG_CONFIG_HOME) |
| SystemScope | /etc/xdg | ||
| macOS | IniFormat | UserScope | $HOME/.config ($XDG_CONFIG_HOME) |
| SystemScope | /Library/Preferences/Qt | ||
| iOS | IniFormat | UserScope | $HOME/Library/Preferences |
| SystemScope | /Library/Preferences/Qt | ||
| macOS und iOS | NativeFormat | UserScope | $HOME/Library/Preferences |
| SystemScope | /Library/Preferences |
Die Standardpfade für „ SystemScope “ können beim Erstellen von Qt überschrieben werden, indem „ -sysconfdir “ an das Skript „ configure “ übergeben wird (Einzelheiten finden Sie unter QLibraryInfo ).
Hinweis: Das Festlegen der „ NativeFormat “-Pfade unter Windows, macOS und iOS hat keine Auswirkungen.
Warnung: Diese Funktion hat keine Auswirkungen auf bereits vorhandene „ QSettings “-Objekte.
Siehe auch registerFormat().
void QSettings::setValue(QAnyStringView key, const QVariant &value)
Setzt den Wert der Einstellung „ key “ auf „ value “. Falls die Datei „ key “ bereits vorhanden ist, wird der bisherige Wert überschrieben.
Die Schlüsselsuche erfolgt je nach Dateiformat und Betriebssystem entweder groß- und kleinschreibungsabhängig oder groß- und kleinschreibungsunabhängig. Um Portabilitätsprobleme zu vermeiden, beachten Sie die Regeln unter „ Section and Key Syntax “.
Beispiel:
QSettings settings;
settings.setValue("interval", 30);
settings.value("interval").toInt(); // returns 30
settings.setValue("interval", 6.55);
settings.value("interval").toDouble(); // returns 6.55Hinweis: In Qt-Versionen vor 6.4 nahm diese Funktion „ QString “ entgegen, nicht „ QAnyStringView “.
Siehe auch „ value()“, „ remove()“ und „ contains()“.
QSettings::Status QSettings::status() const
Gibt einen Statuscode zurück, der den ersten Fehler angibt, auf den QSettings gestoßen ist, oder QSettings::NoError, falls kein Fehler aufgetreten ist.
Beachten Sie, dass QSettings die Ausführung einiger Operationen verzögert. Aus diesem Grund sollten Sie möglicherweise sync() aufrufen, um sicherzustellen, dass die in QSettings gespeicherten Daten auf die Festplatte geschrieben werden, bevor Sie status() aufrufen.
Siehe auch ` sync()`.
void QSettings::sync()
Schreibt alle nicht gespeicherten Änderungen in den permanenten Speicher und lädt alle Einstellungen neu, die in der Zwischenzeit von einer anderen Anwendung geändert wurden.
Diese Funktion wird automatisch vom Destruktor von ` QSettings` sowie in regelmäßigen Abständen von der Ereignisschleife aufgerufen, sodass Sie sie normalerweise nicht selbst aufrufen müssen.
Siehe auch ` status()`.
QVariant QSettings::value(QAnyStringView key) const
QVariant QSettings::value(QAnyStringView key, const QVariant &defaultValue) const
Gibt den Wert für die Einstellung „ key “ zurück. Falls die Einstellung nicht vorhanden ist, wird „ defaultValue “ zurückgegeben.
Wenn kein Standardwert angegeben wird, wird ein Standardwert für „ QVariant “ zurückgegeben.
Die Schlüsselabfrage erfolgt je nach Dateiformat und Betriebssystem entweder unter Berücksichtigung der Groß-/Kleinschreibung oder ohne diese. Um Portabilitätsprobleme zu vermeiden, beachten Sie die Regeln für „ Section and Key Syntax “.
Beispiel:
QSettings settings;
settings.setValue("animal/snake", 58);
settings.value("animal/snake", 1024).toInt(); // returns 58
settings.value("animal/zebra", 1024).toInt(); // returns 1024
settings.value("animal/zebra").toInt(); // returns 0Hinweis: In Qt-Versionen vor 6.4 nahm diese Funktion ` QString` entgegen, nicht ` QAnyStringView`.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.