updates for 3.2.97 bis

1 files changed, 137 insertions, 42 deletions

diff --git a/doc/refman.tex b/doc/refman.tex
index 651f53f..b8cda01 100644
--- a/doc/refman.tex
+++ b/doc/refman.tex
@@ -208,9 +208,9 @@
 \setlength{\marginparwidth}{20pt}
 \setlength{\textwidth}{480pt}
 
-\title{Zinc, an advanced scriptable Canvas.\\The pre 3.3 (3.2.96) Reference Manual.\\\small{[CENA technical Note NT03-532]} }
+\title{Zinc, an advanced scriptable Canvas.\\The pre 3.3 (3.2.97) Reference Manual.\\\small{[CENA technical Note NT03-532]} }
 \author{Patrick Lecoanet, Christophe Mertz}
-\date{8 Octobre 2003}
+\date{1 April 2004}
 
 
 \begin{document}
@@ -291,16 +291,38 @@ This document is also referenced as CENA technical note NT03-532.
 
 \section{Differences with previous version}
 
-\subsection{Differences between 3.2.96 and 3.2.6 release}
+\subsection{Differences between 3.2.97 and 3.2.6 release}
 \begin{itemize}
-\item  Three new methods are now available for managing the transforms: 
-tcompose, tset and skew. A predefined named transformation is also available 
+\item  TkZinc now works with Perl ptk 8.4 and utf8; However there remains 
+some serious performance hit at launch time, when combinig openGL and ptk8.4,  
+due to utf8 fonts management.
+\item  text and icons can now be scaled and rotated in X (i.e. without openGL)
+\item  translate method accepts an additionnal argument 'absolute'
+\item  scale method accepts additionnal arguments: unit and rotation center
+\item  find and addtag methods can now search inside atomic group
+\item  the bbox method accepts into account the clipping area of a group
+\item  TkZinc option -trackmanagehistory is replaced by -trackvisiblehistorysize
+and in for track items the attribute -visiblehistorysize has been removed and
+replaced by  -historyvisible. {\bf Beware: Incompatible change}
+\item  Default value of -composescale and -composerotation of texts
+and icons is now false. This is coherent with the default behavior
+of these items (being rigids). The impact of this change is
+greatly minored by the new processing of the -position attribute.
+\item  transformation of items with a -position has been slightly
+modified. The point described by -position is no longer considered
+in the coordinate space of the item but in the coordinate space
+of its parent group. The item is always located in 0,0 of its
+own coordinate space. This is so to make use of -composescale and
+-composerotation a lot more useful (and compatible).
+\item  The fieldbbox method has been added to get item filed bounding box.
+\item  Four new methods are now available for managing the transforms: 
+tcompose, tget, tset and skew. A predefined named transformation is also available 
 'identity' to be used with tsave. A predefined tag 'device' can be used to 
 convert coordinates in or from device coordinates (with transform method).
 \item  TkZinc with Tcl/Tk now works on windows and MacOS X (with X11 and fink).
 \item  compilation on Linux works fine now, and TkZinc for Perl is on the CPAN
 \item  A powerful perl module Tk::Zinc::Graphics has been added to help creating
-complex curves 
+complex curves. French man pages are available. A port in Tcl is also available.
 \item  png images with transparencies can now be displayed (requires openGL rendering)
 \item  bezier items have been suppressed; they can now be easily replaced by curve items.
 \item  curve items support now a higher level of description: they may be composed of line
@@ -496,7 +518,9 @@ chance to find a solution.
 \item The second way to contribute is by commenting on and proposing enhancement to
 this reference manual. As it has been written by french writers, english readers may
 really help in making this document easier to use. If you really feel ambitious, you
-may even try to write a tutorial, but that may be quite an undertaking!
+may even try to write a tutorial, but that may be quite an undertaking! Some 
+documentation (currently Tk::Zinc::Graphics) are in French only. Translating it in
+english would be great.
 \item The third way to contribute, and may be the funniest way, is to enrich the set
 of demos (see chapter \conceptref{Other resources provided by the
 widget}{otherresources}). Feel free to send us your productions. They may be simple
@@ -945,8 +969,8 @@ propagate past it downward. If an item part of an atomic group is under the poin
 will try to trigger bindings associated with the atomic group not with the item under the
 pointer. This improves greatly the metaphor of an indivisible item.
 
-It must also be noted that commands such as \cmdref{find} 'enclosed'/'overlapping' or
-\cmdref{addtag} 'enclosed'/'overlapping' {\tt act differently on an atomic group}.
+It must also be noted that commands such as \cmdref{find} {\tt 'enclosed'/'overlapping'} or
+\cmdref{addtag} {\tt 'enclosed'/'overlapping'} {\bf act differently on an atomic group}.
 Such search command will not traverse an atomic group. So if a part of the atomic
 group is enclosed or overlapping, the search command will return the atomic group
 and not its part.
@@ -1480,10 +1504,10 @@ In this chapter, we first list all commands by categories, then we details each
 \cmdref{coords} \cmdref{gettags} \cmdref{group} \cmdref{itemcget} \cmdref{itemconfigure}    
 
 \item{Accessing field attributes of track, waypoint and tabular} :  \cmdref{currentpart}
-\cmdref{hasfields} \cmdref{itemcget} \cmdref{itemconfigure}  \cmdref{numparts}
+\cmdref{hasfields} \cmdref{fieldbbox} \cmdref{itemcget} \cmdref{itemconfigure}  \cmdref{numparts}
 
 \item{Transformations} :  \cmdref{rotate}  \cmdref{scale} \cmdref{skew} \cmdref{tapply}
-\cmdref{tcompose} \cmdref{tdelete} \cmdref{transform} \cmdref{translate} \cmdref{treset}
+\cmdref{tcompose} \cmdref{tdelete} \cmdref{tget} \cmdref{transform} \cmdref{translate} \cmdref{treset}
 \cmdref{tsave} \cmdref{tset}
 
 \item{Groups, Display list and Priorities} : \cmdref{chggroup} \cmdref{find}('ancestors') \cmdref{group} \cmdref{lower}
@@ -1497,7 +1521,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{hasanchor} \cmdref{smooth} \cmdref{transform} \cmdref{vertexat}
+\cmdref{fieldbbox} \cmdref{fit} \cmdref{hasanchor} \cmdref{smooth} \cmdref{transform} \cmdref{vertexat}
 
 \item{Named resources} : \cmdref{gname} \cmdref{gdelete} \cmdref{tsave}
 
@@ -1746,20 +1770,16 @@ reference) and all list parameters are given as array references.
 \end{blockindent}
 
 
-\zinccmd{bbox}{tagOrId ?fieldIndex?}
+\zinccmd{bbox}{tagOrId ?tagOrId ...?}
 
-{\tt\large (\$xo, \$yo, \$xc, \$yc) = \$zinc->{\bf bbox}(tagOrId, ?fieldIndex?);}
+{\tt\large (\$xo, \$yo, \$xc, \$yc) = \$zinc->{\bf bbox}(tagOrId, ?tagOrId ...?);}
 
 \begin{blockindent}
   Returns a list of 4 numbers describing the \emph{window coordinates} of the origin
   and corner of a rectangle bounding all the items named by the {\tt tagOrId}
-  argument. If no items are named by {\tt tagOrId} or if the matching items
-  have an empty bounding box, an empty string is returned. The bounding box of
-  a label field can be queried by specifying an optional {\tt fieldIndex}.
-  If {\tt fieldIndex} is ``label'' the bounding box of the label itself is returned.
-  These two forms of the command apply only to one item, if a tag is used the
-  first matching item is used, if the item does not support fields an empty
-  string is returned.
+  arguments. 
+  If no items are named by {\tt tagOrId} or if the matching items
+  have an empty bounding box, an empty string is returned.
 \end{blockindent}
 
 
@@ -1772,12 +1792,12 @@ reference) and all list parameters are given as array references.
 \end{blockindent}
 
 
-\zinccmd{bind}{tagOrId ?sequence? ?command?}
+\zinccmd{bind}{tagOrId ?part? ?sequence? ?command?}
 
-{\tt\large @bindings = \$zinc->{\bf bind}(tagOrId);}\\
-{\tt\large @binding = \$zinc->{\bf bind}(tagOrId, sequence);}\\
-{\tt\large \$zinc->{\bf bind}(tagOrId, sequence, '');}\\
-{\tt\large \$zinc->{\bf bind}(tagOrId, sequence, command);}
+{\tt\large @bindings = \$zinc->{\bf bind}(tagOrId, ?part?);}\\
+{\tt\large @binding = \$zinc->{\bf bind}(tagOrId, ?fpart?, sequence);}\\
+{\tt\large \$zinc->{\bf bind}(tagOrId, ?part?, sequence, '');}\\
+{\tt\large \$zinc->{\bf bind}(tagOrId, ?part?, sequence, command);}
 
 \begin{blockindent}
   This command associates {\tt command} with the item tag, item id, part tag {\tt
@@ -1815,6 +1835,10 @@ reference) and all list parameters are given as array references.
   the binding associated with the item part if relevant. If there are more than one
   binding for a single tag or id, only the most specific is triggered.
   
+  Two syntaxes are available for addressing item parts (for items having part ie. 
+  \objectref{track} \objectref{waypoint} and \objectref{tabular}): either an Id 
+  of the following form: {\tt id:part} or by using the optionnal {\tt part} argument.
+  
   If bindings have been registered for the widget window using the \ident{bind} command,
   they are invoked in addition to bindings registered for the items using this widget
   command. The bindings for items will be invoked before the bindings for the window.
@@ -2117,6 +2141,22 @@ false.
 \end{blockindent}
 
 
+\zinccmd{fieldbbox}{tagOrId fieldIndex}
+
+{\tt\large (\$xo, \$yo, \$xc, \$yc) = \$zinc->{\bf fieldbbox}(tagOrId, fieldIndex);}
+
+\begin{blockindent}
+  Returns a list of 4 numbers describing the \emph{window coordinates} of the origin
+  and corner of a rectangle bounding the item field indexed by {\tt fieldIndex}
+  of the item named by the {\tt tagOrId}  argument. If a tag is used the
+  first matching item is used. If no item is named by {\tt tagOrId} or 
+  if the matching item field have an empty bounding box, an empty string is returned.
+  If {\tt fieldIndex} is ``label'' the bounding box of the label itself is returned.
+  If the item does not support fields an empty
+  string is returned.
+\end{blockindent}
+
+
 \zinccmd{find}{searchCommand ?arg arg ...?}
 
 {\tt\large @items = \$zinc->{\bf find}(searchCommand, ?arg?, ...);}
@@ -2610,6 +2650,26 @@ false.
 \end{blockindent}
 
 
+\zinccmd{tget}{tagOrIdOrTName ?selector?}
+
+{\tt\large (\$m00, \$m01, \$m10, \$m11, \$m20, \$m21) = \$zinc->{\bf tget}(tagOrIdOrTName);}\\
+{\tt\large (\$xtranslate, \$ytranslate, \$xscale, \$yscale, \$angle, \$xskew) =\\
+                        \$zinc->{\bf tget}(tagOrIdOrTName, 'all');}\\
+{\tt\large (\$xtranslate, \$ytranslate) = \$zinc->{\bf tget}(tagOrIdOrTName,  'translate');}\\
+{\tt\large (\$xscale, \$yscale) = \$zinc->{\bf tget}(tagOrIdOrTName, 'scale');}\\
+{\tt\large (\$angle) = \$zinc->{\bf tget}(tagOrIdOrTName, 'rotate');}\\
+{\tt\large (\$xskew) = \$zinc->{\bf tget}(tagOrIdOrTName, 'skew');}
+
+\begin{blockindent}
+  With only one argument, get the six elements of the 3x4 matrix used in affine 
+  transformation for {\tt tagOrIdOrTName}. The result is compatible with the tset method.
+  With optional second parameter 'all' returns the transform decomposed in translation, 
+  scale, rotation, skew and return the list in this order,
+  With 'translation', 'scale', 'rotation', 'skew' optional second parameter, 
+  returns the corresponding values.
+\end{blockindent}
+
+
 \zinccmd{transform}{?tagOrIdFrom? tagOrIdTo coordList}
 
 {\tt\large @coords = \$zinc->{\bf transform}(tagOrIdTo, coordList);}\\
@@ -2651,9 +2711,9 @@ false.
 \end{blockindent}
 
 
-\zinccmd{translate}{tagOrIdOrTName xAmount yAmount}
+\zinccmd{translate}{tagOrIdOrTName xAmount yAmount ?absolute?}
 
-{\tt\large \$zinc->{\bf translate}(tagOrdIdOrTName, xAmount, yAmount);}
+{\tt\large \$zinc->{\bf translate}(tagOrdIdOrTName, xAmount, yAmount, ?absolute?);}
 
 \begin{blockindent}
   Add a translation to the items or the transform described by {\tt tagOrIdOrTName}. If {\tt
@@ -2661,6 +2721,8 @@ false.
   {\tt tagOrIdOrTName} describes more than one item then all the items are affected by the
   opration. If {\tt tagOrIdOrTName} describes neither a named transform nor an item, an error is
   raised. A separate value is specified for X and Y.
+  If the optionnal {\tt ?absolute?} parameter is true, it will set an absolute translation to
+  the {\tt tagOrIdOrTName}
 \end{blockindent}
 
 
@@ -2706,7 +2768,6 @@ false.
 % $  this comment is for emacs colorization only!
 \end{blockindent}
 
-
 \zinccmd{tset}{tagOrIdOrTName m00 m01 m10 m11 m20 m21}
 
 {\tt\large \$zinc->{\bf tset}(tagOrIdOrTName, m00, m01, m10, m11, m20, m21);}
@@ -2953,9 +3014,10 @@ is ??.}
 will be drawn in the same color as the current position instead of being drawn in the
 history color. The default value is {\tt false}.}
 
-\attribute{track}{leaderanchors}{leaderanchors}{The attachments of the leader on the label
-side. The default value is {\tt ""} which means that both leader anchors are at the label
-center.}
+\attribute{track}{leaderanchors}{leaderanchors}{The attachment of the leader on the label
+left or right side (whether the label is on the right or left of the current position). 
+The default value is {\tt ""} which means that the leader anchor is at the label
+center, whatever the label position.}
 
 \attribute{track}{leadercolor}{gradient}{The uniform (possibly transparent) color of the label
 leader. The first color of a real gradient color will be used. The default
@@ -3143,9 +3205,10 @@ the label anchor. The default value is computed from the values in the
 \attribute{waypoint}{labelformat}{labelformat}{Geometry of the label fields. The default
 value is {\tt ""} which means that no label will be displayed.}
 
-\attribute{waypoint}{leaderanchors}{leaderanchors}{The attachments of the leader on the
-label side. The default value is {\tt ""} which means that both leader anchors are at the
-label center.}
+\attribute{waypoint}{leaderanchors}{leaderanchors}{The attachment of the leader on the label
+left or right side (whether the label is on the right or left of the current position). 
+The default value is {\tt ""} which means that the leader anchor is at the label
+center, whatever the label position.}
 
 \attribute{waypoint}{leadercolor}{gradient}{The uniform (possibly transparent) color of the
 label leader. The first color of a real gradient color will be used. The
@@ -3279,6 +3342,10 @@ 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}).
 
+With and without openGL, text items can be rotated or scaled. However, 
+attributes \attributeref{text}{composerotation} and \attributeref{text}{composescale} 
+must be set before rotation and scaling.
+
 A Tcl module, zincText is available, it provides simple bindings for interactive
 text input. For enabling interactive text editing on an item, the item should
 be sensitive and should have the tag ``text''.
@@ -3364,8 +3431,9 @@ must be inserted in the text to have multiple lines. The default value is {\tt 0
 Icon items are used for displaying bitmap images. Any bitmap file format
 supported by Tk can be used. If the bitmap file supports transparency
 (not alpha-blending, only full transparency), TkZinc will render this transparent area.
-With openGL, icons can be rotated or scaled. However, attributes \attributeref{icon}{composerotation}
-and \attributeref{icon}{composescale} must be set before rotation and scaling.
+With and without openGL, icons can be rotated or scaled. However, 
+attributes \attributeref{icon}{composerotation} and \attributeref{icon}{composescale} 
+must be set before rotation and scaling.
 
 Applicable attributes for \ident{icon} are:
 
@@ -4252,6 +4320,11 @@ The following figure shows the effect of fillrule value on curves with multiple
   popular methods, it is possible to specify a font by it's X11 font name or by a list
   whose elements are the font family, the font size and then zero or more styles including
   {\tt normal}, {\tt bold}, {\tt roman}, {\tt italic}, {\tt underline}, {\tt overstrike}.
+
+  {\bf Please note, that some font data are cached by TkZinc, on the application level. 
+   This is specially usefull with openGL}. To avoid breaking the cache mecanism, you 
+   should avoid using a font once on only one item, then modifiy this item font
+   and repeat this again and again.
 \end{blockindent}
 
 \attrtype{gradient}
@@ -4370,9 +4443,19 @@ The following figure shows the effect of fillrule value on curves with multiple
 
 \attrtype{image}
 \begin{blockindent}
-  This should be the name of a previously registered Tk image. In pure Tk only GIF, PPM
+  This should be the name of a previously registered Tk image. 
+
+  In pure Tcl-Tk only GIF, PPM
   and bitmap formats are available as source for images. With the Img extension many
   others popular formats are added including JPEG, XPM and PNG.
+
+  In Perl/Tk most image formats can be used, specially with Tk::JPEG or Tk::PNG modules.
+
+  {\bf Please note, that some image data are cached by TkZinc, on the application level. 
+   This is specially usefull with openGL}. To avoid breaking the cache mecanism, you 
+   should avoid using an image once on only one item option, then modifiy this item option
+   and repeat this again and again.
+
 \end{blockindent}
 
 \attrtype{item}
@@ -4464,8 +4547,9 @@ The following figure shows the effect of fillrule value on curves with multiple
 
 \attrtype{leaderanchors}
 \begin{blockindent}
-  Describes where to attach the label leader on the label. These are not to be confused
-  with the regular rectangular anchors.
+  Describes where to attach the label leader on the label. Two positions can be defined: one 
+  when the label is at the right of current position and the other when the label is at the 
+  left of current position. {\bf Not to be confused with the regular rectangular anchors}.
   
   The format is: \verb+lChar leftLeaderAnchor [lChar rightLeaderAnchor]+
   
@@ -4723,7 +4807,7 @@ named AlphaStipple0 to AlphaStipple15, AlphaStipple0 being the most transparent.
 
 
 
-\section{Tk::Zinc::Debug.pm}
+\section{Tk::Zinc::Debug Perl module}
 
 \ident{Tk::Zinc::Debug.pm} is a Perl module useful for debugging purpose. It can be used in a
 Perl application using TkZinc to display the hierarchical tree of items, to display
@@ -4806,7 +4890,18 @@ are all accessible through an application called \ident{zinc-demos}. These numer
 real applications. They consists in toy applications, graphically advanced examples
 or even a TkZinc port of \ident{TkTetris} from Slaven Rezic.
 
-\section{Tk::Zinc::Text}
+\section{Tk::Zinc::Graphics Perl module}
+\concept{zincGraphics}
+
+The Tk::Zinc::Graphics Perl module implements many high level functions for 
+building high quality graphic objects with TkZinc.
+
+Please read the man page for more details: {\tt man Tk::Zinc::Graphics}, french 
+version only currently. Any volontear to translate it in English?
+
+NB: There is also a tcl version of this module.
+
+\section{Tk::Zinc::Text Perl module}
 \concept{zinctext}
 
 The Tk::Zinc::Text Perl module implements bindings for text input 'a la emacs'.