1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
# 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.
|
