Класс QSettings

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

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

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

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

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

Общие типы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QVariant и типы GUI

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void MainWindow::writeSettings()
{
    QSettings settings("Moose Soft", "Clipper");

    settings.beginGroup("MainWindow");
    settings.setValue("size", size());
    settings.setValue("pos", pos());
    settings.endGroup();
}

void MainWindow::readSettings()
{
    QSettings settings("Moose Soft", "Clipper");

    settings.beginGroup("MainWindow");
    resize(settings.value("size", QSize(400, 400)).toSize());
    move(settings.value("pos", QPoint(200, 200)).toPoint());
    settings.endGroup();
}

См. Геометрия окна для обсуждения того, почему лучше вызывать QWidget::resize() и QWidget::move() вместо QWidget::setGeometry() для восстановления геометрии окна.

Функции readSettings() и writeSettings() должны вызываться из конструктора главного окна и обработчика события закрытия следующим образом:

MainWindow::MainWindow()
{
    ...
    readSettings();
}

void MainWindow::closeEvent(QCloseEvent *event)
{
    if (userReallyWantsToQuit()) {
        writeSettings();
        event->accept();
    } else {
        event->ignore();
    }
}

См. пример Application для автономного примера, использующего QSettings.

Доступ к настройкам из нескольких потоков или процессов одновременно

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

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

Обратите внимание, что sync() импортирует изменения, внесённые другими процессами (кроме записи изменений из этого объекта QSettings).

Плаформенно-специфические замечания

Расположения, где хранятся настройки приложения

Как упоминалось в разделе Механизм падения по умолчанию, QSettings хранит настройки приложения вплоть до четырех мест, в зависимости от того, являются ли настройки специфичными для пользователя или системы, и являются ли они специфичными для приложения или организации. Для простоты мы предполагаем, что организация называется MySoft, а приложение — Star Runner.

В системах Unix, если формат файла — NativeFormat, по умолчанию используются следующие файлы:

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

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

В версиях macOS 10.2 и 10.3 по умолчанию используются эти файлы:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

Доступ к общим настройкам реестра в Windows

В Windows возможно, чтобы ключ имел как значение, так и подключаемые ключи. Его значение по умолчанию доступно с использованием "Default" или "." вместо подключаемого ключа:

settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy", "Milkyway");
settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Sun", "OurStar");
settings.value("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Default"); // returns "Milkyway"

На платформах, отличных от Windows, "Default" и "." будут обрабатываться как обычные подключаемые ключи.

Ограничения платформ

Хотя QSettings пытается сгладить различия между различными поддерживаемыми платформами, все же есть несколько различий, о которых вам следует знать при переносе вашего приложения:

• Системный реестр Windows имеет следующие ограничения: подключаемый ключ не может превышать 255 символов, значение записи не может превышать 16 383 символов, и все значения ключа не могут превышать 65 535 символов. Один из способов обойти эти ограничения — хранить настройки с использованием IniFormat вместо NativeFormat.
• В Windows, когда используется системный реестр Windows, QSettings не сохраняет исходный тип значения. Поэтому тип значения может измениться при установке нового значения. Например, значение типа REG_EXPAND_SZ изменится на REG_SZ.
• В macOS и iOS allKeys() вернет некоторые дополнительные ключи для глобальных настроек, которые применяются ко всем приложениям. Эти ключи можно прочитать с помощью value(), но их нельзя изменить, только затенять. Вызов setFallbacksEnabled(false) скроет эти глобальные настройки.
• В macOS и iOS API CFPreferences, используемый QSettings, ожидает доменные имена интернета, а не имена организаций. Для обеспечения единообразного API QSettings получает псевдоним доменного имени из имени организации (если имя организации уже не является доменным именем, например OpenOffice.org). Алгоритм добавляет ".com" к названию компании и заменяет пробелы и другие недопустимые символы дефисами. Если вы хотите указать другое доменное имя, вызовите QCoreApplication::setOrganizationDomain(), QCoreApplication::setOrganizationName() и QCoreApplication::setApplicationName() в вашей функции main(), а затем используйте конструктор QSettings по умолчанию. Другое решение — использование препроцессорных директив, например:

  #ifdef Q_OS_MAC
      QSettings settings("grenoullelogique.fr", "Squash");
  #else
      QSettings settings("Grenoulle Logique", "Squash");
  #endif

• В macOS разрешения на доступ к настройкам, не принадлежащим текущему пользователю (т.е. SystemScope), изменились с версии 10.7 (Lion). До этой версии пользователи с правами администратора могли получить к ним доступ. Для 10.7 и 10.8 (Mountain Lion) доступ только у root. Однако в 10.9 (Mavericks) это правило меняется вновь, но только для формата native (файлы plist).

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

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

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

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

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

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

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

  pos = @Point(100 100)

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

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

  windir = C:\Windows

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

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

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

typedef QSettings::ReadFunc

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

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

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

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

enum QSettings::Scope

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

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

typedef QSettings::SettingsMap

Тип-синоним для QMap<QString, QVariant>.

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

enum QSettings::Status

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

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

typedef QSettings::WriteFunc

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

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

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

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

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

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

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

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

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

QSettings::QSettings(QObject *parent = nullptr)

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

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

Код

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

[virtual] QSettings::~QSettings()

Удаляет объект QSettings.

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

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

QStringList QSettings::allKeys() const

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

Пример:

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

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

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

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

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

QString QSettings::applicationName() const

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

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

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

void QSettings::beginGroup(const QString &prefix)

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

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

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

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

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

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

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

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

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

int QSettings::beginReadArray(const QString &prefix)

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

Чтобы прочитать массив, используйте beginReadArray().

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

QStringList QSettings::childGroups() const

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

Пример:

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

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

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

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

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

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

QStringList QSettings::childKeys() const

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

Пример:

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

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

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

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

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

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

void QSettings::clear()

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

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

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

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

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

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

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

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

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

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

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

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

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

void QSettings::endArray()

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

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

void QSettings::endGroup()

Возвращает группу к её значению до вызова соответствующей функции beginGroup().

Пример:

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

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

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

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

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

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

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

bool QSettings::fallbacksEnabled() const

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

По умолчанию обратная совместимость включена.

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

QString QSettings::fileName() const

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

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

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

QSettings::Format QSettings::format() const

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

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

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

QString QSettings::group() const

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

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

QTextCodec *QSettings::iniCodec() const

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

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

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

bool QSettings::isAtomicSyncRequired() const

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

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

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

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

bool QSettings::isWritable() const

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

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

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

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

QString QSettings::organizationName() const

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

    ...
}

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

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

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

void QSettings::remove(const QString &key)

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

Пример:

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

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

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

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

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

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

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

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

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

QSettings::Scope QSettings::scope() const

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

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

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

void QSettings::setArrayIndex(int i)

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

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

void QSettings::setAtomicSyncRequired(bool enable)

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

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

См. 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 escape-последовательностей.

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

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

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

void QSettings::setIniCodec(const char *codecName)

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

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

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

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

[static] void QSettings::setPath(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().