# See README.md for details on doc processing.
#
# The `desc` field can be formatted with markdown, but please do not include
# headings (lines beginning with `#`) in the `desc` field.
#
# The supported fields are:
#
#  * `name`: the name of the thing
#  * `desc`: a markdown-formatted description of the thing
#  * `args`: optional list of arguments
#  * `default`: an optional default value, if applicable
---
desc: |-
  Conky features a Lua Programming API, and also ships with Lua bindings
  for some useful libraries. Note that the bindings require tolua++.

  To use Lua Conky, you first need to make sure you have a version of
  Conky with Lua support enabled (`conky -v` will report this).
  Conky defines certain global functions and variables which can be
  accessed from Lua code running in Conky. Scripts must first be loaded
  using the lua_load configuration option. You then call functions in Lua
  via Conky's $lua, $lua_read, and Lua hooks.

  Be careful when creating threaded objects through the Lua API. You could
  wind up with a whole bunch of threads running if a thread is created
  with each iteration.

  NOTE: In order to accommodate certain features in the cairo library's
  API, Conky will export a few additional functions for the creation of
  certain structures. These are documented below.
values:
  - name: RsvgDimensionData:create()
    desc: |-
      Call this method to return a new RsvgDimensionData
      structure. A creation function for this structure is not provided
      by the Rsvg API.

      After calling this, you should use `tolua.takeownership(rect)` on the return
      value to ensure ownership is passed properly.
  - name: RsvgDimensionData:destroy()
    desc: |-
      Call this method to free memory allocated by
      `RsvgDimensionData:create`.

      You should call `tolua.releaseownership(dd)` before calling this function to
      avoid double-frees, but only if you previously called
      `tolua.takeownership(dd)`
  - name: RsvgDimensionData:get()
    desc: |-
      Gets the values of an existing RsvgDimensionData.
  - name: RsvgDimensionData:set(x, y, width, height)
    desc: |-
      Sets the values of an existing RsvgDimensionData.
  - name: RsvgRectangle:create()
    desc: |-
      Call this method to return a new RsvgRectangle
      structure. A creation function for this structure is not provided
      by the Rsvg API.

      After calling this, you should use `tolua.takeownership(rect)` on the return
      value to ensure ownership is passed properly.
  - name: RsvgRectangle:destroy()
    desc: |-
      Call this method to free memory allocated by
      `RsvgRectangle:create`.

      You should call `tolua.releaseownership(rect)` before calling this function to
      avoid double-frees, but only if you previously called
      `tolua.takeownership(rect)`
  - name: RsvgRectangle:get()
    desc: |-
      Gets the values of an existing RsvgRectangle.
  - name: RsvgRectangle:set(x, y, width, height)
    desc: |-
      Sets the values of an existing RsvgRectangle.
  - name: cairo_font_extents_t:create()
    desc: |-
      Call this function to return a new cairo_font_extents_t
      structure. A creation function for this structure is not provided
      by the cairo API.

      After calling this, you should use
      `tolua.takeownership(cfe)` on the return value to ensure ownership is
      passed properly.
  - name: cairo_font_extents_t:destroy(structure)
    desc: |-
      Call this function to free memory allocated by
      cairo_font_extents_t:create.

      You should call `tolua.releaseownership(cfe)` before calling this function to
      avoid double-frees, but only if you previously called
      `tolua.takeownership(cfe)`
  - name: cairo_matrix_t:create()
    desc: |-
      Call this function to return a new cairo_matrix_t structure.
      A creation function for this structure is not provided by the
      cairo API.

      After calling this, you should use
      `tolua.takeownership(cm)` on the return value to ensure ownership is
      passed properly.
  - name: cairo_matrix_t:destroy(structure)
    desc: |-
      Call this function to free memory allocated by
      cairo_matrix_t:create.

      You should call `tolua.releaseownership(cm)` before calling this function to
      avoid double-frees, but only if you previously called
      `tolua.takeownership(cm)`
  - name: cairo_place_image(file, cr, x, y, width, height, alpha)
    desc: |-
      Renders an image onto a cairo_t, using imlib2. In some cases using a cairo_t and exact coordinates is more
      useful.

      | Argument            | Description                                                                          |
      |---------------------|--------------------------------------------------------------------------------------|
      | file                | Path to the image to render.                                                         |
      | cr                  | The `cairo_t` to render to.                                                          |
      | x,y                 | Position to render the image.                                                        |
      | width, height       | The width and height to draw the image                                               |
      | alpha               | The transparency of the image 1.0 is solid 0.0 is fully translucent.                 |

      require('cairo_imlib2_helper') in your lua file.
  - name: cairo_text_extents_t:create()
    desc: |-
      Call this function to return a new cairo_text_extents_t
      structure. A creation function for this structure is not provided
      by the cairo API.

      After calling this, you should use
      `tolua.takeownership(cte)` on the return value to ensure ownership is
      passed properly.
  - name: cairo_text_extents_t:destroy(structure)
    desc: |-
      Call this function to free memory allocated by
      cairo_text_extents_t:create.

      You should call `tolua.releaseownership(cte)` before calling this function to
      avoid double-frees, but only if you previously called
      `tolua.takeownership(cte)`
  - name: conky_build_arch
    desc: |-
      A string containing the build architecture for this
      particular instance of Conky.
  - name: conky_build_info
    desc: |-
      A string containing the build info for this particular
      instance of Conky, including the version, build date, and
      architecture.
  - name: conky_config
    desc: |-
      A string containing the path of the current Conky
      configuration file.
  - name: conky_info
    desc: |-
      This table contains some information about Conky's internal
      data. The following table describes the values contained:

      | Key             | Value                                 |
      |-----------------|---------------------------------------|
      | update_interval | Conky's update interval (in seconds). |
  - name: conky_parse(string)
    desc: |-
      This function takes a string that is evaluated as per
      Conky's TEXT section, and then returns a string with the
      result.
  - name: conky_set_update_interval(number)
    desc: |-
      Sets Conky's update interval (in seconds) to
      'number'.
  - name: conky_version
    desc: |-
      A string containing the version of the current instance of
      Conky.
  - name: conky_window
    desc: |-
      This table contains some information about Conky's window.
      The following table describes the values contained:

      | Key                 | Value                                                                           |
      |---------------------|---------------------------------------------------------------------------------|
      | drawable            | Window's drawable (Xlib Drawable), requires Lua extras enabled at compile time. |
      | visual              | Window's visual (Xlib Visual), requires Lua extras enabled at compile time.     |
      | display             | Window's display (Xlib Display), requires Lua extras enabled at compile time.   |
      | width               | Window width (in pixels).                                                       |
      | height              | Window height (in pixels).                                                      |
      | border_inner_margin | Window's inner border margin (in pixels).                                       |
      | border_outer_margin | Window's outer border margin (in pixels).                                       |
      | border_width        | Window's border width (in pixels).                                              |
      | text_start_x        | The x component of the starting coordinate of text drawing.                     |
      | text_start_y        | The y component of the starting coordinate of text drawing.                     |
      | text_width          | The width of the text drawing region.                                           |
      | text_height         | The height of the text drawing region.                                          |

      NOTE: This table is only defined when X support is
      enabled.
  - name: ret_scale_x,ret_scale_y:cairo_draw_image(file, cs, x, y, scale_x, scale_y)
    desc: |-
      Renders an image onto a cairo_surface_t, using imlib2. Returns the amount the image was scaled by

      | Argument            | Description                                                                          |
      |---------------------|--------------------------------------------------------------------------------------|
      | file                | Path to the image to render.                                                         |
      | cs                  | The `cairo_surface_t` to render to.                                                  |
      | x,y                 | Position to render the image.                                                        |
      | scale_x, scale_y    | The amount to scale the image, 1.0 provides no scaling, 2.0 for twice the size and   |
      |                     | 0.5 for half size etc. <br/>Default value: No Scaling (1.0,1.0)                      |

      require('cairo_imlib2_helper') in your lua file.

  - name: cairo_text_hp_show(cr, x, y, text, font, font_size, alignment, language, script, direction)
    desc: |-
      Renders text to a cairo_t using harfbuzz and freetype, this provides significantly
      better text rendering then using cairo's inbuilt functions.

      | Argument            | Description                                                                          |
      |---------------------|--------------------------------------------------------------------------------------|
      | cr                  | The `cairo_t` to render to.                                                          |
      | x,y                 | Position to render the text.                                                         |
      | text                | The text to render.                                                                  |
      | font                | The name of the font to be used, `Fontconfig` is used to search for the font.        |
      | font_size           | The font size.                                                                       |
      | alignment           | One of `CAIRO_TEXT_ALIGN_LEFT`, `CAIRO_TEXT_ALIGN_RIGHT`, `CAIRO_TEXT_ALIGN_CENTER`.<br/>Default value: `CAIRO_TEXT_ALIGN_LEFT` |
      | language            | A string containing a BCP 47 language tag.<br/>Default value: `en`                   |
      | script              | A string containing a ISO 15924 script tag.<br/>Default value: auto-detect from text |
      | direction           | A string representing text direction eg `LTR`, `RTL` or `TTB`<br/>Default value: auto-detect from text otherwise `LTR` |
  - name: width,height:cairo_text_hp_text_size(text, font, font_size, language, script, direction)
    desc: |-
      Used to calculate how many pixels will be required to render a string with
      `cairo_text_hp_show` returns a pair of int's with `width` and `height`.

      | Argument            | Description                                                                          |
      |---------------------|--------------------------------------------------------------------------------------|
      | cr                  | The `cairo_t` to render to.                                                          |
      | text                | The text to render.                                                                  |
      | font                | The name of the font to be used, `Fontconfig` is used to search for the font.        |
      | font_size           | The font size.                                                                       |
      | language            | A string containing a BCP 47 language tag.<br/>Default value: `en`                   |
      | script              | A string containing a ISO 15924 script tag.<br/>Default value: auto-detect from text |
      | direction           | A string representing text direction eg `LTR`, `RTL` or `TTB`<br/> Default value: auto-detect from text otherwise `LTR` |
  - name: cairo_text_hp_delete_fonts()
    desc: |-
      `cairo_text_hp_show` and `cairo_text_hp_text_size` both cache internal font details,
      this function clears those caches.
