Read and write preferences

An ArcOS user has an object called the UserPreferences interface. It's a multidimensional object containing settings saved by ArcOS and its applications. Effectively anything the user can set that doesn't involve the account credentials is saved in here.

The User Daemon has a Svelte Store named preferences, which is initialised when the user logs in. Any changes made to this object are immediately saved to the server, and dispatched to other clients using Global Dispatch.

Getting a preference

To get a preference in your app process, call this.userPreferences(). It returns the user preferences as a regular JS object:

const accent = this.userPreferences()?.desktop.accent;

Assuming your editor supports it, you'll get autofill suggestions as you're typing, to figure out where to find the preference you're looking for.

Updating the preferences

Updating the preferences IS RISKY. If you forget to return the preferences in the update callback, the user will lose their ArcOS preferences in an instant. I'll implement checks in the future to prevent this, but for the moment: DO NOT FORGET TO RETURN THE PREFERENCES.

The first way to change the user preferences is to call this.userPreferences.update in your process class. This function takes a callback that expects the user preferences to be returned! If you forget to return the user preferences after you've modified them, the preferences of the user WILL BE LOST. Be careful. Here's an example:

this.userPreferences.update((v) => {
  v.desktop.accent = "#FF00FF";
  return v; // <- DO NOT FORGET TO RETURN!!!!
})

Setting the preferences

If you've retrieved the user preferences using this.userPreferences(), and you've modified them in the midst of another operation, you can manually save them back into the variable using this.userPreferences.set:

const preferences = this.userPreferences();

// Do something...

this.userPreferences.set(preferences);

You're not supposed to have a large amount of time between getting and setting the preferences, because of desynchronisation. Basically it means that if you get the preferences, and something else changes them before you set them back, you'll accidentally roll back the state of the user's preferences, causing confusion and a potential loss of information. Perform time-intensive operations before getting the preferences to prevent this.

App preferences

When you app's process is constructed, it creates a key in the appPreferences object. Take a look at this snippet from the base AppProcess source code:

src/ts/apps/process.ts -> AppProcess -> constructor

const preferences = this.userPreferences();

if (!preferences.appPreferences[app.id]) {
  this.userPreferences.update((v) => {
    v.appPreferences[app.id] = {};

    return v;
  });
}

You can use this object to store settings specific to your applications. For example, the File Manager uses this to store the view mode.

Getting an app preference

Use this snippet to get app preferences of your app:

const appPref = this.userPreferences().appPreferences[this.app.id];

Setting an app preference

Similarly, use this snippet to set a preference:

this.userPreferences.update((v) => {
  v.appPreferences[this.app.id]. = ;
  
  return v; // <- DO NOT FORGET TO RETURN!!!!
})