# 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++, which currently only compiles against Lua 5.1. 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. | | | Default value: No Scaling (1.0,1.0) | require('cairo_imlib2_helper') in your lua file.