Settings QML Type

Bietet dauerhafte, plattformunabhängige Anwendungseinstellungen. Mehr...

• Liste aller Elemente, einschließlich vererbter Elemente

Eigenschaften

• category : string
• location : url

Methoden

• void setValue(string key, var value)
• void sync()
• var value(string key, var defaultValue)

Ausführliche Beschreibung

Der Typ „Einstellungen“ ermöglicht dauerhafte, plattformunabhängige Anwendungseinstellungen.

Benutzer erwarten in der Regel, dass sich eine Anwendung ihre Einstellungen (Fenstergrößen und -positionen, Optionen usw.) über mehrere Sitzungen hinweg merkt. Der Typ „Settings“ ermöglicht es Ihnen, solche Anwendungseinstellungen mit minimalem Aufwand zu speichern und wiederherzustellen.

Einzelne Einstellungswerte werden durch die Deklaration von Eigenschaften innerhalb eines „Settings“-Elements festgelegt. Es werden nur Werttypen unterstützt, die von „ QSettings “ erkannt werden. Es wird empfohlen, Eigenschaftsaliase zu verwenden, um automatische Eigenschaftsaktualisierungen in beide Richtungen zu gewährleisten. Das folgende Beispiel zeigt, wie Sie mit „Settings“ die Geometrie eines Fensters speichern und wiederherstellen können.

import QtCore
import QtQuick

Window {
    id: window

    width: 800
    height: 600

    Settings {
        property alias x: window.x
        property alias y: window.y
        property alias width: window.width
        property alias height: window.height
    }
}

Beim ersten Start der Anwendung erhält das Fenster die Standardabmessungen 800×600. Beachten Sie, dass keine Standardposition angegeben wird – dies überlassen wir dem Fenstermanager. Später, wenn sich die Fenstergeometrie ändert, werden neue Werte automatisch in den persistenten Einstellungen gespeichert. Beim zweiten Start der Anwendung werden die Anfangswerte aus den persistenten Einstellungen abgerufen, wodurch das Fenster wieder an die vorherige Position und Größe zurückversetzt wird.

Eine vollständig deklarative Syntax, die durch die Verwendung von Eigenschaftsaliasen erreicht wird, geht mit dem Nachteil einher, dass persistente Einstellungen immer dann gespeichert werden müssen, wenn sich die Werte der aliasierten Eigenschaften ändern. Normale Eigenschaften können verwendet werden, um eine feinere Kontrolle über das Speichern der persistenten Einstellungen zu erlangen. Das folgende Beispiel veranschaulicht, wie eine Einstellung beim Zerstören einer Komponente gespeichert wird.

import QtCore
import QtQuick

Item {
    id: page

    state: settings.state

    states: [
        State {
            name: "active"
            // ...
        },
        State {
            name: "inactive"
            // ...
        }
    ]

    Settings {
        id: settings
        property string state: "active"
    }

    Component.onDestruction: {
        settings.state = page.state
    }
}

Beachten Sie, wie der Standardwert nun in der persistenten Einstellungseigenschaft angegeben wird und die eigentliche Eigenschaft an die Einstellung gebunden ist, um den Anfangswert aus den persistenten Einstellungen zu beziehen.

Anwendungskennungen

Anwendungsspezifische Einstellungen werden durch die Angabe von Anwendungs name, organization und domain oder durch die Angabe von location identifiziert.

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    app.setOrganizationName("Some Company");
    app.setOrganizationDomain("somecompany.com");
    app.setApplicationName("Amazing Application");

    QQmlApplicationEngine engine("main.qml");
    return app.exec();
}

Diese werden in C++ typischerweise am Anfang von ` main()` angegeben, können aber auch in QML über die folgenden Eigenschaften gesteuert werden:

• Qt.application.name,
• Qt.application.organization und
• Qt.application.domain.

Kategorien

Anwendungseinstellungen können durch die Angabe eines Kategorienamens über die Eigenschaft „ category “ in logische Kategorien unterteilt werden. Die Verwendung logischer Kategorien sorgt nicht nur für eine übersichtlichere Struktur der Einstellungen, sondern verhindert auch mögliche Konflikte zwischen Einstellungsschlüsseln.

Wenn mehrere Kategorien erforderlich sind, verwenden Sie mehrere „Settings“-Objekte, von denen jedes seine eigene Kategorie hat:

Item {
    id: panel

    visible: true

    Settings {
        category: "OutputPanel"
        property alias visible: panel.visible
        // ...
    }

    Settings {
        category: "General"
        property alias fontSize: fontSizeSpinBox.value
        // ...
    }
}

Anstatt sicherzustellen, dass alle Einstellungen in der Anwendung eindeutige Namen haben, können die Einstellungen in eindeutige Kategorien unterteilt werden, die dann Einstellungen mit denselben Namen enthalten können, die auch in anderen Kategorien verwendet werden – ohne dass es zu Konflikten kommt.

Einstellungs-Singleton

Oft ist es sinnvoll, Einstellungen als Singleton für jede QML-Datei verfügbar zu machen. Ein Beispiel hierfür finden Sie im Beispiel „To-Do-Liste“. Konkret ist „AppSettings.qml“ das Singleton, und in der Datei „CMakeLists.txt“ wird die Eigenschaft „ QT_QML_SINGLETON_TYPE “ für diese Datei über „ set_source_files_properties “ auf „ TRUE “ gesetzt.

Hinweise

Die aktuelle Implementierung basiert auf QSettings. Dies bringt gewisse Einschränkungen mit sich, wie zum Beispiel fehlende Änderungsbenachrichtigungen. Das Schreiben eines Einstellungswerts mithilfe einer Instanz von „Settings“ aktualisiert den Wert in einer anderen „Settings“-Instanz nicht, selbst wenn diese sich auf dieselbe Einstellung in derselben Kategorie beziehen.

Die Informationen werden unter Windows in der Systemregistrierung und unter macOS in XML-Einstellungsdateien gespeichert. Auf anderen Unix-Systemen werden mangels eines Standards INI-Textdateien verwendet. Weitere Details finden Sie in der Dokumentation unter QSettings.

Siehe auch QSettings.

Dokumentation zu Eigenschaften

category : string

Diese Eigenschaft enthält den Namen der Einstellungskategorie.

Kategorien können verwendet werden, um zusammengehörige Einstellungen zu gruppieren.

Siehe auch QSettings::group.

location : url

Diese Eigenschaft enthält den Pfad zur Einstellungsdatei. Falls die Datei noch nicht existiert, wird sie angelegt.

Ist diese Eigenschaft leer (Standardeinstellung), wird QSettings::defaultFormat() verwendet. Andernfalls wird QSettings::IniFormat verwendet.

Siehe auch QSettings::fileName, QSettings::defaultFormat und QSettings::IniFormat.

Methodendokumentation

void setValue(string key, var value)

Setzt den Wert der Einstellung „ key “ auf „ value “. Falls der Schlüssel bereits vorhanden ist, wird der bisherige Wert überschrieben.

Siehe auch „ value()“ und „ QSettings::setValue “.

void 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 ` QSettings::sync`.

var value(string key, var defaultValue)

Gibt den Wert für die Einstellung „ key “ zurück. Falls die Einstellung nicht vorhanden ist, wird „ defaultValue “ zurückgegeben.

Siehe auch ` setValue()` und ` QSettings::value`.