Settings API

To provide a clean and consistent API for settings and storage we need to be clear about what is application local (user preferences) vs global (system settings). Also some things can be set by environment variables to override settings.

App.Preferences

The following items are proposed as additions to the existing Preferences API.

Interface and complex types (to be discussed)

We should support complex types as well - the underlying struct must support JSON marshalling - exported types will be persisted and the Go language tags for json can be used to configure how it is stored.

Get(key string, value interface{})

Access a complex type that was stored previously - the developer must pass in the struct to be filled.

Set(key string, value interface{})

Store a complex type, any struct with exported values can be persisted in this manner. It will use the builtin JSON encoding to store the values.

App.SecurePreferences

A proposed extension would allow encrypted storage of application secret preferences.

App.Cache

The correct location to cache documents or assets that you don't want to keep in memory.

Save

Create a new cache entry with specified name and content.

Load

Get the content of a named cache entry.

Remove

Clear the content of a named cache entry.

---

Released in 2.1

---

App.Storage

A place where an application can store user documents - within the standard user documents directory. This will usually be a simple filesystem abstraction but may vary across different platforms.

Create(name string) (fyne.URIWriteCloser, error)

Create a new (empty) document with a simple string identifier (like filename). The document must not exist with this name when calling - an error will be thrown if one exists.

Open(name string) (fyne.URIReadCloser, error)

Open an existing document from its identifier. Will error if the document does not exist.

Save(name string) (fyne.URIWriteCloser, error)

Save to an existing document from its identifier. Will error if the document does not exist.

Remove(name string) error

Delete a named document from the storage.

List() []string

Return a list of available document names for the given application.

---

Released in 1.3

---

fyne.URI

To support managing documents and files across multiple platforms we cannot simply pass around file paths for the generic io handling. On some platforms files use a URI instead of path. Some platforms also require that we call privileged API to read the data, so we should wrap them and handle this automatically.

type URIReadCloser interface {
    io.ReadCloser
    Name()     string
    URI()      string
}

type URIWriteCloser interface {
    io.WriteCloser
    URI()      string
}

The fyne.URIReadCloser type will be returned by the dialog.ShowOpenFile() callback and the file.URIWriteCloser will be returned by the callback of dialog.ShowSaveFile(). Usage of the reader and writer streams will handle permissions etc automatically but must be Close()d after use.

In addition to this a developer may wish to re-open an existing file reference (for example, storing an accessed file in a "recent" list. To do this the developer will use the file identifier (from previously calling URIReadCloser.URI()), and then pass that to the following function:

func OpenFileFromURI(uri string) (URIReadCloser, error)
func SaveFileToURI(uri string) (URIWriteCloser, error)

In addition the documents section described below will use this type so that the storage behind the scenes can be appropriate to the operating system.

---

Released in 1.2

---

The items in this section have been implemented

fyne.Settings

The settings API for fyne provides information about global values. These can be configured by the user of a system. Some of these values can be overridden by the application.

Theme

The user can set their preferred theme that will apply to applications if they don't override.

It can be overridden by the user with FYNE_THEME. It can also be set by the application if the developer wants to use a custom theme.

AddChangeListener

An application can listen to changes in global settings. This will occur if a user changes their settings like by using the fyne_settings helper.

App.UniqueID

For the sections below about app storage we will require a App.UniqueID which will have to be set through a new constructor or directly on the app instance. Global settings can function without this addition. This could be added without breaking the existing API and helpful errors can indicate when storage functions are used without an appropriate identifier set.

App.Preferences

A key value store of primitive preferences for an application. All basic types can be stored with simple typed APIs.

GetString(key string):string

Access a user configuration string that was stored previously.

SetString(key string, value string)

Allows an application to store a user configuration string for later access.

Additional types to add...

Additional typed versions (like GetFloat or SetBool) should be added to avoid conversions.