• Home
• Felgo
• Storage

Storage

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

• List of all members, including inherited members

Properties

• clearAllAtStartup : bool
• databaseName : string

Methods

• clearAll()
• clearValue(key)
• getValue(key, callback)
• setValue(key, value)

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
     }
   }


 }

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
      }
    }
  }
 }

Property Documentation

Method Documentation

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

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