X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=tricks.tex;h=b99968834ead85469e99e92d3f064b9c99502a22;hb=6121e0e6f3aea3e43bf6d432fdd474566fd08a16;hp=69fe9459fa57604da8fbe20feac9e743a725b5c5;hpb=6e84dc8312f2fdb5b8b7467a0279afd5b2df107f;p=ion3-doc.git diff --git a/tricks.tex b/tricks.tex index 69fe945..b999688 100644 --- 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 -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} @@ -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}. +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