Learn what Felgo offers to help your business succeed. Start your free evaluation today! Felgo for Your Business

Storage

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

Import Statement: import Felgo 4.0
Inherits:

Item

Properties

Methods

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 QML Types 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 Felgo
 import QtQuick

 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.id, fruit) you will get the fruit object when you call getValue().

See the following example:

 import Felgo
 import QtQuick

 GameWindow {

   Storage {
     id: myLocalStorage

     Component.onCompleted: {

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

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

         // NOTE: no JSON.stringify() needed - it is called automatically in setValue()
         myLocalStorage.setValue(fruit.id, fruit)
       } else {
         console.debug("the fruit with id", fruit.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
     }
   }


 }

More Storage Examples

You can also use the WebStorage to synchronize app data across multiple user devices with the Felgo Game Network service. See more info on storage, data and Firebase here: Store Data Persistent

How to use default app settings in Felgo?

The App::settings property allows to store simple key/value pairs in a local database. If you format the value as a JSON string, you can also store more complex data in a very easy way.

 import Felgo
 import QtQuick

 App {
  id: app
  // this property holds how often the app was started
  property int numberAppStarts

  Component.onCompleted: {
    // getValue() returns undefined, if no setting for this key is found, so when this is the first start of the app
    numberAppStarts = app.settings.getValue("numberAppStarts") || 0 // defaults to '0' if 'undefined' is returned
    numberAppStarts++

    app.settings.setValue("numberAppStarts", numberAppStarts)
  }

  NavigationStack {

    AppPage {
      title: "Settings"

      AppText {
        anchors.centerIn: parent
        text: "App starts: " + numberAppStarts
      }
    }
  }
 }

More Frequently Asked Development Questions

Find more examples for frequently asked development questions and important concepts in the following guides:

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

clearAll()

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.


clearValue(key)

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.id, fruit)

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

See also getValue().


Qt_Technology_Partner_RGB_475 Qt_Service_Partner_RGB_475_padded