diff options
| -rw-r--r-- | doc/refman.tex | 306 |
1 files changed, 162 insertions, 144 deletions
diff --git a/doc/refman.tex b/doc/refman.tex index 5a3fed4..6c92b73 100644 --- a/doc/refman.tex +++ b/doc/refman.tex @@ -36,8 +36,8 @@ citecolor=webbrightgreen, pdftitle={Zinc, an advanced scriptable Canvas.}, pdfauthor={Patrick Lecoanet, Centre d'Étude de la Navigation Aérienne}, - pdfsubject={The 3.2.6 Reference Manual.}, - pdfkeywords={tk tcl perl x11 canvas opengl script gui zinc}, + pdfsubject={The 3.3 Reference Manual.}, + pdfkeywords={tk tcl perl x11 canvas opengl script gui TkZinc}, pagebackref, pdfpagemode=None, bookmarksopen=true @@ -205,9 +205,9 @@ \setlength{\marginparwidth}{20pt} \setlength{\textwidth}{480pt} -\title{Zinc, an advanced scriptable Canvas.\\The 3.2.6d Reference Manual.\\\small{[CENA technical Note NT02-782]} } +\title{Zinc, an advanced scriptable Canvas.\\The 3.3 Reference Manual.\\\small{[CENA technical Note NT02-782]} } \author{Patrick Lecoanet} -\date{20 December 2002} +\date{15 January 2003} \begin{document} @@ -231,13 +231,13 @@ \concept{introduction} -\section{What is Zinc ?} +\section{What is TkZinc ?} -Zinc widgets are very similar to Tk Canvases in that they support -structured graphics. Like the Canvas, Zinc implements items used to +TkZinc widgets are very similar to Tk Canvases in that they support +structured graphics. Like the Canvas, TkZinc implements items used to display graphical entities. Those items can be manipulated and bindings can be associated with them to implement interaction behaviors. But unlike the -Canvas, Zinc can structure the items in a hierarchy (with the use of +Canvas, TkZinc can structure the items in a hierarchy (with the use of group items), has support for affine 2D transforms (i.e.\ translation, scaling, and rotation), clipping can be set for sub-trees of the item hierarchy, the item set is quite more powerful including field specific items for Air Traffic systems and @@ -245,18 +245,18 @@ new rendering techniques such as transparency and gradients. If needed, it is al possible to extend the item set in an additionnal dynamic library through the use of a C api. -Since the 3.2.2 version, Zinc also offers as a runtime option, the support +Since the 3.2.2 version, TkZinc also offers as a runtime option, the support for openGL rendering, giving access to features such as antialiasing, transparency, color gradients and even a new, openGL oriented, item type : \objectref{triangles}. In order to use the openGL features, you need the support of the GLX extension on your X11 server. Of course, performances will be dependant of your graphic card. At the time of writing, NVidia drivers for XFree86 R4.1 are doing a nice job. A laptop with a GeForce GO graphic card works nice for non trivial applications. We also -succeeded in using Zinc with openGL on the Exceed X11 server (running on windows and +succeeded in using TkZinc with openGL on the Exceed X11 server (running on windows and developped by Hummingbird) with the 3D extension. -As an example of Zinc capabilities when combined with openGL, we implemented -the tk Zinc logo as a Perl module (available as a goodie in \ident{LogoZinc.pm}). +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. @@ -264,7 +264,7 @@ This logo (see below) was designed with Adobe Illustrator and then programmed in \fig{tkzinclogo}{Zinc Logo written as a Perl/Tk module}{1} -Like the canvas Zinc focuses on the notion of script language. We strongly +Like the canvas TkZinc focuses on the notion of script language. We strongly believe that the script environments are very powerful for rapid prototyping and for developping small to medium scale field specific applications. In these cases developper know-how and time are a scarce resource and the application either has few @@ -272,34 +272,36 @@ clients or is short lived. It is important to grant non-specialists an access to powerful tools that are available today for HMI building, through a rather simple product. -The Zinc widget is available for the Tcl/Tk and the Perl/Tk scripting +The TkZinc widget is available for the Tcl/Tk and the Perl/Tk scripting environments. A binding over Tcl/Tk is also provided for Python. It should be easy to do the same for Ruby, a binding for Tk is provided in the standard distribution of Ruby. Other scripting languages may be used as well depending on the availability of a Tk interface. This document is Tcl/Tk and Perl/Tk oriented but it should be easy for Python or Ruby -programmers to adapt. Every time a Zinc command is described in this +programmers to adapt. Every time a TkZinc command is described in this document, it is given first in Tcl/Tk idiom and then in Perl/Tk idiom. This document is also referenced as the CENA technical note NT02-782. \section{Differences with previous version} -\subsection{Differences current release and 3.2.6 release} +\subsection{Differences between 3.3 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 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 +\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 +segments, and bezier segments. In the future they may 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. +(and no more a flat list of x y x y ...). {\bf Beware this is an small incompatible change in the API}. +\item operators of the contour command have been replaced by a flag which indicates +if the contour must be taken as counterclockwise, clockwise or unchanged. +Contours ids are now predictable. The GPC ``not-so-free'' library is no more used. +It has been replaced by the GLU library. So TkZinc is again fully free software. +\item curve item have a new -fillrule attribute. \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 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 pathTags introduced in 3.2.6 have been examplified and documented. Label and label @@ -313,7 +315,7 @@ format documentation has been enhanced. \item the contour command can return the contour number \item the ZincDebug.pm perl module has been fairly augmented \item the find command may return item ancestor(s) -\item the zinc command may return the version number +\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 @@ -330,18 +332,18 @@ format documentation has been enhanced. \subsection{Differences between 3.2.4 and 3.2.2 release} \begin{itemize} \item many bug corrections, of course! -\item Zinc can now use openGL capablities +\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 as color are all gradient (with alpha transparency) the -alpha option has been removed -\item a set of zinc demontrations are available with the zinc-demos command +\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 \end{itemize} -\section{Where can I find Zinc and documentation ?} +\section{Where can I find TkZinc and documentation ?} \ident{Zinc} is available as source in tar.gz format or as Debian or RedHat/Mandrake packages at @@ -352,24 +354,24 @@ packages at \anurl{http://freshmeat.net/projects/zincisnotcanvas/} \end{itemize} -For people from CENA, its possible to get the Zinc source code through +For people from CENA, its possible to get the TkZinc source code through a private CVS server. Please contact directly {\tt lecoanet@cena.fr} for more informations. -This documentation is available as part of the Zinc software. It is also +This documentation is available as part of the TkZinc software. It is also available separately on the web sites. This document is formatted with \LaTeX\ and is distributed as either html pages or a pdf file. -As a complement to this reference manual, small Perl/Tk demos of Zinc are -also available through a small application named \ident{zinc-demos}, highly inspired -from the \emph{widget} application included in Tk. The aim of these demos are both -to demonstrates the power of Zinc and to help newcomers start using +As a complement to this reference manual, small Perl/Tk demos of TkZinc are +also available through a small application named \conceptref{zinc-demos}{zinc-demos}, +highly inspired from the \emph{widget} application included in Tk. The aim of these demos +are both to demonstrates the power of TkZinc and to help newcomers start using Zinc with small examples. \section{What is this document about ?} -This reference manual describes the Tk Zinc widget interface. It shows how to -create and configure a Zinc widget, and how to use the commands it provides to +This reference manual describes the TkZinc widget interface. It shows how to +create and configure a TkZinc widget, and how to use the commands it provides to create and manipulate items. The next chapter \conceptref{Widget creation and options}{options} describes how to create a new widget and which options and resources are available to configure it. @@ -383,7 +385,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 ... -The chapter \conceptref{Item types}{items} describes all the items provided by Zinc along +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 use of labels, the possible attributes of fields and finally the labelformat syntax. @@ -393,7 +395,7 @@ The chapter \conceptref{The mapinfo commands}{mapinfocmds} introduces the mapinf simple map description structure, and describes the commands used to create and manipulate mapinfos. Finally the chapter \conceptref{Other resources provided by the widget}{otherresources} -describes some resources provided by or with Zinc. +describes some resources provided by or with TkZinc. \section{Copyright and Licence} @@ -448,26 +450,26 @@ users and helped a lot either by reporting bugs, problems or solutions. Thanks t these people and to the CENA for supporting this work. The core of this documentation has been written by Patrick Lecoanet, the main author -of Zinc. This documentation has been enriched by Christophe Mertz. +of TkZinc. This documentation has been enriched by Christophe Mertz. -\section{How can I find help with Zinc} +\section{How can I find help with TkZinc} If you are stuck with a feature you don't understand. If you don't know how to -do something with Zinc. If you think you have found a bug or a mismatch between +do something with TkZinc. If you think you have found a bug or a mismatch between the documentation and the behavior of the widget. Please feel free to contact us. -Mail either {\tt lecoanet@cena.fr} or the Zinc mailing list. To subscribe to the mailing +Mail either {\tt lecoanet@cena.fr} or the TkZinc mailing list. To subscribe to the mailing list, please consult the site \anurl{http://www.openatc.org/zinc/}. -\section{How may I contribute to Zinc development} +\section{How may I contribute to TkZinc development} -If you think Zinc is an interesting tool, they are many ways to help with Zinc -development. First of all, subscribe to the Zinc mailing list and get in touch with us. To +If you think TkZinc is an interesting tool, they are many ways to help with TkZinc +development. First of all, subscribe to the TkZinc mailing list and get in touch with us. To subscribe, please consult the site \anurl{http://www.openatc.org/zinc/}. \begin{itemize} -\item The very first way to contribute is to use Zinc and to report +\item The very first way to contribute is to use TkZinc and to report any bug or problem you may experiment. Of course, if you send a script that exhibits the problem or even better a patch, your problem will have more chance to find a solution. @@ -479,11 +481,11 @@ may even try to write a tutorial, but that may be quite an undertaking! of demos (see chapter \conceptref{Other resources provided by the widget}{otherresources}). Feel free to send us your productions. They may be simple but demonstrative or more complex. It is up to you! They will be integrated in the -next release of Zinc if they are worth it. +next release of TkZinc if they are worth it. \item The fourth way to contribute, and may be the most difficult, is to enrich the set of items (see section \conceptref{C api for adding new items}{Capi}) in an separate dynamic library. Then send us source code (with appropriate copyright and licence) -if you want them to be integrated in a future release of Zinc. +if you want them to be integrated in a future release of TkZinc. \end{itemize} @@ -495,7 +497,7 @@ if you want them to be integrated in a future release of Zinc. \chapter{Widget creation and options} \concept{options} -The Zinc command creates a new Zinc widget, the general form are in Tcl and Perl: +The TkZinc command creates a new TkZinc widget, the general form are in Tcl and Perl: \begin{quote} {\tt\large zinc}\medskip @@ -505,7 +507,7 @@ The Zinc command creates a new Zinc widget, the general form are in Tcl and Perl {\tt\large \$Tk::Zinc::VERSION;} \end{quote} -These expressions can be used to get the version of Zinc. The string returned by the last expression also details the graphic head available. For example : ``zinc-version-3205d X11 GL''. +These expressions can be used to get the version of TkZinc. The string returned by the last expression also details the graphic head available. For example : ``zinc-version-3205d X11 GL''. \begin{quote} {\tt\large zinc pathname ?options?}\medskip @@ -516,7 +518,7 @@ These expressions can be used to get the version of Zinc. The string returned by {\tt pathname} name the new widget and specifies where in the widget hierarchy it will be located. -Any new Zinc widget comes with a root group item, always identified by +Any new TkZinc widget comes with a root group item, always identified by the item id 1. This group will contain all other items, either directly or through groups created themselves in the root group. Together the items form a tree rooted at the root group, hence its name. @@ -531,7 +533,7 @@ Tk commands. Options apply only to the widget itself. They are a Tk supported concept and benefit from the option database an other mechanisms used to externally adapt the application to different environments. Attributes are a similar concept available for -items and other Zinc objects. But they are private to Zinc and do not benefit from Tk +items and other TkZinc objects. But they are private to TkZinc and do not benefit from Tk support. They have been named differently to avoid confusion. Any number of options may be specified on the command line or in the option @@ -542,7 +544,7 @@ described below. \option{backcolor}{backColor}{BackColor} { This is the color that will -be used to fill the Zinc window. It is also used as a default color +be used to fill the TkZinc window. It is also used as a default color for some item color attributes. See each color attribute for the actual source of the default color. Its default value is {\tt \#c3c3c3}, a light grey. @@ -551,7 +553,7 @@ actual source of the default color. Its default value is \option{borderwidth}{borderWidth}{BorderWidth} { Specifies the width of the 3d border that should be displayed around the widget - window. This border does overlap the active Zinc display area. The area + window. This border does overlap the active TkZinc display area. The area requested from the geometry manager (or the window manager if applicable) is the area defined by \optref{width} and \optref{height}, the border is not taken into account. This value can be given in any of the forms valid for @@ -560,7 +562,7 @@ actual source of the default color. Its default value is \option{cursor}{cursor}{Cursor} { - Specifies the cursor to use when the pointer is in the Zinc window. The default + Specifies the cursor to use when the pointer is in the TkZinc window. The default value is set to preserve the cursor inherited at widget creation. } @@ -579,15 +581,15 @@ actual source of the default color. Its default value is \option{fullreshape}{fullReshape}{FullReshape} { - If this option is True, the shape applied to the Zinc window will propagate up the + If this option is True, the shape applied to the TkZinc window will propagate up the window hierarchy to the toplevel window. The result will be a shaped toplevel. See also the \optref{reshape} option, it controls whether a shape is applied - to the Zinc window or not. The default is {\tt true}. + to the TkZinc window or not. The default is {\tt true}. } \option{height}{height}{Height} { - Specifies the height of the Zinc window. This value can be given in any of the + Specifies the height of the TkZinc window. This value can be given in any of the forms valid for coordinates (See \cident{Tk\_GetPixels}). The default is {\tt 100} pixels. } @@ -693,7 +695,7 @@ actual source of the default color. Its default value is \option{reshape}{reshape}{Reshape} { Specifies if the clipping shape that can be set in the root group item should clip - the root group children or be used to reshape the Zinc window. This option can be + the root group children or be used to reshape the TkZinc window. This option can be used with the fullreshape option to reshape the toplevel window as well. The default value is {\tt true}. } @@ -738,7 +740,7 @@ actual source of the default color. Its default value is \option{tile}{tile}{Tile} { - Specifies an image name to be used as a tile for painting the Zinc window + Specifies an image name to be used as a tile for painting the TkZinc window background. The default value is {\tt ""} (the empty string). } @@ -766,7 +768,7 @@ actual source of the default color. Its default value is \option{width}{width}{Width} { - Specifies the width of the Zinc window. This value can be given in any of + Specifies the width of the TkZinc window. This value can be given in any of the forms valid for coordinates (See \cident{Tk\_GetPixels}). The default is {\tt 100} pixels. } @@ -784,7 +786,7 @@ actual source of the default color. Its default value is Groups are very powerful items. They have no graphics of their own but are used to bundle items together so that they can be manipulated easily as a whole. Groups can modify in several way how items are displayed and how they react to events. They have -many uses in Zinc and we will describe them in this chapter. The main usages +many uses in TkZinc and we will describe them in this chapter. The main usages are: \begin{itemize} @@ -809,7 +811,7 @@ are: An item, be it simple like a rectangle or more complex like a group, is always created relative to a group which is known as is parent, the group's items are its children. The items form a tree whose nodes are the group items. The top-most node is -known as the root group, of id 1, which is automatically created with Zinc. By +known as the root group, of id 1, which is automatically created with TkZinc. By convention, the root group is its own parent. It is not possible to change the parent of the root group and it is not possible to delete it. However, it is possible to change the group of all other items after creation, and thus modify the item tree at @@ -848,7 +850,7 @@ group is completly transparent so far. So the event dispatch mecanism will try t the smallest most visible item containing the pointer and will trigger the associated bindings. Not exactly what we meant. So groups have a feature, the \attributeref{group}{atomic} attribute, that is used to seal a group so that events cannot -propagate past it downward. If an item part of an atomic group is under the pointer, Zinc +propagate past it downward. If an item part of an atomic group is under the pointer, TkZinc 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. @@ -858,8 +860,8 @@ Such search command will not traverse an atomic group. So if a part of the atomi group is enclosed or overlapping, the search command will return the atomic group and not its part. -A small program, \ident{Atomic groups} is available as part of \ident{zinc-demos} to demonstrate the -atomic groups behaviour. +A small program, \ident{Atomic groups} is available as part of +\conceptref{zinc-demos}{zinc-demos} to demonstrate the atomic groups behaviour. \section{Display order and display lists} @@ -908,7 +910,7 @@ groups. \section{Transformations} -In Zinc each item is geometrically defined in its own coordinate space. So +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. This coordinate system must be related to the coordinate systems of the other items to place the items with respect to each other. This relationship is @@ -1011,10 +1013,11 @@ transformation, \emph{not} to the item transformation itself which is composed \ taking into account the composition attributes. As you can see, the transformation process is quite powerful but complex. A small program, -\ident{Tranformation testbed} is available as part of \ident{zinc-demos} to demonstrate the -transformation capabilities of zinc. This is also a great resource to understand how it -works and to tame its complexity. It is possible to use this program to test one's idea on -a given transformation problem before coding it as part of a complex application. +\ident{Tranformation testbed} is available as part of \conceptref{zinc-demos}{zinc-demos} +to demonstrate the transformation capabilities of TkZinc. This is also a great resource +to understand how it works and to tame its complexity. It is possible to use this program +to test one's idea on a given transformation problem before coding it as part of a +complex application. \section{Clipping and groups} @@ -1045,7 +1048,7 @@ Each item is associated with a unique numerical id which is returned by the \cmdref{add} or \cmdref{clone} commands. All commands on items accept those ids as (often first) parameter in order to uniquely identify on which item they should operate. When an id has been allocated to an item, it is never -collected even after the item has been destroyed, in a Zinc session two +collected even after the item has been destroyed, in a TkZinc session two items cannot have the same id. This property can be quite useful when used in conjonction with tags, which are described below. @@ -1060,8 +1063,8 @@ around and thus it is illegal to use it. Tags can be used to group items to do some action, or to mark an item that has a special function. Many other tasks can be solved with tags once one gets used to them. -Two special tags are implicitly managed by Zinc. The tag \ident{all} is -associated with all items in Zinc. The tag \ident{current} is always +Two special tags are implicitly managed by TkZinc. The tag \ident{all} is +associated with all items in TkZinc. The tag \ident{current} is always associated with the topmost item that lies under the mouse pointer. If no such item exists, no item has this tag. @@ -1217,7 +1220,7 @@ Tags are also very useful to associate scripts with events. The \cmdref{bind} command is used to specify a script to be invoqued when an event sequence is associated with a tag. -The event dispatch mecanism in Zinc collects which tags are related to a given event and +The event dispatch mecanism in TkZinc collects which tags are related to a given event and then use the bindings established by \cmdref{bind} to activate the related scripts. Event dispatching operates on three event sources: mouse events, keyboard events and internally generated enter/leave events. Mouse events are dispatched to the item under the mouse @@ -1353,8 +1356,8 @@ In this chapter, we first list all commands by categories, then we details each The available commands are listed in alphabetical order. -The command set for the Zinc widget is much inspired by the Canvas command set. Someone -comfortable with the Canvas should not have much trouble using the Zinc's commands. +The command set for the TkZinc widget is much inspired by the Canvas command set. Someone +comfortable with the Canvas should not have much trouble using the TkZinc's commands. Eventually, the command set will be a superset of the Canvas command set. Anyway some commands depart radically from the equivalent in the Canvas. For example, the user should be aware that \cmdref{scale} and \cmdref{translate} do not behave in the same @@ -1373,8 +1376,8 @@ reference) and all list parameters are given as array references. {\tt\large \$id = \$zinc->{\bf add}(type, group, initargs, option=>value, ..., ?option=>value?);} \begin{blockindent} - This command is used to create new items in a Zinc widget. It can be called with no - parameters to return the list of all item types currently known by Zinc. It can also be + This command is used to create new items in a TkZinc widget. It can be called with no + parameters to return the list of all item types currently known by TkZinc. It can also be called with a valid item type as first parameter and a group item as second parameter to create a new item of this type in the given group. @@ -1461,7 +1464,7 @@ reference) and all list parameters are given as array references. pathname {\bf addtag} tag all ?inGroup? ?recursive?\\ \$zinc->{\bf addtag}(tag, 'all', ?inGroup?, ?recursive?);} - This form is no more allowed since version 3.2.6 of Zinc. + This form is no more allowed since version 3.2.6 of TkZinc. Please use a form ``'withtag', 'all''' as documented below. \item{\tt\large @@ -1521,7 +1524,7 @@ reference) and all list parameters are given as array references. if the search should descend in the item tree or not. recursive is true by default. - It may be necessary to update the Zinc internal geometry with a call + It may be necessary to update the TkZinc internal geometry with a call to {\tt update} if the current state is not stable (i.e before calling the main loop or in a callback after modifying the transform or doing something else affecting the geometry of items). @@ -1611,7 +1614,7 @@ reference) and all list parameters are given as array references. the sequences for which there are bindings for {\tt tagOrId}. This widget command is similar to the Tk \ident{bind} command except that it operates on - Zinc items instead of widgets. Another difference with the \ident{bind} command + TkZinc items instead of widgets. Another difference with the \ident{bind} command is that only mouse and keyboard related events can be specified (such as \ident{Enter}, \ident{Leave}, \ident{ButtonPress}, \ident{ButtonRelease}, \ident{Motion}, \ident{KeyPress}, \ident{KeyRelease}). The \ident{bind} manual page is the most @@ -1701,7 +1704,7 @@ false. \zinccmd{contour}{tagOrId ?operatorSpec coordListOrTagOrId?} {\tt\large \$zinc->{\bf contour}(tagOrId);}\\ -{\tt\large \$zinc->{\bf contour}(tagOrId, operatorSpec, coordListOrTagOrId);} +{\tt\large \$zinc->{\bf contour}(tagOrId, operatorAndFlag, coordListOrTagOrId);} \begin{blockindent} Manipulate contours on items that can handle multiples geometric contours. Currently @@ -1728,17 +1731,23 @@ false. coordListOrTagOrId} describes more than one item, the first in display list order will be used. - {\tt operator} specifies the operation that will be carried. This can be: + {\tt operatorAndFlag} specifies the operation that will be carried. This can be: \begin{description} - \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{add}} to extend the surface of the curve. In this case there is a mandatory + flag describing the way the contour will be added. It may take the following values: + \begin{description} + \item{0} the list of points is taken unchanged. + \item{1} the list of points is reverted, if needed, so that the points defines + a {\bf counterclockwise} contour. + \item{-1} the list of points is reverted,if needed, so that the points defines + a {\bf clockwise} contour. + \end{description} \item{\ident{remove}} to remove an existing contour \end{description} - 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 + The following operations are no more available: \ident{diff}, + \ident{inter}, \ident{union}, \ident{xor}; An error is generated if the items are not of a correct type or if the coordinate list is malformed. @@ -1810,7 +1819,8 @@ false. Set coordinate at coordIndex in contour at contourIndex. All items can do it 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, coordIndex must zero or one. + rectangles and arcs, coordIndex must zero or one. {\bf WARNING:} coordList must be a + list of one list describing x, y and optionnaly the point type. \item{\tt\large pathname {\bf coords} tagOrId remove contourIndex coordIndex\\ @@ -2030,7 +2040,7 @@ false. \zinccmd{gname}{?gradientDesc? gradientName} -{\tt\large \$zinc->{\bf gname}('black:100|white:0/0', 'fading');} +{\tt\large \$zinc->{\bf gname}('black:100|white:0/0', 'fading');}\\ {\tt\large \$exist = \$zinc->{\bf gname}('nameOrGradient');} \begin{blockindent} @@ -2505,7 +2515,7 @@ false. \chapter{Item types} \concept{items} -This chapter introduces the item types that can be used in Zinc. Each item type +This chapter introduces the item types that can be used in TkZinc. Each item type provides a set of options that may be used to query or change the item behavior. Some item types cannot be used with some widget commands, or use special parameters with some commands. Those cases are noted in the description of the item. @@ -2606,14 +2616,14 @@ positions. This track also shows a marker, the circle around the current positio %%% XXX CM add here an image with a openGL track (end ticks,... antialising...) -An other very important feature of \ident{track} item is that Zinc offers an +An other very important feature of \ident{track} item is that TkZinc offers an anti-overlap manager. This manager tries to avoid any overlap of tracks labels. It also avoids that the label overlap the speedvector. This manager is stable over time: there should be few cases where labels are moved to a very different position. This manager applies to all tracks included in a group (by default the group 1). It can be enabled/disabled with the attributes XXX. New labels positions are computed by the overlap manager every time a track is moved, a track is created or destroyed and every time the -Zinc widget is resized. Due to software licence limitation, Zinc \emph{do not include} +TkZinc widget is resized. Due to software licence limitation, TkZinc \emph{do not include} the very last version of this anti-overlap manager. If you are interested in this anti-overlap manager, please contact Didier Pavet at {\tt pavet@cena.fr}. @@ -3005,7 +3015,7 @@ value is {\tt true}.} Text items are used for displaying text. They can also be used for text input. In this case, they must get the focus for keyboards events with the command \cmdref{focus}. Many -Zinc options (see chapter \conceptref{Widget options}{options} can be used for +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 @@ -3415,13 +3425,16 @@ attribute has priority over the \attributeref{arc}{fillcolor} attribute and the \object{curve} - 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 + Items of type \ident{curve} display a path of line segments and/or cubic bezier connected + by their end points. The polygon delimited by the path can optionally be filled. + 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. + perform boolean operations between a curve and almost any other item available in TkZinc + including another curve. The exact appearance of a multi-contour curve (i.e. which parts + are filled and which are holes) depends on the value of an attribute, called + \attributeref{curve}{fillrule}. + In the following figure (a snapshot of \conceptref{zinc-demos}{zinc-demos}) 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} @@ -3457,6 +3470,12 @@ value is {\tt false}.} \attribute{curve}{fillpattern}{bitmap}{Specifies the pattern to use when filling the item. The default value is {\tt ""}.} +\attribute{curve}{fillrule}{fillrule}{Specifies the way contours are combined together to +specify complex surfaces, with holes and disjoint surfaces. The default value is {\tt "odd"}. +This means that a point of the space is considered inside the curve surface if an odd number +of contours are surrounding the point. This attribute should only be modified for curves with +multiple or complicated contours.} + \attribute{curve}{firstend}{lineend}{Describes the arrow shape at the start of the curve. This attribute is applicable only if the item is not closed, not filled and the relief of the outline is flat. The default value is {\tt ""}.} @@ -3567,11 +3586,11 @@ value is {\tt true}.} position of the window, relative to the anchor, can be set or read with the \cmdref{coords} command (i.e. if no connected item is specified). - One of the most frequent use of this item is to embed any Tk widget into Zinc, - including, of course, another Zinc instance. Another less obvious use is to embed a - whole Tk application into Zinc, here is how to do it: The embedding application should + One of the most frequent use of this item is to embed any Tk widget into TkZinc, + including, of course, another TkZinc instance. Another less obvious use is to embed a + whole Tk application into TkZinc, here is how to do it: The embedding application should create a frame with the \ident{-container} option set to true; Add a window item to the - relevant Zinc widget with the \attributeref{window}{window} attribute set to the id of + relevant TkZinc widget with the \attributeref{window}{window} attribute set to the id of the container frame; The embedded application should create its toplevel with the \ident{-use} option set to the id of the container frame; Or, as an alternative, the embedded \cident{wish} can be launched with the \ident{-use} option set to the container @@ -3633,17 +3652,17 @@ default value is {\tt ""}.} \chapter{Labels, label formats and fields} \concept{labelsandfields} -Zinc was initially developed for building interactive radar image working on X +TkZinc was initially developed for building interactive radar image working on X server. This requires very good performances, for displaying many hundred tracks and moving them every few seconds. Tracks are typically composed of some geometric parts and some textual parts. These two parts are connected together with a leader. The geometric parts are subject to scaling. For example the speed vector length in pixel depends on the scale. But the textual part must not be zoomed. Managing parts which are scaled and others which are not, can be a real challenge. Usual toolkits or widget are not suited to such -behaviours, but Zinc is. +behaviours, but TkZinc is. To be able to manage many items mixing geometric parts and non-geometric parts, -Zinc introduces the concepts of label, labelformat, fields and fields attributes. +TkZinc introduces the concepts of label, labelformat, fields and fields attributes. \section {Labels and labelformats} \concept{label} \concept{labelformat} @@ -3810,11 +3829,11 @@ value is {\tt true}.} \chapter{Attribute types} \concept{types} -We describe in this chapter all the available types in Zinc. They are listed by +We describe in this chapter all the available types in TkZinc. They are listed by alphabetical order. \emph{NB: Two types are very important and their existence should be known -by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} +by any new user of TkZinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{alignment} @@ -3859,7 +3878,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{bitmap} \begin{blockindent} This should be a string naming a valid Tk bitmap. The bitmap should be known to Tk prior - to its use. Zinc registers a set of bitmaps that can be used for any bitmap valued + to its use. TkZinc registers a set of bitmaps that can be used for any bitmap valued attribute (see section \conceptref{Bitmaps}{builtinbitmaps}). Extensions to Tk are available to create or manipulate bitmaps from a script. The value may also name a file containing a valid X11 bitmap description. The syntax in this case is {\tt @filename}. @@ -3911,9 +3930,20 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \fig{alledges}{edgelist examples}{0.5} +\end{blockindent} + +\attrtype{fillrule} +\begin{blockindent} + This is a string describing the rule used to compose the different contours or pathes of + a curve. The allowed values are directly inspired from the openGL GLU tesselators as +described for example in the chapter 11 of the ``The OpenGL Programming Guide 3rd Edition +The Official Guide to Learning OpenGL Version 1.2'', ISBN 0201604582. You can also refer to +the example fillrule provided with TkZinc in \conceptref{zinc-demos}{zinc-demos}. The allowed values are +{\tt odd}, {\tt nonzero}, {\tt positive}, {\tt negative}, and {\tt abs\_geq\_2}. \end{blockindent} + \attrtype{font} \begin{blockindent} This is a string describing a font. For an exhaustive description of what is legal as a @@ -4240,7 +4270,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} style ({\tt simple}, {\tt dashed}, {\tt dotted}, {\tt mixed}, {\tt marked}), an integer value setting the line width in pixels, two integer values setting the X and Y of the arc center, integer value setting the arc radius and two integer values setting the - start angle and the angular extent of the arc. + start angle (in degree) and the angular extent of the arc (in degree). \item{symbol} \\ This element describes a symbol. Its parameters consists in two integer values setting the X and Y of the symbol position and an integer setting the symbol index in the {\tt -symbols} list of the map item. @@ -4330,14 +4360,14 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \chapter{Other resources provided by the widget} \concept{otherresources} -In this chapter we describe resources included in Zinc widget. This include +In this chapter we describe resources included in TkZinc widget. This include bitmaps sets (used as symbols for some items or used as stipples), Perl modules goodies -and Zinc simple demonstrations. +and TkZinc simple demonstrations. \section{Bitmaps} \concept{builtinbitmaps} -Zinc creates two sets of bitmaps. +TkZinc creates two sets of bitmaps. The first set contains symbols for ATC tracks position, waypoints position and maps symbols. These bitmaps are named AtcSymbol1 to AtcSymbol22. @@ -4358,7 +4388,7 @@ named AlphaStipple0 to AlphaStipple15, AlphaStipple0 being the most transparent. \section{ZincDebug.pm} \ident{ZincDebug.pm} is a Perl module useful for debugging purpose. It can be used in a -Perl application using Zinc to grab items with the mouse and to get the list of +Perl application using TkZinc to grab items with the mouse and to get the list of items enclosed or overlapped by a rectangle designated by the mouse. You will be presented an item list, with many interesting attributes such as position, priority, visibility, group...\ and even more information on request. When an application uses @@ -4366,15 +4396,14 @@ 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} +\section{Tracing TkZinc 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 +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 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: - +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: \begin{itemize} \item the TkZinc method name \item the full filename where this method has been invoked @@ -4382,30 +4411,19 @@ every cal to a TkZinc method. It will trace on the standard output the following \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. +To use this module you can either import either by adding the following +statement in your source code: +\code{import ZincTrace;} or better, by using the -M option of Perl: +\code{perl -MZincTrace yourscript.pl} \section{zinc-demos} +\concept{zinc-demos} -Starting at version 3.2.4 of Zinc small applications are included as demos. They -are all accessible through an application called \ident{zinc-demos}. These tiny demos are -useful for newcomers and as starting points for developing real applications. +Starting at version 3.2.4 of TkZinc small applications are included as demos. They +are all accessible through an application called \ident{zinc-demos}. These numerous +(about 30) tiny demos are useful for newcomers and as starting points for developing +real applications. They consists in toy applications, graphically advanced examples +or even a TkZinc port of \ident{TkTetris} from Slaven Rezic. \section{ZincText.pm} \concept{zinctext} @@ -4419,7 +4437,7 @@ Please read the man page for more details: {\tt man Tk::ZincText} \section{C api for adding new items} \concept{Capi} -The C function AddItemClass provided with the source code of Zinc, can be used to extent +The C function AddItemClass provided with the source code of TkZinc, can be used to extent the default set of items in TkZinc in an additionnal dynamic library. The AddItemClass C function is extensively used for implementing the core item set. So please refer to the source code for examples or send email for more information on precise problems. |