Added -catchevent attributes.

Fixed discrepancies between code and doc reported by C.Mertz

1 files changed, 81 insertions, 31 deletions

diff --git a/doc/refman.tex b/doc/refman.tex
index 3ca23ba..c419602 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 3.3 Reference Manual.},
+    pdfsubject={The 3.3.4 Reference Manual.},
     pdfkeywords={tk tcl perl x11 canvas opengl script gui TkZinc},
     pagebackref,
     pdfpagemode=None,
@@ -53,9 +53,9 @@
   \definecolor{rltblue}{rgb}{0,0,0.75}
   \usepackage[pdftex,hyperindex=false]{hyperref}
 \else
-  \usepackage[html,2]{tex4ht}
+%  \usepackage[html,2]{tex4ht}
   \usepackage{graphicx}
-  \usepackage[tex4ht,hyperindex=false]{hyperref}
+  \usepackage[tex4ht,hyperindex=true]{hyperref}
 \fi
 
 
@@ -187,9 +187,9 @@
 \setlength{\marginparwidth}{20pt}
 \setlength{\textwidth}{480pt}
 
-\title{Zinc, an advanced scriptable Canvas.\\The 3.3 Reference Manual.\\\small{[CENA technical Note NT03-532]} }
+\title{Zinc, an advanced scriptable Canvas.\\The 3.3.4 Reference Manual.\\\small{[CENA technical Note NT03-532]} }
 \author{Patrick Lecoanet, Christophe Mertz}
-\date{17 June 2005}
+\date{12 September 2006}
 
 
 \begin{document}
@@ -597,13 +597,23 @@ actual source of the default color. Its default value is
   value is set to preserve the cursor inherited at widget creation.
 \end{blockindent}
 
+\option{followpointer}{followPointer}{FollowPointer}
+\begin{blockindent}
+  Set this option to zero to disable emission of enter and leave events. Motion
+  processing is still performed as usual. It is in some application state annoying
+  to receive enter and leave events which may result in an endless loop. This is
+  a mean to temporarily deactivate the cause. Use with care. The default value is
+  one, enabled. The name is somewhat a misnommer for Tkzinc is still following the
+  pointer.
+\end{blockindent}
+
 \option{font}{font}{Font}
 \begin{blockindent}
   The font specified by this option is used as a default font for item attributes of
   type font. Its default value is {\tt -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*}.
 \end{blockindent}
 
-\option{forecolor}{foreColor}{ForeColor} %% XXX CM Foreground ?!
+\option{forecolor}{foreColor}{Foreground}
 \begin{blockindent}
   The color specified by this option is used as a default color for many item color
   attributes. See each each color attribute for the actual source of the default
@@ -645,7 +655,7 @@ actual source of the default color. Its default value is
   no focus highlight is drawn around the widget.  The default value is {\tt 2}.
 \end{blockindent}
 
-\option{insertbackground}{insertBackground}{InsertBackground}  %% XXX CM Foreground ?!
+\option{insertbackground}{insertBackground}{Foreground}
 \begin{blockindent}
   Specifies the color to use as background in the area covered by the insertion
   cursor. This color will normally override either the normal background for the
@@ -653,14 +663,14 @@ actual source of the default color. Its default value is
   selection). The default value is {\tt black}.
 \end{blockindent}
 
-\option{insertofftime}{insertOffTime}{InsertOffTime}  %% XXX CM OffTime ?!
+\option{insertofftime}{insertOffTime}{OffTime}
 \begin{blockindent}
   Specifies a non-negative integer value indicating the number of milliseconds the
   insertion cursor should remain off in each blink cycle.  If this option is zero
   then the cursor is on all the time. The default value is {\tt 300}.
 \end{blockindent}
 
-\option{insertontime}{insertOnTime}{InsertOnTime}  %% XXX CM OnTime ?!
+\option{insertontime}{insertOnTime}{OnTime}
 \begin{blockindent}
   Specifies a non-negative integer value indicating the number of milliseconds the
   insertion cursor should remain on in each blink cycle.  The default value is {\tt 600}.
@@ -749,7 +759,7 @@ actual source of the default color. Its default value is
   is considered to be the boundary of the information in the TkZinc.
 \end{blockindent}
 
-\option{selectbackground}{selectBackground}{SelectBackground}  %% XXX CM Foreground ?!
+\option{selectbackground}{selectBackground}{Foreground}
 \begin{blockindent}
   Specifies the background color to use for displaying the selection in text
   items. The default value is {\tt \#a0a0a0}.
@@ -840,7 +850,7 @@ actual source of the default color. Its default value is
   will be executed.
 \end{blockindent}
 
-\option{xscrollincrement}{scrollincrement}{xScrollIncrement}
+\option{xscrollincrement}{xScrollincrement}{ScrollIncrement}
 \begin{blockindent}
   Specifies an increment for horizontal scrolling. If the value of this option
   is greater than zero, the horizontal view in the window will be constrained
@@ -854,12 +864,12 @@ actual source of the default color. Its default value is
 \option{yscrollcommand}{yScrollCommand}{ScrollCommand}
 \begin{blockindent}
   Specifies a callback used to communicate with vertical scrollbars. This option
-  is treated in the same way as the xScrollCommand option, except that it is used
+  is treated in the same way as the {\tt xScrollCommand option}, except that it is used
   for vertical scrollbars and is provided by widgets that support vertical
-  scrolling. See the description of xScrollCommand for details on how this option is used.
+  scrolling. See the description of {\tt xScrollCommand} for details on how this option is used.
 \end{blockindent}
 
-\option{yscrollincrement}{scrollincrement}{yScrollIncrement}
+\option{yscrollincrement}{yScrollincrement}{ScrollIncrement}
 \begin{blockindent}
   Specifies an increment for vertical scrolling. If the value of this option
   is greater than zero, the vertical view in the window will be constrained
@@ -2823,6 +2833,11 @@ use of a group as a single complex object build from smaller parts. It is possib
 search for this item or use it in bindings without dealing with its smaller parts. The
 defaut value is {\tt false}.}
 
+\attribute{group}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. If a group is not catching events, its
+children will not receive events for processing regardless of their own state.
+The default value is {\tt true}.}
+
 \attribute{group}{clip}{item}{The item used to clip the children of the group. The shape
 of this item define an area that is used as a clipping shape when drawing the children of
 the group. Most items can be used here but notable exceptions are the \objectref{reticle} and
@@ -2916,6 +2931,9 @@ is configurable.
 
 Applicable attributes for \ident{track} are :
 
+\attribute{track}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{track}{circlehistory}{boolean}{If set to true the track history will be plotted
 as circles otherwise it will be plotted as squares. The default value is {\tt false}.}
 
@@ -2977,8 +2995,9 @@ there is no automatic update of values from the \attributeref{track}{labeldx},
 \attributeref{track}{labeldy} set to the \attributeref{track}{labeldistance},
 \attributeref{track}{labelangle} set. The default value is {\tt 20}.}
 
-\attribute{track}{labelconvergencestyle}{dimension}{XXX New. To be documented. The default
-value is ??.}
+\attribute{track}{labelconvergencestyle}{integer}{This attribute is a pass through to the
+anti-overlap module intended to select the convergence method. The exact meaning is
+left to the designer of the anti-overlap module actually used. The default value is 0.}
 
 \attribute{track}{labeldistance}{dimension}{The minimum distance in pixels between the
 track position and the label anchor. See the explanation of the \attributeref{track}{labelangle} attribute
@@ -3135,6 +3154,9 @@ borders}{1}
 
 Applicable attributes for \ident{waypoint} are:
 
+\attribute{waypoint}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{waypoint}{composealpha}{boolean}{Specifies if the alpha value inherited from
 the parent group must be composed with the alpha of this item. The default value is {\tt true}.}
 
@@ -3283,6 +3305,9 @@ Applicable attributes for \ident{tabular} are:
 \attribute{tabular}{anchor}{anchor}{The anchor used in positionning the item. The default
 value is {\tt nw}.}
 
+\attribute{tabular}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{tabular}{composealpha}{boolean}{Specifies if the alpha value inherited from
 the parent group should be composed with the alpha of this item. The default value is {\tt true}.}
 
@@ -3353,6 +3378,9 @@ the item. The default value is {\tt left}.}
 \attribute{text}{anchor}{anchor}{The anchor used in positionning the item. The default
 value is {\tt nw}.}
 
+\attribute{text}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{text}{color}{gradient}{Specifies the uniform (possibly transparent) color for
 drawing the text characters, the overstrike and underline lines. The first color of a
 real gradient color will be used. The default value is the current value of
@@ -3391,7 +3419,7 @@ siblings of the same parent group. The default value is {\tt 1}.}
 \attribute{text}{sensitive}{boolean}{Specifies if the item should react to events. The
 default value is {\tt true}.}
 
-\attribute{text}{spacing}{dimension}{Specifies a pixel value that will be added to the
+\attribute{text}{spacing}{short}{Specifies a pixel value that will be added to the
 inter-line spacing specified in the font. The value can be positive to increase the
 spacing or negative to reduce it. The default value is {\tt 0}.}
 
@@ -3407,7 +3435,7 @@ characters. The default value is {\tt false}.}
 \attribute{text}{visible}{boolean}{Specifies if the item is displayed. The default value
 is {\tt true}.}
 
-\attribute{text}{width}{dimension}{Specifies the maximum pixel width of the text, a line
+\attribute{text}{width}{<unsigned short}{Specifies the maximum pixel width of the text, a line
 break will be automatically inserted at the closest character position to match this
 constraint. If the value is zero, the width is not under the item control and line breaks
 must be inserted in the text to have multiple lines. The default value is {\tt 0}.}
@@ -3428,6 +3456,9 @@ Applicable attributes for \ident{icon} are:
 \attribute{icon}{anchor}{anchor}{The anchor used in positionning the item. The default
 value is {\tt nw}.}
 
+\attribute{icon}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{icon}{color}{gradient}{Specifies the uniform (possibly transparent) fill color
 used for drawing the bitmap. The first color of a real gradient color will be used. If
 The icon contains an image, only the transparency of the color is used and
@@ -3494,6 +3525,11 @@ The default value is the current value of the widget option \optref{forecolor}.}
 \attribute{reticle}{brightlinestyle}{linestyle}{This is the line style of the highlighted
 circles. The default value is {\tt simple}.}
 
+\attribute{reticle}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt false}.}
+In the current implementation, this item will not react to events even if this attribute
+is set.
+
 \attribute{reticle}{composealpha}{boolean}{Specifies if the alpha value inherited from
 the parent group should be composed with the alpha of this item. The default value is {\tt true}.}
 
@@ -3556,6 +3592,11 @@ command or more generally created and edited with a set of commands described in
 
   Applicable attributes for \ident{map} are:
 
+\attribute{map}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt false}.}
+In the current implementation, this item will not react to events even if this attribute
+is set.
+
 \attribute{map}{color}{gradient}{Specifies the uniform (possibly transparent) color used
 to draw or fill the map. The texts and symbols that are part of the map are also drawn in
 this color. The first color of a real gradient color will be used. The
@@ -3616,6 +3657,9 @@ value is {\tt ""}.}
 
   Applicable attributes for \ident{rectangle} are:
 
+\attribute{rectangle}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{rectangle}{composealpha}{boolean}{Specifies if the alpha value inherited from
 the parent group should be composed with the alpha of this item. The default value is {\tt true}.}
 
@@ -3689,6 +3733,9 @@ value is {\tt true}.}
 
   Applicable attributes for \ident{arc} are:
 
+\attribute{arc}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{arc}{closed}{boolean}{Specifies if the outline of the arc should be
 closed. This is only pertinent if the arc extent is less than 360 degrees. The default
 value is {\tt false}.}
@@ -3792,6 +3839,9 @@ attribute has priority over the \attributeref{arc}{fillcolor} attribute and the
 
   Applicable attributes for \ident{curve} are:
 
+\attribute{curve}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{curve}{capstyle}{capstyle}{Specifies the form of the outline ends. This
 attribute is only applicable if the curve is not closed and the outline relief is
 flat. The default value is {\tt round}.}
@@ -3897,8 +3947,13 @@ it is also available in the X environment albeit with less features.
 
 Applicable attributes for \ident{triangles} are:
 
+\attribute{triangles}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}.}
+
 \attribute{triangles}{colors}{gradientlist}{Specifies the colors of each vertex of the
-triangles.}  %% XXX what if less/more colors than vertex?
+triangles. If the list has less colors than the number of vertices the last color is
+propagated on the remaining vertices. If the list contains colors in excess they are
+discarded.}
 
 \attribute{triangles}{composealpha}{boolean}{Specifies if the alpha value inherited from
 the parent group should be composed with the alpha of this item. The default value is {\tt true}.}
@@ -3951,6 +4006,11 @@ Applicable attributes for \ident{window} items are:
 \attribute{window}{anchor}{anchor}{The anchor used in positionning the item. The default
 value is {\tt nw}.}
 
+\attribute{triangles}{catchevent}{boolean}{Specifies if the item should block and possibly
+react to events or be transparent event wise. The default value is {\tt true}. It is not
+possible to actually turn off event catching when this attribute is reset. The events are
+caught by the embedded window and nothing can prevent this to happen.}
+
 \attribute{window}{composealpha}{boolean}{Specifies if the alpha value inherited from
 the parent group should be composed with the alpha of this item. The default value is {\tt true}.}
 
@@ -3966,7 +4026,7 @@ placed. Connected item should be in the same group. The default value is {\tt ""
 \attribute{window}{connectionanchor}{anchor}{Specifies the anchor on the connected item
 used for the placement. The default value is {\tt sw}.}
 
-\attribute{window}{height}{dimension}{Specifies the height of the item window in screen
+\attribute{window}{height}{integer}{Specifies the height of the item window in screen
 units. The default value is {\tt 0}.}
 
 \attribute{window}{position}{point}{The item's position relative to the anchor (if no
@@ -3986,7 +4046,7 @@ value is {\tt ""}.}
 \attribute{window}{visible}{boolean}{Specifies if the item is displayed. The default value
 is {\tt true}.}
 
-\attribute{window}{width}{dimension}{Specifies the width of the item window in screen
+\attribute{window}{width}{integer}{Specifies the width of the item window in screen
 units. The default value is {\tt 0}.}
 
 \attribute{window}{window}{window}{Specifies the X id of the window that is displayed by
@@ -4256,16 +4316,6 @@ by any new user of TkZinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.
   and {\tt round}.
 \end{blockindent}
 
-\attrtype{color}
-\begin{blockindent}
-  This is a string that describes a color. The description may have one of two forms, a
-  colorname such as {\tt green} or {\tt LemonChiffon} or an rgb specification in one of
-  the following formats, {\tt \#rgb}, {\tt \#rrggbb}, {\tt \#rrrgggbbb} or {\tt
-  \#rrrrggggbbbb}. If less than four digits are provided for a color component, they
-  represent the most significant bits of the component. For example {\tt \#3a7} is
-  equivalent to {\tt \#3000a0007000}.
-\end{blockindent}
-
 \attrtype{dimension}
 \begin{blockindent}
   This is a string that represent distance. The string consists in a floating point signed