Класс QSettings

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

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

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

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

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

Типы публичного интерфейса

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

• 32 публичных функции, унаследованные от QObject

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

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

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

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

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

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

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

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

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

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

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

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

Основные методы использования

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QVariant и типы GUI

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Механизм подстановки

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

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

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

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

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

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

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

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

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

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

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

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

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

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

enum QSettings::Format

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

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

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

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

  pos = @Point(100 100)

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

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

  windir = C:\Windows

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

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

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

typedef QSettings::ReadFunc

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

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

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

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

enum QSettings::Scope

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

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

typedef QSettings::SettingsMap

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

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

enum QSettings::Status

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

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

typedef QSettings::WriteFunc

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

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

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

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

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

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

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

Пример:

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

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

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

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(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(const QString &fileName, QSettings::Format format, QObject *parent = nullptr)

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

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

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

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

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

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

QSettings::QSettings(QObject *parent = nullptr)

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

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

Код

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

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

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

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

В macOS и iOS, если для организации указано имя и домен в интернете, предпочтительным является домен по сравнению с именем. На других платформах предпочтительным является имя по сравнению с доменом.

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

[virtual] QSettings::~QSettings()

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

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

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

QStringList QSettings::allKeys() const

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

Пример:

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

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

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

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

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

QString QSettings::applicationName() const

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

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

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

void QSettings::beginGroup(const QString &prefix)

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

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

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

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

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

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

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

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

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

int QSettings::beginReadArray(const QString &prefix)

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

QStringList QSettings::childGroups() const

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

Пример:

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

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

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

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

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

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

QStringList QSettings::childKeys() const

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

Пример:

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

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

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

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

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

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

void QSettings::clear()

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

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

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

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

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

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

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

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

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

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

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

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

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

void QSettings::endArray()

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

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

void QSettings::endGroup()

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

Пример:

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

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

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

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

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

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

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

bool QSettings::fallbacksEnabled() const

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

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

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

QString QSettings::fileName() const

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

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

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

QSettings::Format QSettings::format() const

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

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

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

QString QSettings::group() const

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

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

QTextCodec *QSettings::iniCodec() const

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

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

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

bool QSettings::isAtomicSyncRequired() const

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

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

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

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

bool QSettings::isWritable() const

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

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

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

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

QString QSettings::organizationName() const

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

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

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

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

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

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

Параметры readFunc и writeFunc — указатели на функции, которые читают и записывают набор пар «ключ-значение». Параметр QIODevice для функций чтения и записи всегда открывается в двоичном режиме (т. е. без флага 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)

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

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

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

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

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

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

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

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

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

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

void QSettings::setFallbacksEnabled(bool b)

Устанавливает, включены ли резервные копии, в значение b.

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

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

void QSettings::setIniCodec(QTextCodec *codec)

Устанавливает кодек для доступа к файлам INI (включая .conf файлы в Unix) в codec. Кодек используется для декодирования любых данных, считываемых из файла INI, и для кодирования любых данных, записываемых в файл. По умолчанию кодек не используется, а символы, не являющиеся ASCII, кодируются с помощью стандартных последовательностей экранирования INI.

Предупреждение: Кодек должен быть установлен сразу после создания объекта QSettings, перед доступом к любым данным.

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

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

void QSettings::setIniCodec(const char *codecName)

Это перегруженная функция.

Устанавливает кодек для доступа к файлам INI (включая .conf файлы в Unix) на QTextCodec для кодировки, указанной в codecName. Распространенные значения для codecName включают "ISO 8859-1", "UTF-8" и "UTF-16". Если кодировка не распознана, ничего не происходит.

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

См. также QTextCodec::codecForName().

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

QSettings::Status QSettings::status() const

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

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

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

void QSettings::sync()

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

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

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

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

Возвращает значение для настройки key. Если настройка не существует, возвращает defaultValue.

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

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

Пример:

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

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