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 Note that many of the hooks are called in ``protected mode'' and can not
  34 use any functions that modify Ion's internal state.
  35
  36
  37 \section{Referring to regions}
  38
  39 \subsection{Direct object references}
  40
  41 All Ion objects are passed to Lua scripts as 'userdatas', and you may
  42 safely store such object references for future use. The C-side object
  43 may be destroyed while Lua still refers to the object. All exported
  44 functions gracefully fail in such a case, but if you need to explicitly
  45 test that the C-side object still exists, use \fnref{obj_exists}.
  46
  47 As an example, the following short piece of code implements
  48 bookmarking:
  49
  50 \begin{verbatim}
  51 local bookmarks={}
  52
  53 -- Set bookmark bm point to the region reg
  54 function set_bookmark(bm, reg)
  55     bookmarks[bm]=reg
  56 end
  57
  58 -- Go to bookmark bm
  59 function goto_bookmark(bm)
  60     if bookmarks[bm] then
  61         -- We could check that bookmarks[bm] still exists, if we
  62         -- wanted to avoid an error message.
  63         bookmarks[bm]:goto()
  64     end
  65 end
  66 \end{verbatim}
  67
  68 \subsection{Name-based lookups}
  69
  70 If you want to a single non-\type{WClientWin} region with an exact known
  71 name, use \fnref{ioncore.lookup_region}. If you want a list of all regions,
  72 use \fnref{ioncore.region_list}. Both functions accept an optional argument
  73 that can be used to specify that the returned region(s) must be of a more
  74 specific type. Client windows live in a different namespace and for them
  75 you should use the equivalent functions \fnref{ioncore.lookup_clientwin}
  76 and \fnref{ioncore.clientwin_list}.
  77
  78 To get the name of an object, use \fnref{WRegion.name}. Please be
  79 aware, that the names of client windows reflect their titles and
  80 are subject to changes. To change the name of a non-client window
  81 region, use \fnref{WRegion.set_name}.
  82
  83
  84 \section{Alternative winprop selection criteria}
  85
  86 It is possible to write more complex winprop selection routines than
  87 those described in section \ref{sec:winprops}. To match a particular
  88 winprop using whatever way you want to, just set the \var{match}
  89 field of the winprop to a function that receives the client window
  90 as its sole parameter, and that returns \code{true} if the winprop
  91 matches, and \code{false} otherwise.
  92
  93 The class, instance and role properties can be obtained with
  94 \fnref{WClientWin.get_ident}, and the title with \fnref{WRegion.name}.
  95 If you want to match against (almost) arbitrary window properties,
  96 have a look at the documentation for the following functions, and
  97 their standard Xlib counterparts: \fnref{ioncore.x_intern_atom}
  98 (XInternAtom), \fnref{ioncore.x_get_window_property} (XGetWindowProperty),
  99 and \fnref{ioncore.x_get_text_property} (XGetTextProperty).
 100
 101
 102 \input{statusd}
 103