QSettings Class

멤버 함수 문서

설정 값을 반환합니다 key. 설정이 존재하지 않으면 defaultValue 을 반환합니다.

기본값을 지정하지 않으면 기본값 QVariant 이 반환됩니다.

Windows 레지스트리 및 INI 파일은 대소문자를 구분하지 않는 키를 사용하는 반면, macOS 및 iOS의 CFPreferences API는 대소문자를 구분하는 키를 사용한다는 점에 유의하세요. 이식성 문제를 방지하려면 Section and Key Syntax 규칙을 참조하세요.

예시:

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()도 참조하세요 .

[explicit] QSettings::QSettings(QObject *parent = nullptr)

QCoreApplication::setOrganizationName(), QCoreApplication::setOrganizationDomain() 및 QCoreApplication::setApplicationName()를 호출하여 이전에 설정한 애플리케이션 및 조직의 설정에 액세스하기 위한 QSettings 개체를 구성합니다.

범위는 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()도 참조하세요 .

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

QSettings(QObject *부모)와 동일한 방식으로, 지정된 scope 을 사용하여 QSettings 객체를 구성합니다.

QSettings(QObject *부모)도 참조하십시오 .

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

fileName 이라는 파일에 저장된 설정에 액세스하기 위한 QSettings 객체를 parent 을 부모로 하여 생성합니다. 파일이 아직 존재하지 않으면 파일이 생성됩니다.

format 가 QSettings::NativeFormat 인 경우 fileName 의 의미는 플랫폼에 따라 다릅니다. Unix에서 fileName 는 INI 파일의 이름입니다. macOS 및 iOS에서 fileName 는 .plist 파일의 이름입니다. Windows에서 fileName 는 시스템 레지스트리의 경로입니다.

format 가 QSettings::IniFormat 인 경우 fileName 는 INI 파일의 이름입니다.

• QSettings는 INI "경로" 항목, 즉 이스케이프되지 않은 슬래시 문자가 있는 항목을 읽을 수 있는 방법을 제공하지 않습니다. (이러한 항목은 모호하고 자동으로 확인할 수 없기 때문입니다.)
• INI 파일에서 QSettings는 일부 컨텍스트에서 @ 문자를 메타 문자로 사용하여 Qt 특정 데이터 유형(예: @Rect)을 인코딩하므로 순수한 INI 파일에서 발생하면 잘못 해석될 수 있습니다.

fileName()도 참조하십시오 .

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

organization 이라는 조직에서 application 이라는 애플리케이션의 설정에 액세스하고 parent 을 부모로 하는 QSettings 개체를 구성합니다.

예제:

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

범위는 QSettings::UserScope 로 설정되고 형식은 QSettings::NativeFormat 으로 설정됩니다(즉, 이 생성자를 호출하기 전에 setDefaultFormat()를 호출해도 효과가 없음).

setDefaultFormat() 및 Fallback Mechanism도 참조하세요 .

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

organization 이라는 조직에서 parent 을 부모로 하여 application 이라는 애플리케이션의 설정에 액세스하기 위한 QSettings 객체를 구성합니다.

scope 이 QSettings::UserScope 인 경우 QSettings 개체는 시스템 전체 설정을 검색하기 전에 사용자별 설정을 먼저 검색한 다음 폴백으로 시스템 전체 설정을 검색합니다. scope 이 QSettings::SystemScope 인 경우 QSettings 개체는 사용자별 설정을 무시하고 시스템 전체 설정에 대한 액세스를 제공합니다.

저장소 형식은 QSettings::NativeFormat 으로 설정됩니다(즉, 이 생성자를 호출하기 전에 setDefaultFormat()을 호출해도 아무런 효과가 없습니다).

애플리케이션 이름을 지정하지 않으면 QSettings 개체는 조직 전체 locations 에만 액세스합니다.

setDefaultFormat()도 참조하세요 .

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

organization 이라는 조직에서 parent 을 부모로 하여 application 이라는 애플리케이션의 설정에 액세스하기 위한 QSettings 객체를 구성합니다.

scope 이 QSettings::UserScope 인 경우 QSettings 개체는 시스템 전체 설정을 검색하기 전에 사용자별 설정을 먼저 검색한 다음 폴백으로 시스템 전체 설정을 검색합니다. scope 이 QSettings::SystemScope 인 경우 QSettings 개체는 사용자별 설정을 무시하고 시스템 전체 설정에 대한 액세스를 제공합니다.

format 이 QSettings::NativeFormat 인 경우 기본 API가 설정을 저장하는 데 사용됩니다. format 이 QSettings::IniFormat 인 경우 INI 형식이 사용됩니다.

애플리케이션 이름이 지정되지 않은 경우 QSettings 개체는 조직 전체 locations 에만 액세스합니다.

[virtual noexcept] 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

설정을 저장하는 데 사용된 애플리케이션 이름을 반환합니다.

QCoreApplication::applicationName(), format(), scope() 및 organizationName()도 참조하세요 .

void QSettings::beginGroup(QAnyStringView 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()를 호출하여 현재 그룹을 해당 시작 그룹() 호출 이전으로 재설정합니다. 그룹은 중첩될 수 있습니다.

endGroup() 및 group()도 참조하세요 .

int QSettings::beginReadArray(QAnyStringView 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(QAnyStringView prefix, int size = -1)

prefix 을 현재 그룹에 추가하고 size 크기의 배열을 쓰기 시작합니다. size 이 -1(기본값)인 경우, 작성된 항목의 인덱스에 따라 자동으로 결정됩니다.

특정 키 집합이 많이 발생하는 경우 배열을 사용하여 작업을 더 쉽게 할 수 있습니다. 예를 들어 사용자 이름과 비밀번호의 가변 길이 목록을 저장하고 싶다고 가정해 봅시다. 그런 다음 작성할 수 있습니다:

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

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

생성된 키는 다음과 같은 형식을 갖습니다.

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

배열을 다시 읽으려면 beginReadArray()를 사용합니다.

beginReadArray(), endArray() 및 setArrayIndex()도 참조하십시오 .

QStringList QSettings::childGroups() const

QSettings 개체를 사용하여 읽을 수 있는 키가 포함된 모든 키 최상위 그룹 목록을 반환합니다.

예시:

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

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

beginGroup()를 사용하여 그룹을 설정한 경우 그룹 접두사 없이 해당 그룹의 최상위 키가 반환됩니다.

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

childKeys() 및 childGroups()를 재귀적으로 사용하여 전체 설정 계층 구조를 탐색할 수 있습니다.

childKeys() 및 allKeys()도 참조하세요 .

QStringList QSettings::childKeys() const

QSettings 객체를 사용하여 읽을 수 있는 모든 최상위 키의 목록을 반환합니다.

예시:

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

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

beginGroup()를 사용하여 그룹을 설정한 경우 그룹 접두사 없이 해당 그룹의 최상위 키가 반환됩니다:

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

childKeys() 및 childGroups()를 재귀적으로 사용하여 전체 설정 계층 구조를 탐색할 수 있습니다.

childGroups() 및 allKeys()도 참조하세요 .

void QSettings::clear()

이 QSettings 객체와 연결된 기본 위치의 모든 항목을 제거합니다.

대체 위치의 항목은 제거되지 않습니다.

현재 group()에 있는 항목만 제거하려면 remove("")를 대신 사용하세요.

remove() 및 setFallbacksEnabled()도 참조하세요 .

bool QSettings::contains(QAnyStringView key) const

key 이라는 설정이 있으면 true 을 반환하고, 그렇지 않으면 false를 반환합니다.

그룹이 beginGroup()를 사용하여 설정된 경우 key 은 해당 그룹에 상대적인 것으로 간주됩니다.

Windows 레지스트리 및 INI 파일은 대소문자를 구분하지 않는 키를 사용하는 반면, macOS 및 iOS의 CFPreferences API는 대소문자를 구분하는 키를 사용한다는 점에 유의하세요. 이식성 문제를 방지하려면 Section and Key Syntax 규칙을 참조하세요.

value() 및 setValue()도 참조하세요 .

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

QSettings(QObject *) 생성자의 설정을 저장하는 데 사용되는 기본 파일 형식을 반환합니다. 기본 형식이 설정되어 있지 않으면 QSettings::NativeFormat 이 사용됩니다.

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

설정을 저장하는 데 사용되는 형식을 반환합니다.

defaultFormat(), fileName(), scope(), organizationName() 및 applicationName()도 참조하세요 .

QString QSettings::group() const

현재 그룹을 반환합니다.

beginGroup() 및 endGroup()도 참조하세요 .

bool QSettings::isAtomicSyncRequired() const

QSettings 이 설정의 원자 저장 및 재로드(동기화)만 수행할 수 있는 경우 true 을 반환합니다. 설정 내용을 구성 파일에 직접 저장할 수 있는 경우 false 을 반환합니다.

기본값은 true 입니다.

setAtomicSyncRequired() 및 QSaveFile도 참조하세요 .

bool QSettings::isWritable() const

이 QSettings 객체를 사용하여 설정을 쓸 수 있으면 true 을 반환하고, 그렇지 않으면 false 을 반환합니다.

QSettings 가 읽기 전용 파일에서 작동하는 경우 isWritable()이 false를 반환할 수 있습니다.

fileName(), status() 및 sync()도 참조하세요 .

QString QSettings::organizationName() const

설정을 저장하는 데 사용된 조직 이름을 반환합니다.

QCoreApplication::organizationName(), format(), scope() 및 applicationName()도 참조하세요 .

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

사용자 정의 저장소 형식을 등록합니다. 성공하면 QSettings 생성자에 전달할 수 있는 특수 Format 값을 반환합니다. 실패하면 InvalidFormat 을 반환합니다.

extension 은 포맷에 연결된 파일 확장자입니다('.' 제외).

readFunc 및 writeFunc 매개 변수는 키/값 쌍을 읽고 쓰는 함수에 대한 포인터입니다. 읽기 및 쓰기 함수에 대한 QIODevice 매개변수는 항상 바이너리 모드(즉, QIODeviceBase::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");

    ...
}

참고: 이 함수는 스레드에 안전합니다.

setPath()도 참조하세요 .

void QSettings::remove(QAnyStringView 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 파일은 대소문자를 구분하지 않는 키를 사용하는 반면, macOS 및 iOS의 CFPreferences API는 대소문자를 구분하는 키를 사용한다는 점에 유의하세요. 이식성 문제를 방지하려면 Section and Key Syntax 규칙을 참조하세요.

setValue(), value() 및 contains()도 참조하세요 .

QSettings::Scope QSettings::scope() const

설정을 저장하는 데 사용된 범위를 반환합니다.

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 을 참조하세요.

isAtomicSyncRequired() 및 QSaveFile 을참조하세요 .

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

기본 파일 형식을 지정된 format 으로 설정하며, 이는 QSettings(QObject *) 생성자의 설정을 저장하는 데 사용됩니다.

기본 형식을 설정하지 않으면 QSettings::NativeFormat 이 사용됩니다. 사용 중인 QSettings 생성자의 문서를 참조하여 해당 생성자가 이 함수를 무시하는지 확인하세요.

defaultFormat() 및 format()도 참조하세요 .

void QSettings::setFallbacksEnabled(bool b)

폴백 사용 여부를 b 으로 설정합니다.

기본적으로 폴백은 활성화되어 있습니다.

fallbacksEnabled()도 참조하세요 .

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

지정된 format 및 scope 에 대한 설정을 저장하는 데 사용되는 경로를 path 로 설정합니다. format 은 사용자 지정 형식일 수 있습니다.

아래 표에는 기본값이 요약되어 있습니다:

Unix, macOS 및 iOS의 기본 UserScope 경로($HOME/.config 또는 $HOME/Settings)는 사용자가 XDG_CONFIG_HOME 환경 변수를 설정하여 재정의할 수 있습니다. Unix, macOS 및 iOS의 기본 SystemScope 경로(/etc/xdg)는 Qt 라이브러리를 빌드할 때 configure 스크립트의 -sysconfdir 플래그를 사용하여 재정의할 수 있습니다(자세한 내용은 QLibraryInfo 참조).

Windows, macOS 및 iOS에서 NativeFormat 경로를 설정해도 아무런 효과가 없습니다.

registerFormat()도 참조하세요 .

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

key 설정 값을 value 으로 설정합니다. key 이 이미 존재하는 경우 이전 값을 덮어씁니다.

Windows 레지스트리 및 INI 파일은 대소문자를 구분하지 않는 키를 사용하는 반면, macOS 및 iOS의 CFPreferences API는 대소문자를 구분하는 키를 사용한다는 점에 유의하세요. 이식성 문제를 방지하려면 Section and Key Syntax 규칙을 참조하세요.

예시:

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 은 일부 작업 수행을 지연시킨다는 점에 유의하세요. 따라서 status()를 호출하기 전에 sync()를 호출하여 QSettings 에 저장된 데이터가 디스크에 기록되었는지 확인하는 것이 좋습니다.

sync()도 참조하세요 .

void QSettings::sync()

저장되지 않은 변경 사항을 영구 저장소에 쓰고 그 사이에 다른 애플리케이션에서 변경한 설정을 다시 로드합니다.

이 함수는 QSettings 의 소멸자 및 이벤트 루프에서 일정 간격으로 자동으로 호출되므로 일반적으로 직접 호출할 필요가 없습니다.

status()도 참조하세요 .