1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
3 <!--Converted with LaTeX2HTML 2002-2-1 (1.71)
4 original version by: Nikos Drakos, CBLU, University of Leeds
5 * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6 * with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
10 <TITLE>5. Scripting</TITLE>
11 <META NAME="description" CONTENT="5. Scripting">
12 <META NAME="keywords" CONTENT="ionconf">
13 <META NAME="resource-type" CONTENT="document">
14 <META NAME="distribution" CONTENT="global">
16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17 <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
20 <LINK REL="STYLESHEET" HREF="ionconf.css">
22 <LINK REL="next" HREF="node7.html">
23 <LINK REL="previous" HREF="node5.html">
24 <LINK REL="up" HREF="ionconf.html">
25 <LINK REL="next" HREF="node7.html">
30 <DIV CLASS="navigation"><!--Navigation Panel-->
33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
47 <B> Next:</B> <A NAME="tex2html364"
48 HREF="node7.html">6. Function reference</A>
49 <B> Up:</B> <A NAME="tex2html358"
50 HREF="ionconf.html">Configuring and extending Ion3</A>
51 <B> Previous:</B> <A NAME="tex2html352"
52 HREF="node5.html">4. Graphical styles</A>
53 <B> <A NAME="tex2html360"
54 HREF="node1.html">Contents</A></B>
55 <B> <A NAME="tex2html362"
56 HREF="node11.html">Index</A></B>
59 <!--End of Navigation Panel-->
60 <!--Table of Child-Links-->
61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
63 <UL CLASS="ChildLinks">
64 <LI><A NAME="tex2html365"
65 HREF="node6.html#SECTION00610000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Hooks</A>
66 <LI><A NAME="tex2html366"
67 HREF="node6.html#SECTION00620000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Referring to regions</A>
69 <LI><A NAME="tex2html367"
70 HREF="node6.html#SECTION00621000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Direct object references</A>
71 <LI><A NAME="tex2html368"
72 HREF="node6.html#SECTION00622000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Name-based lookups</A>
75 <LI><A NAME="tex2html369"
76 HREF="node6.html#SECTION00630000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Alternative winprop selection criteria</A>
77 <LI><A NAME="tex2html370"
78 HREF="node6.html#SECTION00640000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Writing <TT>ion-statusd</TT> monitors</A>
80 <!--End of Table of Child-Links-->
83 <H1><A NAME="SECTION00600000000000000000"></A>
84 <A NAME="chap:tricks"></A>
86 <SPAN CLASS="arabic">5</SPAN>. Scripting
90 This chapter documents some additional features of the Ion configuration
91 and scripting interface that can be used for more advanced scripting than
92 the basic configuration explained in chapter <A HREF="node4.html#chap:config">3</A>.
96 <H2><A NAME="SECTION00610000000000000000"></A>
97 <A NAME="sec:hooks"></A>
99 <SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Hooks
103 Hooks are lists of functions to be called when a certain event occurs.
104 There are two types of them; normal and ``alternative'' hooks. Normal
105 hooks do not return anything, but alt-hooks should return a boolean
106 indicating whether it handled its assigned task successfully. In the case
107 that <TT>true</TT> is returned, remaining handlers are not called.
110 Hook handlers are registered by first finding the hook
111 with <A HREF="node7.html#fn:ioncore.get_hook"><TT>ioncore.get_hook</TT></A> and then calling <A HREF="node7.html#fn:WHook.add"><TT>WHook.add</TT></A>
112 on the (successful) result with the handler as parameter. Similarly
113 handlers are unregistered with <A HREF="node7.html#fn:WHook.remove"><TT>WHook.remove</TT></A>. For example:
117 ioncore.get_hook("ioncore_snapshot_hook"):add(
118 function() print("Snapshot hook called.") end
123 In this example the hook handler has no parameters, but many hook
124 handlers do. The types of parameters for each hook are listed in
125 the hook reference, section <A HREF="node7.html#sec:hookref">6.9</A>.
128 Note that many of the hooks are called in ``protected mode'' and can not
129 use any functions that modify Ion's internal state.
133 <H2><A NAME="SECTION00620000000000000000">
134 <SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Referring to regions</A>
139 <H3><A NAME="SECTION00621000000000000000">
140 <SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Direct object references</A>
144 All Ion objects are passed to Lua scripts as 'userdatas', and you may
145 safely store such object references for future use. The C-side object
146 may be destroyed while Lua still refers to the object. All exported
147 functions gracefully fail in such a case, but if you need to explicitly
148 test that the C-side object still exists, use <A HREF="#fn:obj_exists"><TT>obj_exists</TT></A>.
151 As an example, the following short piece of code implements
158 -- Set bookmark bm point to the region reg
159 function set_bookmark(bm, reg)
164 function goto_bookmark(bm)
165 if bookmarks[bm] then
166 -- We could check that bookmarks[bm] still exists, if we
167 -- wanted to avoid an error message.
175 <H3><A NAME="SECTION00622000000000000000">
176 <SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Name-based lookups</A>
180 If you want to a single non-WClientWin region with an exact known
181 name, use <A HREF="node7.html#fn:ioncore.lookup_region"><TT>ioncore.lookup_region</TT></A>. If you want a list of all regions,
182 use <A HREF="#fn:ioncore.region_list"><TT>ioncore.region_list</TT></A>. Both functions accept an optional argument
183 that can be used to specify that the returned region(s) must be of a more
184 specific type. Client windows live in a different namespace and for them
185 you should use the equivalent functions <A HREF="node7.html#fn:ioncore.lookup_clientwin"><TT>ioncore.lookup_clientwin</TT></A>
186 and <A HREF="#fn:ioncore.clientwin_list"><TT>ioncore.clientwin_list</TT></A>.
189 To get the name of an object, use <A HREF="node7.html#fn:WRegion.name"><TT>WRegion.name</TT></A>. Please be
190 aware, that the names of client windows reflect their titles and
191 are subject to changes. To change the name of a non-client window
192 region, use <A HREF="node7.html#fn:WRegion.set_name"><TT>WRegion.set_name</TT></A>.
196 <H2><A NAME="SECTION00630000000000000000">
197 <SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Alternative winprop selection criteria</A>
201 It is possible to write more complex winprop selection routines than
202 those described in section <A HREF="node4.html#sec:winprops">3.5</A>. To match a particular
203 winprop using whatever way you want to, just set the <TT>match</TT>
204 field of the winprop to a function that receives the client window
205 as its sole parameter, and that returns <TT>true</TT> if the winprop
206 matches, and <TT>false</TT> otherwise.
209 The class, instance and role properties can be obtained with
210 <A HREF="node7.html#fn:WClientWin.get_ident"><TT>WClientWin.get_ident</TT></A>, and the title with <A HREF="node7.html#fn:WRegion.name"><TT>WRegion.name</TT></A>.
211 If you want to match against (almost) arbitrary window properties,
212 have a look at the documentation for the following functions, and
213 their standard Xlib counterparts: <A HREF="node7.html#fn:ioncore.x_intern_atom"><TT>ioncore.x_intern_atom</TT></A>
214 (XInternAtom), <A HREF="node7.html#fn:ioncore.x_get_window_property"><TT>ioncore.x_get_window_property</TT></A> (XGetWindowProperty),
215 and <A HREF="node7.html#fn:ioncore.x_get_text_property"><TT>ioncore.x_get_text_property</TT></A> (XGetTextProperty).
221 <H2><A NAME="SECTION00640000000000000000"></A>
222 <A NAME="sec:statusd"></A>
224 <SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Writing <TT>ion-statusd</TT> monitors
228 All statusbar meters that do not monitor the internal state of Ion should
229 go in the separate <TT>ion-statusd</TT> program.
232 Whenever the user requests a meter `<TT>%foo</TT>' or `<TT>%foo_bar</TT>' to
233 be inserted in a statusbar, <SPAN CLASS="textit">mod_statusbar</SPAN> asks <TT>ion-statusd</TT>
234 to load <A HREF="#fn:statusd_foo.lua"><TT>statusd_foo.lua</TT></A> on its search path (same as that for Ion-side
235 scripts). This script should then supply all meters with the initial part
239 To provide this value, the script should simply call <TT>statusd.inform</TT>
240 with the name of the meter and the value as a string.
241 Additionally the script should provide a 'template' for the meter to
242 facilitate expected width calculation by <SPAN CLASS="textit">mod_statusbar</SPAN>, and
243 may provide a 'hint' for colour-coding the value. The interpretation
244 of hints depends on the graphical style in use, and currently the
245 stock styles support the `<TT>normal</TT>', `<TT>important</TT>' and
246 `<TT>critical</TT>' hints.
249 In our example of the 'foo monitor', at script initialisation we might broadcast
250 the template as follows:
254 statusd.inform("foo_template", "000")
258 To inform <SPAN CLASS="textit">mod_statusbar</SPAN> of the actual value of the meter and
259 indicate that the value is critical if above 100, we might write the
264 local function inform_foo(foo)
265 statusd.inform("foo", tostring(foo))
267 statusd.inform("foo_hint", "critical")
269 statusd.inform("foo_hint", "normal")
275 To periodically update the value of the meter, we must use timers.
276 First we must create one:
280 local foo_timer=statusd.create_timer()
284 Then we write a function to be called whenever the timer expires.
285 This function must also restart the timer.
289 local function update_foo()
290 local foo= ... measure foo somehow ...
292 foo_timer:set(settings.update_interval, update_foo)
297 Finally, at the end of our script we want to do the initial
298 measurement, and set up timer for further measurements:
306 If our scripts supports configurable parameters, the following code
307 (at the beginning of the script) will allow them to be configured in
308 <SPAN CLASS="textit">cfg_statusbar.lua</SPAN> and passed to the status daemon and our script:
313 update_interval=10*1000, -- 10 seconds
316 local settings=table.join(statusd.get_config("foo"), defaults)
321 <DIV CLASS="navigation"><HR>
322 <!--Navigation Panel-->
323 <A NAME="tex2html363"
325 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
326 <A NAME="tex2html357"
328 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
329 <A NAME="tex2html351"
331 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
332 <A NAME="tex2html359"
334 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
335 <A NAME="tex2html361"
337 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
339 <B> Next:</B> <A NAME="tex2html364"
340 HREF="node7.html">6. Function reference</A>
341 <B> Up:</B> <A NAME="tex2html358"
342 HREF="ionconf.html">Configuring and extending Ion3</A>
343 <B> Previous:</B> <A NAME="tex2html352"
344 HREF="node5.html">4. Graphical styles</A>
345 <B> <A NAME="tex2html360"
346 HREF="node1.html">Contents</A></B>
347 <B> <A NAME="tex2html362"
348 HREF="node11.html">Index</A></B> </DIV>
349 <!--End of Navigation Panel-->