QSettings Class

Descripción Detallada

Normalmente, los usuarios esperan que una aplicación recuerde su configuración (tamaño y posición de las ventanas, opciones, etc.) en todas las sesiones. Esta información suele almacenarse en el registro del sistema en Windows, y en archivos de listas de propiedades en macOS e iOS. En los sistemas Unix, a falta de un estándar, muchas aplicaciones (incluidas las de KDE) utilizan archivos de texto INI.

QSettings es una abstracción en torno a estas tecnologías, lo que le permite guardar y restaurar la configuración de la aplicación de una manera portátil. También es compatible con custom storage formats.

La API de QSettings está basada en QVariant, permitiéndole guardar la mayoría de los tipos basados en valores, como QString, QRect, y QImage, con el mínimo esfuerzo.

Si todo lo que necesita es una estructura no persistente basada en memoria, considere usar QMap<QString, QVariant> en su lugar.

Uso básico

Al crear un objeto QSettings, debe pasar el nombre de su empresa u organización, así como el nombre de su aplicación. Por ejemplo, si tu producto se llama Star Runner y tu empresa se llama MySoft, construirías el objeto QSettings de la siguiente manera:

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

Los objetos QSettings pueden crearse tanto en la pila como en el montón (es decir, utilizando new). Construir y destruir un objeto QSettings es muy rápido.

Si usas QSettings desde muchos lugares en tu aplicación, puede que quieras especificar el nombre de la organización y el nombre de la aplicación usando QCoreApplication::setOrganizationName() y QCoreApplication::setApplicationName(), y luego usar el constructor por defecto de QSettings:

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

(Aquí, también especificamos el dominio de Internet de la organización. Cuando se establece el dominio de Internet, se utiliza en macOS e iOS en lugar del nombre de la organización, ya que las aplicaciones de macOS e iOS utilizan convencionalmente dominios de Internet para identificarse. Si no se establece ningún dominio, se obtiene un dominio falso a partir del nombre de la organización. Consulte Platform-Specific Notes para obtener más información).

QSettings almacena ajustes. Cada configuración consiste en un QString que especifica el nombre de la configuración (la clave) y un QVariant que almacena los datos asociados con la clave. Para escribir una configuración, utilice setValue(). Por ejemplo:

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

Si ya existe una configuración con la misma clave, el valor existente se sobrescribe con el nuevo valor. Por razones de eficacia, es posible que los cambios no se guarden inmediatamente en la memoria permanente. (Siempre puede llamar a sync() para confirmar los cambios).

Puede recuperar el valor de un parámetro utilizando value():

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

Si no hay ningún parámetro con el nombre especificado, QSettings devuelve un valor nulo QVariant (que puede convertirse al entero 0). Puede especificar otro valor por defecto pasando un segundo argumento a value():

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

Para comprobar si existe una clave determinada, llame a contains(). Para eliminar la configuración asociada a una clave, llame a remove(). Para obtener la lista de todas las claves, llame a allKeys(). Para eliminar todas las claves, llame a clear().

Tipos QVariant y GUI

Debido a que QVariant es parte del módulo Qt Core, no puede proporcionar funciones de conversión a tipos de datos como QColor, QImage, y QPixmap, que son parte de Qt GUI. En otras palabras, no hay funciones toColor(), toImage(), o toPixmap() en QVariant.

En su lugar, puede utilizar la función de plantilla QVariant::value() . Por ejemplo:

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

La conversión inversa (por ejemplo, de QColor a QVariant) es automática para todos los tipos de datos admitidos por QVariant, incluidos los tipos relacionados con GUI:

QSettings settings("MySoft", "Star Runner");
QColor color = QColor(Qt::blue);
settings.setValue("DataPump/bgcolor", color);

Los tipos personalizados registrados mediante qRegisterMetaType() que tienen operadores para la transmisión hacia y desde un QDataStream pueden almacenarse mediante QSettings.

Sintaxis de secciones y claves

Las claves de configuración pueden contener cualquier carácter Unicode. El formato del archivo y el sistema operativo determinarán si son sensibles a mayúsculas o minúsculas o no. En Windows, el registro y los archivos INI utilizarán claves que no distinguen entre mayúsculas y minúsculas, mientras que los formatos especificados por el usuario registrados con registerFormat() pueden ser cualquiera de los dos. En los sistemas Unix, las claves siempre distinguen entre mayúsculas y minúsculas.

Para evitar problemas de portabilidad, siga estas sencillas reglas:

1. Refiérase siempre a la misma clave utilizando las mismas mayúsculas y minúsculas. Por ejemplo, si te refieres a una clave como "fuentes de texto" en un lugar de tu código, no te refieras a ella como "Fuentes de Texto" en otro lugar.
2. Evite que los nombres de las teclas sean idénticos, salvo por las mayúsculas y minúsculas. Por ejemplo, si tienes una tecla llamada "MainWindow", no intentes guardar otra tecla como "mainwindow".
3. No utilice barras ('/' y '\') en los nombres de secciones o teclas; la barra invertida se utiliza para separar subclaves (véase más adelante). En windows '\' son convertidos por QSettings a '/', lo que los hace idénticos.

Puede formar claves jerárquicas utilizando el carácter '/' como separador, de forma similar a las rutas de archivos de Unix. Por ejemplo:

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

Si quieres guardar o restaurar muchas configuraciones con el mismo prefijo, puedes especificar el prefijo usando beginGroup() y llamar a endGroup() al final. He aquí de nuevo el mismo ejemplo, pero esta vez utilizando el mecanismo de grupos:

    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();

Si se establece un grupo utilizando beginGroup(), el comportamiento de la mayoría de las funciones cambia en consecuencia. Los grupos pueden establecerse recursivamente.

Además de grupos, QSettings también soporta el concepto de "array". Véase beginReadArray() y beginWriteArray() para más detalles.

Mecanismo de Fallback

Supongamos que has creado un objeto QSettings con el nombre de la organización MySoft y el nombre de la aplicación Star Runner. Al buscar un valor, se buscan hasta cuatro ubicaciones en este orden:

1. una ubicación específica del usuario para la aplicación Star Runner
2. una ubicación específica del usuario para todas las aplicaciones de MySoft
3. una ubicación de todo el sistema para la aplicación Star Runner
4. una ubicación en todo el sistema para todas las aplicaciones de MySoft

(Consulte Platform-Specific Notes más adelante para obtener información sobre cuáles son estas ubicaciones en las distintas plataformas compatibles con Qt).

Si no se puede encontrar una clave en la primera ubicación, la búsqueda continúa en la segunda ubicación, y así sucesivamente. Esto le permite almacenar la configuración de todo el sistema o de toda la organización y anularla por usuario o por aplicación. Para desactivar este mecanismo, llame a setFallbacksEnabled(false).

Aunque se pueden leer las claves de las cuatro ubicaciones, sólo se puede escribir en el primer archivo (la ubicación específica del usuario para la aplicación en cuestión). Para escribir en cualquiera de los otros archivos, omita el nombre de la aplicación y/o especifique QSettings::SystemScope (en lugar de QSettings::UserScope, por defecto).

Veámoslo con un ejemplo:

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

La siguiente tabla resume qué objetos QSettings acceden a qué ubicación. "X" significa que la ubicación es la ubicación principal asociada al objeto QSettings y se utiliza tanto para lectura como para escritura; "o" significa que la ubicación se utiliza como fallback cuando se lee.

La belleza de este mecanismo es que funciona en todas las plataformas soportadas por Qt y que aún te da mucha flexibilidad, sin requerir que especifiques ningún nombre de archivo o ruta de registro.

Si quieres usar archivos INI en todas las plataformas en lugar de la API nativa, puedes pasar QSettings::IniFormat como primer argumento al constructor de QSettings, seguido del ámbito, el nombre de la organización y el nombre de la aplicación:

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

Tenga en cuenta que los archivos INI pierden la distinción entre los datos numéricos y las cadenas utilizadas para codificarlos, por lo que los valores escritos como números se leerán como QString. El valor numérico puede recuperarse utilizando QString::toInt(), QString::toDouble() y funciones relacionadas.

Restauración del estado de una aplicación GUI

QSettings se utiliza a menudo para almacenar el estado de una aplicación GUI. El siguiente ejemplo ilustra cómo utilizar QSettings para guardar y restaurar la geometría de la ventana principal de una aplicación.

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();
}

Ver Geometría de Ventanas para una discusión sobre por qué es mejor llamar a QWidget::resize() y QWidget::move() en lugar de QWidget::setGeometry() para restaurar la geometría de una ventana.

Las funciones readSettings() y writeSettings() deben ser llamadas desde el constructor de la ventana principal y desde el manejador de eventos de cierre de la siguiente manera:

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

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

Accediendo a la Configuración desde Múltiples Hilos o Procesos Simultáneamente

QSettings es reentrante. Esto significa que puede utilizar distintos objetos QSettings en diferentes subprocesos simultáneamente. Esta garantía se mantiene incluso cuando los objetos QSettings se refieren a los mismos ficheros en disco (o a las mismas entradas en el registro del sistema). Si un ajuste se modifica a través de un objeto QSettings, el cambio será inmediatamente visible en cualquier otro objeto QSettings que opere en la misma ubicación y que viva en el mismo proceso.

QSettings puede ser utilizado con seguridad desde diferentes procesos (que pueden ser diferentes instancias de tu aplicación ejecutándose al mismo tiempo o diferentes aplicaciones en conjunto) para leer y escribir en las mismas ubicaciones del sistema, siempre que se cumplan ciertas condiciones. Para QSettings::IniFormat, utiliza el bloqueo de archivos de asesoramiento y un algoritmo de fusión inteligente para garantizar la integridad de los datos. La condición para que esto funcione es que el archivo de configuración de escritura debe ser un archivo normal y debe residir en un directorio en el que el usuario actual pueda crear nuevos archivos temporales. Si no es el caso, hay que utilizar setAtomicSyncRequired() para desactivar la seguridad.

Tenga en cuenta que sync() importa los cambios realizados por otros procesos (además de escribir los cambios de este QSettings).

Notas específicas de la plataforma

Ubicaciones donde se almacenan los ajustes de la aplicación

Como se mencionó en la sección Fallback Mechanism, QSettings almacena las configuraciones para una aplicación en hasta cuatro ubicaciones, dependiendo de si las configuraciones son específicas del usuario o de todo el sistema y si las configuraciones son específicas de la aplicación o de toda la organización. Para simplificar, asumimos que la organización se llama MySoft y la aplicación se llama Star Runner.

En los sistemas Unix, si el formato de archivo es NativeFormat, se utilizan por defecto los siguientes archivos:

1. $HOME/.config/MySoft/Star Runner.conf
2. $HOME/.config/MySoft.conf
3. para cada directorio <dir> en $XDG_CONFIG_DIRS: <dir>/MySoft/Star Runner.conf
4. para cada directorio <dir> en $XDG_CONFIG_DIRS: <dir>/MySoft.conf

En macOS e iOS, si el formato de archivo es NativeFormat, estos archivos se utilizan por defecto:

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

En Windows, la configuración de NativeFormat se almacena en las siguientes rutas del registro:

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

Si el formato del archivo es NativeFormat, se trata de "Settings/MySoft/Star Runner.conf" en el directorio principal de la aplicación.

Si el formato de archivo es IniFormat, en Unix, macOS e iOS se utilizan los siguientes archivos:

1. $HOME/.config/MySoft/Star Runner.ini
2. $HOME/.config/MySoft.ini
3. para cada directorio <dir> en $XDG_CONFIG_DIRS: <dir>/MySoft/Star Runner.ini
4. para cada directorio <dir> en $XDG_CONFIG_DIRS: <dir>/MySoft.ini

En Windows, se utilizan los siguientes archivos:

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

Los identificadores prefijados por FOLDERID_ son listas especiales de ID de elementos que deben pasarse a la función de la API Win32 SHGetKnownFolderPath() para obtener la ruta correspondiente.

FOLDERID_RoamingAppData normalmente apunta a C:\Users\User Name\AppData\Roaming, también indicado por la variable de entorno %APPDATA%.

FOLDERID_ProgramData normalmente apunta a C:\ProgramData.

Si el formato de archivo es IniFormat, se trata de "Settings/MySoft/Star Runner.ini" en el directorio de inicio de la aplicación.

Las rutas de los archivos .ini y .conf pueden modificarse con setPath(). En Unix, macOS e iOS, el usuario puede anularlas configurando la variable de entorno XDG_CONFIG_HOME; consulta setPath() para obtener más información.

Acceso directo a archivos INI y .plist

A veces se desea acceder a la configuración almacenada en un archivo específico o en una ruta del registro. En todas las plataformas, si quieres leer un archivo INI directamente, puedes usar el constructor QSettings que toma un nombre de archivo como primer argumento y pasa QSettings::IniFormat como segundo argumento. Por ejemplo:

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

A continuación, puede utilizar el objeto QSettings para leer y escribir la configuración en el archivo.

En macOS e iOS, puedes acceder a la lista de propiedades de los archivos .plist pasando QSettings::NativeFormat como segundo argumento. Por ejemplo:

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

Acceso directo al Registro de Windows

En Windows, QSettings le permite acceder a las configuraciones que se han escrito con QSettings (o configuraciones en un formato compatible, por ejemplo, datos de cadena) en el registro del sistema. Esto se hace construyendo un objeto QSettings con una ruta en el registro y QSettings::NativeFormat.

Por ejemplo:

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

Todas las entradas del registro que aparezcan bajo la ruta especificada pueden leerse o escribirse a través del objeto QSettings de la forma habitual (utilizando barras inclinadas en lugar de barras invertidas). Por ejemplo:

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

Tenga en cuenta que el carácter barra invertida es, como se ha mencionado, utilizado por QSettings para separar subclaves. Como resultado, no puede leer o escribir entradas del registro de Windows que contengan barras o barras invertidas; debe utilizar una API nativa de Windows si necesita hacerlo.

Acceso a la configuración común del Registro en Windows

En Windows, es posible que una clave tenga tanto un valor como subclaves. Se accede a su valor por defecto utilizando "Por defecto" o "." en lugar de una subclave:

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"

En otras plataformas distintas de Windows, "Predeterminado" y "." se tratarían como subclaves normales.

Limitaciones de plataforma

Aunque QSettings intenta suavizar las diferencias entre las distintas plataformas soportadas, aún existen algunas diferencias que debe tener en cuenta a la hora de portar su aplicación:

• El registro del sistema Windows tiene las siguientes limitaciones: Una subclave no puede superar los 255 caracteres, el valor de una entrada no puede superar los 16.383 caracteres y todos los valores de una clave no pueden superar los 65.535 caracteres. Una forma de sortear estas limitaciones es almacenar la configuración utilizando IniFormat en lugar de NativeFormat.
• En Windows, cuando se utiliza el registro del sistema Windows, QSettings no conserva el tipo original del valor. Por lo tanto, el tipo del valor puede cambiar cuando se establece un nuevo valor. Por ejemplo, un valor del tipo REG_EXPAND_SZ cambiará a REG_SZ.
• En macOS e iOS, allKeys() devolverá algunas claves adicionales para ajustes globales que se aplican a todas las aplicaciones. Estas claves pueden ser leídas usando value() pero no pueden ser cambiadas, sólo sombreadas. Llamar a setFallbacksEnabled(false) ocultará estos ajustes globales.
• En macOS e iOS, la API CFPreferences utilizada por QSettings espera nombres de dominio de Internet en lugar de nombres de organizaciones. Para proporcionar una API uniforme, QSettings obtiene un nombre de dominio falso a partir del nombre de la organización (a menos que el nombre de la organización ya sea un nombre de dominio, por ejemplo OpenOffice.org). El algoritmo añade ".com" al nombre de la empresa y sustituye los espacios y otros caracteres ilegales por guiones. Si desea especificar un nombre de dominio diferente, llame a QCoreApplication::setOrganizationDomain(), QCoreApplication::setOrganizationName(), y QCoreApplication::setApplicationName() en su función main() y, a continuación, utilice el constructor QSettings predeterminado. Otra solución es utilizar directivas de preprocesador, por ejemplo:

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

• En macOS, los permisos para acceder a configuraciones que no pertenecen al usuario actual (es decir, SystemScope) han cambiado con 10.7 (Lion). Antes de esa versión, los usuarios con derechos de administrador podían acceder a ellos. En 10.7 y 10.8 (Mountain Lion), sólo puede hacerlo el usuario root. Sin embargo, 10.9 (Mavericks) vuelve a cambiar esa regla, pero sólo para el formato nativo (archivos plist).