Класс QSettings

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

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

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

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

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

Общие типы

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

• 32 открытые функции унаследованы от QObject

Статические открытые члены

• 11 статических открытых членов унаследованы от QObject

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

• 9 защищённых функций унаследованы от QObject

Дополнительные унаследованные члены

• 1 свойство унаследовано от QObject
• 1 открытый слот унаследован от QObject
• 2 сигнала унаследованы от QObject
• 9 защищённых функций унаследованы от QObject

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

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

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

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

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

enum 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(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() и Fallback Mechanism.

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 будет обращаться только к расположениям организации (см. locations).

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

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 будет обращаться только к расположениям организации (см. locations).

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

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

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. По умолчанию кодек не используется, поэтому возвращается указатель null.

Эта функция была добавлена в 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 для функций read и write всегда открывается в двоичном режиме (то есть без флага 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 Alternate Data Streams.

См. 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().