- mise � jour du delta de la doc par rapport � la v3.2.6

- documentation de l'evolution des curves
- documentation des changements de forme des coordslist
 dans les methodes add 'curve', coords, contour, smooth et fit
- documentation du changement des operateur de la methode contour
- documentation du changement dans les gradients "radial" et "path"
- documentation de la mani�re de tracer les appels de methodes zinc

1 files changed, 109 insertions, 59 deletions

diff --git a/doc/refman.tex b/doc/refman.tex
index d56dfa5..5a3fed4 100644
--- a/doc/refman.tex
+++ b/doc/refman.tex
@@ -205,9 +205,9 @@
 \setlength{\marginparwidth}{20pt}
 \setlength{\textwidth}{480pt}
 
-\title{Zinc, an advanced scriptable Canvas.\\The 3.2.6 Reference Manual.\\\small{[CENA technical Note NT02-782]} }
+\title{Zinc, an advanced scriptable Canvas.\\The 3.2.6d Reference Manual.\\\small{[CENA technical Note NT02-782]} }
 \author{Patrick Lecoanet}
-\date{10 October 2002}
+\date{20 December 2002}
 
 
 \begin{document}
@@ -289,15 +289,21 @@ This document is also referenced as the CENA technical note NT02-782.
 \subsection{Differences current release and 3.2.6 release}
 \begin{itemize}
 \item  bezier item has been suppressed; they can now be easily replaced by curve item.
-\item  curve item supports now a high level description: they may be composed of line
-segment, arcs and bezier.
+\item  curve items support now a high level description: they may be composed of line
+segment, and bezier. In a future release they will also support other kinds of segments
+(such as arcs...).
+\item  the coords method accept a list of arrays as well as flat list of coordinates.
+When coords returns more than one point it is always a list of arrays.
+(and no more a flat list of x y x y ...). \bf+Beware this is an incompatible change in the API+.
 \item  operators of the contour command are now \ident{add} \ident{addhole} \ident{remove}.
 contours ids are now predictable. The GPC ``not-so-free'' library is no more used.
 So Zinc is again fully free software.
+\item  the syntax of radial and path gradient has been changed.
+\item  TkZinc comes now with a patched version of Tk.pm to trace every TkZinc method call
 \item  the hierarchical view in ZincDebug.pm can now display some choosen attributes
 in a choosen format.
 \item  pathTags introduced in 3.2.6 have been examplified and documented. Label and label
-format documentation has been enhanced. 
+format documentation has been enhanced.
 \end{itemize}
 
 \subsection{Differences between 3.2.6 and 3.2.4 release}
@@ -1287,12 +1293,12 @@ item. Indices are accepted as parameters by commands managing text: \cmdref{curs
   \ident{x} and \ident{y} are interpreted as window coordinates. If the point lies outside
   of the area corvered by the item, they refer to the first or last character in the line
   that is closest to the point.
-\item{\ident{bol}}
-\item{\ident{eol}}
-\item{\ident{bow}}
-\item{\ident{eow}}
-\item{\ident{up}}
-\item{\ident{down}}
+\item{\ident{bol}} refers to the beginning of line
+\item{\ident{eol}} refers to the end of line
+\item{\ident{bow}} refers to the beginning of word
+\item{\ident{eow}} refers to the end of word
+\item{\ident{up}}  refers to previous line
+\item{\ident{down}} refers to next line
 \end{description}
 
 
@@ -1333,7 +1339,7 @@ In this chapter, we first list all commands by categories, then we details each
 \item{Bindings} : \cmdref{bind} \cmdref{focus}
 
 \item{Coordinates} : \cmdref{anchorxy} \cmdref{bbox} \cmdref{coords} \cmdref{contour}
-\cmdref{fit} \cmdref{smooth} \cmdref{vertexat}
+\cmdref{fit} \cmdref{smooth} \cmdref{transform} \cmdref{vertexat}
 
 \item{Named resources} : \cmdref{gname} \cmdref{gdelete} \cmdref{tsave}
 
@@ -1381,10 +1387,18 @@ reference) and all list parameters are given as array references.
     The origin should be the top left vertex of the enclosing rectangle and the
     corner the bottom right vertex of the rectangle.
   \item{\bf curve} \\
-    The curve type expects a list of floating point numbers \verb+x0 y0 x1 y1 ... xn yn+,
+    The curve type expects either a flat list or a list of list. In the first case, the flat list
+    must be a list of floating point numbers \verb+x0 y0 x1 y1 ... xn yn+,
     giving the coordinates of the curve vertices. The number of values should be
     pair (or the last value will be discarded) but the list can be empty to build
-    an empty invisible curve. This curve can be defined later with the \cmdref{contour}
+    an empty invisible curve. In the second case, the list must contain lists of 2 or 3
+    items: 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 an example of 2 beziers segments with a straight segment in between:
+    \verb+( [x0, y0], [x1, y1, 'c'], [x2, y2, 'c'], [x3, y3], [x4, y4, 'c'], [x5, y5] )+ As
+    There is only on control point (point 4) for the second cubic bezier, the omitted second
+    control point  will be defaulted to point 4.
+    A curve can be defined later with the \cmdref{contour}
     or \cmdref{coords} commands. As a side effect of the curve behavior, a one vertex
     curve is essentially the same as an empty curve, it only waste some more memory.
   \item{\bf rectangle} \\
@@ -1686,7 +1700,7 @@ false.
 
 \zinccmd{contour}{tagOrId ?operatorSpec coordListOrTagOrId?}
 
-{\tt\large \$zinc->{\bf contour}(tagOrId);}
+{\tt\large \$zinc->{\bf contour}(tagOrId);}\\
 {\tt\large \$zinc->{\bf contour}(tagOrId, operatorSpec, coordListOrTagOrId);}
 
 \begin{blockindent}
@@ -1705,8 +1719,9 @@ false.
   on the item having a contour or not. For example {\tt Tracks} yield 0 while
   {\tt Rectangles} yield 1.
 
-  {\tt coordListOrTagOrId} specifies a list of coordinates or an item describing a
-  contour. If a list is specified it should contain a pair number of floating point values
+  {\tt coordListOrTagOrId} specifies a list of coordinates (either a flat list of X and Y, or
+  a list similar to the one allowed for a curve item) or an item describing a
+  contour. If a flat list is specified it should contain a pair number of floating point values
   specifying the contour vertices X and Y in order. If a tag or an id is specified, it is
   should be from one of these classes: arc, curve, icon, rectangle, tabular, text,
   window. The external shape of the item will be used as the contour. If {\tt
@@ -1716,23 +1731,17 @@ false.
   {\tt operator} specifies the operation that will be carried. This can be:
   
   \begin{description}
-  \item{\ident{add}} 
-  \item{\ident{addhole}} 
-  \item{\ident{remove}} 
+  \item{\ident{add}} to extend the surface of the curve
+  \item{\ident{addhole}} to create a hole or to remove a part o the surface
+  \item{\ident{remove}} to remove an existing contour
   \end{description}
 
-  The following operation are now more available (from Version 3.2.6c): \ident{diff},
-  \ident{inter}, \ident{union}, \ident{xor}.
+  The following operation are no more available (from version 3.2.6c): \ident{diff},
+  \ident{inter}, \ident{union}, \ident{xor}; From version 3.2.6c, the order of the contours
+  generated by the \ident{contour} command is easily predictable
   An error is generated if the items are not of a correct type or if the coordinate list
   is malformed.
 
-  The order of the contours generated by the command is not easily predictable, as a
-  result, it is not easy to use the coords command to edit those contours. Another side
-  effect is the reordering of the contours vertices depending whether the contour is
-  classified as an internal hole or as an external contour (externals are clockwise while
-  holes are counter-clockwise). This is usually not a problem if the curve item is used to
-  describe polygonal areas but can lead to unpredicted effects on real unclosed curves.
-  
 \end{blockindent}
 
 
@@ -1745,9 +1754,10 @@ false.
   tagOrId} describes more than one item, the first in display list order is used. The
   optional {\tt contour} gives the contour, if available, that should be operated. The
   default contour is 0. The optional {\tt index} gives the vertex index that should be
-  operated in the given contour. The optional {\tt coordList} is a list of one or more
-  vertices described as X, Y floating point values that will be used to replace or add
-  coordinates to the current contour.
+  operated in the given contour. The optional {\tt coordList} is either a flat list (of
+  one or more vertices described as X, Y floating point values) or a list of list
+  [X Y ?type?] such as described in the curve item. The coordinates will be used to
+  replace or add coordinates to the current contour.
 
   Almost all items can be manipulated by this command, the map item is the only current
   exception. The effect of the command can be quite different depending on the item. For
@@ -1757,9 +1767,13 @@ false.
   read. For tracks setting the current position this way will make the previous position
   shift into the history. For reticles, the coordinates of the center can be set or
   read. For arcs and rectangles, the coordinates of the origin and corner can be set or
+  read. For curves and triangles, coordinates of all points defining the item can be set or
   read. For all items that do not support multiple contours (currently all except curves)
   the {\tt contour} parameter should be omitted or specified as zero.
-  
+
+  When \tt{coords} is used to get more than one point, the return value is \bf{always} a
+  list of lists. Each sub list contains X, Y and 'c' if the point is a bezier control point.
+
   The optional parameters must be combined to produce a given behavior. Here are the
   various form recognized by the command:
 
@@ -1787,7 +1801,7 @@ false.
     Get coordinate at coordIndex in contour at contourIndex. All items can answer if
     contourIndex is zero. Curves can handle other contours. For groups, icons, texts,
     windows, tabulars, reticles, tracks, waypoints, coordIndex must be zero. For
-    rectangles and arcs, index must zero or one.
+    rectangles and arcs, coordIndex must zero or one.
     
   \item{\tt\large
          pathname {\bf coords} tagOrId contourIndex coordIndex coordList\\      
@@ -1963,11 +1977,9 @@ false.
   This command fits a sequence of Bezier segments on the curve described by the vertices
   in {\tt coordList} and returns a list of vertices describing the control points for the
   generated segments. All the points on the fitted segments will be within {\tt error}
-  distance from the given curve.  {\tt coordList} should contain a pair number of
-  coordinates in x, y order. The returned control point list consists of four control
-  points per Bezier segment with two consecutive segments sharing their last/first control
-  point. The control points are in x, y order and can be used to create or change a
-  Bezier item.
+  distance from the given curve.  {\tt coordList} should be either a flat list of even
+  number of coordinates in x, y order or a lst of [X, Y]. The returned list can be directly used
+  to create or change a curve item contour.
 \end{blockindent}
 
 
@@ -2335,12 +2347,10 @@ false.
 
 \begin{blockindent}
   This command computes a sequence of Bezier segments in order to smooth the curve
-  described by the vertices in {\tt coordList} and returns a list of vertices describing
-  the control points for the generated segments. {\tt coordList} should contain a pair
-  number of coordinates in x, y order. The returned control point list consists of four
-  control points per Bezier segment with two consecutive segments sharing their last/first
-  control point. The control points are in x, y order and can be used to create or change
-  a bezier part of a curve item.
+  described by the vertices in {\tt coordList} and returns a list of lists describing
+  points and control points for the generated segments. {\tt coordList} should be either a
+  flat list of even number of coordinates in x, y order, or a list of [X, Y].
+  The returned list can be used to create or change a contour of a curve item.
 \end{blockindent}
 
 
@@ -2375,8 +2385,10 @@ false.
   tagOrIdTo}. If {\tt tagOrIdFrom} is omitted it defaults to the window coordinate
   space. If either {\tt tagOrId} describes more than one item, the topmost in display list
   order is used. If {\tt tagOrId} doesn't describe either a transform or an item, an error
-  is raised. The {\tt coordList} should contains an even number of coordinates each point
-  having two coordinates.
+  is raised. The {\tt coordList} should either be a flat list containing an even number of
+  coordinates each point having two coordinates, or a list of lists each sublist of the form
+  [ X Y ?pointtype? ]. The returned coordinates list will be isomorphic to the list given
+  as argument.
 
   It is possible to convert from window coordinate space to the coordinate space of any
   item. This is done by omitting {\tt ?tagOrIdFrom?} and specifying in {\tt tagOrIdTo},
@@ -3403,12 +3415,12 @@ attribute has priority over the \attributeref{arc}{fillcolor} attribute and the
 \object{curve}
 
 
-  Items of type \ident{curve} display a path of line segments connected by their end
-  points. It is possible to build curve items with more than one path to describe complex
-  shapes with the \cmdref{contour} command. This command can be used to perform boolean
-  operations between a curve and almost any other item available in Zinc including
-  another curve. The polygon delimited by the path can optionally be filled. In the
-  following figure, two curves with four holes each are in front of a text. You can
+  Items of type \ident{curve} display a path of line segments and or cubic bezier connected
+  by their end points. It is possible to build curve items with more than one path to
+  describe complex shapes with the \cmdref{contour} command. This command can be used to
+  perform boolean operations between a curve and almost any other item available in Zinc
+  including another curve. The polygon delimited by the path can optionally be filled.
+  In the following figure, two curves with four holes each are in front of a text. You can
   partially see the text through the holes.
 
 \fig{textthroughholes}{Two curves with 4 holes each. A text is visible behind}{0.8}
@@ -3929,10 +3941,13 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.}
   angle of the gradient in degres.
 
   The \verb+(x y+ section tells that the gradient is a radial gradient and give the center
-  of the gradient.
+  of the gradient. The center is expressed in percentage of the bounding box, centered on the middle.
+  so \verb+(0 0+ means the center point of the bounding box, and \verb+(-50 -50+ means
+  the lower left corner of the bounding box.
 
   The \verb+[x y+ section tells that the gradient is a path gradient and give the center
-  of the gradient.
+  of the gradient. The center is expressed in % of the bounding box, centered on the middle.
+  See just above for more explanation.
 
   If none of the above gradient type specification is given, the gradient will be drawn as
   an axial gradient with a null angle.
@@ -3970,13 +3985,13 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.}
 
 \verb+axial 4 :  'black|black:0/30'+
 
-\verb+radial 1 : 'white|black(25 15'+
+\verb+radial 1 : 'white|black(-14 -20'+
 
-\verb+radial 2 : 'white:50 0 70|black 50|white 100(35 25'+
+\verb+radial 2 : 'white:50 0 70|black 50|white 100(0 0'+
 
-\verb+path 1 :   'white|black:80[25 15'+
+\verb+path 1 :   'white|black:80[-14 -20'+
 
-\verb+path 2 :   'white|white 30|black:80[25 15'+
+\verb+path 2 :   'white|white 30|black:80[-14 -20'+
 
 \fig{allgradients}{Examples of axial, radial and path gradients}{0.5}
 
@@ -4351,6 +4366,41 @@ visibility, group...\ and even more information on request. When an application
 the main window of this application. Please refer to the \ident{ZincDebug.pm} man pages
 with the classical command {\tt man ZincDebug}
 
+\section{Tracing Zinc methods call in perl/Tk}
+
+Because you some time get some errors inside \ident{TkZinc} with a cryptic message
+like {\tt ``.... errors in Tk.pm line 288''} 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 patched version of the \ident{Tk.pm} module, released with TkZinc.
+This module replaces and explands the perl/Tk Tk.pm and will trace
+every cal to a TkZinc method. It will trace on the standard output the following informations:
+
+\begin{itemize}
+\item  the TkZinc method name
+\item the full filename where this method has been invoked
+\item the line number in the source file
+\item the list of arguments in a human-readable form
+\end{itemize}
+
+To use this module you must just add to the Perl path the directory
+where the modified Tk.pm is located. The exact location depends on your installation
+but it should be in a subdirectory named ZincTrace, for example:
+{\tt /usr/lib/perl/5.6.1/ZincTrace}
+
+So you can for example set or extend the content of the PERLLIB or PERL5LIB environment variables:
+
+{\tt setenv PERL5LIB /usr/lib/perl/5.6.1/ZincTrace} (csh)
+
+or
+
+{\tt export PERL5LIB=/usr/lib/perl/5.6.1/ZincTrace} (sh or ksh)
+
+or you can use the -I option of the perl command:
+
+{\tt perl -I/usr/lib/perl/5.6.1/ZincTrace myscript.pl}
+
+or you can expand the value of the @INC variable in a perl script.
+
 \section{zinc-demos}
 
 Starting at version 3.2.4 of Zinc small applications are included as demos. They