Класс QSettings

Класс QSettings предоставляет средства для хранения платформонезависимых настроек приложения. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Примечание: Эти функции также являются безопасными для потоков:

• registerFormat()

Открытые типы

Открытые функции

Статические публичные члены

Переопределённые защищённые функции

Подробное описание

Пользователи обычно ожидают, что приложение будет запоминать свои настройки (размеры и позиции окон, параметры и т. д.) между сеансами. Эта информация часто хранится в системном реестре в Windows и в файлах списка свойств в macOS и iOS. В системах Unix, в отсутствие стандарта, многие приложения (включая приложения KDE) используют текстовые INI-файлы.

QSettings — это абстракция вокруг этих технологий, позволяющая сохранять и восстанавливать настройки приложения переносимым способом. Она также поддерживает пользовательские форматы хранения.

API QSettings основан на QVariant, что позволяет сохранять большинство типов значений, таких как QString, QRect и QImage, с минимальными усилиями.

Если вам нужна только непостоянная структура на основе памяти, используйте QMap<QString, QVariant> вместо этого.

Основные принципы использования

При создании объекта QSettings, необходимо указать имя вашей компании или организации, а также имя вашего приложения. Например, если ваш продукт называется Star Runner, а ваша компания MySoft, то вы создадите объект QSettings следующим образом:

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

Объекты QSettings могут быть созданы как на стеке, так и на куче (т.е. используя new). Создание и уничтожение объекта QSettings происходит очень быстро.

Если вы используете QSettings во многих местах вашего приложения, вы можете указать имя организации и имя приложения, используя QCoreApplication::setOrganizationName() и QCoreApplication::setApplicationName(), а затем использовать конструктор QSettings по умолчанию:

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

(Здесь мы также указываем домен организации в Интернете. Когда домен в Интернете задан, он используется на macOS и iOS вместо имени организации, так как приложения macOS и iOS обычно используют домены Интернета для самоидентификации. Если домен не задан, он выводится из имени организации. Подробности см. в разделе Плаформенно-специфические заметки ниже.)

QSettings хранит настройки. Каждая настройка состоит из QString, который указывает имя настройки (ключ), и QVariant, который хранит данные, связанные с ключом. Для записи настройки используйте setValue(). Например:

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

Если уже существует настройка с тем же ключом, существующее значение перезаписывается новым. Для повышения эффективности изменения могут не сохраняться в постоянное хранилище сразу. (Вы всегда можете вызвать sync(), чтобы сохранить внесенные изменения.)

Вы можете получить значение настройки с помощью value():

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

Если настройки с указанным именем не существует, QSettings возвращает нулевой QVariant (который может быть преобразован в целое число 0). Вы можете указать другое значение по умолчанию, передав второй аргумент в value():

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

Чтобы проверить, существует ли данный ключ, вызовите contains(). Чтобы удалить настройку, связанную с ключом, вызовите remove(). Чтобы получить список всех ключей, вызовите allKeys(). Чтобы удалить все ключи, вызовите clear().

QVariant и типы GUI

Поскольку QVariant является частью модуля Qt Core, он не может предоставить функции преобразования в такие типы данных, как QColor, QImage и QPixmap, которые являются частью Qt GUI. Другими словами, в QVariant нет функций toColor(), toImage(), или toPixmap().

Вместо этого вы можете использовать шаблонную функцию QVariant::value(). Например:

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

Обратное преобразование (например, из QColor в QVariant) происходит автоматически для всех типов данных, поддерживаемых QVariant, включая типы, связанные с GUI:

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

Пользовательские типы, зарегистрированные с помощью qRegisterMetaType(), которые имеют операторы для потокового ввода-вывода в и из QDataStream, могут быть сохранены с помощью QSettings.

Синтаксис раздела и ключа

Ключи настроек могут содержать любые символы Юникода. Реестр Windows и файлы INI используют нечувствительные к регистру ключи, а API CFPreferences на macOS и iOS использует чувствительные к регистру ключи. Чтобы избежать проблем с переносимостью, следуйте этим простым правилам:

1. Всегда ссылайтесь на тот же ключ с тем же регистром. Например, если вы используете ключ «text fonts» в одном месте кода, не используйте «Text Fonts» в другом.
2. Избегайте имён ключей, которые идентичны, за исключением регистра. Например, если у вас есть ключ «MainWindow», не пытайтесь сохранить другой ключ как «mainwindow».
3. Не используйте слеши («/» и «\») в именах разделов или ключей; символ обратной косой черты используется для разделения подключаемых ключей (см. ниже). В Windows QSettings преобразует «\» в «/», что делает их идентичными.

Иерархические ключи можно создавать с помощью символа «/» в качестве разделителя, аналогично путям Unix. Например:

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

Если вы хотите сохранить или восстановить множество настроек с тем же префиксом, вы можете указать префикс, используя beginGroup(), и вызвать endGroup() в конце. Вот тот же пример, но на этот раз с использованием механизма групп:

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

Если группа задана с помощью beginGroup(), поведение большинства функций соответственно изменяется. Группы могут быть заданы рекурсивно.

В дополнение к группам, QSettings также поддерживает концепцию «массива». Подробности см. в beginReadArray() и beginWriteArray().

Механизм обратного падения

Предположим, что вы создали объект QSettings с именем организации MySoft и именем приложения Star Runner. Когда вы ищете значение, до четырёх местоположений проверяются в указанном порядке:

1. Местоположение, специфичное для пользователя, для приложения Star Runner
2. Местоположение, специфичное для пользователя, для всех приложений MySoft
3. Системное местоположение для приложения Star Runner
4. Системное местоположение для всех приложений MySoft

(См. Плаформенно-специфические заметки ниже для информации о том, где эти местоположения находятся на различных платформах, поддерживаемых Qt.)

Если ключ не найден в первом месте, поиск продолжается во втором месте и так далее. Это позволяет хранить настройки на уровне системы или организации и переопределять их на уровне пользователя или приложения. Чтобы отключить этот механизм, вызовите setFallbacksEnabled(false).

Хотя ключи из всех четырёх местоположений доступны для чтения, только первый файл (местоположение, специфичное для пользователя, для текущего приложения) доступен для записи. Чтобы записать в любой другой файл, опустите имя приложения и/или укажите QSettings::SystemScope (вместо QSettings::UserScope, значение по умолчанию).

Посмотрим на примере:

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

Ниже приведена сводная таблица, показывающая, к каким местоположениям обращаются объекты QSettings. «X» означает, что местоположение является основным местоположением, связанным с объектом QSettings, и используется как для чтения, так и для записи; «o» означает, что местоположение используется в качестве обратного падения при чтении.

Прелесть этого механизма в том, что он работает на всех платформах, поддерживаемых Qt, и при этом даёт большую гибкость, без необходимости указывать имена файлов или пути к реестру.

Если вы хотите использовать файлы INI на всех платформах вместо родного API, вы можете передать QSettings::IniFormat в качестве первого аргумента конструктора QSettings, а затем указать область, имя организации и имя приложения:

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

Обратите внимание, что информация о типе не сохраняется при чтении настроек из файлов INI; все значения будут возвращены как QString.

Пример Settings Editor позволяет экспериментировать с различными местоположениями настроек и с включёнными или выключенными механизмами обратного падения.

Восстановление состояния графического приложения

QSettings часто используется для хранения состояния графического приложения. Следующий пример иллюстрирует, как использовать QSettings для сохранения и восстановления геометрии основного окна приложения.

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

См. раздел Геометрия окна для обсуждения того, почему лучше вызывать QWidget::resize() и QWidget::move() вместо QWidget::setGeometry() для восстановления геометрии окна.

Функции readSettings() и writeSettings() должны вызываться из конструктора главного окна и обработчика закрытия окна следующим образом:

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

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

См. пример Application для автономного примера использования QSettings.

Доступ к настройкам из нескольких потоков или процессов одновременно

QSettings является многопоточным. Это означает, что вы можете использовать отдельные объекты QSettings в различных потоках одновременно. Это гарантируется даже в том случае, если объекты QSettings ссылаются на те же файлы на диске (или на те же записи в системном реестре). Если настройка изменяется через один объект QSettings, изменение будет сразу видно в любых других объектах QSettings, которые работают с тем же местоположением и находятся в том же процессе.

QSettings можно безопасно использовать из разных процессов (которые могут быть разными экземплярами вашего приложения, работающего одновременно, или разными приложениями вообще) для чтения и записи в те же системные местоположения при соблюдении определённых условий. Для QSettings::IniFormat используется консультативное блокирование файлов и алгоритм интеллектуального слияния для обеспечения целостности данных. Условием для этого является то, что конфигурационный файл для записи должен быть обычным файлом и находиться в каталоге, в котором текущий пользователь может создавать новые временные файлы. Если это не так, то необходимо использовать setAtomicSyncRequired() для отключения этой безопасности.

Обратите внимание, что sync() импортирует изменения, внесённые другими процессами (в дополнение к записи изменений из этого QSettings).

Плаформенно-специфические заметки

Местоположения, где хранятся настройки приложения

Как упоминалось в разделе Механизм обратного падения, QSettings хранит настройки приложения в до четырёх местоположений, в зависимости от того, являются ли настройки для конкретного пользователя или для всей системы, и от того, являются ли настройки специфичны для приложения или организации. Для простоты мы предполагаем, что организация называется MySoft, а приложение — Star Runner.

В системах Unix, если формат файла — NativeFormat, по умолчанию используются следующие файлы:

1. $HOME/.config/MySoft/Star Runner.conf (Qt для встраиваемой Linux: $HOME/Settings/MySoft/Star Runner.conf)
2. $HOME/.config/MySoft.conf (Qt для встраиваемой Linux: $HOME/Settings/MySoft.conf)
3. для каждой директории <dir> в $XDG_CONFIG_DIRS: <dir>/MySoft/Star Runner.conf
4. для каждой директории <dir> в $XDG_CONFIG_DIRS: <dir>/MySoft.conf

В macOS и iOS, если формат файла — NativeFormat, по умолчанию используются эти файлы:

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

В Windows настройки с форматом NativeFormat хранятся в следующих путях реестра:

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

Если формат файла — NativeFormat, это "Settings/MySoft/Star Runner.conf" в домашнем каталоге приложения.

Если формат файла — IniFormat, на системах Unix, macOS и iOS используются следующие файлы:

1. $HOME/.config/MySoft/Star Runner.ini (Qt для встраиваемой Linux: $HOME/Settings/MySoft/Star Runner.ini)
2. $HOME/.config/MySoft.ini (Qt для встраиваемой Linux: $HOME/Settings/MySoft.ini)
3. для каждой директории <dir> в $XDG_CONFIG_DIRS: <dir>/MySoft/Star Runner.ini
4. для каждой директории <dir> в $XDG_CONFIG_DIRS: <dir>/MySoft.ini

В Windows используются следующие файлы:

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

Идентификаторы, начинающиеся с FOLDERID_, представляют собой специальные списки идентификаторов элементов, которые должны быть переданы функции Win32 API SHGetKnownFolderPath(), для получения соответствующего пути.

FOLDERID_RoamingAppData обычно указывает на C:\Users\User Name\AppData\Roaming, что также отображается переменной окружения %APPDATA%.

FOLDERID_ProgramData обычно указывает на C:\ProgramData.

Если формат файла — IniFormat, это "Settings/MySoft/Star Runner.ini" в домашнем каталоге приложения.

Пути к файлам .ini и .conf можно изменить с помощью setPath(). В Unix, macOS и iOS пользователь может переопределить их, установив переменную окружения XDG_CONFIG_HOME; подробнее см. setPath().

Прямой доступ к файлам INI и .plist

Иногда вам нужно получить доступ к настройкам, хранящимся в определённом файле или пути реестра. На всех платформах, если вы хотите напрямую прочитать файл INI, можно использовать конструктор QSettings, который принимает имя файла в качестве первого аргумента и передаёт QSettings::IniFormat в качестве второго аргумента. Например:

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

Затем вы можете использовать объект QSettings для чтения и записи настроек в файле.

В macOS и iOS вы можете получить доступ к файлам списков свойств .plist путём передачи QSettings::NativeFormat в качестве второго аргумента. Например:

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

Прямой доступ к реестру Windows

В Windows QSettings позволяет получить доступ к настройкам, записанным с помощью QSettings (или настройкам в поддерживаемом формате, например, строковые данные) в системном реестре. Это делается путём создания объекта QSettings с путём в реестре и QSettings::NativeFormat.

Например:

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

Все записи реестра, которые появляются под указанным путём, могут быть прочитаны или записаны через объект QSettings обычным способом (используя слэши вместо обратных слэшей). Например:

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

Обратите внимание, что символ обратной косой черты используется QSettings для разделения подключаемых ключей. В результате вы не можете читать или записывать записи реестра Windows, содержащие слэши или обратные слэши; если вам это необходимо, используйте родной API Windows.

Доступ к общим настройкам реестра в Windows

В Windows, ключ может иметь как значение, так и подключаемые ключи. Его значение по умолчанию доступно с использованием "Default" или "." вместо подключаемого ключа:

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"

На платформах, отличных от Windows, "Default" и "." будут обрабатываться как обычные подключаемые ключи.

Ограничения платформ

Хотя QSettings пытается сгладить различия между разными поддерживаемыми платформами, всё же существуют некоторые различия, о которых следует помнить при переносе приложения:

• Системный реестр Windows имеет следующие ограничения: подключаемый ключ не может превышать 255 символов, значение записи не может превышать 16 383 символов, и все значения ключа не могут превышать 65 535 символов. Один из способов обойти эти ограничения — хранить настройки с использованием IniFormat вместо NativeFormat.
• В Windows, когда используется системный реестр Windows, QSettings не сохраняет исходный тип значения. Поэтому тип значения может измениться при установке нового значения. Например, значение типа REG_EXPAND_SZ изменится на REG_SZ.
• В macOS и iOS, allKeys() вернёт дополнительные ключи для глобальных настроек, которые применяются ко всем приложениям. Эти ключи могут быть прочитаны с помощью value(), но не могут быть изменены, только затенены. Вызов setFallbacksEnabled(false) скроет эти глобальные настройки.
• В macOS и iOS API CFPreferences, используемый QSettings, ожидает имена доменных имён интернета, а не имён организаций. Для обеспечения единого API QSettings выводит псевдоним доменного имени из имени организации (если имя организации уже является именем домена, например, OpenOffice.org). Алгоритм добавляет ".com" к имени компании и заменяет пробелы и другие недопустимые символы дефисами. Если вы хотите указать другое доменное имя, вызовите QCoreApplication::setOrganizationDomain(), QCoreApplication::setOrganizationName() и QCoreApplication::setApplicationName() в вашей функции main() и затем используйте стандартный конструктор QSettings. Другое решение — использовать препроцессорные директивы, например:

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

• В macOS разрешения на доступ к настройкам, не принадлежащим текущему пользователю (т.е. SystemScope), изменились с 10.7 (Lion). До этой версии пользователи с правами администратора могли к ним получить доступ. Для 10.7 и 10.8 (Mountain Lion) доступ имеют только root. Однако в 10.9 (Mavericks) это правило снова меняется, но только для родного формата (файлы plist).

См. также QVariant, QSessionManager, Пример редактора настроек и Пример приложения Qt Widgets.

Документация типов членов

перечисление QSettings::Format

Это перечисление типов, определяющее формат хранения, используемый QSettings.

В Unix NativeFormat и IniFormat означают одно и то же, за исключением того, что расширение файла отличается (.conf для NativeFormat, .ini для IniFormat).

Формат INI файла — это формат файла Windows, который поддерживается Qt на всех платформах. В отсутствие стандарта INI мы стараемся следовать тому, что делает Microsoft, с следующими исключениями:

• Если вы храните типы, которые QVariant не может преобразовать в QString (например, QPoint, QRect и QSize), Qt использует синтаксис на основе @, чтобы закодировать тип. Например:

  pos = @Point(100 100)

  Чтобы свести к минимуму проблемы совместимости, любой @, который не стоит на первом месте в значении или не следует за типом Qt (Point, Rect, Size, и т. д.), обрабатывается как обычный символ.

• Хотя обратная косая черта является специальным символом в файлах INI, большинство приложений Windows не экранируют обратные косые черты (\) в путях к файлам:

  windir = C:\Windows

  QSettings всегда обрабатывает обратную косую черту как специальный символ и не предоставляет API для чтения или записи таких записей.

• Формат INI имеет жёсткие ограничения на синтаксис ключа. Qt обходит это, используя % в качестве символа экранирования в ключах. Кроме того, если вы сохраняете параметр верхнего уровня (ключ без слешей, например, «someKey»), он будет отображаться в разделе «General» файла INI. Чтобы избежать перезаписи других ключей, если вы сохраняете что-либо с ключом, таким как «General/someKey», ключ будет расположен в разделе «%General», а не в разделе «General».
• В соответствии с большинством реализаций сегодня, QSettings будет предполагать, что файл INI закодирован в utf-8. Это означает, что ключи и значения будут декодированы как записи, закодированные в utf-8, и записаны обратно как utf-8.

Совместимость со старыми версиями Qt

Обратите внимание, что это поведение отличается от того, как QSettings работал в версиях Qt до Qt 6. Однако файлы INI, записанные с Qt 5 или ранее, полностью читаемы приложением Qt 6 (если не был установлен ini-кодек, отличный от utf8). Но файлы INI, записанные с Qt 6, будут читаемы только более старыми версиями Qt, если вы установите «iniCodec» на кодек utf-8.

См. также registerFormat() и setPath().

QSettings::ReadFunc

Тип для указателя на функцию со следующим сигнатурой:

bool myReadFunc(QIODevice &device, QSettings::SettingsMap &map);

ReadFunc используется в registerFormat() в качестве указателя на функцию, которая считывает набор пар «ключ-значение». ReadFunc должен прочитать все параметры за один проход и вернуть все параметры в контейнер SettingsMap, который изначально пуст.

См. также WriteFunc и registerFormat().

Перечисление QSettings::Scope

Это перечисление определяет, являются ли параметры специфичными для пользователя или общими для всех пользователей одной системы.

См. также setPath().

QSettings::SettingsMap

Тип для QMap<QString, QVariant>.

См. также registerFormat().

Перечисление QSettings::Status

Возможны следующие значения статуса:

См. также status().

QSettings::WriteFunc

Тип для указателя на функцию со следующим сигнатурой:

bool myWriteFunc(QIODevice &device, const QSettings::SettingsMap &map);

WriteFunc используется в registerFormat() как указатель на функцию, которая записывает набор пар «ключ-значение». WriteFunc вызывается только один раз, поэтому вам нужно вывести параметры за один раз.

См. также ReadFunc и registerFormat().

Документация по методам-членам

[since 5.13] QSettings::QSettings(QSettings::Scope scope, QObject *parent = nullptr)

Создает объект QSettings так же, как и QSettings(QObject *parent), но со заданным scope.

Эта функция была добавлена в Qt 5.13.

См. также QSettings(QObject *parent).

QSettings::QSettings(QObject *parent = nullptr)

Создает объект QSettings для доступа к параметрам приложения и организации, которые были установлены ранее с вызовом QCoreApplication::setOrganizationName(), QCoreApplication::setOrganizationDomain() и QCoreApplication::setApplicationName().

Область действия — QSettings::UserScope, а формат — defaultFormat() (по умолчанию QSettings::NativeFormat). Используйте setDefaultFormat() перед вызовом этого конструктора, чтобы изменить используемый по умолчанию формат.

Код

QSettings settings("Moose Soft", "Facturo-Pro");

эквивалентен

QCoreApplication::setOrganizationName("Moose Soft");
QCoreApplication::setApplicationName("Facturo-Pro");
QSettings settings;

Если QCoreApplication::setOrganizationName() и QCoreApplication::setApplicationName() не были вызваны ранее, объект QSettings не сможет читать или записывать параметры, и status() вернёт AccessError.

Вы должны предоставить как домен (используется по умолчанию на macOS и iOS), так и имя (используется по умолчанию в других местах), хотя код справится, если вы предоставите только одно, которое затем будет использоваться (на всех платформах), что не соответствует обычному названию файла на платформах, для которых это не является стандартным.

См. также QCoreApplication::setOrganizationName(), QCoreApplication::setOrganizationDomain(), QCoreApplication::setApplicationName() и setDefaultFormat().

QSettings::QSettings(const QString &fileName, QSettings::Format format, QObject *parent = nullptr)

Создаёт объект QSettings для доступа к параметрам, хранящимся в файле с именем fileName, с родителем parent. Если файл ещё не существует, он создаётся.

Если format равен QSettings::NativeFormat, значение fileName зависит от платформы. В Unix, fileName — это имя файла INI. На macOS и iOS, fileName — это имя файла .plist . В Windows, fileName — это путь в системном реестре.

Если format равен QSettings::IniFormat, fileName — это имя файла INI.

• QSettings не предоставляет способ чтения записей INI «путь», то есть записей с неэкранированными символами косой черты. (Это связано с тем, что эти записи являются неоднозначными и не могут быть автоматически разрешены.)
• В файлах INI QSettings использует символ @ в качестве метасимвола в некоторых контекстах, чтобы закодировать типы данных Qt (например, @Rect), и поэтому может неправильно интерпретировать его, когда он встречается в чистых INI-файлах.

См. также fileName().

QSettings::QSettings(QSettings::Format format, QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr)

Создает объект QSettings для доступа к настройкам приложения с именем application из организации organization и с родителем parent.

Если scope равен QSettings::UserScope, объект QSettings ищет параметры, специфичные для пользователя, прежде чем обратиться к системным параметрам как к резервному варианту. Если scope равен QSettings::SystemScope, объект QSettings игнорирует параметры, специфичные для пользователя, и предоставляет доступ к системным параметрам.

Если format равен QSettings::NativeFormat, используется родной API для хранения параметров. Если format равен QSettings::IniFormat, используется формат INI.

Если имя приложения не указано, объект QSettings будет обращаться только к организационным расположениям.

QSettings::QSettings(QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr)

Создаёт объект QSettings для доступа к настройкам приложения с именем application из организации organization и с родителем parent.

Если scope равен QSettings::UserScope, объект QSettings сначала ищет настройки пользователя, а затем, в качестве резервного варианта, ищет настройки системы. Если scope равен QSettings::SystemScope, объект QSettings игнорирует настройки пользователя и предоставляет доступ к настройкам системы.

Формат хранения устанавливается в QSettings::NativeFormat (т.е. вызов setDefaultFormat() перед вызовом этого конструктора не имеет эффекта).

Если имя приложения не указано, объект QSettings будет получать доступ только к общеорганизационным местоположениям.

См. также setDefaultFormat().

QSettings::QSettings(const QString &organization, const QString &application = QString(), QObject *parent = nullptr)

Создаёт объект QSettings для доступа к настройкам приложения с именем application из организации organization и с родителем parent.

Пример:

QSettings settings("Moose Tech", "Facturo-Pro");

Область действия устанавливается в QSettings::UserScope, а формат — в QSettings::NativeFormat (т.е. вызов setDefaultFormat() перед вызовом этого конструктора не имеет эффекта).

См. также setDefaultFormat() и Механизм резервного копирования.

[virtual] QSettings::~QSettings()

Уничтожает объект QSettings.

Любые несохранённые изменения в конечном итоге будут записаны в постоянное хранилище.

См. также sync().

QStringList QSettings::allKeys() const

Возвращает список всех ключей, включая подключаемые, которые можно прочитать с помощью объекта QSettings.

Пример:

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"]

Если группа устанавливается с помощью beginGroup(), возвращаются только ключи в группе без префикса группы:

settings.beginGroup("fridge");
keys = settings.allKeys();
// keys: ["color", "size"]

См. также childGroups() и childKeys().

QString QSettings::applicationName() const

Возвращает имя приложения, используемое для хранения настроек.

См. также QCoreApplication::applicationName(), format(), scope() и organizationName().

void QSettings::beginGroup(const QString &prefix)

Добавляет prefix к текущей группе.

Текущая группа автоматически добавляется в качестве префикса ко всем ключам, заданным для QSettings. Кроме того, функции запроса, такие как childGroups(), childKeys() и allKeys(), основаны на группе. По умолчанию группа не установлена.

Группы полезны для того, чтобы не писать одни и те же пути к настройкам снова и снова. Например:

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

Это установит значения трёх настроек:

• mainwindow/size
• mainwindow/fullScreen
• outputpanel/visible

Вызовите endGroup(), чтобы сбросить текущую группу до того состояния, которое было до вызова соответствующей функции beginGroup(). Группы могут быть вложены.

См. также endGroup() и group().

int QSettings::beginReadArray(const QString &prefix)

Добавляет prefix к текущей группе и начинает чтение из массива. Возвращает размер массива.

Пример:

struct Login {
    QString userName;
    QString password;
};
QList<Login> logins;
...

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

Используйте beginWriteArray(), чтобы в первую очередь записать массив.

См. также beginWriteArray(), endArray() и setArrayIndex().

void QSettings::beginWriteArray(const QString &prefix, int size = -1)

Добавляет prefix к текущей группе и начинает запись массива размером size. Если size равно -1 (по умолчанию), он автоматически определяется на основе индексов записанных элементов.

Если у вас много вхождений определённого набора ключей, вы можете использовать массивы, чтобы облегчить себе жизнь. Например, предположим, что вы хотите сохранить переменный список имён пользователей и паролей. Тогда вы можете записать:

struct Login {
    QString userName;
    QString password;
};
QList<Login> logins;
...

QSettings settings;
settings.beginWriteArray("logins");
for (int i = 0; i < logins.size(); ++i) {
    settings.setArrayIndex(i);
    settings.setValue("userName", list.at(i).userName);
    settings.setValue("password", list.at(i).password);
}
settings.endArray();

Сгенерированные ключи будут иметь вид

• logins/size
• logins/1/userName
• logins/1/password
• logins/2/userName
• logins/2/password
• logins/3/userName
• logins/3/password
• ...

Для повторного чтения массива используйте beginReadArray().

См. также beginReadArray(), endArray() и setArrayIndex().

QStringList QSettings::childGroups() const

Возвращает список всех групп ключей верхнего уровня, содержащих ключи, которые можно прочитать с помощью объекта QSettings.

Пример:

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"]

Если группа устанавливается с помощью beginGroup(), возвращаются ключи первого уровня в этой группе без префикса группы.

settings.beginGroup("fridge");
groups = settings.childGroups();
// groups: []

Вы можете перемещаться по всей иерархии настроек, используя childKeys() и childGroups() рекурсивно.

См. также childKeys() и allKeys().

QStringList QSettings::childKeys() const

Возвращает список всех ключей верхнего уровня, которые можно прочитать с помощью объекта QSettings.

Пример:

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"]

Если группа устанавливается с помощью beginGroup(), возвращаются ключи верхнего уровня в этой группе без префикса группы:

settings.beginGroup("fridge");
keys = settings.childKeys();
// keys: ["color", "size"]

Вы можете перемещаться по всей иерархии настроек, используя childKeys() и childGroups() рекурсивно.

См. также childGroups() и allKeys().

void QSettings::clear()

Удаляет все записи в основном расположении, связанном с объектом QSettings.

Записи в резервных расположениях не удаляются.

Если вы хотите удалить только записи в текущей группе, используйте remove("") вместо этого.

См. также remove() и setFallbacksEnabled().

bool QSettings::contains(const QString &key) const

Возвращает true , если существует настройка с именем key; в противном случае возвращает false.

Если группа устанавливается с помощью beginGroup(), key рассматривается как относительный к этой группе.

Обратите внимание, что в Windows реестре и файлах INI ключи регистронезависимы, тогда как в API CFPreferences на macOS и iOS ключи регистрозависимы. Чтобы избежать проблем с переносимостью, см. правила Синтаксиса секции и ключа.

См. также value() и setValue().

[static] QSettings::Format QSettings::defaultFormat()

Возвращает используемый по умолчанию формат файла для хранения настроек для конструктора QSettings(QObject *). Если формат по умолчанию не задан, используется QSettings::NativeFormat.

См. также setDefaultFormat() и format().

void QSettings::endArray()

Закрывает массив, который был начат с помощью beginReadArray() или beginWriteArray().

См. также beginReadArray() и beginWriteArray().

void QSettings::endGroup()

Сбрасывает группу до состояния, которое было до вызова соответствующей функции beginGroup().

Пример:

settings.beginGroup("alpha");
// settings.group() == "alpha"

settings.beginGroup("beta");
// settings.group() == "alpha/beta"

settings.endGroup();
// settings.group() == "alpha"

settings.endGroup();
// settings.group() == ""

См. также beginGroup() и group().

[override virtual protected] bool QSettings::event(QEvent *event)

Переопределяет: QObject::event(QEvent *e).

bool QSettings::fallbacksEnabled() const

Возвращает true , если резервные копии включены; в противном случае возвращает false.

По умолчанию резервные копии включены.

См. также setFallbacksEnabled().

QString QSettings::fileName() const

Возвращает путь, где хранятся настройки, записанные с помощью этого объекта QSettings.

В Windows, если формат — QSettings::NativeFormat, возвращаемое значение — путь в системном реестре, а не путь к файлу.

См. также isWritable() и format().

QSettings::Format QSettings::format() const

Возвращает формат, используемый для хранения настроек.

См. также defaultFormat(), fileName(), scope(), organizationName() и applicationName().

QString QSettings::group() const

Возвращает текущую группу.

См. также beginGroup() и endGroup().

[since 5.10] bool QSettings::isAtomicSyncRequired() const

Возвращает true, если QSettings разрешено только атомарное сохранение и перезагрузка (синхронизация) настроек. Возвращает false, если разрешено сохранять содержимое настроек непосредственно в конфигурационный файл.

По умолчанию true.

Эта функция была добавлена в Qt 5.10.

См. также setAtomicSyncRequired() и QSaveFile.

bool QSettings::isWritable() const

Возвращает true, если настройки можно записать с помощью этого объекта QSettings; в противном случае возвращает false.

Одна из причин, по которой isWritable() может вернуть false, — QSettings работает с файлом только для чтения.

См. также fileName(), status() и sync().

QString QSettings::organizationName() const

Возвращает имя организации, используемое для хранения настроек.

См. также QCoreApplication::organizationName(), format(), scope() и applicationName().

[static] QSettings::Format QSettings::registerFormat(const QString &extension, QSettings::ReadFunc readFunc, QSettings::WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive)

Регистрирует пользовательский формат хранения. При успехе возвращает специальное значение Format, которое затем может быть передано конструктору QSettings. При ошибке возвращает InvalidFormat.

extension — расширение файла, связанное с форматом (без '.').

Параметры readFunc и writeFunc — указатели на функции, которые читают и записывают набор пар «ключ-значение». Параметр QIODevice для функций чтения и записи всегда открывается в двоичном режиме (то есть без флага QIODevice::Text).

Параметр caseSensitivity определяет, чувствительны ли ключи к регистру. Это имеет значение при поиске значений с помощью QSettings. По умолчанию регистрозависимые.

По умолчанию, если вы используете один из конструкторов, которые работают с именем организации и именем приложения, места в файловой системе используются такие же, как и для IniFormat. Используйте setPath(), чтобы указать другие места.

Пример:

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

    ...
}

Примечание: Эта функция безопасна для потоков.

См. также setPath().

void QSettings::remove(const QString &key)

Удаляет настройку key и любые поднастройки key.

Пример:

QSettings settings;
settings.setValue("ape");
settings.setValue("monkey", 1);
settings.setValue("monkey/sea", 2);
settings.setValue("monkey/doe", 4);

settings.remove("monkey");
QStringList keys = settings.allKeys();
// keys: ["ape"]

Обратите внимание, что если одно из резервных мест содержит настройку с тем же ключом, эта настройка будет видна после вызова remove().

Если key — пустая строка, удаляются все ключи в текущей группе group(). Например:

QSettings settings;
settings.setValue("ape");
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"]

Обратите внимание, что в Windows реестре и INI-файлах ключи нечувствительны к регистру, а в API CFPreferences на macOS и iOS ключи чувствительны к регистру. Чтобы избежать проблем с переносимостью, см. правила Синтаксиса разделов и ключей.

См. также setValue(), value() и contains().

QSettings::Scope QSettings::scope() const

Возвращает область, используемую для хранения настроек.

См. также format(), organizationName() и applicationName().

void QSettings::setArrayIndex(int i)

Устанавливает текущий индекс массива в i. Вызовы функций, таких как setValue(), value(), remove() и contains(), будут работать с элементом массива с этим индексом.

Необходимо вызвать beginReadArray() или beginWriteArray() перед вызовом этой функции.

[since 5.10] void QSettings::setAtomicSyncRequired(bool enable)

Настраивает необходимость атомарного сохранения и перезагрузки (синхронизации) настроек QSettings. Если аргумент enable равен true (по умолчанию), sync() будет выполнять только атомарные операции синхронизации. Если это невозможно, sync() завершится ошибкой, и status() будет содержать код ошибки.

Установление этого свойства в false позволит QSettings напрямую записывать в конфигурационный файл и игнорировать любые ошибки, связанные с блокировкой файла при одновременных попытка записи других процессов. Из-за возможной потери данных этот вариант следует использовать с осторожностью, но он необходим в определённых ситуациях, например, в случае конфигурационного файла QSettings::IniFormat, который находится в каталоге, который не имеет прав на запись, или в NTFS Alternate Data Streams.

Для получения дополнительной информации об этой функции обратитесь к QSaveFile.

Эта функция была добавлена в Qt 5.10.

См. также isAtomicSyncRequired() и QSaveFile.

[static] void QSettings::setDefaultFormat(QSettings::Format format)

Устанавливает формат файла по умолчанию на заданный format, который используется для хранения настроек в конструкторе QSettings(QObject *).

Если формат по умолчанию не задан, используется QSettings::NativeFormat. Смотрите документацию для используемого конструктора QSettings для получения информации о том, будет ли этот конструктор игнорировать эту функцию.

См. также defaultFormat() и format().

void QSettings::setFallbacksEnabled(bool b)

Устанавливает включение резервных копий в b.

По умолчанию резервные копии включены.

См. также fallbacksEnabled().

[static] void QSettings::setPath(QSettings::Format format, QSettings::Scope scope, const QString &path)

Устанавливает путь, используемый для хранения настроек для заданного format и scope, в path. format может быть пользовательским форматом.

Таблица ниже обобщает значения по умолчанию:

Пути по умолчанию UserScope на Unix, macOS и iOS ($HOME/.config или $HOME/Settings) могут быть переопределены пользователем путём установки переменной среды XDG_CONFIG_HOME. Пути по умолчанию SystemScope на Unix, macOS и iOS (/etc/xdg) можно переопределить при сборке библиотеки Qt, используя флаг configure скрипта -sysconfdir (подробности см. в QLibraryInfo).

Установка путей NativeFormat в Windows, macOS и iOS не оказывает никакого эффекта.

См. также registerFormat().

void QSettings::setValue(const QString &key, const QVariant &value)

Устанавливает значение параметра key в value. Если key уже существует, предыдущее значение перезаписывается.

Обратите внимание, что в реестре Windows и INI-файлах ключи нечувствительны к регистру, тогда как в API CFPreferences на macOS и iOS ключи чувствительны к регистру. Чтобы избежать проблем с переносимостью, см. правила Синтаксиса раздела и ключа.

Пример:

QSettings settings;
settings.setValue("interval", 30);
settings.value("interval").toInt();     // returns 30

settings.setValue("interval", 6.55);
settings.value("interval").toDouble();  // returns 6.55

См. также value(), remove() и contains().

QSettings::Status QSettings::status() const

Возвращает код состояния, указывающий на первую ошибку, с которой столкнулась QSettings, или QSettings::NoError, если ошибок не было.

Обратите внимание, что QSettings откладывает выполнение некоторых операций. По этой причине вы можете вызвать sync(), чтобы убедиться, что данные, хранящиеся в QSettings, записаны на диск перед вызовом status().

См. также sync().

void QSettings::sync()

Записывает любые несохраненные изменения в постоянное хранилище и перезагружает любые параметры, которые были изменены в это время другой программой.

Эта функция вызывается автоматически из деструктора QSettings и циклом событий через равные промежутки времени, поэтому обычно вам не нужно вызывать её самостоятельно.

См. также status().

QVariant QSettings::value(const QString &key, const QVariant &defaultValue = QVariant()) const

Возвращает значение параметра key. Если параметр не существует, возвращает defaultValue.

Если значение по умолчанию не указано, возвращается значение по умолчанию QVariant.

Обратите внимание, что в реестре Windows и INI-файлах ключи нечувствительны к регистру, тогда как в API CFPreferences на macOS и iOS ключи чувствительны к регистру. Чтобы избежать проблем с переносимостью, см. правила Синтаксиса раздела и ключа.

Пример:

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 0

См. также setValue(), contains() и remove().