Класс QSettings

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

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

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

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

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

Общественные типы

Общедоступные функции

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

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

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

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

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

QSettings's API основан на 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. Другими словами, нет функций toColor(), toImage(), или toPixmap() в QVariant.

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

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() и qRegisterMetaTypeStreamOperators(), могут храниться с помощью 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 можно экспериментировать с различными расположениями настроек и с включенным или выключенным механизмом обратной совместимости.

Восстановление состояния приложения GUI

QSettings часто используется для хранения состояния приложения GUI. Следующий пример демонстрирует, как использовать 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 10.2 и 10.3 по умолчанию используются эти файлы:

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, Пример редактора настроек и Пример приложения.

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

перечисление 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, закодированные в Latin-1, но генерировать файлы в чистом ASCII, где значения, не являющиеся ASCII, кодируются с использованием стандартных последовательностей экранирования INI. Чтобы сделать файлы INI более читаемыми (но потенциально менее совместимыми), вызовите setIniCodec().

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

typedef QSettings::ReadFunc

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

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

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

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

enum QSettings::Scope

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

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

typedef QSettings::SettingsMap

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

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

enum QSettings::Status

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

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

typedef QSettings::WriteFunc

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QString QSettings::group() const

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

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

QTextCodec *QSettings::iniCodec() const

Возвращает кодек, используемый для доступа к файлам INI. По умолчанию кодек не используется, поэтому возвращается nullptr.

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

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

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

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

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

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

    ...
}

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

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

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

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

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

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

void QSettings::setArrayIndex(int i)

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

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

void QSettings::setAtomicSyncRequired(bool enable)

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

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

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

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

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

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

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

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

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

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

void QSettings::setFallbacksEnabled(bool b)

Устанавливает, включены ли обратные ссылки на b.

По умолчанию, обратные ссылки включены.

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

void QSettings::setIniCodec(QTextCodec *codec)

Устанавливает кодек для доступа к файлам INI (включая .conf файлы на Unix) в codec. Кодек используется для декодирования любой данных, которые читаются из файла INI, и для кодирования любых данных, которые записываются в файл. По умолчанию, кодек не используется, а символы, отличные от ASCII, кодируются с помощью стандартных последовательностей эскейпов INI.

Предупреждение: Кодек должен быть установлен сразу после создания объекта QSettings, перед доступом к любым данным.

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

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

void QSettings::setIniCodec(const char *codecName)

Это перегруженная функция.

Устанавливает кодек для доступа к файлам INI (включая .conf файлы на Unix) на QTextCodec для кодировки, указанной в codecName. Общие значения для codecName включают "ISO 8859-1", "UTF-8" и "UTF-16". Если кодировка не распознана, ничего не происходит.

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

См. также QTextCodec::codecForName().

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

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

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