[svn-upgrade] Integrating new upstream version, ion3-doc (20080103)

[ion3-doc.git] / tricks.tex

diff --git a/tricks.tex b/tricks.tex
index 69fe9459fa57604da8fbe20feac9e743a725b5c5..3069d3caa6415083c75fce421c47db7a54d96805 100644 (file)
--- a/tricks.tex
+++ b/tricks.tex
@@ -4,20 +4,20 @@
 
 This chapter documents some additional features of the Ion configuration
 and scripting interface that can be used for more advanced scripting than
 
 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.
 
 \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
 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}
 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 are unregistered with \fnref{WHook.remove}. For example:
 
 \begin{verbatim}


@@ -30,16 +30,15 @@ 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 \ref{sec:hookref}.
 
 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}
 
 
 \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
 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


@@ -87,12 +86,15 @@ region, use \fnref{WRegion.set_name}.
 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}
 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}
 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}