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 exlained in chapter \ref{chap:config}.
+the basic configuration explained in chapter \ref{chap:config}.
\section{Hooks}
\label{sec:hooks}
Hooks are lists of functions to be called when a certain event occurs.
-There are two types of them; normal and ''alternative'' hooks. Normal
+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 succesfully. In the case
+indicating whether it handled its assigned task successfully. In the case
that \var{true} is returned, remaining handlers are not called.
Hook handlers are registered by first finding the hook
with \fnref{ioncore.get_hook} and then calling \fnref{WHook.add}
-on the (succesfull) result with the handler as parameter. Similarly
+on the (successful) result with the handler as parameter. Similarly
handlers are unregistered with \fnref{WHook.remove}. For example:
\begin{verbatim}
handlers do. The types of parameters for each hook are listed in
the hook reference, section \ref{sec:hookref}.
+Note that many of the hooks are called in ``protected mode'' and can not
+use any functions that modify Ion's internal state.
-Note that many of the hooks are called in ''protected mode'' and can not
-use any functions that modify Ion's internal state. TODO: More detailed
-documentation when this is final.
\section{Referring to regions}
\subsection{Direct object references}
-All Ion objects are passed to Lua scriptss as 'userdatas', and you may
+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
It is possible to write more complex winprop selection routines than
those described in section \ref{sec:winprops}. To match a particular
winprop using whatever way you want to, just set the \var{match}
-field of the winprop to a function that receives the client window
-as its sole parameter, and that returns \code{true} if the winprop
-matches, and \code{false} otherwise.
-
-The class, instance and role properties can be obtained with
-\fnref{WClientWin.get_ident}, and the title with \fnref{WRegion.name}.
+field of the winprop to a function that receives the as its parameters
+the triple \var{(prop, cwin, id)}, where \var{prop} is the table for
+the winprop itself, \code{cwin} is the client window object,
+and \var{id} is the \fnref{WClientWin.get_ident} result.
+The function should return \var{true} if the winprop matches,
+and \code{false} otherwise. Note that the \var{match} function
+is only called after matching against class/role/instance.
+
+The title of a client window can be obtained with \fnref{WRegion.name}.
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: \fnref{ioncore.x_intern_atom}