- describing news of the 3.2.96

- documenting  skew, tcompose and tset
- better documenting tsave
- documenting 'device' tag

1 files changed, 73 insertions, 26 deletions

diff --git a/doc/refman.tex b/doc/refman.tex
index 009505c..7947079 100644
--- a/doc/refman.tex
+++ b/doc/refman.tex
@@ -293,6 +293,10 @@ This document is also referenced as CENA technical note NT03-532.
 
 \subsection{Differences between 3.2.96 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 
+'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
@@ -334,7 +338,7 @@ format documentation has been enhanced.
 \item  the TkZinc command may return the version number
 \item  icom items may be scaled and rotated (needs openGL)
 \item  anti-overlapping of tracks labels works again
-\item  tsave can now be used to know if a named transformation is already defined 
+\item  tsave can now be used to know if a named transform is already defined 
 \item  gname can now be used to know if a named gradient is already defined 
 \item  new tags can now be used : ``pathTags'' to go through groups. 
 \item  find and addtag commands have been modified to be ``pathTag'' compliant
@@ -400,7 +404,7 @@ description of textual indices.
 
 The chapter \conceptref{Widget commands}{commands} describes the commands which apply to a
 Zinc widget. They are used for creating, modifying or deleting objects, applying
-transformations ...
+transforms ...
 The chapter \conceptref{Item types}{items} describes all the items provided by TkZinc along
 with their attributes.
 The chapter \conceptref{Labels, fields and labelformat}{labelsandfields} describes the
@@ -666,7 +670,7 @@ actual source of the default color. Its default value is
 
 \option{lightangle}{lightAngle}{LightAngle}
 \begin{blockindent}
-  Specifies the lighting angle used when displaying relief. The default value is {\tt 120}. %%% XXX CM to be completed!
+  Specifies the lighting angle in degre used when displaying relief. The default value is {\tt 120}. %%% XXX CM to be completed!
 \end{blockindent}
 
 \option{mapdistancesymbol}{mapDistanceSymbol}{MapDistanceSymbol}
@@ -1038,9 +1042,9 @@ all the items in an absolute coordinate system known as the window space.
 
 Just after item creation, the item transformation is set to identity, i.e the item
 coordinate system maps exactly on the system of its group. The commands
-\cmdref{translate}, \cmdref{scale}, \cmdref{rotate} can be used to modify
-this relationship to the effect of translating, enlarging, shrinking or
-rotating the item. It must be emphasized that those commands act on the
+\cmdref{translate}, \cmdref{scale}, \cmdref{rotate} , \cmdref{skew} can be 
+used to modify this relationship to the effect of translating, enlarging, shrinking,
+rotating or skewing the item. It must be emphasized that those commands act on the
 relation between two coordinate spaces, \emph{not} on the item geometry itself.
 If the goal is to change the item (except for groups, see next paragraph) geometry,
 the command \cmdref{coords} may be more appropriate (but see below the command
@@ -1064,8 +1068,11 @@ good factorization example.
 
 In fact, transformation are so useful that a whole set of functions are available
 to help use them in full. Apart from the already mentioned \cmdref{translate},
-\cmdref{scale} and \cmdref{rotate} commands, it is also possible to restore a
-transformation to its initial state, identity, with the \cmdref{treset} command.
+\cmdref{scale}, \cmdref{rotate}, and \cmdref{skew} commands, it is also possible 
+to restore a transformation to its initial state, identity, with the 
+\cmdref{treset} command. 
+It is also possible to compose a transformation with another name transform with 
+the \cmdref{tcompose} command.
 
 An item transformation can be saved under a name, in fact creating
 a named transformation which can be manipulated just as an item transformation (i.e
@@ -1471,14 +1478,15 @@ In this chapter, we first list all commands by categories, then we details each
 
 \item{Items creation and deletion} : \cmdref{add} \cmdref{becomes}  \cmdref{clone} \cmdref{remove}
 
-\item{Accessing options and attributes} : \cmdref{configure} \cmdref{gettags} \cmdref{itemcget}
-\cmdref{itemconfigure}  \cmdref{group}  \cmdref{chggroup}  \cmdref{coords}
+\item{Accessing options and attributes} : \cmdref{chggroup} \cmdref{configure} 
+\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}
 
-\item{Transformations} :  \cmdref{rotate}  \cmdref{scale} \cmdref{tapply} \cmdref{tdelete}
-\cmdref{transform} \cmdref{translate} \cmdref{treset} \cmdref{tsave}
+\item{Transformations} :  \cmdref{rotate}  \cmdref{scale} \cmdref{skew} \cmdref{tapply}
+\cmdref{tcompose} \cmdref{tdelete} \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}
 \cmdref{raise} 
@@ -2442,7 +2450,7 @@ false.
   tagOrId} describes a named transform then this transform is used to do the operation. If
   {\tt tagOrId} describes more than one item then all the items are affected by the
   operation. If {\tt tagOrId} describes neither a named transform nor an item, an error is
-  raised. The angle is given in radians. The optional parameters describe the center of
+  raised. The angle is given in radian. The optional parameters describe the center of
   rotation, which defaults to the origin.
 \end{blockindent}
 
@@ -2524,6 +2532,20 @@ false.
 \end{blockindent}
 
 
+\zinccmd{skew}{tagOrIdOrTName xSkewAngle ySkewAngle}
+
+{\tt\large \$zinc->{\bf skew}(tagOrIdOrTName, xSkewAngle, ySkewAngle);}
+
+\begin{blockindent}
+  Add a skew (or shear) transform to the  to the items or the transform described 
+  by {\tt tagOrIdOrTName}. If {\tt tagOrId} describes a named transform then this 
+  transform is used to do the operation. If {\tt tagOrId} describes more than 
+  one item then all the items are affected by the operation. 
+  If {\tt tagOrId} describes neither a named transform nor an item, an 
+  error is raised. The angles are given in radian.
+\end{blockindent}
+
+
 \zinccmd{smooth}{coordList}
 
 {\tt\large @coords = \$zinc->{\bf smooth}(coordList);}
@@ -2548,6 +2570,21 @@ false.
 \end{blockindent}
 
 
+\zinccmd{tcompose}{tagOrIdOrTName tName ?invert?}
+
+{\tt\large \$zinc->{\bf tcompose}(tagOrIdOrTName, tName);}\\
+{\tt\large \$zinc->{\bf tcompose}(tagOrIdOrTName, tName, invert);}
+
+\begin{blockindent}
+  Modify either the named transform {\tt tagOrIdOrTName} or the corresponding 
+  item by composing the {\tt tName} transform. The {\tt invert} boolean, if specified, 
+  causes the {\tt tName} transform to be inverted prior composition.
+
+  If {\tt tagOrIdOrTName} describes neither a named transform nor an item, an error is
+  raised. If {\tt tName} does not describe a named transform an error is raised.
+\end{blockindent}
+
+
 \zinccmd{tdelete}{tName}
 
 {\tt\large \$zinc->{\bf tdelete}(tName);}
@@ -2578,25 +2615,20 @@ false.
 
   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},
-  the id of the item.
+  the id of the item. It can also be done by using the predefined tag 'device' as first argument.
 
   It is also possible to convert from the coordinate space of an item to the window
-  coordinate space but it is a bit more tricky. In order to be able to do so, the root
-  group must not have any transform. Its coordinate space is thus the window coordinate
-  space. In this case it is possible to use this group as the {\tt tagOrIdTo} of the transform
-  command to obtain the desired effect.
+  coordinate space by using the predefined tag 'device' as second argument.
 
   For example:
 
   \begin{itemize}
-    \item{\verb+($x, $y) = $zinc->transform($mygroup, [$xdev, $ydev]);+}\\
+    \item{\verb+($x, $y) = $zinc->transform('device', $mygroup, [$xdev, $ydev]);+}\\
       transforms the point described by \verb+$xdev,$ydev+ in window coordinates,
       to \verb+$mygroup+ coordinates in \verb+$x,$y+;
-    \item{\verb+($xdev, $ydev) = $zinc->transform($mygroup, $top, [$x, $y]);+}\\
+    \item{\verb+($xdev, $ydev) = $zinc->transform($mygroup, 'device', [$x, $y]);+}\\
       transforms the point described by \verb+$x,$y+ in \verb+$mygroup+
-      coordinates, to window coordinates in \verb+$xdev,$ydev+, assuming that \verb+$top+
-      is a group whose coordinate space is equivalent to window space, for example
-      the root group after a \cmdref{treset};
+      coordinates, to window coordinates in \verb+$xdev,$ydev+
     \item{\verb+($x2, $y2) = $zinc->transform($group1, $group2, [$x1, $y1]);+}\\
       transforms the point described by \verb+$x1,$y1+ in \verb+$group1+ coordinates,
       to \verb+$group2+ coordinates in \verb+$x2,$y2+;%$
@@ -2646,14 +2678,29 @@ false.
 {\tt\large \$zinc->{\bf tsave}(tagOrdIdOrTName, tName, invert);}
 
 \begin{blockindent}
-  Create (or reset) a transform associated with the name {\tt tName} which has for initial
+  Create (or reset) a transform associated with the name {\tt tName} with initial
   value the transform associated with the item {\tt tagOrIdOrTName}. If {\tt tagOrIdOrTName} describes
   more than one item, the topmost in display list order is used. If {\tt tagOrIdOrTName} doesn't
-  describe any item, an error is raised. If {\tt tName} already exists, the transform is
-  set to the new value. This command is the only way to create a named transform.
+  describe any item or named transformation, an error is raised. If {\tt tName} already exists, 
+  the transform is set to the new value. This command is the only way to create a named transform.
   If {\tt tagOrIdOrTName} is not specified, the command returns a boolean telling if the
   name is already in use. The {\tt invert} boolean, if specified, cause the transform
   to be inverted prior to be saved.
+
+  It is possible to create a new named transformation from the identity by using the predefined tag 'identity': {\verb+$zinc->tsave('identity', 'myTransfo');+}
+% $  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);}
+
+\begin{blockindent}
+  Set the six elements of the 3x4 matrix used in affine transformation for 
+  {\tt tagOrIdOrTName}. \bf{ BEWARE that depending on mij values, it is possible 
+  to define a not inversible matrix which will end up in core dump. This 
+  method must BE USED CAUTIOUSLY. }
 \end{blockindent}