Persistent data

Persistent data allows you to save app settings to the persistent store and load them when they are needed. The persistent store lets you save objects to persistent memory, and these objects are retained in memory after a device is restarted. Persistent data improves the user experience of an app by making sure that if a user customizes an app's settings, these settings are preserved and used until the user changes them.

You can use persistent data to store app settings, but not app data. If you need to save app data, you should use one of the other supported formats, such as JSON, SQL, and XML.

Persistent data in Cascades is handled by the QSettings class. The QSettings class provides persistent app settings that are platform-independent. The QSettings class is based on QVariant, which allows you to save and retrieve several value-based types, such as QString, QRect, and QImage with minimal code.

Using persistent data in C++

Cascades uses organization and application names to save settings values to the persistent store. When you create a QSettings object, you must pass in the name of your organization and the name of your application. The following code sample shows you how to create a QSettings object with an organization name of "MyOrganization" and an application name of "MyApp":

QSettings settings("MyOrganization", "MyApp");

If you plan to use QSettings from more than one place in your application, you can declare your organization and application name using QCoreApplication::setOrganizationName() and QCoreApplication::setApplicationName() in the default constructor:

QCoreApplication::setOrganizationName("MyOrganization");
QCoreApplication::setApplicationName("MyApp");

After you provide the organization and application names for your QSettings object, you can store settings using the setValue() function. To store a value, you call the setValue() function and provide a key (a name for the setting) and an associated value for your setting. The example below uses a key of "mainwindow/size" and uses the size() function to return the current size of the window and store it.

settings.setValue("mainwindow/size", win->size());

The example above uses the '/' character as a separator, similar to UNIX file paths. Separators allow you to group your settings in a logical hierarchy. You can also use the beginGroup() and endGroup() functions to store and retrieve settings with the same prefix:

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

After you save a value to the persistent store, you can retrieve it using the value() function:

QString fullScreenSetting = settings.value("mainwindow/fullScreen");

Using persistent data in QML

Cascades doesn't support saving and retrieving persistent data directly in QML. If you want to use persistent data in QML, you still need to use C++ to pass in the organization and application name, as well as for the save and retrieve functions.

The following series of code samples are used in the StarshipSettings sample app. If you want to see the full sample, check out the Sample apps page.

To use persistent data in QML, the first thing you need to do is pass in your organization and application name, in C++:

// Set the organization and application name, which is used by QSettings
// when saving values to the persistent store.
QCoreApplication::setOrganizationName("Example");
QCoreApplication::setApplicationName("Starship Settings");

Then create a custom function to retrieve any saved settings in C++:

QString StarshipSettingsApp::getValueFor(const QString &objectName, const QString &defaultValue)
{
    QSettings settings;

    // If no value has been saved, return the default value.
    if (settings.value(objectName).isNull()) {
        return defaultValue;
    }

    // Otherwise, return the value stored in the settings object.
    return settings.value(objectName).toString();
}

You also need a function to save the settings in C++:

void StarshipSettingsApp::saveValueFor(const QString &objectName, const QString &inputValue)
{
    // A new value is saved to the application settings object.
    QSettings settings;
    settings.setValue(objectName, QVariant(inputValue));
}

After you pass in your names and create your custom functions, you can access the persistent store from QML:

CheckBox {
    id: uranuscanner
    text: qsTr("URANUS SCANNER") + Retranslate.onLanguageChanged
    objectName: "uranuscanner"
    checked: _starshipApp.getValueFor(objectName, "yes") == "true" ? true : false
    onCheckedChanged: {
        _starshipApp.saveValueFor(uranuscanner.objectName, checked)
    }
}

The _starshipApp object is registered as a context property in C++, which makes the functions in that class available for use in QML. For more information, see QML and C++ integration.

The example above calls your custom getValueFor() function to retrieve stored settings (either user-selected or default) and uses the value to set the checked state of the CheckBox control. When the checkedChanged() signal is emitted, the saveValueFor() function is called to update the value in the persistent store.

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus