5 This chapter documents some additional features of the Ion configuration
6 and scripting interface that can be used for more advanced scripting than
7 the basic configuration explained in chapter \ref{chap:config}.
12 Hooks are lists of functions to be called when a certain event occurs.
13 There are two types of them; normal and ``alternative'' hooks. Normal
14 hooks do not return anything, but alt-hooks should return a boolean
15 indicating whether it handled its assigned task successfully. In the case
16 that \var{true} is returned, remaining handlers are not called.
18 Hook handlers are registered by first finding the hook
19 with \fnref{ioncore.get_hook} and then calling \fnref{WHook.add}
20 on the (successful) result with the handler as parameter. Similarly
21 handlers are unregistered with \fnref{WHook.remove}. For example:
24 ioncore.get_hook("ioncore_snapshot_hook"):add(
25 function() print("Snapshot hook called.") end
29 In this example the hook handler has no parameters, but many hook
30 handlers do. The types of parameters for each hook are listed in
31 the hook reference, section \ref{sec:hookref}.
34 Note that many of the hooks are called in ``protected mode'' and can not
35 use any functions that modify Ion's internal state. TODO: More detailed
36 documentation when this is final.
38 \section{Referring to regions}
40 \subsection{Direct object references}
42 All Ion objects are passed to Lua scripts as 'userdatas', and you may
43 safely store such object references for future use. The C-side object
44 may be destroyed while Lua still refers to the object. All exported
45 functions gracefully fail in such a case, but if you need to explicitly
46 test that the C-side object still exists, use \fnref{obj_exists}.
48 As an example, the following short piece of code implements
54 -- Set bookmark bm point to the region reg
55 function set_bookmark(bm, reg)
60 function goto_bookmark(bm)
62 -- We could check that bookmarks[bm] still exists, if we
63 -- wanted to avoid an error message.
69 \subsection{Name-based lookups}
71 If you want to a single non-\type{WClientWin} region with an exact known
72 name, use \fnref{ioncore.lookup_region}. If you want a list of all regions,
73 use \fnref{ioncore.region_list}. Both functions accept an optional argument
74 that can be used to specify that the returned region(s) must be of a more
75 specific type. Client windows live in a different namespace and for them
76 you should use the equivalent functions \fnref{ioncore.lookup_clientwin}
77 and \fnref{ioncore.clientwin_list}.
79 To get the name of an object, use \fnref{WRegion.name}. Please be
80 aware, that the names of client windows reflect their titles and
81 are subject to changes. To change the name of a non-client window
82 region, use \fnref{WRegion.set_name}.
85 \section{Alternative winprop selection criteria}
87 It is possible to write more complex winprop selection routines than
88 those described in section \ref{sec:winprops}. To match a particular
89 winprop using whatever way you want to, just set the \var{match}
90 field of the winprop to a function that receives the client window
91 as its sole parameter, and that returns \code{true} if the winprop
92 matches, and \code{false} otherwise.
94 The class, instance and role properties can be obtained with
95 \fnref{WClientWin.get_ident}, and the title with \fnref{WRegion.name}.
96 If you want to match against (almost) arbitrary window properties,
97 have a look at the documentation for the following functions, and
98 their standard Xlib counterparts: \fnref{ioncore.x_intern_atom}
99 (XInternAtom), \fnref{ioncore.x_get_window_property} (XGetWindowProperty),
100 and \fnref{ioncore.x_get_text_property} (XGetTextProperty).