En esta página

QSettings Class

La clase QSettings proporciona ajustes de aplicación persistentes e independientes de la plataforma. Más información...

Encabezado: #include <QSettings>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Heredado de: QObject

Nota: Todas las funciones de esta clase son reentrantes.

Nota: Estas funciones también son seguras para subprocesos:

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

Tipos públicos

enum Format { NativeFormat, Registry32Format, Registry64Format, IniFormat, WebLocalStorageFormat, …, InvalidFormat }
ReadFunc
enum Scope { UserScope, SystemScope }
SettingsMap
enum Status { NoError, AccessError, FormatError }
WriteFunc

Funciones públicas

QSettings(QObject *parent = nullptr)
QSettings(QSettings::Scope scope, QObject *parent = nullptr)
QSettings(const QString &fileName, QSettings::Format format, QObject *parent = nullptr)
QSettings(const QString &organization, const QString &application = QString(), QObject *parent = nullptr)
QSettings(QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr)
QSettings(QSettings::Format format, QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr)
virtual ~QSettings()
QStringList allKeys() const
QString applicationName() const
void beginGroup(QAnyStringView prefix)
int beginReadArray(QAnyStringView prefix)
void beginWriteArray(QAnyStringView prefix, int size = -1)
QStringList childGroups() const
QStringList childKeys() const
void clear()
bool contains(QAnyStringView key) const
void endArray()
void endGroup()
bool fallbacksEnabled() const
QString fileName() const
QSettings::Format format() const
QString group() const
bool isAtomicSyncRequired() const
bool isWritable() const
QString organizationName() const
void remove(QAnyStringView key)
QSettings::Scope scope() const
void setArrayIndex(int i)
void setAtomicSyncRequired(bool enable)
void setFallbacksEnabled(bool b)
void setValue(QAnyStringView key, const QVariant &value)
QSettings::Status status() const
void sync()
QVariant value(QAnyStringView key) const
QVariant value(QAnyStringView key, const QVariant &defaultValue) const

Miembros públicos estáticos

QSettings::Format defaultFormat()
QSettings::Format registerFormat(const QString &extension, QSettings::ReadFunc readFunc, QSettings::WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive)
void setDefaultFormat(QSettings::Format format)
void setPath(QSettings::Format format, QSettings::Scope scope, const QString &path)

Funciones protegidas reimplementadas

virtual bool event(QEvent *event) override

Descripción detallada

Los usuarios suelen esperar que una aplicación recuerde su configuración (tamaños y posiciones de las ventanas, opciones, etc.) de una sesión a otra. Esta información suele almacenarse en el registro del sistema en Windows y en archivos de lista de propiedades en macOS e iOS. En los sistemas Unix, al no existir 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 que permite guardar y restaurar la configuración de la aplicación de forma portátil. También es compatible con custom storage formats.

La API de QSettings se basa en QVariant, lo que permite guardar la mayoría de los tipos basados en valores, como QString, QRect y QImage, con el mínimo esfuerzo.

Si lo único que necesitas es una estructura basada en memoria no persistente, plantéate utilizar en su lugar QMap<QString, QVariant>.

Uso básico

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

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

Los objetos QSettings se pueden crear tanto en la pila como en el montón (es decir, utilizando ` new`). La creación y destrucción de un objeto QSettings es muy rápida.

Si utilizas QSettings en muchos lugares de tu aplicación, es posible que quieras especificar el nombre de la organización y el nombre de la aplicación mediante QCoreApplication::setOrganizationName() y QCoreApplication::setApplicationName(), y luego utilizar el constructor predeterminado 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, este se utiliza en macOS e iOS en lugar del nombre de la organización, ya que las aplicaciones de macOS e iOS suelen utilizar dominios de Internet para identificarse. Si no se establece ningún dominio, se deriva un dominio ficticio a partir del nombre de la organización. Consulta el Platform-Specific Notes más abajo para obtener más detalles.)

QSettings almacena los ajustes. Cada ajuste consta de un « QString » que especifica el nombre del ajuste (la clave) y un « QVariant » que almacena los datos asociados a la clave. Para escribir un ajuste, utiliza ` 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. Por motivos de eficiencia, es posible que los cambios no se guarden inmediatamente en el almacenamiento permanente. (Siempre puedes llamar a sync() para confirmar los cambios.)

Puedes recuperar el valor de una configuración utilizando value():

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

Si no existe ninguna configuración con el nombre especificado, QSettings devuelve un QVariant nulo (que se puede convertir en el entero 0). Puedes 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, llama a ` contains()`. Para eliminar la configuración asociada a una clave, llama a ` remove()`. Para obtener la lista de todas las claves, llama a ` allKeys()`. Para eliminar todas las claves, llama a ` clear()`.

QVariant y tipos de interfaz gráfica de usuario

Dado que QVariant forma parte del módulo Qt Core, no puede proporcionar funciones de conversión a tipos de datos como QColor, QImage y QPixmap, que forman parte de Qt GUI. En otras palabras, no existen las funciones toColor(), toImage() ni toPixmap() en QVariant.

En su lugar, puedes 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 compatibles con QVariant, incluidos los tipos relacionados con la interfaz gráfica de usuario (GUI):

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

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

Sintaxis de secciones y claves

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

Para evitar problemas de portabilidad, sigue estas sencillas reglas:

  1. Utiliza siempre las mismas mayúsculas y minúsculas al hacer referencia a una misma clave. Por ejemplo, si te refieres a una clave como «text fonts» en un lugar del código, no te refieras a ella como «Text Fonts» en otro.
  2. Evita los nombres de claves que sean idénticos salvo por las mayúsculas y minúsculas. Por ejemplo, si tienes una clave llamada «MainWindow», no intentes guardar otra clave como «mainwindow».
  3. No utilices barras («/» y «\») en los nombres de secciones o claves; el carácter de barra invertida se utiliza para separar subclaves (véase más abajo). En Windows, QSettings convierte las barras invertidas («\») en barras («/»), lo que las hace idénticas.

Puedes crear 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 muchos ajustes con el mismo prefijo, puedes especificar el prefijo mediante ` beginGroup()` y llamar a ` endGroup()` al final. Aquí tienes 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 mediante beginGroup(), el comportamiento de la mayoría de las funciones cambia en consecuencia. Los grupos se pueden establecer de forma recursiva.

Además de los grupos, QSettings también admite el concepto de «matriz». Consulta beginReadArray() y beginWriteArray() para obtener más detalles.

Mecanismo de reserva

Supongamos que ha 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 revisan 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 de todo el sistema para todas las aplicaciones de MySoft

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

Si no se encuentra una clave en la primera ubicación, la búsqueda continúa en la segunda, y así sucesivamente. Esto te permite almacenar configuraciones para todo el sistema o para toda la organización y anularlas por usuario o por aplicación. Para desactivar este mecanismo, llama a ` setFallbacksEnabled(false)`.

Aunque las claves de las cuatro ubicaciones están disponibles para su lectura, solo 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 demás archivos, omite el nombre de la aplicación y/o especifica ` QSettings::SystemScope ` (en lugar de ` QSettings::UserScope`, que es el valor 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 tabla siguiente resume qué objetos QSettings acceden a qué ubicación.«X» significa que la ubicación es la principal asociada al objeto QSettings y se utiliza tanto para leer como para escribir; «o» significa que la ubicación se utiliza como alternativa al leer.

Ubicacionesobj1obj2obj3obj4
1. Usuario, aplicaciónX
2. Usuario, organizaciónoX
3. Sistema, aplicaciónoX
4. Sistema, organizaciónoooX

La ventaja de este mecanismo es que funciona en todas las plataformas compatibles con Qt y que, además, ofrece una gran flexibilidad, sin necesidad de especificar nombres de archivo ni rutas del registro.

Si quieres utilizar 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");

Ten 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 se puede recuperar 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();
}

Consulte «Geometría de la ventana » para conocer las razones por las que 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 invocarse desde el constructor de la ventana principal y desde el controlador de eventos de cierre, tal y como se muestra a continuación:

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

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

Acceso a la configuración desde varios subprocesos o procesos simultáneamente

QSettings es reentrante. Esto significa que se pueden utilizar distintos objetos QSettings en diferentes subprocesos al mismo tiempo. Esta garantía se mantiene incluso cuando los objetos QSettings hacen referencia a los mismos archivos en el disco (o a las mismas entradas en el registro del sistema). Si se modifica una configuración a través de un objeto QSettings, el cambio se verá inmediatamente en cualquier otro objeto QSettings que opere en la misma ubicación y que se encuentre en el mismo proceso.

QSettings se puede utilizar de forma segura desde diferentes procesos (que pueden ser distintas instancias de tu aplicación ejecutándose al mismo tiempo o aplicaciones totalmente diferentes) para leer y escribir en las mismas ubicaciones del sistema, siempre que se cumplan ciertas condiciones. En el caso de ` QSettings::IniFormat`, utiliza el bloqueo de archivos de tipo «advisory» 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 en el que se puede escribir sea un archivo normal y se encuentre en un directorio en el que el usuario actual pueda crear nuevos archivos temporales. Si no es así, hay que utilizar ` setAtomicSyncRequired()` para desactivar la protección.

Ten 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 menciona en la sección Fallback Mechanism, QSettings almacena la configuración de una aplicación en hasta cuatro ubicaciones, dependiendo de si la configuración es específica del usuario o de todo el sistema, y de si es específica de la aplicación o de toda la organización. Para simplificar, suponemos que la organización se llama MySoft y la aplicación se llama Star Runner.

En 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

Nota: Si XDG_CONFIG_DIRS no está definido, se utiliza el valor por defecto de /etc/xdg.

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

  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

Nota: En Windows, para los programas de 32 bits que se ejecutan en modo WOW64, la configuración se almacena en la siguiente ruta del Registro: HKEY_LOCAL_MACHINE\Software\WOW6432node.

Si el formato de archivo es NativeFormat, se trata de «Settings/MySoft/Star Runner.conf» en el directorio de inicio de la aplicación.

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

  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

Nota: Si XDG_CONFIG_DIRS no está definido, se utiliza el valor predeterminado de /etc/xdg.

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 precedidos por FOLDERID_ son listas especiales de ID de elementos que se pasan a la función de la API de Win32 SHGetKnownFolderPath() para obtener la ruta correspondiente.

FOLDERID_RoamingAppData suele apuntar a C:\Users\User Name\AppData\Roaming, tal y como indica también la variable de entorno %APPDATA%.

FOLDERID_ProgramData suele apuntar a C:\ProgramData.

Si el formato del 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 se pueden modificar mediante setPath(). En Unix, macOS e iOS, el usuario puede anularlas configurando la variable de entorno XDG_CONFIG_HOME; consulta setPath() para obtener más detalles.

Acceso directo a archivos INI y .plist

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

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

A continuación, puedes utilizar el objeto QSettings para leer y escribir configuraciones en el archivo.

En macOS e iOS, puedes acceder a los archivos de lista de propiedades ( .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 permite acceder a la configuración que se ha escrito con QSettings (o a la configuración en un formato compatible, por ejemplo, datos de cadena) en el Registro del sistema. Para ello, se crea 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 aparecen bajo la ruta especificada se pueden leer o escribir a través del objeto QSettings como de costumbre (utilizando barras en lugar de barras invertidas). Por ejemplo:

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

Ten en cuenta que el carácter de barra invertida, como se ha mencionado, lo utiliza QSettings para separar subclaves. Por ello, no es posible leer ni escribir entradas del Registro de Windows que contengan barras o barras invertidas; si necesitas hacerlo, debes utilizar una API nativa de Windows.

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 «Default» 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 plataformas distintas de Windows, «Default» y «.» se tratarían como subclaves normales.

Limitaciones de la plataforma

Aunque QSettings intenta suavizar las diferencias entre las distintas plataformas compatibles, sigue habiendo algunas diferencias que debes tener en cuenta al portar tu aplicación:

  • El registro del sistema de Windows presenta las siguientes limitaciones: una subclave no puede superar los 255 caracteres, el valor de una entrada no puede superar los 16 383 caracteres y el conjunto de valores de una clave no puede superar los 65 535 caracteres. Una forma de sortear estas limitaciones es almacenar la configuración utilizando el ` IniFormat ` en lugar de ` NativeFormat`.
  • En Windows, cuando se utiliza el registro del sistema de Windows, QSettings no conserva el tipo original del valor. Por lo tanto, el tipo del valor podría cambiar al establecer un nuevo valor. Por ejemplo, un valor con el 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 se pueden leer mediante ` value()`, pero no se pueden modificar, solo se pueden ocultar. Al llamar a ` setFallbacksEnabled(false)`, se ocultarán estos ajustes globales.
  • En macOS e iOS, la API CFPreferences utilizada por QSettings espera nombres de dominio de Internet en lugar de nombres de organización. Para ofrecer una API uniforme, QSettings deriva un nombre de dominio ficticio a partir del nombre de la organización (a menos que el nombre de la organización ya sea un nombre de dominio, p. ej., OpenOffice.org). El algoritmo añade «.com» al nombre de la empresa y sustituye los espacios y otros caracteres no válidos por guiones. Si deseas especificar un nombre de dominio diferente, llama a QCoreApplication::setOrganizationDomain(), QCoreApplication::setOrganizationName() y QCoreApplication::setApplicationName() en tu función main() y, a continuación, utiliza el constructor predeterminado de QSettings. Otra solución es utilizar directivas del 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 la configuración que no pertenece al usuario actual (es decir, SystemScope) han cambiado a partir de la versión 10.7 (Lion). Antes de esa versión, los usuarios con derechos de administrador podían acceder a ellas. En las versiones 10.7 y 10.8 (Mountain Lion), solo el usuario root puede hacerlo. Sin embargo, la versión 10.9 (Mavericks) vuelve a modificar esa regla, pero solo para el formato nativo (archivos plist).

Consideraciones de seguridad

La clase utiliza QDataStream para deserializar datos en QVariant. Por lo tanto, presenta el mismo security consideration as QDataStream y solo debe utilizarse con entradas de confianza.

Véase también QVariant y QSessionManager.

Documentación sobre tipos de miembros

enum QSettings::Format

Este tipo de enumeración especifica el formato de almacenamiento utilizado por QSettings.

ConstanteValorDescripción
QSettings::NativeFormat0Almacena la configuración utilizando el formato de almacenamiento más adecuado para la plataforma. En Windows, esto significa el registro del sistema; en macOS e iOS, la API CFPreferences; en Unix, archivos de configuración de texto en formato INI.
QSettings::Registry32Format2Solo en Windows: accede explícitamente al registro del sistema de 32 bits desde una aplicación de 64 bits que se ejecute en Windows de 64 bits. En Windows de 32 bits o desde una aplicación de 32 bits en un sistema Windows de 64 bits, esto funciona igual que al especificar NativeFormat. Este valor de enumeración se añadió en Qt 5.7.
QSettings::Registry64Format3Solo en Windows: Accede explícitamente al registro del sistema de 64 bits desde una aplicación de 32 bits que se ejecute en un sistema Windows de 64 bits. En Windows de 32 bits o desde una aplicación de 64 bits en un sistema Windows de 64 bits, esto funciona igual que al especificar NativeFormat. Este valor de la enumeración se añadió en Qt 5.7.
QSettings::IniFormat1Almacena la configuración en archivos INI. Ten en cuenta que los archivos INI no distinguen 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 ».
QSettings::WebLocalStorageFormat4Solo WASM: Almacena la configuración en `window.localStorage` para el origen actual. Si no se permiten las cookies, se recurre al formato INI. Esto proporciona hasta 5 MiB de almacenamiento por origen, pero el acceso es síncrono y no se requiere JSPI.
QSettings::WebIndexedDBFormat5Solo WASM: Almacena la configuración en una base de datos indexada (IndexedDB) para el origen actual. Si no se permiten las cookies, se recurre al formato INI. Esto requiere JSPI, pero proporciona más almacenamiento que WebLocalStorageFormat.
QSettings::InvalidFormat16Valor especial devuelto por registerFormat().

En Unix, NativeFormat e IniFormat significan lo mismo, salvo que la extensión del archivo es diferente (.conf para NativeFormat, .ini para IniFormat).

El formato de archivo INI es un formato de Windows que Qt admite en todas las plataformas. A falta de un estándar INI, intentamos seguir el ejemplo de Microsoft, con las siguientes excepciones:

  • Si almacenas tipos que QVariant no puede convertir a QString (por ejemplo, QPoint, QRect y QSize), Qt utiliza una sintaxis basada en @ para codificar el tipo. Por ejemplo:
    pos = @QPoint(100 100)

    @Point Rect Size

  • Aunque la barra invertida es un carácter especial en los archivos INI, la mayoría de las aplicaciones de Windows no escapan las barras invertidas (\) en las rutas de los archivos:
    windir = C:\Windows

    QSettings siempre trata la barra invertida como un carácter especial y no proporciona ninguna API para leer o escribir este tipo de entradas.

  • El formato de archivo INI tiene restricciones muy estrictas en cuanto a la sintaxis de las claves. Qt soluciona esto utilizando % como carácter de escape en las claves. Además, si guardas una configuración de nivel superior (una clave sin barras, p. ej., «someKey»), aparecerá en la sección «General» del archivo INI. Para evitar sobrescribir otras claves, si guardas algo utilizando una clave como «General/someKey», la clave se ubicará en la sección «%General», no en la sección «General».
  • En consonancia con la mayoría de las implementaciones actuales, QSettings asumirá que los valores del archivo INI están codificados en UTF-8. Esto significa que los valores se descodificarán como entradas codificadas en UTF-8 y se volverán a escribir en UTF-8. Para mantener la compatibilidad con versiones anteriores de Qt, las claves del archivo INI se escriben en formato codificado con %, pero pueden leerse tanto en formato codificado con % como en UTF-8.
Compatibilidad con versiones anteriores de Qt

Ten en cuenta que este comportamiento difiere del que presentaba « QSettings » en versiones de Qt anteriores a la 6. No obstante, los archivos INI creados con Qt 5 o versiones anteriores son totalmente legibles para una aplicación basada en Qt 6 (a menos que se haya configurado un códec INI distinto de utf8). No obstante, los archivos INI creados con Qt 6 solo serán legibles en versiones anteriores de Qt si se configura «iniCodec» con un códec de texto UTF-8.

Véase también registerFormat() y setPath().

QSettings::ReadFunc

Definición de tipo (typedef) para un puntero a una función con la siguiente firma:

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

ReadFunc se utiliza en registerFormat() como puntero a una función que lee un conjunto de pares clave/valor. ReadFunc debe leer todas las opciones en una sola pasada y devolver todos los ajustes en el contenedor SettingsMap, que inicialmente está vacío.

Véase también WriteFunc y registerFormat().

enum QSettings::Scope

Esta enumeración especifica si la configuración es específica de cada usuario o si la comparten todos los usuarios del mismo sistema.

ConstanteValorDescripción
QSettings::UserScope0Almacena la configuración en una ubicación específica para el usuario actual (por ejemplo, en el directorio de inicio del usuario).
QSettings::SystemScope1Almacena la configuración en una ubicación global, de modo que todos los usuarios de la misma máquina accedan al mismo conjunto de ajustes.

Véase también setPath().

QSettings::SettingsMap

Definición de tipo para QMap<QString, QVariant>.

Véase también registerFormat().

enum QSettings::Status

Los siguientes valores de estado son posibles:

ConstanteValorDescripción
QSettings::NoError0No se ha producido ningún error.
QSettings::AccessError1Se ha producido un error de acceso (por ejemplo, al intentar escribir en un archivo de solo lectura).
QSettings::FormatError2Se ha producido un error de formato (por ejemplo, al cargar un archivo INI con formato incorrecto).

Véase también status().

QSettings::WriteFunc

Definición de tipo para un puntero a una función con la siguiente firma:

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

WriteFunc se utiliza en registerFormat() como puntero a una función que escribe un conjunto de pares clave/valor. WriteFunc solo se llama una vez, por lo que debes generar la salida de la configuración de una sola vez.

Véase también ReadFunc y registerFormat().

Documentación de funciones de miembro

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

Crea un objeto QSettings para acceder a la configuración de la aplicación y de la organización establecidas previamente mediante las llamadas a QCoreApplication::setOrganizationName(), QCoreApplication::setOrganizationDomain() y QCoreApplication::setApplicationName().

El ámbito es QSettings::UserScope y el formato es defaultFormat() (QSettings::NativeFormat por defecto). Utiliza setDefaultFormat() antes de llamar a este constructor para cambiar el formato por defecto que utiliza este constructor.

El código

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

es equivalente a

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

Si no se han llamado previamente QCoreApplication::setOrganizationName() y QCoreApplication::setApplicationName(), el objeto QSettings no podrá leer ni escribir ninguna configuración, y status() devolverá AccessError.

Debes proporcionar tanto el dominio (utilizado por defecto en macOS e iOS) como el nombre (utilizado por defecto en el resto de plataformas), aunque el código se adaptará si solo proporcionas uno de ellos, que se utilizará entonces (en todas las plataformas), lo que no se ajusta a la nomenclatura habitual del archivo en aquellas plataformas en las que no sea el valor por defecto.

Véase también QCoreApplication::setOrganizationName(), QCoreApplication::setOrganizationDomain(), QCoreApplication::setApplicationName() y setDefaultFormat().

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

Crea un objeto QSettings de la misma forma que QSettings(QObject *parent), pero con el objeto scope especificado.

Véase también QSettings(QObject *parent).

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

Crea un objeto QSettings para acceder a la configuración almacenada en el archivo denominado « fileName », cuyo padre es « parent ». Si el archivo aún no existe, se crea.

Si format es QSettings::NativeFormat, el significado de fileName depende de la plataforma. En Unix, fileName es el nombre de un archivo INI. En macOS e iOS, fileName es el nombre de un archivo .plist. En Windows, fileName es una ruta del registro del sistema.

Si format es QSettings::IniFormat, fileName es el nombre de un archivo INI.

Advertencia: Esta función se proporciona por comodidad. Funciona bien para acceder a archivos INI o .plist generados por Qt, pero podría fallar con algunas sintaxis que se encuentran en dichos archivos originados por otros programas. En particular, ten en cuenta las siguientes limitaciones:

  • QSettings no ofrece ninguna forma de leer entradas INI de «ruta», es decir, entradas con caracteres de barra no escapados. (Esto se debe a que estas entradas son ambiguas y no pueden resolverse automáticamente).
  • En los archivos INI, QSettings utiliza el carácter « @ » como metacarácter en algunos contextos, para codificar tipos de datos específicos de Qt (p. ej., @Rect), y, por lo tanto, podría interpretarlo erróneamente cuando aparece en archivos INI puros.

Véase también fileName().

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

Crea un objeto QSettings para acceder a la configuración de la aplicación denominada « application », perteneciente a la organización denominada « organization » y cuyo padre es « parent ».

Ejemplo:

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

El ámbito se establece en QSettings::UserScope y el formato en QSettings::NativeFormat (es decir, llamar a setDefaultFormat() antes de llamar a este constructor no tiene ningún efecto).

Véase también setDefaultFormat() y Fallback Mechanism.

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

Crea un objeto QSettings para acceder a la configuración de la aplicación denominada « application », perteneciente a la organización « organization » y cuyo padre es « parent ».

Si scope es QSettings::UserScope, el objeto QSettings busca primero la configuración específica del usuario, antes de buscar la configuración del sistema como alternativa. Si scope es QSettings::SystemScope, el objeto QSettings ignora la configuración específica del usuario y proporciona acceso a la configuración del sistema.

El formato de almacenamiento se establece en QSettings::NativeFormat (es decir, llamar a setDefaultFormat() antes de llamar a este constructor no tiene ningún efecto).

Si no se especifica ningún nombre de aplicación, el objeto QSettings solo accederá a la configuración de toda la organización locations.

Véase también setDefaultFormat().

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

Crea un objeto QSettings para acceder a la configuración de la aplicación denominada « application », perteneciente a la organización « organization » y cuyo padre es « parent ».

Si scope es QSettings::UserScope, el objeto QSettings busca primero la configuración específica del usuario, antes de recurrir a la configuración del sistema como alternativa. Si scope es QSettings::SystemScope, el objeto QSettings ignora la configuración específica del usuario y proporciona acceso a la configuración del sistema.

Si format es QSettings::NativeFormat, se utiliza la API nativa para almacenar la configuración. Si format es QSettings::IniFormat, se utiliza el formato INI.

Si no se especifica ningún nombre de aplicación, el objeto `QSettings` solo accederá al archivo ` locations` de toda la organización.

[virtual noexcept] QSettings::~QSettings()

Elimina el objeto « QSettings ».

Cualquier cambio no guardado se escribirá finalmente en el almacenamiento permanente.

Véase también sync().

QStringList QSettings::allKeys() const

Devuelve una lista de todas las claves, incluidas las subclaves, que se pueden leer mediante el objeto ` QSettings `.

Ejemplo:

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"]

Si se establece un grupo mediante ` beginGroup()`, solo se devuelven las claves del grupo, sin el prefijo del grupo:

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

Véase también childGroups() y childKeys().

QString QSettings::applicationName() const

Devuelve el nombre de la aplicación utilizado para almacenar la configuración.

Véase también QCoreApplication::applicationName(), format(), scope() y organizationName().

void QSettings::beginGroup(QAnyStringView prefix)

Añade « prefix » al grupo actual.

El grupo actual se añade automáticamente al principio de todas las claves especificadas en QSettings. Además, las funciones de consulta como childGroups(), childKeys() y allKeys() se basan en el grupo. Por defecto, no hay ningún grupo establecido.

Los grupos resultan útiles para evitar tener que escribir las mismas rutas de configuración una y otra vez. Por ejemplo:

settings.beginGroup("mainwindow");
settings.setValue("size", win->size());
settings.setValue("active", win->isActive());
settings.endGroup();

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

Esto establecerá el valor de tres ajustes:

  • mainwindow/size
  • mainwindow/active
  • outputpanel/visible

Llama a endGroup() para restablecer el grupo actual a su estado anterior a la llamada correspondiente a beginGroup(). Los grupos se pueden anidar.

Nota: En las versiones de Qt anteriores a la 6.4, esta función aceptaba QString, no QAnyStringView.

Véase también ` endGroup()` y ` group()`.

int QSettings::beginReadArray(QAnyStringView prefix)

Añade « prefix » al grupo actual y comienza a leer desde un array. Devuelve el tamaño del array.

Ejemplo:

struct Login {
    QString userName;
    QString password;
};
QList<Login> logins;
//...
void some_function()
{
    //...
    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();
    //...
}

Utiliza beginWriteArray() para escribir el array en primer lugar.

Nota: En las versiones de Qt anteriores a la 6.4, esta función aceptaba ` QString`, no ` QAnyStringView`.

Véase también beginWriteArray(), endArray() y setArrayIndex().

void QSettings::beginWriteArray(QAnyStringView prefix, int size = -1)

Añade ` prefix ` al grupo actual y comienza a escribir una matriz de tamaño ` size`. Si ` size ` es -1 (el valor por defecto), se determina automáticamente en función de los índices de las entradas escritas.

Si tienes muchas ocurrencias de un determinado conjunto de claves, puedes utilizar matrices para facilitarte la tarea. Por ejemplo, supongamos que quieres guardar una lista de longitud variable de nombres de usuario y contraseñas. En ese caso, podrías escribir:

struct Login {
    QString userName;
    QString password;
};
QList<Login> logins;
//...
void some_function()
{
    //...
    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();
    //...
}

Las claves generadas tendrán la forma

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

Para recuperar un array, utiliza beginReadArray().

Nota: En las versiones de Qt anteriores a la 6.4, esta función aceptaba QString, no QAnyStringView.

Véanse también beginReadArray(), endArray() y setArrayIndex().

QStringList QSettings::childGroups() const

Devuelve una lista de todos los grupos de nivel superior que contienen claves que pueden leerse mediante el objeto ` QSettings `.

Ejemplo:

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"]

Si se configura un grupo mediante beginGroup(), se devuelven las claves de primer nivel de ese grupo, sin el prefijo del grupo.

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

Se puede navegar por toda la jerarquía de configuración utilizando childKeys() y childGroups() de forma recursiva.

Véase también ` childKeys()` y ` allKeys()`.

QStringList QSettings::childKeys() const

Devuelve una lista de todas las claves de nivel superior que se pueden leer mediante el objeto ` QSettings `.

Ejemplo:

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"]

Si se establece un grupo mediante beginGroup(), se devuelven las claves de nivel superior de ese grupo, sin el prefijo del grupo:

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

Se puede navegar por toda la jerarquía de configuración utilizando `childKeys()` y ` childGroups()` de forma recursiva.

Véase también childGroups() y allKeys().

void QSettings::clear()

Elimina todas las entradas de la ubicación principal asociada a este objeto QSettings.

Las entradas de las ubicaciones alternativas no se eliminan.

Si solo desea eliminar las entradas del ` group()` actual, utilice `remove("")` en su lugar.

Véase también remove() y setFallbacksEnabled().

bool QSettings::contains(QAnyStringView key) const

Devuelve « true » si existe una configuración denominada « key »; en caso contrario, devuelve «false».

Si se establece un grupo mediante beginGroup(), se considera que key es relativa a ese grupo.

La búsqueda de claves distinguirá o no entre mayúsculas y minúsculas, dependiendo del formato de archivo y del sistema operativo. Para evitar problemas de portabilidad, consulta las reglas de Section and Key Syntax.

Nota: En las versiones de Qt anteriores a la 6.4, esta función aceptaba QString, no QAnyStringView.

Véase también value() y setValue().

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

Devuelve el formato de archivo predeterminado que se utiliza para almacenar la configuración del constructor de ` QSettings` (QObject *). Si no se ha establecido ningún formato predeterminado, se utiliza ` QSettings::NativeFormat `.

Véase también setDefaultFormat() y format().

void QSettings::endArray()

Cierra el array que se creó mediante beginReadArray() o beginWriteArray().

Véanse también beginReadArray() y beginWriteArray().

void QSettings::endGroup()

Restablece el grupo a su estado anterior a la llamada correspondiente a beginGroup().

Ejemplo:

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

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

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

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

Véanse también beginGroup() y group().

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

Reimplementa: ` QObject::event(QEvent *e)`.

bool QSettings::fallbacksEnabled() const

Devuelve « true » si las opciones de reserva están activadas; en caso contrario, devuelve « false ».

Por defecto, los valores de reserva están activados.

Véase también setFallbacksEnabled().

QString QSettings::fileName() const

Devuelve la ruta en la que se almacenan los ajustes configurados mediante este objeto ` QSettings `.

En Windows, si el formato es QSettings::NativeFormat, el valor devuelto es una ruta del registro del sistema, no una ruta de archivo.

Véase también isWritable() y format().

QSettings::Format QSettings::format() const

Devuelve el formato utilizado para almacenar la configuración.

Véase también defaultFormat(), fileName(), scope(), organizationName() y applicationName().

QString QSettings::group() const

Devuelve el grupo actual.

Véase también beginGroup() y endGroup().

bool QSettings::isAtomicSyncRequired() const

Devuelve ` true ` si ` QSettings ` solo puede realizar operaciones atómicas de guardado y recarga (sincronización) de los ajustes. Devuelve ` false ` si se permite guardar el contenido de los ajustes directamente en el archivo de configuración.

El valor por defecto es ` true`.

Véase también setAtomicSyncRequired() y QSaveFile.

bool QSettings::isWritable() const

Devuelve ` true ` si se pueden escribir los ajustes utilizando este objeto ` QSettings `; en caso contrario, devuelve ` false `.

Una de las razones por las que isWritable() podría devolver «false» es que QSettings opere sobre un archivo de solo lectura.

Advertencia: Esta función no es totalmente fiable, ya que los permisos del archivo pueden cambiar en cualquier momento.

Véase también fileName(), status() y sync().

QString QSettings::organizationName() const

Devuelve el nombre de la organización utilizado para almacenar la configuración.

Véase también QCoreApplication::organizationName(), format(), scope() y applicationName().

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

Registra un formato de almacenamiento personalizado. Si la operación se realiza correctamente, devuelve un valor de «Format» especial que luego se puede pasar al constructor de « QSettings ». Si se produce un error, devuelve « InvalidFormat ».

extension es la extensión de archivo asociada al formato (sin el «.»).

Los parámetros ` readFunc ` y ` writeFunc ` son punteros a funciones que leen y escriben un conjunto de pares clave/valor. El parámetro ` QIODevice ` de las funciones de lectura y escritura siempre se abre en modo binario (es decir, sin el indicador ` QIODeviceBase::Text `).

El parámetro caseSensitivity especifica si se distingue entre mayúsculas y minúsculas en las claves. Esto influye a la hora de buscar valores mediante QSettings. Por defecto, se distingue entre mayúsculas y minúsculas. En sistemas Unix, el parámetro debe ser Qt::CaseSensitive.

Por defecto, si se utiliza uno de los constructores que funcionan con un nombre de organización y un nombre de aplicación, las ubicaciones del sistema de archivos utilizadas son las mismas que para ` IniFormat`. Utilice ` setPath()` para especificar otras ubicaciones.

Ejemplo:

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

    //...
}

Nota: Esta función es segura para subprocesos.

Véase también setPath().

void QSettings::remove(QAnyStringView key)

Elimina la configuración « key » y cualquier subconfiguración de « key ».

Ejemplo:

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

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

Ten en cuenta que, si una de las ubicaciones de reserva contiene una configuración con la misma clave, dicha configuración seguirá siendo visible tras llamar a remove().

Si ` key ` es una cadena vacía, se eliminarán todas las claves de la configuración actual ` group()`. Por ejemplo:

QSettings settings;
settings.setValue("ape", 0);
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"]

La búsqueda de claves puede distinguir o no entre mayúsculas y minúsculas, dependiendo del formato de archivo y del sistema operativo. Para evitar problemas de portabilidad, consulta las reglas de Section and Key Syntax.

Nota: En las versiones de Qt anteriores a la 6.4, esta función aceptaba QString, no QAnyStringView.

Véanse también setValue(), value() y contains().

QSettings::Scope QSettings::scope() const

Devuelve el ámbito utilizado para almacenar la configuración.

Véase también format(), organizationName() y applicationName().

void QSettings::setArrayIndex(int i)

Establece el índice actual del array en i. Las llamadas a funciones como setValue(), value(), remove() y contains() actuarán sobre la entrada del array correspondiente a ese índice.

Debes llamar a beginReadArray() o beginWriteArray() antes de poder llamar a esta función.

void QSettings::setAtomicSyncRequired(bool enable)

Configura si se requiere que QSettings realice un guardado y una recarga atómicos (sincronización) de la configuración. Si el argumento enable tiene el valor true (por defecto), sync() solo realizará operaciones de sincronización que sean atómicas. Si esto no es posible, sync() fallará y status() dará lugar a una condición de error.

Al establecer esta propiedad en false, se permitirá que QSettings escriba directamente en el archivo de configuración e ignore cualquier error al intentar bloquearlo frente a otros procesos que intenten escribir al mismo tiempo. Debido al riesgo de corrupción, esta opción debe utilizarse con precaución, pero resulta necesaria en determinadas condiciones, como en el caso de un archivo de configuración QSettings::IniFormat que se encuentre en un directorio en el que, por lo demás, no se pueda escribir, o en el caso de las secuencias de datos alternativas de NTFS.

Consulte QSaveFile para obtener más información sobre esta característica.

Véase también isAtomicSyncRequired() y QSaveFile.

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

Establece el formato de archivo predeterminado en el especificado en format, que se utiliza para almacenar la configuración del constructor QSettings(QObject *).

Si no se establece ningún formato predeterminado, se utiliza QSettings::NativeFormat. Consulta la documentación del constructor QSettings que estés utilizando para comprobar si dicho constructor ignorará esta función.

Véanse también defaultFormat() y format().

void QSettings::setFallbacksEnabled(bool b)

Establece si las opciones de reserva están activadas en b.

Por defecto, las opciones de reserva están activadas.

Véase también fallbacksEnabled().

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

Establece la ruta utilizada para almacenar la configuración de los archivos « format » y « scope » en « path ». El archivo « format » puede tener un formato personalizado.

La siguiente tabla resume los valores predeterminados:

PlataformaFormatoÁmbitoRuta
WindowsIniFormatUserScopeFOLDERID_RoamingAppData
SystemScopeFOLDERID_ProgramData
UnixNativeFormat, IniFormatUserScope$HOME/.config ($XDG_CONFIG_HOME)
SystemScope/etc/xdg
macOSIniFormatUserScope$HOME/.config ($XDG_CONFIG_HOME)
SystemScope/Library/Preferences/Qt
iOSIniFormatUserScope$HOME/Library/Preferences
SystemScope/Library/Preferences/Qt
macOS e iOSNativeFormatUserScope$HOME/Library/Preferences
SystemScope/Library/Preferences

Las rutas predeterminadas de « SystemScope » se pueden anular al compilar Qt pasando « -sysconfdir » al script « configure » (consulta QLibraryInfo para obtener más detalles).

Nota: La configuración de las rutas de « NativeFormat » en Windows, macOS e iOS no tiene ningún efecto.

Advertencia: Esta función no afecta a los objetos QSettings existentes.

Véase también registerFormat().

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

Establece el valor de la configuración « key » en « value ». Si la configuración « key » ya existe, se sobrescribe el valor anterior.

La búsqueda de claves distinguirá o no entre mayúsculas y minúsculas, dependiendo del formato de archivo y del sistema operativo. Para evitar problemas de portabilidad, consulta las reglas de Section and Key Syntax.

Ejemplo:

QSettings settings;
settings.setValue("interval", 30);
settings.value("interval").toInt();     // returns 30

settings.setValue("interval", 6.55);
settings.value("interval").toDouble();  // returns 6.55

Nota: En las versiones de Qt anteriores a la 6.4, esta función aceptaba QString, no QAnyStringView.

Véase también value(), remove() y contains().

QSettings::Status QSettings::status() const

Devuelve un código de estado que indica el primer error detectado por QSettings, o QSettings::NoError si no se ha producido ningún error.

Ten en cuenta que QSettings retrasa la ejecución de algunas operaciones. Por este motivo, es posible que te interese llamar a sync() para asegurarte de que los datos almacenados en QSettings se escriben en el disco antes de llamar a status().

Véase también sync().

void QSettings::sync()

Guarda en el almacenamiento permanente cualquier cambio no guardado y vuelve a cargar cualquier configuración que haya sido modificada entretanto por otra aplicación.

Esta función se invoca automáticamente desde el destructor de ` QSettings` y mediante el bucle de eventos a intervalos regulares, por lo que normalmente no es necesario invocarla manualmente.

Véase también status().

QVariant QSettings::value(QAnyStringView key) const

QVariant QSettings::value(QAnyStringView key, const QVariant &defaultValue) const

Devuelve el valor de la configuración « key ». Si la configuración no existe, devuelve « defaultValue ».

Si no se especifica ningún valor por defecto, se devuelve el valor predeterminado de « QVariant ».

La búsqueda de claves puede distinguir o no entre mayúsculas y minúsculas, dependiendo del formato de archivo y del sistema operativo. Para evitar problemas de portabilidad, consulta las reglas de Section and Key Syntax.

Ejemplo:

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

Nota: En las versiones de Qt anteriores a la 6.4, esta función aceptaba QString, no QAnyStringView.

Véase también setValue(), contains() y remove().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.