QSettings (译)

QSetting
QSetting类提供保存跨平台的应用程序设置.

Win: 注册表
Mac OS X: XML
UNIX: 没统一的标准,很多程序(包括KDE)用INI文本文件
QSetting是这些技术的抽象,能让我们很方便的保存和还原程序配置信息,也支持自定义存储格式.
QSetting的API基于QVariant,允许我们很轻松的存储基于值的类型,例如: QString, QRect,QImage.
如果需要是的是不固定且基于内存的结构,考虑使用QMap<QString, QVariant>代替QSetting.

基本用法:
当实例化QSetting对象的时候,必须把公司或者组织和程序名加进去.
//公司:Star Runner 程序名:MySoft
QSetting setting("MySoft", "Star Runner");

QSetting可创建于栈或者堆上,构造和析构一个QSetting对象非常块.

如果会在很多地点使用自己的程序,就想指定一个组织名和程序名,可以分别使用,QCoreApplication::setOrganizationName(),QCoreApplication::setApplicationName(),同时用默认构造函数实例化QSetting对象.
QCoreApplication::setOrganizationName("MySoft");
QCoreApplication::setOrganizationDomain("mysoft.com");
QCoreApplication::setApplicationName("Star Runner");
...
QSettings settings;
(这里我们也指定了组织的域名,当域名被设置了,它常常在Mac OS X上代替组织名,因为Mac OS X应用程序习惯性的用域名来定义自己. 如果域名没设置,那么一个隐藏域名会来自于组织名)

QSetting存储配置信息.每条配置信息都是由一个指定配置信息名(键)的字符串和一个QVariant容器用于存储与键相关联的数据.写一个配置信息,用setValue()方法: 例如:
setting.setValue("editor/wrapMargin", 68);
如果已经存在一个相同的键,那么它会被新的键覆盖掉.但为了提高效率,这样的改变不会很迅速的保存到永久储存器上(磁盘)(不过可以可以委托sync()函数)

可以同value()方法获取配置文件的值:
int margin = settings.value("editor/wrapMargin").toInt();

如果没有那个配置信息满足指定的名字,QSetting就返回一个null QVariant(可以转换成为整形0). 也可以通过给value()方法传递第二个参数来获取其他的默认值.
int margin = setting.value("editor/wrapMargin", 80).toInt();

用contians()方法测试给出的键是否存在.
用remove()方法删除关联到key的配置信息
用allKeys()方法获取所有信息的列表.
用clear()方法清空所有的键.

QVariant和GUI类型
因为QVariant是QtCore库的一部分,所以它不能提供转换为QtGuit类型(QColor, QImage)的转换函数,例如:toColor(), toImage().

不过可以使用QVariant::value()或qVariantValue()模版函数来代替, 例如:
QSetting setting("MySoft", "Star Runner");
QColor color = setting.value("DataPump/bgcolor").value<QColor>();

QVariant提供了自动反向转换的功能(比如: QColor --> QVariant),包括GUI类型:
QSetting setting("MySoft", "Star Runner");
QColor color = palette().background().color();
setting.setValue("DataPump/bgcolor", color);

自定义类型通过qRegisterMetaType() and qRegisterMetaTypeStreamOperators()注册后,也能用于QSetting.

分隔和key语法规则:
配置信息键可以包含任意Unicode字符.Windows注册表和INI文件用大小写不敏感的键,然而Mac OS X上的Carbon Preferences API 键大小写敏感.为了避免可移植性,则要遵循以下规则:
1.时刻将相同的大小写指向相同的key.比如,如果在代码的某处指定一个名为"text font"的key,那么就不要在别的地方指定"Text Fonts"了.
2.除了大小写之外,也要避免将key的名字取完全一样,例如:如果有一个名为"MainWindow"的key,那么就不要试图把其他的key也命名为"mainwindow".
3.不要在分隔和key名中使用斜杠;其中,反斜杠是用来分隔子键的(如下):

可以在分层的keys之间使用'/'作为分隔符, 类似于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也提供了"arrary"的概念, 详细信息看beginReadArray() 和beginWriteArray().

回调机制:

假设已经建立了一个以MySoft作为组织名以及Star Runner作为程序名的QSettings配置信息.当检索一个值的时候,按照四个位置的顺序来寻找.
1.为Star Runner程序指定的用户区域.
2.MySoft组织为所有程序指定的用户区域.
3.Star Runner程序指定的全局区域
4.Mysoft组织为所以程序指定的全局区域.
如果一个key不能在第一个区域找到,便会在第二个区域寻找,以此类推.这使我们可以对每个人或者每个程序设置一个系统全局的或者组织全局的配置信息.
可以使用setFallbacksEnabled(false)关闭回调机制.

虽然这四个区域的key是可读的,但是仅仅只有第一个区域(即:用户对程序设置的区域是可写的). 要是想写其他的任意文件, 那么就得忽略应用程序名字已经'/'或者指定QSettings::SystemScope(与默认值QSetting::UserScope相反).例如:
QSettings obj1("MySoft", "Star Runner");
QSettings obj2("MySoft");
QSettings obj3(QSettings::SystemScope, "MySoft", "Star Runner");
QSettings obj4(QSettings::SystemScope, "MySoft");

Locations obj1 obj2 obj3 obj4
1. User, Application X
2. User, Organization o X
3. System, Application o X
4. System, Organization o o o X
这些机制允许工作在所有的平台上,而且很方便.不需要指定任何文件名以及注册路径.
如果想使用所有的平台上使用INI文件,可以把QSettings::IniFormat作为QSettings构造函数的第一个参数,接下来是范围,组织名,程序名.
QSettings settings(QSettings::IniFormat, QSettings::UserScope,
"MySoft", "Star Runner");