QSettings Class

상세 설명

사용자는 일반적으로 애플리케이션이 세션 간에 설정(창 크기 및 위치, 옵션 등)을 기억하기를 기대합니다. 이 정보는 Windows에서는 시스템 레지스트리에, macOS 및 iOS에서는 속성 목록 파일에 저장되는 경우가 많습니다. Unix 시스템의 경우 표준이 없기 때문에 많은 애플리케이션(KDE 애플리케이션 포함)이 INI 텍스트 파일을 사용합니다.

QSettings는 이러한 기술들을 추상화한 것으로, 애플리케이션 설정을 이식성 있게 저장하고 복원할 수 있게 해줍니다. 또한 custom storage formats 도 지원합니다.

QSettings의 API는 QVariant 를 기반으로 하여, QString, QRect, QImage 과 같은 대부분의 값 기반 유형을 최소한의 노력으로 저장할 수 있게 해줍니다.

단순히 비영구적인 메모리 기반 구조체만 필요한 경우에는 QMap<QString, QVariant>를 사용하는 것을 고려해 보십시오.

기본 사용법

QSettings 객체를 생성할 때는 애플리케이션 이름뿐만 아니라 회사나 조직의 이름도 함께 전달해야 합니다. 예를 들어, 제품 이름이 Star Runner이고 회사 이름이 MySoft인 경우, QSettings 객체는 다음과 같이 생성합니다:

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

QSettings 객체는 스택이나 힙(즉, ` new`를 사용하여)에서 생성할 수 있습니다. QSettings 객체의 생성 및 소멸은 매우 빠르게 이루어집니다.

애플리케이션의 여러 곳에서 QSettings를 사용하는 경우, QCoreApplication::setOrganizationName() 및 QCoreApplication::setApplicationName()를 사용하여 조직명과 애플리케이션 이름을 지정한 다음, 기본 QSettings 생성자를 사용하는 것이 좋습니다:

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

(여기서는 조직의 인터넷 도메인도 함께 지정합니다. 인터넷 도메인이 설정되면 macOS 및 iOS에서는 조직 이름 대신 이 도메인이 사용됩니다. 이는 macOS 및 iOS 애플리케이션이 관례적으로 인터넷 도메인을 사용하여 자신을 식별하기 때문입니다. 도메인이 설정되지 않은 경우, 조직 이름에서 파생된 가상의 도메인이 사용됩니다. 자세한 내용은 아래의 ` Platform-Specific Notes `을 참조하십시오.)

QSettings는 설정을 저장합니다. 각 설정은 설정의 이름( 키)을 지정하는 키-값 쌍( QString )과 키와 관련된 데이터를 저장하는 값( QVariant )으로 구성됩니다. 설정을 작성하려면 ` setValue()`를 사용합니다. 예를 들면 다음과 같습니다:

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

동일한 키를 가진 설정이 이미 존재하는 경우, 기존 값은 새 값으로 덮어쓰게 됩니다. 효율성을 위해 변경 사항이 즉시 영구 저장소에 저장되지 않을 수 있습니다. (언제든지 sync()를 호출하여 변경 사항을 반영할 수 있습니다.)

value()를 사용하여 설정값을 가져올 수 있습니다:

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

지정된 이름의 설정이 없는 경우, QSettings는 null 값의 QVariant 를 반환합니다(이는 정수 0으로 변환할 수 있습니다). value()에 두 번째 인수를 전달하여 다른 기본값을 지정할 수 있습니다:

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

주어진 키가 존재하는지 확인하려면 contains()를 호출하십시오. 키와 연관된 설정을 제거하려면 remove()를 호출하십시오. 모든 키의 목록을 얻으려면 allKeys()를 호출하십시오. 모든 키를 제거하려면 clear()를 호출하십시오.

QVariant 및 GUI 유형

QVariant 는 Qt Core 모듈의 일부이므로, Qt GUI 에 속하는 QColor, QImage, QPixmap 와 같은 데이터 유형에 대한 변환 함수를 제공할 수 없습니다. 즉, 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 = QColor(Qt::blue);
settings.setValue("DataPump/bgcolor", color);

qRegisterMetaType()를 사용하여 등록된 사용자 정의 유형 중 QDataStream 로 데이터를 스트리밍하거나 에서 데이터를 가져오는 연산자를 가진 유형은 QSettings를 사용하여 저장할 수 있습니다.

섹션 및 키 구문

설정 키에는 모든 유니코드 문자를 포함할 수 있습니다. 대소문자 구분이 적용되는지 여부는 파일 형식과 운영 체제에 따라 결정됩니다. Windows에서는 레지스트리와 INI 파일이 대소문자를 구분하지 않는 키를 사용하는 반면, registerFormat()로 등록된 사용자 지정 형식은 대소문자를 구분하거나 구분하지 않을 수 있습니다. Unix 시스템에서는 키가 항상 대소문자를 구분합니다.

이식성 문제를 방지하려면 다음의 간단한 규칙을 따르십시오:

1. 항상 동일한 대소문자 표기법을 사용하여 같은 키를 참조하십시오. 예를 들어, 코드 내 한 곳에서 키를 "text fonts"로 참조했다면, 다른 곳에서는 "Text Fonts"로 참조하지 마십시오.
2. 대소문자만 다를 뿐 동일한 키 이름은 피하십시오. 예를 들어, "MainWindow"라는 키가 있다면 다른 키를 "mainwindow"로 저장하려고 시도하지 마십시오.
3. 섹션이나 키 이름에 슬래시('/' 및 '\')를 사용하지 마십시오. 백슬래시 문자는 하위 키를 구분하는 데 사용됩니다(아래 참조). Windows에서 '\'는 QSettings에 의해 '/'로 변환되므로, 두 기호는 동일하게 처리됩니다.

유닉스 파일 경로와 마찬가지로 '/' 문자를 구분자로 사용하여 계층적 키를 구성할 수 있습니다. 예를 들어:

    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()을 참조하십시오.

폴백 메커니즘

조직 이름을 MySoft, 애플리케이션 이름을 Star Runner로 설정하여 QSettings 객체를 생성했다고 가정해 봅시다. 값을 조회할 때, 다음 순서대로 최대 네 곳의 위치가 검색됩니다:

1. Star Runner 애플리케이션의 사용자별 위치
2. MySoft에서 개발한 모든 애플리케이션에 대한 사용자별 위치
3. Star Runner 애플리케이션의 시스템 전체 위치
4. MySoft에서 개발한 모든 애플리케이션에 대한 시스템 전체 위치

(Qt가 지원하는 다양한 플랫폼에서 이러한 위치가 어디인지에 대한 정보는 아래의 Platform-Specific Notes 를 참조하십시오.)

첫 번째 위치에서 키를 찾을 수 없는 경우, 검색은 두 번째 위치로 이어지며, 이 과정이 반복됩니다. 이를 통해 시스템 전체 또는 조직 전체의 설정을 저장하고, 사용자별 또는 애플리케이션별로 해당 설정을 재정의할 수 있습니다. 이 메커니즘을 비활성화하려면 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가 지원하는 모든 플랫폼에서 작동하며, 파일 이름이나 레지스트리 경로를 명시할 필요 없이도 여전히 높은 유연성을 제공한다는 점입니다.

네이티브 API 대신 모든 플랫폼에서 INI 파일을 사용하려면, QSettings 생성자의 첫 번째 인자로 QSettings::IniFormat 를 전달하고, 그 뒤에 범위, 조직 이름, 애플리케이션 이름을 순서대로 지정하면 됩니다:

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

INI 파일은 숫자 데이터와 이를 인코딩하는 데 사용되는 문자열 간의 구분을 잃어버리므로, 숫자로 기록된 값은 ` QString`로 다시 읽히게 됩니다. 숫자 값은 ` QString::toInt()`, ` QString::toDouble()` 및 관련 함수를 사용하여 복원할 수 있습니다.

GUI 애플리케이션 상태 복원

QSettings는 GUI 애플리케이션의 상태를 저장하는 데 자주 사용됩니다. 다음 예제는 QSettings를 사용하여 애플리케이션 메인 창의 기하학적 정보를 저장하고 복원하는 방법을 보여줍니다.

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

    settings.beginGroup("MainWindow");
    settings.setValue("geometry", saveGeometry());
    settings.endGroup();
}

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

    settings.beginGroup("MainWindow");
    const auto geometry = settings.value("geometry", QByteArray()).toByteArray();
    if (geometry.isEmpty())
        setGeometry(200, 200, 400, 400);
    else
        restoreGeometry(geometry);
    settings.endGroup();
}

창의 기하학적 구조를 복원할 때 QWidget::setGeometry() 대신 QWidget::resize() 및 QWidget::move()를 호출하는 것이 더 좋은 이유에 대한 설명은 창 기하학적 구조(Window Geometry)를 참조하십시오.

readSettings() 및 writeSettings() 함수는 다음과 같이 메인 창의 생성자 및 닫기 이벤트 핸들러에서 호출해야 합니다:

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

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

여러 스레드 또는 프로세스에서 동시에 설정에 액세스하기

QSettings는 재진입 가능합니다. 즉, 서로 다른 스레드에서 서로 다른 QSettings 객체를 동시에 사용할 수 있습니다. 이 보장은 QSettings 객체가 디스크상의 동일한 파일(또는 시스템 레지스트리의 동일한 항목)을 참조하는 경우에도 유효합니다. 한 QSettings 객체를 통해 설정이 수정되면, 동일한 위치에서 작동하며 동일한 프로세스에 속한 다른 모든 QSettings 객체에서도 해당 변경 사항이 즉시 반영됩니다.

QSettings는 특정 조건이 충족되는 경우, 서로 다른 프로세스(동시에 실행 중인 애플리케이션의 서로 다른 인스턴스이거나 완전히 다른 애플리케이션일 수 있음)에서 동일한 시스템 위치를 읽고 쓰기 위해 안전하게 사용할 수 있습니다. QSettings::IniFormat 의 경우, 데이터 무결성을 보장하기 위해 자문형 파일 잠금 및 스마트 병합 알고리즘을 사용합니다. 이 기능이 작동하기 위한 조건은 쓰기 가능한 구성 파일이 일반 파일이어야 하고, 현재 사용자가 새로운 임시 파일을 생성할 수 있는 디렉터리에 위치해야 한다는 것입니다. 그렇지 않은 경우, setAtomicSyncRequired()를 사용하여 안전 모드를 해제해야 합니다.

sync()는 (이 QSettings의 변경 사항을 기록하는 것 외에도) 다른 프로세스에서 수행한 변경 사항을 가져온다는 점에 유의하십시오.

플랫폼별 참고 사항

애플리케이션 설정이 저장되는 위치

Fallback Mechanism 섹션에서 언급한 바와 같이, QSettings는 설정이 사용자별인지 시스템 전체인지, 그리고 애플리케이션별인지 조직 전체인지에 따라 최대 네 곳의 위치에 애플리케이션 설정을 저장합니다. 설명을 단순화하기 위해, 조직 이름을 MySoft, 애플리케이션 이름을 Star Runner라고 가정하겠습니다.

유닉스 시스템에서 파일 형식이 NativeFormat 인 경우, 기본적으로 다음 파일들이 사용됩니다:

1. $HOME/.config/MySoft/Star Runner.conf
2. $HOME/.config/MySoft.conf
3. $XDG_CONFIG_DIRS에 포함된 각 디렉터리 <dir>에 대해: <dir>/MySoft/Star Runner.conf
4. $XDG_CONFIG_DIRS에 포함된 각 디렉터리 <dir>에 대해: <dir>/MySoft.conf

macOS 및 iOS에서 파일 형식이 NativeFormat 인 경우, 기본적으로 다음 파일이 사용됩니다:

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

파일 형식이 NativeFormat 인 경우, 이는 애플리케이션의 홈 디렉터리 내 "Settings/MySoft/Star Runner.conf" 파일입니다.

파일 형식이 IniFormat 인 경우, Unix, macOS 및 iOS에서는 다음 파일이 사용됩니다:

1. $HOME/.config/MySoft/Star Runner.ini
2. $HOME/.config/MySoft.ini
3. $XDG_CONFIG_DIRS에 포함된 각 디렉터리 <dir>에 대해: <dir>/MySoft/Star Runner.ini
4. $XDG_CONFIG_DIRS에 포함된 각 디렉터리 <dir>에 대해: <dir>/MySoft.ini

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() 에 전달되어 해당 경로를 가져오는 특수 항목 ID 목록입니다.

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::IniFormat `를 전달하는 QSettings 생성자를 사용할 수 있습니다. 예를 들어:

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

그런 다음 QSettings 객체를 사용하여 파일 내의 설정을 읽고 쓸 수 있습니다.

macOS 및 iOS에서는 두 번째 인자로 ` QSettings::NativeFormat `를 전달하여 속성 목록( .plist ) 파일에 접근할 수 있습니다. 예를 들어:

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

Windows 레지스트리에 직접 접근하기

Windows에서 QSettings를 사용하면 시스템 레지스트리에 QSettings로 기록된 설정(또는 지원되는 형식의 설정, 예: 문자열 데이터)에 접근할 수 있습니다. 이를 위해서는 레지스트리 경로와 ` QSettings::NativeFormat`를 사용하여 QSettings 객체를 생성하면 됩니다.

예를 들면 다음과 같습니다:

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

지정된 경로 아래에 나타나는 모든 레지스트리 항목은 평소와 같이(백슬래시 대신 슬래시를 사용하여) QSettings 객체를 통해 읽거나 쓸 수 있습니다. 예를 들어:

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

앞서 언급한 바와 같이, 백슬래시 문자는 QSettings에서 하위 키를 구분하는 데 사용된다는 점에 유의하십시오. 따라서 슬래시나 백슬래시가 포함된 Windows 레지스트리 항목은 읽거나 쓸 수 없으며, 이러한 작업이 필요한 경우 네이티브 Windows API를 사용해야 합니다.

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자를 초과할 수 없습니다. 이러한 제한을 우회하는 한 가지 방법은 NativeFormat 대신 IniFormat 을 사용하여 설정을 저장하는 것입니다.
• Windows에서 Windows 시스템 레지스트리를 사용할 경우, QSettings는 값의 원래 유형을 유지하지 않습니다. 따라서 새 값을 설정할 때 값의 유형이 변경될 수 있습니다. 예를 들어, 유형이 REG_EXPAND_SZ 인 값은 REG_SZ 로 변경됩니다.
• macOS 및 iOS에서는 allKeys()가 모든 애플리케이션에 적용되는 전역 설정에 대한 추가 키를 반환합니다. 이러한 키는 value()를 사용하여 읽을 수 있지만 변경할 수는 없고, 오직 가림 처리만 가능합니다. setFallbacksEnabled(false)를 호출하면 이러한 전역 설정이 숨겨집니다.
• macOS 및 iOS에서 QSettings가 사용하는 CFPreferences API는 조직명이 아닌 인터넷 도메인 이름을 기대합니다. 일관된 API를 제공하기 위해, QSettings는 조직명에서 가상의 도메인 이름을 파생시킵니다(조직명이 이미 도메인 이름인 경우, 예: OpenOffice.org는 제외). 이 알고리즘은 회사 이름 뒤에 ".com"을 추가하고, 공백 및 기타 허용되지 않는 문자를 하이픈으로 대체합니다. 다른 도메인 이름을 지정하려면 main() 함수 내에서 QCoreApplication::setOrganizationDomain(), QCoreApplication::setOrganizationName(), QCoreApplication::setApplicationName()을 호출한 다음 기본 QSettings 생성자를 사용하십시오. 또 다른 해결책은 전처리기 지시문을 사용하는 것입니다. 예를 들어:

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

• macOS에서는 10.7(Lion)부터 현재 사용자에게 속하지 않는 설정(예: SystemScope)에 대한 액세스 권한이 변경되었습니다. 이 버전 이전에는 관리자 권한을 가진 사용자가 해당 설정에 접근할 수 있었습니다. 10.7 및 10.8(Mountain Lion)에서는 root 사용자만 접근할 수 있습니다. 그러나 10.9(Mavericks)에서는 이 규칙이 다시 변경되었으나, 이는 네이티브 형식(plist 파일)에만 적용됩니다.

보안 고려 사항

이 클래스는 QDataStream 를 사용하여 데이터를 QVariant 로 역직렬화합니다. 따라서 동일한 security consideration as QDataStream 를 가지며, 신뢰할 수 있는 입력에 대해서만 사용해야 합니다.