User settings

⭐ New in 0.2.9.

User settings system loads and saves registered consumer settings transparently to application. Consumers are menu items, widgets and windows, and settings system handles loading and saving window position, widget state, radio group selection, and so on. Settings are located in user home directory, either .config or .local subdirectory. If none of those two directories exists, application user home directory is used.

See FOSS Mixer and Desktop menu demo for live example.

Functions

Each settings function explained.

settings_register

Register settings consumer to update its state to user setting system. User settings are loaded and saved automatically by the engine.

Returns settings handle on success, zero on failure.

handle
settings_register([string] consumer_name, [string] consumer_class)

consumer_name is the name of the consumer, like menu item key or widget unique name.
consumer_class can be one of:

SETTINGS_CLASS_CUSTOM is used when consumer_name is Ano script variable name,
SETTINGS_CLASS_MENU is used when consumer_name is menu item key,
SETTINGS_CLASS_WIDGET is used when consumer_name is widget unique name, and
SETTINGS_CLASS_WINDOW is used when consumer_name is window title.

SETTINGS_CLASS_CUSTOM class can be used to store variable values in settings. This example increases variable value by one each time it runs:

main [exit: 0] {
	; Program that increases my_var by one.
	;
	settings_register (\
		consumer_name: "my_var", \
		consumer_class: SETTINGS_CUSTOM)

	; Initialize variable, its initial value is fetched from settings.
	;
	var [number] my_var

	; Dump it out and increase by one, its value and type is saved
	; automatically back to settings when program terminates.
	;
	dump	my_var
	inc	my_var
}

settings_unregister

Unregister settings consumer. Unregistering detaches consumer from user settings system, so consumer state is not updated or saved to settings after this call returns succesfully. Normally there is no need to unregister settings consumer.

Returns zero on success, non-zero on failure.

int
settings_unregister([handle] settings_handle)

settings_handle is the handle returned by settings_register().

settings_flush

Save settings immediately if certain conditions are met. Registered consumer settings will not be saved if some menu item has follow_settings_saving flag and its state is not set. If menu subsystem is not in use, settings are saved unconditionally. Engine saves settings automatically when program exits, so there is necessarily no need for manual saving.

Returns zero on success, non-zero on failure.

int
settings_flush([int] settings_scope)

settings_scope is either:

SETTINGS_SCOPE_LOCAL is application default, saves settings beneath user home directory,
SETTINGS_SCOPE_GLOBAL saves settings to system database directory, location depends on operating system but is usually located somewhere under /var, and
SETTINGS_SCOPE_DEFAULT is whichever scope is the default.

settings_sync

Save settings immediately. Engine saves settings automatically when program exits, so there is necessarily no need for manual saving.

Returns zero on success, non-zero on failure.

int
settings_sync([int] settings_scope)

settings_scope is explained in settings_flush() section.

settings_save_forbid

Forbid saving settings by increasing forbid counter by one. Settings are saved only if counter is zero, meaning that settings_save_permit() function must be called to decrease the counter before settings are saved. Forbid counter resets to zero when last consumer unregisters itself.

void
settings_save_forbid()

settings_save_permit

Permit saving settings by decreasing forbid counter by one. Settings are saved only if counter is zero, meaning this function must be called equal amount of times than settings_save_forbid() was called. Forbid counter resets to zero when last consumer unregisters itself.

void
settings_save_permit()