Класс QSettings

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

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

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

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

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

Открытые типы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Всегда ссылайтесь на один и тот же ключ, используя один и тот же регистр. Например, если вы ссылаетесь на ключ как «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");

Пример 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. для каждого каталога <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, содержащие косые или обратные косые черты; вам следует использовать native 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(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 будет получать доступ только к местоположениям организации.

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

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.

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

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

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

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

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

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

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

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

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

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

Эта функция была добавлена в 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, кодируются с помощью стандартных escape-последовательностей 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(Формат 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().