Detailed explanation of QSetting

1. Introduction to QSettings

Often when you design an application, you want to remember its settings (window size, position, options, etc.) after the application is closed. This information is typically stored in the system registry on Windows, and in property list files on macOS and iOS. On Unix systems, in the absence of a standard, many applications (including KDE applications) use INI text files to save the application's parameter settings. Qt provides the QSettings class to support application parameter saving. Using QSetting, you can save and restore application settings in the portable manager. The QSettings API is based on QVariant and can save most value-based types, such as QString ORect and Qlmage, with minimal effort.

2. Instructions for using QSettings

1. Initialization of QSettings
   When creating a QSettings object, you must pass the name of the company or organization and the name of the application. For example, if the product is named Star Runner and the company is named MySoft, you need to construct the QSettings object as follows:

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

   If you use Q settings in multiple places in your application, you may need to use QCoreApplication:setOrganizationName()and QCoreApplication:setApplicationNamel()specify the organization name and application name, and then use the default QSettings hook function:

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

   Sometimes you want to access settings stored in a specific file or registry path. On all platforms, if you want to read the INI file directly, you can use QSettingsthe constructor, which takes the file name as the first parameter and will pass it QSettings::IniFormatas the second parameter. For example:

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

2. Parameter settings for QSettings
   Each setting consists of a specified setting name (composed of a section and key, separated by /) QStringand a section that stores data related to the key QVariant. Use setValue()functions to set parameters. For example:

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

   If a setting with the same key already exists, the new value will overwrite the existing value. For efficiency reasons, changes may not be saved immediately to permanent storage. (Can be called sync()to commit changes.)

3. Parameter reading of QSettings Reading parameters
   through value()functions:

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

   If no setting with the specified name is found, QSettings will return an empty QVariant(can be converted to the integer 0). You can value()specify another default value by passing a second argument to (this default argument will be returned even if it does not exist):

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

4. Check and delete parameters in QSettings
   Called contains()to test whether the given key exists. Called to remove()delete the settings associated with a key. Called allKeys()to get a list of all keys. Called clear()to delete all keys.

5. Naming rules for parameter names (keys)
   Setting keys can contain any Unicode characters. The Windows registry and INI files use case-insensitive keys, while the CFPreferences API on macOS and iOS uses case-sensitive keys. To avoid portability issues, follow these simple rules:

   • Always use the same case to reference the same key. For example, if you call a key somewhere in your code text font, don't call it somewhere else Text Fonts.
   • Except for case, avoid using the same key name. For example, if you have a MainWindowkey called , don't try to save another key as mainwindow.
   • /Do not use slashes ( and ) in section or keyword names \; the backslash character is used to separate subkeys (see below). On the window, \converted by QSettings /, this makes them exactly the same.

   Hierarchical keys can be formed using the "/" character as a delimiter, similar to Unix file paths. For example:

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

   If you want to save or restore many settings with the same prefix, you can specify beginGroup()the prefix and call it at the end endGroup(). Here's the same example, but this time using the group mechanism:

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

6. QSettings' thread-safe
   Q settings are reentrant. This means that different QSettings objects can be used simultaneously in different threads. Even though the QSettings object refers to the same file on disk (or the same entry in the system registry). If a setting is modified through one QSettings object, the changes will be immediately seen in any other QSettings objects operating in the same location and in the same process. As long as certain conditions are met, Q settings can be safely used to read and write to the same system location from different processes (which can be different instances of an application running simultaneously, or completely different applications). For QSettings::IniFormat, it uses advisory file locking and smart merge algorithms to ensure data integrity. The condition for this is that the writable configuration file must be a regular file and must be located in a directory where the current user can create new temporary files

7. The storage location of the configuration file saved by QSettings in the system

   • On Unix systems, NativeFormatthe following is used by default if the file format is (or XDG_CONFIG_DIRSthe /etc/XDGdefault if not set):

     1. $HOME/.config/MySoft/Star Runner.conf (Qt for Embedded Linux: $HOME/Settings/MySoft/Star Runner.conf)
     2. $HOME/.config/MySoft.conf (Qt for Embedded Linux: $HOME/Settings/MySoft.conf)
     3. for each directory <dir> in $XDG_CONFIG_DIRS: <dir>/MySoft/Star Runner.conf
     4. for each directory <dir> in $XDG_CONFIG_DIRS: <dir>/MySoft.conf

   • On macOS versions 10.2 and 10.3, the following files are used by default:

     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

   • On Windows, NativeFormatsettings are stored in the following registry path (On Windows, for 32-bit programs running in WOW64 mode, settings are stored in the following registry path: . in the HKEY_LOCAL_MACHINE\Software\WOW6432nodeapplication's home directory Settings/MySoft/StarRunner.conf.):

     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

   • If the file format is IniFormat, the following is used on Unix, macOS, and iOS (if not set XDG_CONFIG_DIRS, /etc/XDGthe default is used.):

     1. $HOME/.config/MySoft/Star Runner.ini (Qt for Embedded Linux: $HOME/Settings/MySoft/Star Runner.ini)
     2. $HOME/.config/MySoft.ini (Qt for Embedded Linux: $HOME/Settings/MySoft.ini)
     3. for each directory <dir> in $XDG_CONFIG_DIRS: <dir>/MySoft/Star Runner.ini
     4. for each directory <dir> in $XDG_CONFIG_DIRS: <dir>/MySoft.ini

     On Windows, use the following files ( FOLDRID_RoamingAppDatausually pointed to C:\Users\UserName\AppData\Roaming, also %AppData%shown by environment variables. FOLDERID_ProgramDataUsually pointed to C:\ProgramData.):

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