Класс QSettings

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QVariant и типы GUI

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

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

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

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

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

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

Синтаксис секций и ключей

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

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

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

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

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

    settings.beginGroup("mainwindow");
    settings.setValue("size", win->size());
    settings.setValue("fullScreen", win->isFullScreen());
    settings.endGroup();

    settings.beginGroup("outputpanel");
    settings.setValue("visible", panel->isVisible());
    settings.endGroup();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Восстановление состояния 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 и iOS, если формат файла — NativeFormat, по умолчанию используются следующие файлы:

1. $HOME/Library/Preferences/com.MySoft.Star Runner.plist
2. $HOME/Library/Preferences/com.MySoft.plist
3. /Library/Preferences/com.MySoft.Star Runner.plist
4. /Library/Preferences/com.MySoft.plist

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

1. HKEY_CURRENT_USER\Software\MySoft\Star Runner
2. HKEY_CURRENT_USER\Software\MySoft\OrganizationDefaults
3. HKEY_LOCAL_MACHINE\Software\MySoft\Star Runner
4. HKEY_LOCAL_MACHINE\Software\MySoft\OrganizationDefaults

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

Доступ к общим настройкам реестра в 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) снова изменяет это правило, но только для формата Native (файлы plist).

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

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

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

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

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

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

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

  pos = @Point(100 100)

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

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

  windir = C:\Windows

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

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

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

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

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

QSettings::ReadFunc

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

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

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

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

enum QSettings::Scope

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

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

QSettings::SettingsMap

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

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

enum QSettings::Status

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

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

QSettings::WriteFunc

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

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

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

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

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

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

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

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

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

QSettings::QSettings(QObject *parent = nullptr)

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

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

Код

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

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

См. также setDefaultFormat() и Механизм обращений к резервным вариантам.

[virtual] QSettings::~QSettings()

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

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

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

QStringList QSettings::allKeys() const

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

Пример:

QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);

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

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

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

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

QString QSettings::applicationName() const

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

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

void QSettings::beginGroup(const QString &prefix)

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

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

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

settings.beginGroup("mainwindow");
settings.setValue("size", win->size());
settings.setValue("fullScreen", win->isFullScreen());
settings.endGroup();

settings.beginGroup("outputpanel");
settings.setValue("visible", panel->isVisible());
settings.endGroup();

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

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

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

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

int QSettings::beginReadArray(const QString &prefix)

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

Пример:

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

QSettings settings;
int size = settings.beginReadArray("logins");
for (int i = 0; i < size; ++i) {
    settings.setArrayIndex(i);
    Login login;
    login.userName = settings.value("userName").toString();
    login.password = settings.value("password").toString();
    logins.append(login);
}
settings.endArray();

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

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

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

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

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

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

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

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

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

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

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

QStringList QSettings::childGroups() const

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

Пример:

QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);

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

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

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

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

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

QStringList QSettings::childKeys() const

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

Пример:

QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);

QStringList keys = settings.childKeys();
// keys: ["sofa", "tv"]

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

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

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

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

void QSettings::clear()

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

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

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

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

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

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

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

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

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

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

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

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

void QSettings::endArray()

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

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

void QSettings::endGroup()

Сбрасывает группу до её состояния перед соответствующим вызовом beginGroup().

Пример:

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

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

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

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

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

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

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

bool QSettings::fallbacksEnabled() const

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

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

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

QString QSettings::fileName() const

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

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

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

QSettings::Format QSettings::format() const

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

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

QString QSettings::group() const

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

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

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

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

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

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

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

bool QSettings::isWritable() const

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

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

Предупреждение: Эта функция не является идеально надёжной, так как права доступа к файлам могут измениться в любой момент.

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

QString QSettings::organizationName() const

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

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

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

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

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

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

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

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

Пример:

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

int main(int argc, char *argv[])
{
    const QSettings::Format XmlFormat =
            QSettings::registerFormat("xml", readXmlFile, writeXmlFile);

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

    ...
}

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

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

void QSettings::remove(const QString &key)

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

Пример:

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

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

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

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

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

settings.beginGroup("monkey");
settings.remove("");
settings.endGroup();

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

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

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

QSettings::Scope QSettings::scope() const

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

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

void QSettings::setArrayIndex(int i)

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

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

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

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

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

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

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

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

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

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

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

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

void QSettings::setFallbacksEnabled(bool b)

Устанавливает возможность использования резервных копий в b.

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

QSettings::Status QSettings::status() const

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

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

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

void QSettings::sync()

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

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

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

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

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

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

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

Пример:

QSettings settings;
settings.setValue("animal/snake", 58);
settings.value("animal/snake", 1024).toInt();   // returns 58
settings.value("animal/zebra", 1024).toInt();   // returns 1024
settings.value("animal/zebra").toInt();         // returns 0

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