Home / Lua API Manual / darktable / darktable.tags
< darktable.styles
types >

# darktable.tags

Allows access to all existing tags.

# 🔗darktable.tags.#

types.dt_lua_tag_t

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

# 🔗darktable.tags.create

    function(
      name : string
    )

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

- name - string - The name of the new tag.

# 🔗darktable.tags.find

    function(
      name : string
    ) : types.dt_lua_tag_t

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

- name - string - The name of the tag to find.
- return - _ types.dt_lua_tag_t_ - The tag object or nil.

# 🔗darktable.tags.delete

    function(
      tag : types.dt_lua_tag_t
    )

Deletes the tag object, detaching it from all images.

- tag - types.dt_lua_tag_t - The tag to be deleted.

# 🔗darktable.tags.attach

    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.

- tag - types.dt_lua_tag_t - The tag to be attached.
- image - types.dt_lua_image_t - The image to attach the tag to.

# 🔗darktable.tags.detach

    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.

- tag - types.dt_lua_tag_t - The tag to be detached.
- image - types.dt_lua_image_t - The image to detach the tag from.

# 🔗darktable.tags.get_tags

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

Gets all tags attached to an image.

- image - types.dt_lua_image_t - The image to get the tags from.
- return - table of types.dt_lua_tag_t - A table of tags that are attached to the image.

# 🔗darktable.tags.get_tagged_images

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

Gets all images with the attached tag.

- tag - types.dt_lua_tag_t - The tag to search images for.
- return - table of types.dt_lua_image_t - A table of images that have the tag attached.

< darktable.styles
types >