darktable.preferences

table

Lua allows you to manipulate preferences. Lua has its own namespace for preferences and you can’t write normal darktable preferences. Preference handling functions take a script parameter. This is a string used to avoid name collision in preferences (i.e namespace). Set it to something unique, usually the name of the script handling the preference. Preference handling functions can’t guess the type of a parameter. You must pass the type of the preference you are handling. Note that the directory, enum, lua and file type preferences are stored internally as string. The user can only select valid values, but a lua script can set it to any string

🔗darktable.preferences.register

function(
  script : string,
  name : string,
  type : types.lua_pref_type,
  label : string,
  tooltip : string,
  [default : depends on type],
  [min : int or float],
  [max : int or float],
  [step : float],
  [values : string...],
  [widget : types.lua_widget],
  [set_callback : function]
)

Creates a new preference entry in the Lua tab of the preference screen. If this function is not called the preference can’t be set by the user (you can still read and write invisible preferences).

script - string - Invisible prefix to guarantee unicity of preferences.
name - string - A unique name used with the script part to identify the preference.
type - _types.lua_pref_type_The type of the preference - one of the string values described above.
label - string - The label displayed in the preference screen.
tooltip - string - The tooltip to display in the preference menu.
[default] - Thedepends on type - Default value to use when not set explicitly or by the user. For the enum type of pref, this is mandatory
[mi] - int or float - Minimum value (integer and float preferences only).
[max] - int or float - Maximum value (integer and float preferences only).
[step] - float - Step of the spinner (float preferences only).
[values] - string - Other allowed values (enum preferences only)
[widget] - types.lua_widget - The widget to use in preference (lua preferences only)
[set_callback] - function_ - A function called when the widget needs to be updated from the preference

[set_callback] -

function(
  widget : types.lua_widget
)

A function called when the widget needs to be updated from the preference

widget - types.lua_widget - The widget to update

🔗darktable.preferences.read

function(
  script : string,
  name : string,
  type : types.lua_pref_type
) : depends on type

Reads a value from a Lua preference.

script - string - Invisible prefix to guarantee unicity of preferences. Specifying “darktable” as the script name allows access to the darktable core preferences.
name - string - The name of the preference displayed in the preference screen.
type - types.lua_pref_type - The type of the preference.
return - depends on type - The value of the preference.

🔗darktable.preferences.write

function(
  script : string,
  name : string,
  type : types.lua_pref_type,
  value : depends on type
)

Writes a value to a Lua preference.

script - string - Invisible prefix to guarantee unicity of preferences.
name - string - The name of the preference displayed in the preference screen.
type - types.lua_pref_type - The type of the preference.
value - depends on type - The value to set the preference to.

🔗darktable.preferences.destroy

function(
  script : string,
  name : string,
) : return boolean

Destroys a lua preference key and value.

script - string - Invisible prefix to guarantee unicity of preferences.
name - string - The name of the preference displayed in the preference screen.
return - boolean - True for success, false otherwise.

🔗darktable.preferences.get_keys

function(
  script : string,
  name : string,
) : return table of strings

Get all of the darktable core and lua preference keys and return them in a sorted table.

return - table of string - Sorted darktable core preference and lua preference keys.