tricks.tex

   1
   2 \chapter{Scripting}
   3 \label{chap:tricks}
   4
   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}.
   8
   9 \section{Hooks}
  10 \label{sec:hooks}
  11
  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.
  17
  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:
  22
  23 \begin{verbatim}
  24 ioncore.get_hook("ioncore_snapshot_hook"):add(
  25     function() print("Snapshot hook called.") end
  26 )
  27 \end{verbatim}
  28
  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}.
  32
  33
  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.
  37
  38 \section{Referring to regions}
  39
  40 \subsection{Direct object references}
  41
  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}.
  47
  48 As an example, the following short piece of code implements
  49 bookmarking:
  50
  51 \begin{verbatim}
  52 local bookmarks={}
  53
  54 -- Set bookmark bm point to the region reg
  55 function set_bookmark(bm, reg)
  56     bookmarks[bm]=reg
  57 end
  58
  59 -- Go to bookmark bm
  60 function goto_bookmark(bm)
  61     if bookmarks[bm] then
  62         -- We could check that bookmarks[bm] still exists, if we
  63         -- wanted to avoid an error message.
  64         bookmarks[bm]:goto()
  65     end
  66 end
  67 \end{verbatim}
  68
  69 \subsection{Name-based lookups}
  70
  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}.
  78
  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}.
  83
  84
  85 \section{Alternative winprop selection criteria}
  86
  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.
  93
  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).
 101
 102
 103 \input{statusd}
 104