Lua API

types.dt_lua_film_t

Each film has a numeric entry in the database.

function( 
	directory : string
) : types.dt_lua_film_t

Creates a new empty film

see darktable.database.import to import a directory with all its images and to add images to a film

see types.dt_lua_film_t.delete

table

A table of types.dt_lua_image_t on which the user expects UI actions to happen.

It is based on both the hovered image and the selection and is consistent with the way darktable works.

It is recommended to use this table to implement Lua actions rather than darktable.gui.hovered or darktable.gui.selection to be consistent with darktable's GUI.

types.dt_lua_image_t

The image under the cursor or nil if no image is hovered.

function( 
	[selection : table of types.dt_lua_image_t]
) : table of types.dt_lua_image_t

Allows to change the set of selected images.

function( 
	[view : types.dt_lua_view_t]
) : types.dt_lua_view_t

Allows to change the current view.

function( 
	text : string, 
	[percentage : boolean], 
	[cancel_callback : function]
) : types.dt_lua_backgroundjob_t

Create a new progress_bar displayed in darktable.gui.libs.backgroundjobs

The different views in darktable

number

number

number

This table allows to reference all lib objects

lib are the graphical blocks within each view.

To quickly figure out what lib is what, you can use the following code which will make a given lib blink.

local tested_module="global_toolbox"
dt.gui.libs[tested_module].visible=false
coroutine.yield("WAIT_MS",2000)
while true do
	dt.gui.libs[tested_module].visible = not dt.gui.libs[tested_module].visible
	coroutine.yield("WAIT_MS",2000)
end

number

types.snapshot_direction_t

types.dt_lua_snapshot_t

types.dt_lua_snapshot_t

function( 
)

number

function( 
	[rules : array oftypes.dt_lib_collect_params_rule_t]
) : array oftypes.dt_lib_collect_params_rule_t

function( 
) : types.dt_lib_collect_params_rule_t

function( 
	widget : types.lua_widget
)

function( 
	name : string, 
	callback : function
)

boolean

boolean

function( 
	label : string, 
	callback : function, 
	[tooltip : string]
)

function( 
	label : string, 
	callback : function, 
	[tooltip : string]
)

function( 
	name : string, 
	draw_callback : function, 
	[gui_callback : function]
)

Register a new guide.

types.dt_lua_tag_t

Each existing tag has a numeric entry in the tags table - use ipairs to iterate over them.

function( 
	name : string
)

Creates a new tag and return it. If the tag exists return the existing tag.

function( 
	name : string
) : types.dt_lua_tag_t

Returns the tag object or nil if the tag doesn't exist.

function( 
	tag : types.dt_lua_tag_t
)

Deletes the tag object, detaching it from all images.

function( 
	tag : types.dt_lua_tag_t, 
	image : types.dt_lua_image_t
)

Attach a tag to an image; the order of the parameters can be reversed.

function( 
	tag : types.dt_lua_tag_t, 
	image : types.dt_lua_image_t
)

Detach a tag from an image; the order of the parameters can be reversed.

function( 
	image : types.dt_lua_image_t
) : table of types.dt_lua_tag_t

Gets all tags attached to an image.

string

The version number of darktable.

boolean

True if darktable has a GUI (launched through the main darktable command, not darktable-cli).

boolean

True if the Lua logdomain is enabled.

string

The name of the directory where darktable will store temporary files.

string

The name of the directory where darktable will find its global configuration objects (modules).

string

The name of the directory where darktable will store its mipmaps.

number

The major version number of the lua API.

number

The minor version number of the lua API.

number

The patch version number of the lua API.

string

The version suffix of the lua API.

string

The version description of the lua API. This is a string compatible with the semantic versioning convention

string

The name of the Operating system darktable is currently running on

function( 
	module_name : string, 
	... : table...
)

Check that a module is compatible with the running version of darktable

Add the following line at the top of your module :

darktable.configuration.check(...,{M,m,p},{M2,m2,p2})

To document that your module has been tested with API version M.m.p and M2.m2.p2.

This will raise an error if the user is running a released version of DT and a warning if he is running a development version

(the ... here will automatically expand to your module name if used at the top of your script

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...], 
	[wiget : 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).

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

Reads a value from a Lua preference.

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

Writes a value to a Lua preference.

types.dt_style_t

Each existing style has a numeric index; you can iterate them using ipairs.

function( 
	image : types.dt_lua_image_t, 
	name : string, 
	description : string
) : types.dt_style_t

Create a new style based on an image.

function( 
	style : types.dt_style_t
)

Deletes an existing style.

function( 
	style : types.dt_style_t, 
	name : string, 
	description : string
) : types.dt_style_t

Create a new style based on an existing style.

function( 
	style : types.dt_style_t, 
	image : types.dt_lua_image_t
)

Apply a style to an image. The order of parameters can be inverted.

function( 
	filename : string
)

Import a style from an external .dtstyle file

function( 
	style : types.dt_style_t, 
	directory : string, 
	overwrite : boolean
)

Export a style to an external .dtstyle file

types.dt_lua_image_t

Each image in the database appears with a numerical index; you can iterate them using ipairs.

function( 
	image : types.dt_lua_image_t
) : types.dt_lua_image_t

Creates a duplicate of an image and returns it.

function( 
	location : string
) : types.dt_lua_image_t

Imports new images into the database.

function( 
	image : types.dt_lua_image_t, 
	film : types.dt_lua_film_t
)

Physically moves an image (and all its duplicates) to another film.

This will move the image file, the related XMP and all XMP for the duplicates to the directory of the new film

Note that the parameter order is not relevant.

function( 
	image : types.dt_lua_image_t, 
	film : types.dt_lua_film_t
) : types.dt_lua_image_t

Physically copies an image to another film.

This will copy the image file and the related XMP to the directory of the new film

If there is already a file with the same name as the image file, it will create a duplicate from that file instead

Note that the parameter order is not relevant.

see types.dt_lua_image_t.delete

types.dt_lua_image_t

Each image in the collection appears with a numerical index; you can iterate them using ipairs.

boolean

TRUE when darktable is terminating

Use this variable to detect when you should finish long running jobs

function( 
	function : function, 
	... : anything
)

Runs a function in the background. This function will be run at a later point, after luarc has finished running. If you do a loop in such a function, please check darktable.control.ending in your loop to finish the function when DT exits

function( 
	delay : int
)

Suspends execution while not blocking darktable

function( 
	command : string
) : int

Run a command in a shell while not blocking darktable

function( 
	file : file
)

Block until a file is readable while not blocking darktable

This function is not available on Windows builds

function( 
	msgid : string
) : string

Translate a string using the darktable textdomain

function( 
	domainname : string, 
	msgid : string
) : string

Translate a string using the specified textdomain

function( 
	msgid : string, 
	msgid_plural : string, 
	n : int
) : string

Translate a string depending on the number of objects using the darktable textdomain

function( 
	domainname : string, 
	msgid : string, 
	msgid_plural : string, 
	n : int
) : string

Translate a string depending on the number of objects using the specified textdomain

function( 
	domainname : string, 
	dirname : string
)

Tell gettext where to find the .mo file translating messages for a particular domain

function( 
	object : anything, 
	[name : string], 
	[known : table]
) : string

This will return a string describing everything Lua knows about an object, used to know what an object is. This function is recursion-safe and can be used to dump _G if needed.

boolean

Initialized to false; set it to true to also dump information about metatables.

number

Initialized to 10; The maximum depth to recursively dump content.

table

A table containing the default value of darktable.debug.dump.known

function( 
	object : anything
) : string

Similar to the system function type() but it will return the real type instead of "userdata" for darktable specific objects.