Класс QSettings

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

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

Примечание: Все функции в этом классе являются повторно входящими.

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

• registerFormat(const QString &extension, QSettings::ReadFunc readFunc, QSettings::WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity)

Публичные типы

Публичные функции

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

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

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

Пользователи обычно ожидают, что приложение будет запоминать свои настройки (размеры и позиции окон, параметры и т. д.) между сеансами. Эта информация часто хранится в системном реестре в 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. Всегда ссылайтесь на тот же ключ с тем же регистром. Например, если вы ссылаетесь на ключ как на «шрифты текста» в одном месте кода, не ссылайтесь на него как на «Шрифты текста» где-то еще.
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("size", size());
    settings.setValue("pos", pos());
    settings.endGroup();
}

void MainWindow::readSettings()
{
    QSettings settings("Moose Soft", "Clipper");

    settings.beginGroup("MainWindow");
    resize(settings.value("size", QSize(400, 400)).toSize());
    move(settings.value("pos", QPoint(200, 200)).toPoint());
    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

Примечание: Если XDG_CONFIG_DIRS не задано, используется значение по умолчанию /etc/xdg.

В 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

Примечание: В Windows для 32-битных программ, работающих в режиме WOW64, настройки хранятся в следующем пути реестра: HKEY_LOCAL_MACHINE\Software\WOW6432node.

Если формат файла — 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

Примечание: Если XDG_CONFIG_DIRS не задано, используется значение по умолчанию /etc/xdg.

В 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.

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

enum QSettings::Format

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

Формат 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 textcodec.

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

QSettings::ReadFunc

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

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

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

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

enum QSettings::Scope

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

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

QSettings::SettingsMap

Тип указателя на QMap<QString, QVariant>.

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

enum 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.

Предупреждение: Эта функция предоставляется для удобства. Она хорошо работает для доступа к файлам INI или .plist созданным Qt, но может завершиться неудачей для некоторых синтаксисов, найденных в таких файлах, созданных другими программами. В частности, обратите внимание на следующие ограничения:

• 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 не имеет эффекта.

Предупреждение: Данная функция не влияет на существующие объекты QSettings.

См. также 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().