+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-
-<!--Converted with LaTeX2HTML 2002-2-1 (1.71)
-original version by: Nikos Drakos, CBLU, University of Leeds
-* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
-* with significant contributions from:
- Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-<HTML>
-<HEAD>
-<TITLE>5. Scripting</TITLE>
-<META NAME="description" CONTENT="5. Scripting">
-<META NAME="keywords" CONTENT="ionconf">
-<META NAME="resource-type" CONTENT="document">
-<META NAME="distribution" CONTENT="global">
-
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
-<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
-<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
-
-<LINK REL="STYLESHEET" HREF="ionconf.css">
-
-<LINK REL="next" HREF="node7.html">
-<LINK REL="previous" HREF="node5.html">
-<LINK REL="up" HREF="ionconf.html">
-<LINK REL="next" HREF="node7.html">
-</HEAD>
-
-<BODY >
-
-<DIV CLASS="navigation"><!--Navigation Panel-->
-<A NAME="tex2html363"
- HREF="node7.html">
-<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
-<A NAME="tex2html357"
- HREF="ionconf.html">
-<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
-<A NAME="tex2html351"
- HREF="node5.html">
-<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
-<A NAME="tex2html359"
- HREF="node1.html">
-<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
-<A NAME="tex2html361"
- HREF="node11.html">
-<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
-<BR>
-<B> Next:</B> <A NAME="tex2html364"
- HREF="node7.html">6. Function reference</A>
-<B> Up:</B> <A NAME="tex2html358"
- HREF="ionconf.html">Configuring and extending Ion3</A>
-<B> Previous:</B> <A NAME="tex2html352"
- HREF="node5.html">4. Graphical styles</A>
- <B> <A NAME="tex2html360"
- HREF="node1.html">Contents</A></B>
- <B> <A NAME="tex2html362"
- HREF="node11.html">Index</A></B>
-<BR>
-<BR></DIV>
-<!--End of Navigation Panel-->
-<!--Table of Child-Links-->
-<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
-
-<UL CLASS="ChildLinks">
-<LI><A NAME="tex2html365"
- HREF="node6.html#SECTION00610000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Hooks</A>
-<LI><A NAME="tex2html366"
- HREF="node6.html#SECTION00620000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Referring to regions</A>
-<UL>
-<LI><A NAME="tex2html367"
- HREF="node6.html#SECTION00621000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Direct object references</A>
-<LI><A NAME="tex2html368"
- HREF="node6.html#SECTION00622000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Name-based lookups</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html369"
- HREF="node6.html#SECTION00630000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Alternative winprop selection criteria</A>
-<LI><A NAME="tex2html370"
- HREF="node6.html#SECTION00640000000000000000"><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Writing <TT>ion-statusd</TT> monitors</A>
-</UL>
-<!--End of Table of Child-Links-->
-<HR>
-
-<H1><A NAME="SECTION00600000000000000000"></A>
-<A NAME="chap:tricks"></A>
-<BR>
-<SPAN CLASS="arabic">5</SPAN>. Scripting
-</H1>
-
-<P>
-This chapter documents some additional features of the Ion configuration
-and scripting interface that can be used for more advanced scripting than
-the basic configuration explained in chapter <A HREF="node4.html#chap:config">3</A>.
-
-<P>
-
-<H2><A NAME="SECTION00610000000000000000"></A>
-<A NAME="sec:hooks"></A>
-<BR>
-<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN> Hooks
-</H2>
-
-<P>
-Hooks are lists of functions to be called when a certain event occurs.
-There are two types of them; normal and ``alternative'' hooks. Normal
-hooks do not return anything, but alt-hooks should return a boolean
-indicating whether it handled its assigned task successfully. In the case
-that <TT>true</TT> is returned, remaining handlers are not called.
-
-<P>
-Hook handlers are registered by first finding the hook
-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>
-on the (successful) result with the handler as parameter. Similarly
-handlers are unregistered with <A HREF="node7.html#fn:WHook.remove"><TT>WHook.remove</TT></A>. For example:
-
-<P>
-<PRE>
-ioncore.get_hook("ioncore_snapshot_hook"):add(
- function() print("Snapshot hook called.") end
-)
-</PRE>
-
-<P>
-In this example the hook handler has no parameters, but many hook
-handlers do. The types of parameters for each hook are listed in
-the hook reference, section <A HREF="node7.html#sec:hookref">6.9</A>.
-
-<P>
-Note that many of the hooks are called in ``protected mode'' and can not
-use any functions that modify Ion's internal state.
-
-<P>
-
-<H2><A NAME="SECTION00620000000000000000">
-<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN> Referring to regions</A>
-</H2>
-
-<P>
-
-<H3><A NAME="SECTION00621000000000000000">
-<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Direct object references</A>
-</H3>
-
-<P>
-All Ion objects are passed to Lua scripts as 'userdatas', and you may
-safely store such object references for future use. The C-side object
-may be destroyed while Lua still refers to the object. All exported
-functions gracefully fail in such a case, but if you need to explicitly
-test that the C-side object still exists, use <A HREF="#fn:obj_exists"><TT>obj_exists</TT></A>.
-
-<P>
-As an example, the following short piece of code implements
-bookmarking:
-
-<P>
-<PRE>
-local bookmarks={}
-
--- Set bookmark bm point to the region reg
-function set_bookmark(bm, reg)
- bookmarks[bm]=reg
-end
-
--- Go to bookmark bm
-function goto_bookmark(bm)
- if bookmarks[bm] then
- -- We could check that bookmarks[bm] still exists, if we
- -- wanted to avoid an error message.
- bookmarks[bm]:goto()
- end
-end
-</PRE>
-
-<P>
-
-<H3><A NAME="SECTION00622000000000000000">
-<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Name-based lookups</A>
-</H3>
-
-<P>
-If you want to a single non-WClientWin region with an exact known
-name, use <A HREF="node7.html#fn:ioncore.lookup_region"><TT>ioncore.lookup_region</TT></A>. If you want a list of all regions,
-use <A HREF="#fn:ioncore.region_list"><TT>ioncore.region_list</TT></A>. Both functions accept an optional argument
-that can be used to specify that the returned region(s) must be of a more
-specific type. Client windows live in a different namespace and for them
-you should use the equivalent functions <A HREF="node7.html#fn:ioncore.lookup_clientwin"><TT>ioncore.lookup_clientwin</TT></A>
-and <A HREF="#fn:ioncore.clientwin_list"><TT>ioncore.clientwin_list</TT></A>.
-
-<P>
-To get the name of an object, use <A HREF="node7.html#fn:WRegion.name"><TT>WRegion.name</TT></A>. Please be
-aware, that the names of client windows reflect their titles and
-are subject to changes. To change the name of a non-client window
-region, use <A HREF="node7.html#fn:WRegion.set_name"><TT>WRegion.set_name</TT></A>.
-
-<P>
-
-<H2><A NAME="SECTION00630000000000000000">
-<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN> Alternative winprop selection criteria</A>
-</H2>
-
-<P>
-It is possible to write more complex winprop selection routines than
-those described in section <A HREF="node4.html#sec:winprops">3.5</A>. To match a particular
-winprop using whatever way you want to, just set the <TT>match</TT>
-field of the winprop to a function that receives the client window
-as its sole parameter, and that returns <TT>true</TT> if the winprop
-matches, and <TT>false</TT> otherwise.
-
-<P>
-The class, instance and role properties can be obtained with
-<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>.
-If you want to match against (almost) arbitrary window properties,
-have a look at the documentation for the following functions, and
-their standard Xlib counterparts: <A HREF="node7.html#fn:ioncore.x_intern_atom"><TT>ioncore.x_intern_atom</TT></A>
-(XInternAtom), <A HREF="node7.html#fn:ioncore.x_get_window_property"><TT>ioncore.x_get_window_property</TT></A> (XGetWindowProperty),
-and <A HREF="node7.html#fn:ioncore.x_get_text_property"><TT>ioncore.x_get_text_property</TT></A> (XGetTextProperty).
-
-<P>
-
-<P>
-
-<H2><A NAME="SECTION00640000000000000000"></A>
-<A NAME="sec:statusd"></A>
-<BR>
-<SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN> Writing <TT>ion-statusd</TT> monitors
-</H2>
-
-<P>
-All statusbar meters that do not monitor the internal state of Ion should
-go in the separate <TT>ion-statusd</TT> program.
-
-<P>
-Whenever the user requests a meter `<TT>%foo</TT>' or `<TT>%foo_bar</TT>' to
-be inserted in a statusbar, <SPAN CLASS="textit">mod_statusbar</SPAN> asks <TT>ion-statusd</TT>
-to load <A HREF="#fn:statusd_foo.lua"><TT>statusd_foo.lua</TT></A> on its search path (same as that for Ion-side
-scripts). This script should then supply all meters with the initial part
-`<TT>foo</TT>'.
-
-<P>
-To provide this value, the script should simply call <TT>statusd.inform</TT>
-with the name of the meter and the value as a string.
-Additionally the script should provide a 'template' for the meter to
-facilitate expected width calculation by <SPAN CLASS="textit">mod_statusbar</SPAN>, and
-may provide a 'hint' for colour-coding the value. The interpretation
-of hints depends on the graphical style in use, and currently the
-stock styles support the `<TT>normal</TT>', `<TT>important</TT>' and
-`<TT>critical</TT>' hints.
-
-<P>
-In our example of the 'foo monitor', at script initialisation we might broadcast
-the template as follows:
-
-<P>
-<PRE>
-statusd.inform("foo_template", "000")
-</PRE>
-
-<P>
-To inform <SPAN CLASS="textit">mod_statusbar</SPAN> of the actual value of the meter and
-indicate that the value is critical if above 100, we might write the
-following function:
-
-<P>
-<PRE>
-local function inform_foo(foo)
- statusd.inform("foo", tostring(foo))
- if foo>100 then
- statusd.inform("foo_hint", "critical")
- else
- statusd.inform("foo_hint", "normal")
- end
-end
-</PRE>
-
-<P>
-To periodically update the value of the meter, we must use timers.
-First we must create one:
-
-<P>
-<PRE>
-local foo_timer=statusd.create_timer()
-</PRE>
-
-<P>
-Then we write a function to be called whenever the timer expires.
-This function must also restart the timer.
-
-<P>
-<PRE>
-local function update_foo()
- local foo= ... measure foo somehow ...
- inform_foo(foo)
- foo_timer:set(settings.update_interval, update_foo)
-end
-</PRE>
-
-<P>
-Finally, at the end of our script we want to do the initial
-measurement, and set up timer for further measurements:
-
-<P>
-<PRE>
-update_foo()
-</PRE>
-
-<P>
-If our scripts supports configurable parameters, the following code
-(at the beginning of the script) will allow them to be configured in
-<SPAN CLASS="textit">cfg_statusbar.lua</SPAN> and passed to the status daemon and our script:
-
-<P>
-<PRE>
-local defaults={
- update_interval=10*1000, -- 10 seconds
-}
-
-local settings=table.join(statusd.get_config("foo"), defaults)
-</PRE>
-
-<P>
-
-<DIV CLASS="navigation"><HR>
-<!--Navigation Panel-->
-<A NAME="tex2html363"
- HREF="node7.html">
-<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
-<A NAME="tex2html357"
- HREF="ionconf.html">
-<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
-<A NAME="tex2html351"
- HREF="node5.html">
-<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
-<A NAME="tex2html359"
- HREF="node1.html">
-<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
-<A NAME="tex2html361"
- HREF="node11.html">
-<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
-<BR>
-<B> Next:</B> <A NAME="tex2html364"
- HREF="node7.html">6. Function reference</A>
-<B> Up:</B> <A NAME="tex2html358"
- HREF="ionconf.html">Configuring and extending Ion3</A>
-<B> Previous:</B> <A NAME="tex2html352"
- HREF="node5.html">4. Graphical styles</A>
- <B> <A NAME="tex2html360"
- HREF="node1.html">Contents</A></B>
- <B> <A NAME="tex2html362"
- HREF="node11.html">Index</A></B> </DIV>
-<!--End of Navigation Panel-->
-
-</BODY>
-</HTML>
projects / ion3.git / blobdiff