- a small section describes the condition for an itme to catch an event

- up-to-date description of ZincTrace and ZincTraceErrors modules

1 files changed, 87 insertions, 28 deletions

diff --git a/doc/refman.tex b/doc/refman.tex
index f3def21..4218dc5 100644
--- a/doc/refman.tex
+++ b/doc/refman.tex
@@ -36,7 +36,7 @@
     citecolor=webbrightgreen,
     pdftitle={Zinc, an advanced scriptable Canvas.},
     pdfauthor={Patrick Lecoanet, Christophe Mertz, Centre d'Étude de la Navigation Aérienne},
-    pdfsubject={The pre-3.3 (3.2.93) Reference Manual.},
+    pdfsubject={The pre-3.3 (3.2.94) Reference Manual.},
     pdfkeywords={tk tcl perl x11 canvas opengl script gui TkZinc},
     pagebackref,
     pdfpagemode=None,
@@ -208,9 +208,9 @@
 \setlength{\marginparwidth}{20pt}
 \setlength{\textwidth}{480pt}
 
-\title{Zinc, an advanced scriptable Canvas.\\The pre 3.3 (3.2.93) Reference Manual.\\\small{[CENA technical Note NT03-532]} }
+\title{Zinc, an advanced scriptable Canvas.\\The pre 3.3 (3.2.94) Reference Manual.\\\small{[CENA technical Note NT03-532]} }
 \author{Patrick Lecoanet, Christophe Mertz}
-\date{16 May 2003}
+\date{13 June 2003}
 
 
 \begin{document}
@@ -262,7 +262,7 @@ developped by Hummingbird) with the 3D extension.
 
 As an example of TkZinc capabilities when combined with openGL, we implemented
 the TkZinc logo as a Perl module (available as a goodie in \ident{LogoZinc.pm}).
-This logo (see below) was designed with Adobe Illustrator and then programmed in perl.
+This logo (see below) was designed with Adobe Illustrator and then programmed in Perl.
 
 
 %\includefigure{tkzinclogo}{Zinc logo written as a Perl/Tk module}{fig:logozinc}
@@ -291,7 +291,7 @@ This document is also referenced as CENA technical note NT03-532.
 
 \section{Differences with previous version}
 
-\subsection{Differences between 3.2.93 and 3.2.6 release}
+\subsection{Differences between 3.2.94 and 3.2.6 release}
 \begin{itemize}
 \item  TkZinc now works on windows (with Tcl).
 \item  compilation on Linux works fine now.
@@ -313,7 +313,7 @@ defined for X. {\bf Beware that old gradient are no more compatible}
 \item  TkZinc comes now with a ZincTrace.pm module to trace every TkZinc method call
 \item  the hierarchical view in ZincDebug.pm can now display some choosen attributes
 in a choosen format.
-\item  4 new perl demos in zinc-demos: ``pathTags'', ``tiger'' and ``curve with bezier control points''
+\item  4 new Perl demos in zinc-demos: ``pathTags'', ``tiger'' and ``curve with bezier control points''
 and ``fillrule''. Most Perl/Tk demos have been ported to Tcl/Tk.
 \item  pathTags introduced in 3.2.6 have been documented. Label and label
 format documentation has been enhanced.
@@ -324,7 +324,7 @@ format documentation has been enhanced.
 \item  many bug corrections, of course!
 \item  this documentation has been improved (changelog, new figures, completions) 
 \item  the contour command can return the contour number
-\item  the ZincDebug.pm perl module has been fairly augmented
+\item  the ZincDebug.pm Perl module has been fairly augmented
 \item  the find command may return item ancestor(s)
 \item  the TkZinc command may return the version number
 \item  icom items may be scaled and rotated (needs openGL)
@@ -345,13 +345,13 @@ format documentation has been enhanced.
 \item  many bug corrections, of course!
 \item  TkZinc can now use openGL capablities
 \item  many new item options (due to openGL capablilites) and a new triangles item
-\item  a new perl module : ZincDebug.pm to interactively browse the item hierarchy
+\item  a new Perl module : ZincDebug.pm to interactively browse the item hierarchy
 \item  as color are all gradient (with alpha transparency) the -alpha option has been removed
 \item  a set of TkZinc demontrations are available with the zinc-demos command
 \item  many new explanations in this doc: groups, item ids and tags ... 
 \item  the postscript version of this doc has been replaced by a pdf version
 \item  configuring an unexisting option of an item is no more an error (this was a design mistake)
-\item  a perl module ZincText.pm make it easier to implement text input
+\item  a Perl module ZincText.pm make it easier to implement text input
 \end{itemize}
 
 \section{Where can I find TkZinc and documentation ?}
@@ -884,7 +884,7 @@ list from the least visible item to the most visible one. Each time a group is
 encoutered the traversal proceed with this group display list before resuming the
 upper display list traversal. The search to find the item that should receive an
 event is done in the opposite direction. In this way, items are drawn according to
-their relative stacking order and events are dispatched to the most visible item at a
+their relative stacking order and events are dispatched to the top-most item at a
 given location.
 
 It is important to note as a consequence of this structuring, that items of a group are
@@ -921,6 +921,30 @@ groups.
 \end{itemize}
 
 
+\section{Event sensitivity}
+
+An item will catch an event if all the following conditions are satisfied:
+\begin{itemize}
+\item
+ the item \ident{-sensitive} must be set to true (this is the default).
+\item
+ the item must be under the pointer location.
+\item
+ the item must be on top of the display list (at the pointer location). Beware
+ that an other item with its \ident{-visible} set to false DOES catch event
+ before any underneath items.
+\item
+ the item must not be clipped (at the pointer location)
+\item
+ the item must not belong to an atomic group, since an atomic group catchs the event
+ instead of the item.
+\end{itemize}
+
+An item satisfying all the above conditions can have its \ident{-visible} set
+to false, or can be fully transparent (when  using openGL). It will still catch
+the events.
+
+
 \section{Transformations}
 In TkZinc each item is geometrically defined in its own coordinate space. So
 each time a new item is created, a new coordinate system is attached to it.
@@ -1046,11 +1070,14 @@ it so it can act as the background. Of course, other creative uses can be found
 warned that the clipper outline will never be easthetically drawn due to round off or
 quantization errors, it is better to turn off borders or outlines in this case.
 
-It is also possible to clip the root group. Depending on the value of TkZinc options
-\optref{reshape} and \optref{fullreshape}, the clipping form can be used either to
-clip all items in the TkZinc widget, or reshape the TkZinc widget, or to propagate
-the TkZinc widget shape to the parent windows. In the latter case, this allows to build
-non-rectangulaire applications. Example:
+It is also possible to clip the root group (only on X11 system. Does not work on windows
+systems). Depending on the value of TkZinc options \optref{reshape} and
+\optref{fullreshape}, the clipping form can be used either to clip all items in the TkZinc
+widget, or reshape the TkZinc widget, or to propagate the TkZinc widget shape to the parent
+windows. In the latter case, this allows to build non-rectangulaire applications. This
+requires both the SHAPE X11 extension and a compliant Window Manager (fvwm is known
+to support non rectangulaire top windows). The clipping form should have a bounding box
+with the same ratio as the topwindow or some normalisation will occur. Example:
 
 \code{
   use Tk::Zinc;\\
@@ -1431,7 +1458,7 @@ reference) and all list parameters are given as array references.
     even (or the last value will be discarded) but the list can be empty to build
     an empty invisible curve. In the second case, the list must contain lists of 2 or 3
     elements: xi, yi and and an optionnal point type. Currently, the only available point type
-    is 'c' for a cubic bezier control point. For example in perl/Tk, the following list
+    is 'c' for a cubic bezier control point. For example in Perl/Tk, the following list
     is an example of 2 beziers segments with a straight segment in-between:
 
 \code{
@@ -3098,7 +3125,7 @@ case, they must get the focus for keyboards events with the command \cmdref{focu
 TkZinc options (see chapter \conceptref{Widget options}{options} can be used for
 configuring the text input (for example : \optref{insertbackground},
 \optref{insertofftime} \optref{insertontime}, \optref{insertwidth}).
-A perl module, called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext}) is provided for easing text input in text items
+A Perl module, called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext}) is provided for easing text input in text items
 (it can also be used for text input in labelled items such as \objectref{track},
 \objectref{waypoint} or \objectref{tabular}).
 
@@ -3852,7 +3879,7 @@ As an example:
 Inside a callback function, it is possible to know which field the mouse cursor is over
 with the command \cmdref{currentpart}.
 
-A perl module, called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext})
+A Perl module, called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext})
 is provided for easing text input in text fields (it can also be used for easing text input
 in \objectref{text} item).
 
@@ -4525,20 +4552,51 @@ tree(\$zinc, -optionsToDisplay => '-tags', -optionsFormat => 'row');\\}
 or simply by using the -M option of Perl:
 \code{\\perl -MZincDebug yourscript.pl\\}
 
-\section{Tracing TkZinc methods call in perl/Tk}
+\section{Tracing TkZinc methods call in Perl/Tk}
+
+TkZinc package includes two tools for helping you debugging your Perl/Tk scripts
+or tracking some nasty segfault which should never occure since TkZinc is
+(almost) totally bugfree.
 
-Because you some time get some errors inside \ident{TkZinc} with a cryptic message
-like {\tt ".... errors in Tk.pm line 228"} it may be usefull to know where exactly
-in your code is this error. There is a simple and convenient mean to do this, just
-by using a small module called \ident{ZincTrace.pm}, released with \ident{TkZinc}.
-It will trace every call of a TkZinc method. It will trace on the standard output
-the following informations:
+\subsection{Tracking Perl/Tk script errors}
+
+Because you sometime get some errors inside \ident{TkZinc} with a cryptic message
+like {\tt ".... errors in Tk.pm line 228"}, it may be usefull to know where exactly
+in your code is the error. There is a simple and convenient mean to do this, just
+by using a small module called \ident{ZincTraceErrors.pm}, released with \ident{TkZinc}.
+It traces every call of a TkZinc method inducing a Tk error. It prints on
+the standard output the following informations:
 \begin{itemize}
 \item the filename where the method has been invoked
 \item the line number in the source file
 \item the TkZinc method name
 \item the list of arguments in a human-readable form
-\item the returned value of this method invocation
+\item the error message
+\end{itemize}
+
+To use this module you can import it either by adding the following
+statement in your source code:
+\code{\\use ZincTraceErrors;\\} or better, by using the -M option of Perl:
+\code{\\perl -MZincTraceErrors yourscript.pl\\}
+
+\subsection{Tracking TkZinc segfaults in Perl/Tk}
+
+If you encounters a segfault in one Perl/Tk script and you suspects
+that TkZinc might be responsible, you should use a small module called
+\ident{ZincTraceErrors.pm}, released with \ident{TkZinc}.
+It traces every call of a TkZinc method. The method call is printed
+on the standard output before the effective call, and the
+result of the invokation is printed after the call. To be sure
+to identify a segfault at the proper time, it forces an update of TkZinc
+widget. Thus, this might slow down your script, but should dramatically 
+speed up the identification of the call which makes TkZinc segfaulting.
+It prints on the standard output the following informations:
+\begin{itemize}
+\item the filename where the method has been invoked
+\item the line number in the source file
+\item the TkZinc method name
+\item the list of arguments in a human-readable form
+\item the returned value
 \end{itemize}
 
 To use this module you can import it either by adding the following
@@ -4546,6 +4604,7 @@ statement in your source code:
 \code{\\use ZincTrace;\\} or better, by using the -M option of Perl:
 \code{\\perl -MZincTrace yourscript.pl\\}
 
+
 \section{zinc-demos}
 \concept{zinc-demos}
 
@@ -4558,9 +4617,9 @@ or even a TkZinc port of \ident{TkTetris} from Slaven Rezic.
 \section{ZincText.pm}
 \concept{zinctext}
 
-The Tk::ZincText perl module implements bindings for text input 'a la emacs'.
+The Tk::ZincText Perl module implements bindings for text input 'a la emacs'.
 It works for text item or for text fields of track, waypoint or tabular items.
-The item which require text input must just be tagged with the 'text' tag.
+The item which requires text input must just be tagged with the 'text' tag.
 
 Please read the man page for more details: {\tt man Tk::ZincText}