- Qt 6.8
- Qt Qml Core
- QML Types
- Settings
- Qt 6.8.3 Reference Documentation

# Settings QML Type

Provides persistent platform-independent application settings. More...

Import Statement: | `import QtCore`
Since: | Qt 6.5
Inherits: | QtObject

- List of all members, including inherited members

## Properties

- category : string
- location : url

## Methods

- setValue(string key, var value)
- sync()
- var value(string key, var defaultValue)

## Detailed Description

The Settings type provides persistent platform-independent application settings.

Users normally expect an application to remember its settings (window sizes and positions, options, etc.) across sessions. The Settings type enables you to save and restore such application settings with the minimum of effort.

Individual setting values are specified by declaring properties within a Settings element. Only value types recognized by QSettings are supported. The recommended approach is to use property aliases in order to get automatic property updates both ways. The following example shows how to use Settings to store and restore the geometry of a window.

     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
         }
     }

At first application startup, the window gets default dimensions specified as 800x600. Notice that no default position is specified - we let the window manager handle that. Later when the window geometry changes, new values will be automatically stored to the persistent settings. The second application run will get initial values from the persistent settings, bringing the window back to the previous position and size.

A fully declarative syntax, achieved by using property aliases, comes at the cost of storing persistent settings whenever the values of aliased properties change. Normal properties can be used to gain more fine-grained control over storing the persistent settings. The following example illustrates how to save a setting on component destruction.

     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
         }
     }

Notice how the default value is now specified in the persistent setting property, and the actual property is bound to the setting in order to get the initial value from the persistent settings.

## Application Identifiers

Application specific settings are identified by providing application name, organization and domain, or by specifying location.

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

These are typically specified in C++ in the beginning of `main()`, but can also be controlled in QML via the following properties:

- Qt.application.name,
- Qt.application.organization and
- Qt.application.domain.

## Categories

Application settings may be divided into logical categories by specifying a category name via the category property. Using logical categories not only provides a cleaner settings structure, but also prevents possible conflicts between setting keys.

If several categories are required, use several Settings objects, each with their own category:

     Item {
         id: panel

         visible: true

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

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

Instead of ensuring that all settings in the application have unique names, the settings can be divided into unique categories that may then contain settings using the same names that are used in other categories - without a conflict.

## Settings singleton

It's often useful to have settings available to every QML file as a singleton. For an example of this, see the To Do List example. Specifically, AppSettings.qml is the singleton, and in the CMakeLists.txt file, the `QT_QML_SINGLETON_TYPE` property is set to `TRUE` for that file via `set_source_files_properties`.

## Notes

The current implementation is based on QSettings. This imposes certain limitations, such as missing change notifications. Writing a setting value using one instance of Settings does not update the value in another Settings instance, even if they are referring to the same setting in the same category.

The information is stored in the system registry on Windows, and in XML preferences files on macOS. On other Unix systems, in the absence of a standard, INI text files are used. See QSettings documentation for more details.

See also QSettings.

## Property Documentation

category : string

This property holds the name of the settings category.

Categories can be used to group related settings together.

See also QSettings::group.

location : url

This property holds the path to the settings file. If the file doesn't already exist, it will be created.

If this property is empty (the default), then QSettings::defaultFormat() will be used. Otherwise, QSettings::IniFormat will be used.

See also QSettings::fileName, QSettings::defaultFormat, and QSettings::IniFormat.

## Method Documentation

setValue(string key, var value)

Sets the value of setting key to value. If the key already exists, the previous value is overwritten.

See also value() and QSettings::setValue.

sync()

Writes any unsaved changes to permanent storage, and reloads any settings that have been changed in the meantime by another application.

This function is called automatically from QSettings's destructor and by the event loop at regular intervals, so you normally don't need to call it yourself.

See also QSettings::sync.

var value(string key, var defaultValue)

Returns the value for setting key. If the setting doesn't exist, returns defaultValue.

See also setValue() and QSettings::value.