Storing Additional Data From a Plugin

Certain plugins might have the need to store (and retrieve) additional information, be it preferences and general configuration settings or specific workspace related settings. This guide will walk you through the various options and explain when, why and how to use them.

Preferences

See also: https://github.com/Ultimaker/Uranium/blob/master/UM/Preferences.py

Preferences are application-based settings that are saved for future use. Typical preferences would be window size, standard machine or default behavior for certain user interaction ("Always", "Never", "Ask"). There is no need to worry if the preferences are correctly stored to file since this is already handled by the application.

A preference first needs to be registered before it can be used. This is usually done in the initialization of your plugin object. Registering a preference also sets the default value of that preference. If the preference has never been added, it will be added with the default value. If the stored preference ever mentions a different value, that value is used instead.

preferences = Application.getInstance().getPreferences()
preferences.addPreference("yourPluginNamespace/preferenceThatStoresNumber", 12)
preferences.addPreference("yourPluginNamespace/preferenceThatStoresString", "omg")
preferences.addPreference("yourPluginNamespace/preferenceThatStoresBool", True)

Note that preferences must be stored in a specific namespace, as such a preference tag must adhere to the following format:

"{namespace}/{preference_name}".format(namespace = "whatever", preference_name = "preference")

Setting the value of a preference can be done by:

preferences = Application.getInstance().getPreferences()
preferences.getValue("yourPluginNamespace/preferenceThatStoresNumber")  # 12
preferences.getValue("yourPluginNamespace/preferenceThatStoresString")  # "omg"
preferences.getValue("yourPluginNamespace/preferenceThatStoresBool")  # True

Finally, changing the value of a preference can be done by:

preferences = Application.getInstance().getPreferences()
# The preference doesn't care what type it is, to it's always possible to change it. 
preferences.setValue("yourPluginNamespace/preferenceThatStoresNumber", "whatever") 

The preferences object also has a signal that emits on change. This can be useful if there are multiple parts in a plugin that have behavior which depends on what is in the preferences. This signal preferenceChanged is emitted on every change with the full key of the changed preference as it's parameter.

WorkspaceMetadata

See also https://github.com/Ultimaker/Uranium/blob/master/UM/Workspace/WorkspaceMetadataStorage.py

The workspace metadata is, as the name already implies, extra data that will be stored together with the workspace / project. This data will be cleared when a new project is started (QtApplication.getInstance().resetWorkspace()) and overridden when a new project is loaded. As such, only data that is explicitly part of the given workspace should be stored here.

Note; Clearing the build plate will not reset this data.

metadata_storage = Application.getInstance().getWorkspaceMetadataStorage()
metadata_storage.setEntryToStore("namespace", "value_identifier", 12)
metadata_storage.setEntryToStore("namespace", "value_identifier_2", {"nested_value_identifier": 12})
metadata_storage.setEntryToStore("namespace", "value_identifier_3", "zomg")

If a workspace has finished loading (As indicated by the workspaceLoaded signal of the Application) and your plugin might want to retrieve some data, you can do the following:

metadata_storage = Application.getInstance().getWorkspaceMetadataStorage()
stored_data = metadata_storage.getPluginMetadata("namespace")