The storage item provides a persistent and offline storage for arbitrary key-value pair data. More...

Import Statement: import VPlay 2.0




Detailed Description

The Storage item encapsulates a simple key-value store which is saved permanently and accessible across the whole game.

Note: The value stored to the database, is also available after the user updated the app.

The Storage item is a key-value store wrapper and uses the Qt Quick Local Storage Module internally. For most use cases, having simple key-value data is sufficient and you thus get a more convenient way to store & access key-value data. If you have large databases though and want to make complex search queries, using the SQL syntax for these queries with the Local Storage Module is the better option.

Example Usage

The following example shows how to detect if the application starts for the first time.

 import VPlay 2.0
 import QtQuick 2.0

 GameWindow {

   property bool applicationFirstStart: false

   Storage {
     id: myLocalStorage

     Component.onCompleted: {

       var isFirstStartApplication = myLocalStorage.getValue("firstStart")
       if(isFirstStartApplication == undefined) {
         // if undefined is returned, this means the app was not started before
         applicationFirstStart = true

       // now the application was started at least once, so set the flag to true
       myLocalStorage.setValue("firstStart", true)

   Scene {

     SimpleButton {
       text: "Only visible if first start"
       visible: applicationFirstStart

Advanced Usage

You can store arbitrary complex data in the key-value store, and access this data with the unique key.

Let's say you have a Fruit object:

 var fruit = {id: 1, value: 100, description: "Some text."}

Now, when you call setValue() you can take the id as the key and the whole object as the value.

Stringification via JSON.stringify() is done automatically when you call setValue(). So if you call myLocalStorage.setValue(, fruit) you will get the fruit object when you call getValue().

See the following example:

 import VPlay 2.0
 import QtQuick 2.0

 GameWindow {

   Storage {
     id: myLocalStorage

     Component.onCompleted: {

       var fruit = {id: 1, value: 100, description: "Some text."}

       if(!myLocalStorage.getValue( {
         console.debug("storing the fruit object with id",

         // NOTE: no JSON.stringify() needed - it is called automatically in setValue()
         myLocalStorage.setValue(, fruit)
       } else {
         console.debug("the fruit with id",, "was already stored")

   Scene {

     SimpleButton {
       text: "Press to read the fruit with id 1"

       // with getValue we get the JavaScript fruit object
       // to display its content as a string, call stringify()
       // the output is '{"id":1,"value":100,"description":"Some text."}'
       onClicked: fruitContent.text = JSON.stringify( myLocalStorage.getValue(1) )

     Text {
       id: fruitContent
       y: 40


Property Documentation

clearAllAtStartup : bool

Set this property temporarily to true to clear all local data at app startup.

This is only useful during testing, if you have faulty local data.

See also clearAll().

databaseName : string

Set this property to store the key-value pairs to a file with this name. By default, the name is an empty string. Multiple instances of the Storage element with the same databaseName have access to the same data set. The GameWindow::settings property uses the databaseName "settings" internally, so if you do not want to use the same data set avoid this name.

Method Documentation


Clears all entries in the key-values store.

This might be useful for resetting the database during development for testing.

If an error occurred, storageError() is emitted.


Clears the value for the provided key. If an error occurred, storageError() is emitted.

getValue(key, callback)

Load the previously stored value for key from the store. The returned object contains the JSON-serialized data saved before with setValue or undefined if nothing was stored for this key before.

If callback is set, the result is returned as first parameter to the callback function. The result is guaranteed to have no errors, because if an error occurs the storageError() signal is emitted.

Note: If you want to be able to also use the WebStorage component with the same API, make sure to always use the callback parameter and not rely on direct return values, because in asynchronous connections the result can take a while to load.

Here is an example call which uses the asynchronous callback functionality:

 Storage {
   id: storage

   onStorageError: {
     console.debug("there was an error:", errorData.message)

 function startLoadingValue() {
   storage.getValue("myKey", successfullyLoadedCallback)

 function successfullyLoadedCallback(result) {
   console.debug("the result was:", result)

See also setValue().

setValue(key, value)

Stores the value with the provided key permanently to the store. If an error occurred, storageError() is emitted.

Note: The value gets stringified with JSON.stringify() automatically, and is then parsed with JSON.parse() in getValue. So you can also store arbitrary complex JSON objects like the following:

 var fruit = {id: 1, value: 100, description: "Some text."}

 // NOTE: no JSON.stringify() needed - it is called automatically in setValue()
 setValue(, fruit)

 // retrieve the fruitObject, no JSON.parse() is needed
 var fruitObject = getValue(1)
 console.debug(fruitObject.description) // will output "Some text."

See also getValue().

Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
create apps
create games
cross platform
native performance
3rd party services
game network
level editor
easiest to learn
biggest time saving
best support