Класс QSettings

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

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

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

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

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

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

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

• 31 public functions inherited from QObject

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QVariant и типы GUI

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Механизм падения

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

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

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

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

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

Давайте посмотрим на пример:

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

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

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

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

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

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

Восстановление состояния приложения 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 безопасно использовать из разных процессов (которые могут представлять собой разные экземпляры вашего приложения, работающие одновременно, или разные приложения целиком), для чтения и записи в одни и те же системные расположения. Она использует консультационную блокировку файлов и интеллектуальный алгоритм слияния для обеспечения целостности данных. Обратите внимание, что 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. /etc/xdg/MySoft/Star Runner.conf
4. /etc/xdg/MySoft.conf

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

В BlackBerry используется только один файл (см. Ограничения платформы). Если формат файла — 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. /etc/xdg/MySoft/Star Runner.ini
4. /etc/xdg/MySoft.ini

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

1. CSIDL_APPDATA\MySoft\Star Runner.ini
2. CSIDL_APPDATA\MySoft.ini
3. CSIDL_COMMON_APPDATA\MySoft\Star Runner.ini
4. CSIDL_COMMON_APPDATA\MySoft.ini

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

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

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

В BlackBerry используется только один файл (см. Ограничения платформы). Если формат файла — 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.
• В 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).
• На платформе BlackBerry приложения работают в песочнице. Им запрещено читать или писать за пределами этой песочницы. Это влечёт за собой следующие ограничения:
  • Поскольку существует только один scope, он просто игнорируется, т.е. нет различия между SystemScope и UserScope.
  • Механизм обратного вызова Fallback Mechanism не применяется, т.е. рассматривается только одно местоположение.
  • Не рекомендуется устанавливать и использовать пользовательские пути к файлам.

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

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

enum QSettings::Format

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

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

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

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

  pos = @Point(100 100)

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

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

  windir = C:\Windows

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

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

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

typedef QSettings::ReadFunc

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

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

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

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

enum QSettings::Scope

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

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

typedef QSettings::SettingsMap

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

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

enum QSettings::Status

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

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

typedef QSettings::WriteFunc

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

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

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

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QSettings::QSettings(QObject *parent = Q_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()

Уничтожает объект 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.

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

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

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

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

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

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

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

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

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

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

Переопределена из QObject::event().

bool QSettings::fallbacksEnabled() const

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

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

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

QString QSettings::fileName() const

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

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

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

Формат QSettings::format() const

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

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

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

QString QSettings::group() const

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

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

QTextCodec *QSettings::iniCodec() const

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

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

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

bool QSettings::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::registerFormat(const QString &extension, ReadFunc readFunc, 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().

Scope QSettings::scope() const

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

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

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

void QSettings::setArrayIndex(int i)

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

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

[static] void QSettings::setDefaultFormat(Формат 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 escape-последовательностей.

Предупреждение: Кодек необходимо установить сразу после создания объекта 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(Формат format, Область scope, const QString &path)

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

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

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