Класс QSettings

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

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

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

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

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

Общие типы

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

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

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

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

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

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

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

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

Базовое использование

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QVariant и типы GUI

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Механизм обратного поиска

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

1. Место хранения настроек для конкретного пользователя приложения Star Runner
2. Место хранения настроек для всех приложений MySoft
3. Место хранения настроек для всех пользователей приложения Star Runner
4. Место хранения настроек для всех приложений MySoft

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  pos = @Point(100 100)

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

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

  windir = C:\Windows

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

• Формат INI имеет жёсткие ограничения на синтаксис ключа. Qt обходит это, используя % в качестве символа экранирования в ключах. Кроме того, если вы сохраняете параметр верхнего уровня (ключ без слешей, например, "someKey"), он будет отображаться в разделе "General" файла INI. Чтобы избежать перезаписи других ключей, если вы сохраняете что-либо с ключом, таким как "General/someKey", ключ будет находиться в разделе "%General", а не в разделе "General".
• Следуя философии о том, что мы должны быть либеральными в отношении того, что принимаем, и консервативными в отношении того, что генерируем, QSettings будет принимать файлы INI с кодировкой Latin-1, но генерировать чистые ASCII-файлы, где значения, не являющиеся ASCII, кодируются с использованием стандартных последовательностей экранирования INI. Для повышения читабельности файлов INI (но потенциально снижения совместимости) вызовите setIniCodec().

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

typedef QSettings::ReadFunc

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

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

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

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

enum QSettings::Scope

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

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

typedef QSettings::SettingsMap

Псевдоним для QMap<QString, QVariant>.

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

enum QSettings::Status

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

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

typedef QSettings::WriteFunc

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

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

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

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

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

QSettings::QSettings(QSettings::Scope scope, QObject *parent = nullptr)

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

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

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

QSettings::QSettings(QObject *parent = nullptr)

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

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

Код

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

[virtual] QSettings::~QSettings()

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

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

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

QStringList QSettings::allKeys() const

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

Пример:

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

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

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

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

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

QString QSettings::applicationName() const

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

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

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

void QSettings::beginGroup(const QString &prefix)

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

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

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

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

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

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

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

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

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

int QSettings::beginReadArray(const QString &prefix)

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

QStringList QSettings::childGroups() const

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

Пример:

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

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

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

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

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

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

QStringList QSettings::childKeys() const

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

Пример:

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

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

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

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

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

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

void QSettings::clear()

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

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

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

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

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

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

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

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

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

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

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

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

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

void QSettings::endArray()

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

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

void QSettings::endGroup()

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

Пример:

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

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

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

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

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

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

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

bool QSettings::fallbacksEnabled() const

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

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

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

QString QSettings::fileName() const

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

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

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

QSettings::Format QSettings::format() const

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

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

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

QString QSettings::group() const

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

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

QTextCodec *QSettings::iniCodec() const

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

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

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

bool QSettings::isAtomicSyncRequired() const

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

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

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

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

bool QSettings::isWritable() const

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

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

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

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

QString QSettings::organizationName() const

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

    ...
}

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

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

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

void QSettings::remove(const QString &key)

Удаляет настройку key и все вложенные настройки key.

Пример:

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

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

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

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

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

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

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

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

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

QSettings::Scope QSettings::scope() const

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

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

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

void QSettings::setArrayIndex(int i)

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

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

void QSettings::setAtomicSyncRequired(bool enable)

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

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

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

В таблице ниже приведены значения по умолчанию:

Пути по умолчанию для 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().