\documentclass[11pt,twoside]{book} %---------------------------------------------------------------------- % $Revision$ % % TODO % % Relire et reprendre l'item Track et compléter les attributs % Même chose pour triangles % Vérifier que les couleurs sont bien décrites comme des gradients % Les reliefs sont calculés sur le linecolor/bordercolor et non % sur le fillcolor comme avant % Ecrire les quelques descriptions d'item qui manquent. % Mettre quelques images: au moins une par item, une pour chaque relief, % une pour chaque type de gradient. % % \newif\ifpdf \ifx\pdfoutput\undefined \pdffalse % we are not running PDFLaTeX \else \pdfoutput=1 % we are running PDFLaTeX \pdftrue \fi \ifpdf \usepackage[pdftex, colorlinks=true, urlcolor=rltblue, anchorcolor=rltbrightblue, filecolor=rltgreen, linkcolor=rltred, menucolor=webdarkblue, 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}, pagebackref, pdfpagemode=None, bookmarksopen=true ]{hyperref} \pdfcompresslevel=9 \usepackage[pdftex]{graphicx} \usepackage{thumbpdf} \usepackage{color} \definecolor{rltred}{rgb}{0.75,0,0.20} \definecolor{rltgreen}{rgb}{0,0.5,0} \definecolor{rltblue}{rgb}{0,0,0.75} \else \usepackage{graphicx} \fi \usepackage{html} \usepackage{a4wide} \usepackage{makeidx} \newcommand{\cident}[1] {% {\tt #1}} \newcommand{\code}[1] {% {\tt #1}} \newcommand{\ident}[1] {% {\tt\large #1}} \newenvironment{blockindent}{\begin{quotation}\vspace{-0.8\baselineskip}}{\end{quotation}\vspace{\parskip}} \newcommand{\option}[3]{% \label{opt:#1} \index{#1} \latexhtml{\ifpdf\hyperdef{opt}{#1}{}\fi}{\htmlrule[WIDTH="300" left]} \begin{tabular}{rl} Command line switch: & \ident{-#1} \\ Database name: & \ident{#2} \\ Database class: & \ident{#3} \\ \end{tabular}} \newcommand{\command}[3]{% \label{cmd:#2} \index{#2} \latexhtml{\ifpdf\hyperdef{cmd}{#2}{}\fi}{\htmlrule[WIDTH="300" left]} {\tt\large #1 {\bf #2} #3}} \newcommand{\zinccmd}[2]{% \command{pathname}{#1}{#2}} \newcommand{\mapinfocmd}[3]{% \label{mapcmd:#2} \index{#2} \latexhtml{\ifpdf\hyperdef{mapcmd}{#2}{}\fi}{\htmlrule[WIDTH="300" left]} {\tt\large mapinfo #1 {\bf #2} #3}\\ {\tt\large \$mainwindow->mapinfo(#1, {\bf #2}, #3) } % slightly buggy XXX : missing commas when #3 contains many words } \newcommand{\attrtype}[1]{% \label{attrtype:#1} \index{#1} \latexhtml{\ifpdf\hyperdef{attrtype}{#1}{}\fi}{\htmlrule[WIDTH="300" left]} {\tt {\bf #1}} } \newcommand{\attrtyperef}[1]{% \latexhtml{\ifpdf\hyperlink{attrtype.#1}{\ident{#1}}\else\ident{#1}\fi}{% \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{attrtype:#1}} } % the following command is never used!! \newcommand{\available}[1]{% \latexhtml{\ifpdf\hyperlink{obj.#1}{\ident{#1}}\else\ident{#1}\fi}{% \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{obj:#1}} } \newcommand{\optref}[1]{% \latexhtml{\ifpdf\hyperlink{opt.#1}{\ident{-#1}}\fi}{% \hyperref[page]{\ident{-#1}}{\ident{-#1} (}{)}{opt:#1}} } \newcommand{\cmdref}[1]{% \latexhtml{\ifpdf\hyperlink{cmd.#1}{\ident{#1}}\else\ident{#1}\fi}{% \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{cmd:#1}} } %first argument : item type or 'option' %second argument: attribute %third argument : type %fourth argument; explanation \newcommand{\attribute}[4]{% \label{attribute:#1:#2} \ident{-#2 }% \index{#2} \latexhtml{\ifpdf\hyperlink{attrtype.#3}{\ident{#3}}\hyperdef{attribute}{#1#2}{}\fi}{% \hyperref[no]{\tt \bf #3}{\ident{#3}}{attrtype:#3}} \begin{quotation}\vspace{-\baselineskip}#4\end{quotation} } % first argument : item type or 'option' % second argument: attribute \newcommand{\attributeref}[2]{% \latexhtml{\ifpdf\hyperlink{attribute.#1#2}{\ident{-#2}}\else\ident{-#2}\fi}{% \hyperref[page]{\ident{#2}}{\ident{-#2} (}{)}{attribute:#1:#2}} } \newcommand{\object}[1]{% \label{obj:#1} \index{#1} \latexhtml{\ifpdf\hyperdef{obj}{#1}{}\fi}{\index{#1}} } \newcommand{\concept}[1]{% \label{concept:#1} \latexhtml{\ifpdf\hyperdef{concept}{#1}{}\fi}{} % XXX bug? en html? } \newcommand{\objectref}[1]{% \latexhtml{\ifpdf\hyperlink{obj.#1}{\ident{#1}}\else\ident{#1}\fi}{% \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{obj:#1}} } \newcommand{\conceptref}[2]{% \latexhtml{\ifpdf\hyperlink{concept.#2}{\ident{#1}}\else\ident{#1}\fi}{% \hyperref[page]{#1}{#1 (page }{)}{concept:#2}} } % Premier parametre : nom du fichier image % Deuxieme parametre : legende % Troisieme parametre : scaling (e.g. 2.2 1 ou 0.54) à appliquer en pdf / dvi \newcommand{\fig}[3]{% \latexhtml{% \begin{figure}[htbp]% \centering% \label{fig:#1}% \ifpdf\includegraphics[scale=#3]{#1.png}\else\includegraphics[scale=#3]{#1.eps}\fi% \caption{#2}% \end{figure}}{% \begin{center}% \htmladdimg{#1.png}% %scale factor for html is a bad idea !? \end{center} } } \newcommand{\anurl}[1]{% \latexhtml{\ifpdf\href{#1}{#1}\else{\tt #1}\fi}{% \htmladdnormallink{#1}{#1}} } \makeindex \setlength{\parindent}{0cm} \setlength{\parskip}{0.2cm} \setlength{\oddsidemargin}{10pt} \setlength{\evensidemargin}{20pt} \setlength{\marginparwidth}{20pt} \setlength{\textwidth}{480pt} \title{Zinc, an advanced scriptable Canvas.\\The 3.2.6 Reference Manual.\\\small{[CENA technical Note NT02-782]} } \author{Patrick Lecoanet} \date{4 July 2002} \begin{document} \latex{\DeclareGraphicsExtensions{.png,.ps,.eps,.pdf}} \maketitle \tableofcontents %% %% %% C h a p t e r : I n t r o d u c t i o n %% %% \chapter{Introduction} \concept{introduction} \section{What is Zinc ?} Zinc widgets are very similar to Tk Canvases in that they support structured graphics. Like the Canvas, Zinc 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 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 new rendering techniques such as transparency and gradients. If needed, it is also 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 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 succeded in using Zinc with openGL on the Exceed X11 server (running on windows and developped by Hummingbird) with the 3D extension. As an exemple 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}). This logo (see below) was designed with Adobe Illustrator and then programmed in perl. %\includefigure{tkzinclogo}{Zinc logo written as a Perl/Tk module}{fig:logozinc} \fig{tkzinclogo}{Zinc Logo written as a Perl/Tk module}{1} Like the canvas Zinc 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 clients or is short lived. It is important to grant non-specialists an access to the 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 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 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 between 3.2.6 and 3.2.4 release} \begin{itemize} \item many bug corrections, of course! \item this documentation has been improved (changelog, new figures, completions) \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 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 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. Yet to be documented! \item find and addtag commands have been modified to be ``pathtag'' compliant \item the clone command only clone one item when using a tag. \item all items have now a -composealpha option \item it is again an error to configure an unexisting option of an item \item all items can now get the keyboard focus; thus focus and 'select item' return a list of two elements. \item new tagged index (bol, eol, bow, eow, up, down) for text items and labels of track, waypoint and tabular \end{itemize} \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 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 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 ?} \ident{Zinc} is available as source in tar.gz format or as Debian or RedHat/Mandrake packages at \begin{itemize} \item \anurl{http://www.openatc.org/zinc/} or \item \anurl{http://freshmeat.net/projects/zincisnotcanvas/} \end{itemize} For people from CENA, its possible to get the Zinc 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 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 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 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. The chapter \conceptref{Groups, Display List and Transformations}{coordinates} describes the use of groups and coordinates transformations. The chapter \conceptref{Item ids, tags and indices} {tagOrId} describes the item tags along with their main purposes. Also introduced is the concept of part name used by some items (\objectref{track} and \objectref{waypoint}). Finally, this chapter provides a 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 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. The chapter \conceptref{Attributes types}{types} describes the legal form of all item attributes. The chapter \conceptref{The mapinfo commands}{mapinfocmds} introduces the mapinfo, a 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. \section{Copyright and Licence} Zinc has been developed by the CENA (Centres d'Etudes de la Navigation Aérienne) for its own needs in advanced HMI (Human Machine Interfaces or Interactions). Because we are confident in the benefit of free software, the CENA delivered this toolkit under the GNU Library General Public License. This code is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This code is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this code; if not, write to the Free Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. While this software is distributed under the GNU Library General Public License, part of it are derived from the Tk toolkit which is copyrighted under another open source license by The Regents of the University of California and Sun Microsystems, Inc. The general polygon clipper, GPC, is copyrighted by the Advanced Interfaces Group, Department of Computer Science, University of Manchester. GPC can't be used for commercial purposes without the agreement of the University of Manchester and a monetary contribution to the University of Manchester. Please contact them at gpc@cs.man.ac.uk or browse http://www.cs.man.ac.uk/aig/staff/alan/software/ It is possible to use Zinc without including GPC, it is a compile time decision. The GL font rendering is derived from Mark Kilgard code described in ``A Simple OpenGL-based API for Texture Mapped Text'' and is copyrighted by Mark Kilgard under an open source license. \section{Authors and credits} Zinc has been developed by Patrick Lecoanet. He also developed two previous version called \emph{Radar Widget} which share some caracteristics with this version. The \emph{Radar Widget} was heavily used at CENA for many projects over nearly 10 years. The release 2 is still in use. It was enhanced and then used for actual radar displays in two main French Air Traffic Control Centres 24 hours a day. Dominique Ruiz, Frederic Lepied helped a lot in the developement of these earlier versions. Zinc benefited greatly from the close interaction and the needs expressed by Jean-Luc Vinot. Jean-Luc has a background of Graphic Designer and is now an HMI developer at CENA. He envisions many, many new ideas for advanced HMI. Many of them would have been difficult to implement if at all possible with similar widgets. Zinc would have been less interesting without his ideas. Didier Pavet and his team as well as Daniel Etienne and Herve Damiano were the first users and helped a lot either by reporting bugs, problems or solutions. Thanks to all 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. \section{How can I find help with Zinc} 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 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 list, please consult the site \anurl{http://www.openatc.org/zinc/}. \section{How may I contribute to Zinc 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 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 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. \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! \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 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. \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. \end{itemize} %% %% %% C h a p t e r : W i d g e t c r e a t i o n a n d o p t i o n s %% %% \chapter{Widget creation and options} \concept{options} The Zinc command creates a new Zinc widget, the general form is \begin{quotation} {\tt\large zinc}\bigskip {\tt\large \$version = \$mainwindow->zinc();} {\tt\large \$Tk::Zinc::VERSION;} \end{quotation} These two expressions can be used to get the version of Zinc. The string returned by the second expression also details the graphic head available. For example : ``zinc-version-3205d X11 GL''. \begin{quotation} {\tt\large zinc pathname ?options?}\bigskip {\tt\large \$mainwindow->Zinc(?option=>value?, ..., ?option=>value?);} \end{quotation} {\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 the item id 1. This group will contain all other items, either directly or through groups created themselves in the top group. Together the items form a tree rooted at the root group, hence its name. The chapter \conceptref{Groups, Display List and Transformations}{coordinates} describes the use of groups. The chapter \conceptref{Item ids, tags and indices}{tagOrId} describes the item ids and item tags, used as argument in most commands. The options are used to configure how the newly created widget will behave. They can be changed later by using the \cmdref{configure} and \cmdref{itemconfigure} 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 support. They have been named differently to avoid confusion. Any number of options may be specified on the command line or in the option database to modify the global behavior of the widget. Available options are described below. \option{backcolor}{backColor}{BackColor} \begin{blockindent} This is the color that will be used to fill the Zinc 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 \verb+#c3c3c3+, a light grey. \end{blockindent} \option{borderwidth}{borderWidth}{BorderWidth} \begin{blockindent} 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 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 coordinates (See \cident{TkGet\_Pixels}). The default value is \verb+2+. \end{blockindent} \option{cursor}{cursor}{Cursor} \begin{blockindent} Specifies the cursor to use when the pointer is in the Zinc window. The default value is set to preserve the cursor inherited at widget creation. \end{blockindent} \option{font}{font}{Font} \begin{blockindent} The font specified by this option is used as a default font for item attributes of type font. Its default value is \verb+-adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*+. \end{blockindent} \option{forecolor}{foreColor}{ForeColor} %% XXX CM Foreground ?! \begin{blockindent} The color specified by this option is used as a default color for many item color attributes. See each each color attribute for the actual source of the default color. Its default value is \verb+black+. \end{blockindent} \option{fullreshape}{fullReshape}{FullReshape} \begin{blockindent} If this option is True, the shape applied to the Zinc window will propagate up the window hierarchy to the top level window. The result will be a shaped top level. See also the \optref{reshape} option, it controls whether a shape is applied to the Zinc window or not. The default is \verb+true+. \end{blockindent} \option{height}{height}{Height} \begin{blockindent} Specifies the height of the Zinc window. This value can be given in any of the forms valid for coordinates (See \cident{Tk\_GetPixels}). The default is \verb+100+ pixels. \end{blockindent} \option{highlightbackground}{highlightBackground}{HighlightBackground} \begin{blockindent} Specifies the color to display in the traversal highlight region when the widget does not have the input focus. The default value is \verb+\#c3c3c3+. \end{blockindent} \option{highlightcolor}{highlightColor}{HighlightColor} \begin{blockindent} Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. The default value is \verb+black+. \end{blockindent} \option{highlightthickness}{highlightThickness}{HighlightThickness} \begin{blockindent} Specifies a non-negative value indicating the width of the highlight rectangle drawn around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to \cident{Tk\_GetPixels}. If the value is zero, no focus highlight is drawn around the widget. The default value is \verb+2+. \end{blockindent} \option{insertbackground}{insertBackground}{InsertBackground} %% XXX CM Foreground ?! \begin{blockindent} Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). The default value is \verb+black+. \end{blockindent} \option{insertofftime}{insertOffTime}{InsertOffTime} %% XXX CM OffTime ?! \begin{blockindent} Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain off in each blink cycle. If this option is zero then the cursor is on all the time. The default value is \verb+300+. \end{blockindent} \option{insertontime}{insertOnTime}{InsertOnTime} %% XXX CM OnTime ?! \begin{blockindent} Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain on in each blink cycle. The default value is \verb+600+. \end{blockindent} \option{insertwidth}{insertWidth}{InsertWidth} \begin{blockindent} Specifies a value indicating the width of the insertion cursor. The value may have any of the forms acceptable to \cident{Tk\_GetPixels}. The default value is \verb+2+. \end{blockindent} \option{lightangle}{lightAngle}{LightAngle} \begin{blockindent} Specifies the lighting angle used when displaying relief. The default value is \verb+120+. %%% XXX CM to be completed! \end{blockindent} \option{mapdistancesymbol}{mapDistanceSymbol}{MapDistanceSymbol} \begin{blockindent} This option specifies the symbol to be used as a milestone along map lines. This option can be given any Tk bitmap which can be obtained by \cident{Tk\_GetBitmap}. The spacing between markers is 10 nautic miles. The default value is \verb+AtcSymbol19+ (see \conceptref{Other resources provided by the widget}{otherresources}). \end{blockindent} \option{maptextfont}{mapTextFont}{MapTextFont} \begin{blockindent} Specifies the font used to draw the texts contained in maps. The default is \verb+-adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*+. \end{blockindent} \option{overlapmanager}{overlapManager}{OverlapManager} \begin{blockindent} This option accepts an item id. It specifies if the label overlapping avoidance algorithm should be allowed to do its work on the track labels and which group should be considered to look for tracks. The default is to enable the avoidance algorithm in the top group (id 1). To disable the algorithm this option should be set to \verb+0+. \end{blockindent} \option{pickaperture}{pickAperture}{PickAperture} \begin{blockindent} Specifies the size of an area around the pointer that is used to tell if the pointer is inside an item. This is useful to lessen the precision required when picking graphical elements. This value must be a positive integer. It defaults to \verb+1+. \end{blockindent} \option{relief}{relief}{Relief} \begin{blockindent} Specifies the border relief. This option can be given any legal value for a relief (See \attrtyperef{relief} for a description of possible values). XXX what is the meaning of this option. The default value is \verb+flat+. \end{blockindent} \option{render}{render}{Render} \begin{blockindent} Specifies whether to use or not the openGL rendering. When True, requires the GLX extension to the X server. Must be defined at widget creation time. This option is readonly and can be used to ask if the widget is drawing with the GLX extension or in plain X (to adapt the application code for example). The default value is \verb+false+. \end{blockindent} \option{reshape}{reshape}{Reshape} \begin{blockindent} Specifies if the clipping shape that can be set in the top group item should clip the top group children or be used to reshape the Zinc window. This option can be used with the fullreshape option to reshape the toplevel window as well. The default value is \verb+true+. \end{blockindent} \option{selectbackground}{selectBackground}{SelectBackground} %% XXX CM Foreground ?! \begin{blockindent} Specifies the background color to use for displaying the selection in text items. The default value is \verb+\#a0a0a0+. \end{blockindent} \option{speedvectorlength}{speedVectorLength}{SpeedVectorLength} \begin{blockindent} Specifies the duration of track speed vectors. This option is expressed using a time unit that should be chosen by the application (usually minutes) and kept coherent with the unit of the track attribute \attributeref{track}{speedvector} (usually nautic mile / minute). The default value is \verb+3+. \end{blockindent} \option{takefocus}{takeFocus}{TakeFocus} \begin{blockindent} (Slightly adapted from the Tk options manpage). Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts consult the value of the takeFocus option. A value of 0 means that the window should be skipped entirely during keyboard traversal. 1 means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). An empty value for the option means that the traversal scripts make the decision about whether or not to focus on the window: the current algorithm is to skip the window if it is disabled, if it has no key bindings, or if it is not viewable. If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a callback. The script must return 0, 1, or an empty string: a 0 or 1 value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. \emph{Note: this interpretation of the option is defined entirely by the callbacks (part of the keyboard traversal scripts) that implement traversal; the widget implementations ignore the option entirely, so you can change its meaning if you redefine the keyboard traversal scripts.} The default value is empty. \end{blockindent} \option{tile}{tile}{Tile} \begin{blockindent} Specifies an image name to be used as a tile for painting the Zinc window background. The default value is \verb+""+ (the empty string). \end{blockindent} \option{trackmanagedhistorysize}{trackManagedHistorySize}{TrackManagedHistorySize} \begin{blockindent} This option accepts only positive integers. It specifies the size of the past position list that should be maintained by the track items. See also the \optref{trackmanagehistory} option and the \attributeref{track}{visiblehistorysize} track attribute. The default value is \verb+6+. \end{blockindent} \option{trackmanagehistory}{trackManageHistory}{TrackManageHistory} \begin{blockindent} This option accepts any form valid for a boolean. It specifies if the track items should maintain a list of their past positions to be displayed as trailing speckles. If this option is turned off and then back on, the history list is erased and the collection is resumed at the next available position. The number of position collected in the history list is specified by the option \optref{trackmanagedhistorysize}. When this many positions are collected, the oldest is dropped to make room for the new one on a first in first out basis. The number of past positions actually displayed if specified for each track by the \attributeref{track}{visiblehistorysize} attribute. The default is to enable the history collection. \end{blockindent} \option{width}{width}{Width} \begin{blockindent} Specifies the width of the Zinc window. This value can be given in any of the forms valid for coordinates (See \cident{Tk\_GetPixels}). The default is \verb+100+ pixels. \end{blockindent} %% %% %% C h a p t e r : G r o u p s , D i s p l a y l i s t s , C l i p p i n g %% %% \chapter{Groups, Display lists, Clipping and Transformations} \concept{coordinates} 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 are: \begin{itemize} \item to bundle items together so they can be cloned, destroyed, hidden, moved and more as a whole, \item to bundle several items together so that they form a new single item composed of several simpler one. This is done by modifying the way events are associated with items (see \attributeref{group}{atomic}), \item to interpose a new coordinate system in a hierarchy of items. This can be very useful to manage panning, zooming and other kind of viewing transformation. See below for an explanation of the transformation system \item to compose some specific attributes such as transparency, sensitivity, visibility, ... with those of their children items, \item to apply a clipping to their children items, \item to manage display ordering between items and to do the display lists housekeeping. \end{itemize} \section{The root group and the item tree} 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 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 any time. This is the use of the \cmdref{chggroup} command. \section{Attributes composed with children} The following attributes are composed down the item tree to form the resulting attribute value in the leaf items: \begin{itemize} \item\ident{-sensitive}: the sensitivity (to keyboards or mouse event) of an item is the result of and-ing together the \ident{-sensitive} attributes found when descending from the root group to a specific leaf item. \item\ident{-visible}: the visibility of an item is the result of and-ing together the \ident{-visible} attributes found when descending from the root group to a specific leaf item. \item\ident{-alpha}: the transparency of an item is the result of combining the \ident{-alpha} attributes of the groups found when descending from the root group to a specific item with the alpha channel found in a given color of this item. The transparency is a percentage between 0 and 100, two transparencies are combined by multiplying both and then dividing by 100. The transparency can be used only if the environment support openGL and if the widget was created with the \optref{render} option set to True. \end{itemize} \section{Atomic groups} It may seem at first that there is a contradiction in this title, but there is not. It is possible to built complex objects from simple items simply by assembling those items together in a group (using other intervening groups if the need arise). Once this is done, it would be convenient if the whole acted as a single item, the top assembling group. It is already so for many commands that act on a group, it is possible to move, resize, rotate, restack, clone, hide, change the transparency, delete the group as a whole without knowing anything of its children. But when it comes to event dispatching, the group is completly transparent so far. So the event dispatch mecanism will try to locate 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 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}. 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. A small program, \ident{Atomic groups} is available as part of \ident{zinc-demos} to demonstrate the atomic groups behaviour. \section{Display order and display lists} The items are displayed in a specific order which determines how they stack. This order is also important for associating events with items. The items are arranged in a display list for each group. The display list imposes a total ordering among its items. The group display lists are connected in a tree identical to the group tree and form a hierarchical display list. The items are drawn by traversing the display list from the least visible item to the most visible one. Each time a group is encoutered the traversal proceed with this group display list before resuming the upper display list traversal. The search to find the item that should receive an event is done in the opposite direction. In this way, items are drawn according to their relative stacking order and events are dispatched to the most visible item at a given location. It is important to note as a consequence of this structuring, that a group's items are stacked between the items that are under the group and the items that are on top of the group. Items of two groups cannot be intertwinned, they stack exactly as their groups stack, that is items of the underneath group a drawn then the items of the other group are drawn on top. The item ordering imposed by the display lists can be ajusted in three ways. The two first are local to a group's display list. The third can be used to rearrange between groups. \begin{itemize} \item The attribute \ident{-priority} can be used to give an absolute stacking position to an item amongst the items of its group. When a new item is added to a group with a priority matching the priority of existing items of the group, the new item is placed on top of the those items. Last comer is most visible. The same rule is followed when changing the priority of an item and when moving an item to a new group. \item The commands \cmdref{raise} and \cmdref{lower} adjust the relative order of an item in its group. These commands can be used to bring an item in front or to the back of its group. It is also possible to place an item before or after a given item of its group. These commands act in such a way as to preserve the absolute relationship set by the \ident{-priority} attribute. To do so they may adjust the priority of the moved item to match the priority of the item just below (raise) or just above (lower). If the priority of the moved item is not in conflict with its new neighborhood, it is not affected. \item It is also possible to move the item to another group. This has an effect on the item stacking as it will be forced to the stacking location of its new group. \end{itemize} \section{Transformations} In Zinc 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 defined by an affine transformation associated with the item. This transformation establishes the relationship between an item and its group. The items being arranged in a tree by their groups, its possible via the transformations to place 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 relation between two coordinate spaces, \emph{not} on the item geometry itself. If the goal is to change the item geometry, the command \cmdref{coords} may be more appropriate (but see below the command \cmdref{tapply}). As it should be clear, groups are like any other items, they are defined in their own coordinate space and are assembled with their parents by transformations. This is a very powerful tool to manage the geometry of clusters of items. One must not refrain from using groups only to assign them a transformation task such as panning a whole set of items or scaling a set while another is kept in place in another group. Another very interesting use of a group as a transformation tool is to manage a window coordinate space where the origin is not in the top left corner and where the Y axis goes from bottom to top. It is quite simple to write a function that is triggerred on the window resize event whose only goal is to compute a new transformation for the group. Other parts of the application and the other items are not aware of this happening. A good factorisation 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. 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 using translate, scale, rotate, treset). Once a transformation has been named it can be used to set the transformation of any item using with the command \cmdref{trestore}. And it can be disposed of with the command \cmdref{tdelete}. An item can be physically modified by applying its own transformation to itself. This is the goal of the \cmdref{tapply} command. It applies the item transformation to its own coordinates an then reset the item transformation. Visually nothing has changed but in fact the item is irrevocably modified. Be aware that if it is quite easy to undo a change in a transformation by using treset or by saving and then restoring a transformation, it is not so easy to revert a physical modification on an item. The exact order of the operations must be recorded and even then there is no shield against round off errors that will probably occur. This command may be used together with the translate, scale and rotate commands if someone really want, even after reading this paragraph, to implement the canvas move, scale and even rotate commands. When dealing with mouse events and other sources of window coordinates, it is often useful to map the window coordinates to an appropriate coordinate space. The command \cmdref{transform} is just what is needed to do so. It is powerful enough to be able to convert coordinates from any coordinate space to any other. A special provision has been made to facilitate conversion from window space to another space. The opposite is not impossible but rely on a small trick: the root group transformation must be left as identity (the default at creation time). In this way, it is possible to use the root group space, which is then the same as the window space, as the target space of the \cmdref{transform} command. If you need to manage many different transformations independently, it is a good practice to apply these transformations to different groups. For example, a group can be used for translation and an other group (father or son) for scaling. When a rotation or a scale appear in a transformation, all items do not behave exactly in the same manner. For example text items do not scale or rotate. Only their position moves according to the rotation or the scaling factor. Here is how items react to the scale and rotation factors of the transformation. \begin{itemize} \item \objectref{group} They have no graphical shape by themselves; \item \objectref{track} The position, past positions, speedvector are fully transformed. The circular marker is transformed by the X scale factor, it always remains circular. The label position is computed relative to the new position and speedvector direction but is otherwise rigid and its distance (in pixels) to the position is unchanged. \item \objectref{waypoint} The position is fully transformed. The label position is computed relative to the new position and new rotation but is otherwise rigid and its distance (in pixels) to the position is unchanged. \item \objectref{tabular}, \objectref{text} Only the position (relative to the anchor) is affected. \item \objectref{icon} With openGL, icon items can be rotated and zoomed. \item \objectref{reticle} Only the center and the spacing between circles are affected. \item \objectref{map} lines and arcs are fully transformed. For texts and symbols only the position is affected. \item \objectref{rectangle}, \objectref{arc}, \objectref{curve}, and \objectref{bezier} are fully transformed. \item \objectref{window} Only the position (relative to the anchor) is affected. \end{itemize} However, every item has a couple of attributes \ident{-composescale} and \ident{-composerotation} that can be used to control how the scale and rotation factors are inherited from the parents' transformations. These attributes default to \ident{true} (i.e. rotation and scale from parents are meaningful, except for \objectref{icon} where these attributes defaulted to \ident{false}). When one of these attributes is set to false the corresponding factor is reset from the inherited transformation. Scale factors are reset to 1.0 and rotation is reset to 0. Be careful that this applies to the inherited transformation, \emph{not} to the item transformation itself which is composed \emph{after} 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. \section{Clipping and groups} Groups can set a clip boundary before drawing their children. Thought of this feature as if a group can be made to act as a window on its children. Except that the window can have any shape you like to give it. Each group has a \attributeref{group}{clip} attribute which can be set to an item of the group. This item, known as the clipper of the group, defines the shape of the clipping. All item types except \objectref{group}, \objectref{track}, \objectref{waypoint}, \objectref{reticle} and \objectref{map} can be used as clippers but the clipper must be a direct child of the clipped group. The clipper defines the shape of the clipping but is also drawn as a regular group item. It is typical to either mask explicitly the clipper by turning off its \ident{-visible} attribute or to fill and lower it so it can act as the background. Of course, other creative uses can be found but be warned that the clipper outline will never be easthetically drawn due to round off or quantization errors, it is better to turn off borders or outlines in this case. %% %% %% C h a p t e r : I t e m I d s , t a g s a n d i n d i c e s %% %% \chapter{Item ids, tags and indices} \concept{tagOrId} \section{Item ids} 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 items cannot have the same id. This property can be quite useful when used in conjonction with tags, which are described below. \section{Tags} Apart from an id, an item can be associated with as many symbolic names as it may be needed by an application. Those names are called tags and can be any string which does not form a valid id (an integer). Tags exists, and may be used in commands, even if no item are associated with them. In contrast an item id doesn't exist if its item is no longer 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 associated with the topmost item that lies under the mouse pointer. If no such item exists, no item has this tag. In commands, tags can be used almost anywhere an item id would be legal. In the command descriptions, the expression \ident{tagOrId} means that it is legal to provide either a tag or an item id. This means that virtually all actions can be either performed on a specific item by using its id or on a whole set of items by using a tag. In order for this collective behavior to be useful, if a command or an attribute does not apply to an item named by the tag, it is simply ignored, no error will be reported (This may yet not be the case with all commands, please report infringements). Everywhere a \ident{tagOrId} can be specified as a target for some action, it is possible to give a logical expression of tags and ids. The available boolean operators include logical and \verb+&&+, logical or \verb+||+, logical xor \verb+^+, logical not \verb+!+ and subexpression grouping \verb+()+. Here is an example of a \cmdref{bbox} command called on a set of items defined by a logical expression. Note that tags and ids can be mixed. \begin{verbatim} ($xo, $yo, $xc, $yc) = $zinc->bbox("(red && black)||(pink && !$thisitem)"); \end{verbatim} Many methods only operate on a single item at a time; if \ident{tagOrId} is specified in a way that names multiple items, then the normal behavior for these methods is to use the first of these items in the display list (most visible) that is suitable for the method. Exceptions are noted in the method descriptions below. Tags can be associated with items by giving a tag list to the \ident{-tags} attribute or by using the more powerful \cmdref{addtag} command. A tag can be removed by the \cmdref{dtag} command, by setting the \ident{-tags} attribute to the empty list, all tags are remove from an item at once (except the implicit ones). Tags can be read with the \cmdref{gettags} or by querying the \ident{-tags} attribute. The items named by a tag are returned in a list by the \cmdref{find} command which as exactly the same capabilities as \cmdref{addtag}. \section{Tags and bindings} 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 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 pointer, if any; keyboard events are dispatched to the focus item, if any; leave events are dispatched to the item previously under the pointer, enter events to the item newly under the pointer. Tags are collected from the item found. Special tags are managed for items with fields or parts (e.g. a \objectref{track} has both, a \objectref{tabular} has only \ident{fields} and a \objectref{rectangle} has none). They are built from a tag or an id followed by a \verb+:+ followed by a (zero based) field index or by the name of a part. Those tags can only be used in event bindings. Here is the complete list of tags, either real or implicit, that are tried to find bindings. They are listed in the order they are processed. \begin{enumerate} \item the implicit tag \verb+all+ (associated with all items), \item the other tags (in some not reliable order), \item the item id, \item the implicit tags build from the tags and the current part name or field index, if any,, \item the implicit tag build from the item id and the current part name or field index, if any. \end{enumerate} An exception is made for the \ident{Leave} event when dispatched to an item with parts or fields. This is needed to process the exit of a field/part before the exit of the corresponding item. In this case the order is shown by the following list. \begin{enumerate} \item the implicit tags build from the tags and the current part name or field index, \item the implicit tag build from the item id and the current part name or field index, \item the implicit tag \verb+all+, \item the other tags, \item the item id. \end{enumerate} Here are examples of possible bindings. \begin{enumerate} \item \verb+$zinc->bind($id, '<1>', \&acallback);+\\ will call \verb+acallback+ if mouse button 1 is clicked anywhere over item \verb+$id+; \item \verb+$zinc->bind('selected', '<1>', \&acallback);+\\ the click must be anywhere over any item associated with the \verb+selected+ tag; \item \verb+$zinc->bind('foo:0', '<1>', \&acallback);+\\ the click must occurs over field 0 of an item with tag \verb+foo+; \item \verb+$zinc->bind("$id:3", '<1>', \&acallback);+\\ the click must be over field 3 of item \verb+$id+, and the field must exists in the item; \item \verb+$zinc->bind("$id:speedvector", '<1>', \&acallback);+\\ the click must be over a part named \verb+speedvector+ (item track) in item \verb+$id+, the part must exists in the item.%$ \end{enumerate} \section{Text indices} \concept{indices} Indices are used to specify a character position in textual items such as the \objectref{text} item. Indices are accepted as parameters by commands managing text: \cmdref{cursor}, \cmdref{index}, \cmdref{insert}, \cmdref{dchars} and \cmdref{select}. \begin{description} \item{\ident{number}} This should be an integer giving the character position within the text of the item. The indices are zero based. A number less than zero is treated as zero and a number greater than the text length is rounded to the text length. A number equal to the text length refers to the position past the last character in the text. \item{\ident{end}} Refers to the position past the last character in the text. This is the same as specifying a number equal to the text length. \item{\ident{insert}} Refers to the character just before the insertion cursor in the item. \item{\ident{sel.first}} Refers to the first character of the selection in the item. If the selection is not in the item, this form returns an error. \item{\ident{sel.last}} Refers to the last character of the selection in the item. If the selection is not in the item, this form returns an error. \item{\ident{@x,y}} Refers to the character at the point given by \ident{x} and \ident{y}, \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}} \end{description} %% %% %% C h a p t e r : W i d g e t c o m m a n d s %% %% \chapter{Widget commands} \concept{commands} In this chapter, we first list all commands by categories, then we details each command, by alphabetical order. \section{Categories of commands} \concept{commandsCategories} \begin{itemize} \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 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{Groups, Display list and Priorities} : \cmdref{chggroup} \cmdref{find}('ancestors') \cmdref{group} \cmdref{lower} \cmdref{raise} \item{Tag management} : \cmdref{addtag} \cmdref{dtag} \cmdref{find} \cmdref{gettags} \cmdref{hastag} \item{Text management (text item and text fields} : \cmdref{cursor} \cmdref{dchars} \cmdref{focus} \cmdref{index} \cmdref{insert} \cmdref{select} \item{Bindings} : \cmdref{bind} \cmdref{focus} \item{Coordinates} : \cmdref{anchorxy} \cmdref{bbox} \cmdref{coords} \cmdref{contour} \cmdref{fit} \cmdref{smooth} \cmdref{vertexat} \item{Named resources} : \cmdref{gname} \cmdref{gdelete} \cmdref{tsave} \item{Micellanous} : \cmdref{monitor} \cmdref{postscript} \cmdref{type} \end{itemize} \section{Commands by alphabetical order} \concept{commandsAlphabetically} 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. 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 way at all; \cmdref{find} and \cmdref{addtag} have been extended to support groups, etc. So use the available knowledge with some care. In the Perl/Tk version, the commands returning a list, return a Perl array (not a reference) and all list parameters are given as array references. \vspace{.5cm} \zinccmd{add}{?type group? ?initargs? ?option value? ... ?option value?} {\tt\large @types = \$zinc->{\bf add}();}\\ {\tt\large \$id = \$zinc->{\bf add}(type, group);}\\ {\tt\large \$id = \$zinc->{\bf add}(type, group, initargs);}\\ {\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 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. After these first two parameters come some item type specific arguments. Here is detailed description of these arguments by type: \begin{description} \item{\bf arc} \\ The arc type expects a list of four floating point numbers \verb+xo yo xc yc+, giving the coordinates of the origin and the corner of the enclosing rectangle. The origin should be the top left vertex of the enclosing rectangle and the corner the bottom right vertex of the rectangle. \item{\bf bezier} \\ The bezier type expects a list of floating point numbers \verb+x0 y0 x1 y1 ... xn yn+, giving the coordinates of the bezier segment controls. The number of values should be pair (or the last value will be discarded), and there should be at least two control points. The segments are built as follow: if there is at least four points, they are used as the four controls of a cubic Bezier. Then, if more than four points are provided , the first three are discarded and the process is restarted using as first control the last control of the previous segment. The process is repeated until there is less than four points left. If three points are left, a segment is drawn using the second point for the two off-curve controls. If two points are left, a line segment is drawn between the two. \item{\bf curve} \\ The curve type expects 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} 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} \\ The rectangle type expects a list of four floating point numbers \verb+xo yo xc yc+, giving the coordinates of the origin and the corner of the rectangle. \item{\bf triangles} \\ The triangles type expects a list of at least 6 floating point numbers \verb+x0 y0 x1 y1+ \verb+... xn yn+, giving the coordinates of the vertices of the triangles composing this item. The triangles layout is defined by the attribute \attributeref{triangles}{fan}. If \attributeref{triangles}{fan} is true, the triangles are arranged in a fan with the first point being the center and the other points defining the perimeter. If \attributeref{triangles}{fan} is false, the triangles are arranged in a strip. (XXX Afficher un diagramme avec l'ordre des sommets). \item{\bf tabular, track, waypoint} \\ These types expects the number of fields they will manage in the label or tabular form. This number must be greater or equal to zero. \item{\bf group, icon, map, reticle, text, window} \\ These types doesn't expect type specific arguments. \end{description} Following the creation args the command accept any number of attributes\ -\ values pairs to configure the newly created item. All the configurable item type attributes are valid in this context. The command returns the item id. \end{blockindent} \zinccmd{addtag}{tag searchSpec ?arg arg ...?} {\tt\large \$zinc->{\bf addtag}(tag, searchSpec);} \begin{blockindent} This command add the given tag to all items matching the search specification. If the tag is already present on some item, nothing is done for that item. The command has no effect if no item satisfy the given criteria. The command returns an empty string. Many commands take a group as a starting point for the search. If no group is given, the top group is assumed. In any cases, the starting group will not be reported in the search result. This means that the top group will never be reported in a search and that tags cannot be attached to it except in specifying its id. The search specification and the associated arguments can take the following forms: \begin{itemize} \item{\tt\large pathname {\bf addtag} tag above tagOrId \\ \$zinc->{\bf addtag}(tag, 'above', tagOrId);} Selects the item just above the one given by {\tt tagOrId}. If {\tt tagOrId} names more than one item, the topmost of these items in the display list will be used. If {\tt tagOrId} does not refer to any item then nothing happen. \item{\tt\large 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. Please use a form ``'withtag', 'all''' as documented below. \item{\tt\large pathname {\bf addtag} tag atpriority priority ?tagOrId?\\ \$zinc->{\bf addtag}(tag, 'atpriority', priority, ?tagOrId?);} Selects all the items at the given priority. The tagOrId optional parameter can be specified to restrict the search. It specifies a group to start with instead of the top group and it can be used to control if the search should be recursive or not (see path tags for more on this subject). \item{\tt\large pathname {\bf addtag} tag ancestors tagOrId ?tagOrId2?\\ \$zinc->{\bf addtag}(tag, 'ancestors', tagOrId, ?tagOrId2?);} Selects all ancestors (i.e. parent groups) of tagOrId. If {\tt tagOrId} names more than one item, the first, (or the topmost) of these items in the display list will be used. If ?tagOrId2? is specified, only parent groups with this tag are selected. \item{\tt\large pathname {\bf addtag} tag below tagOrId\\ \$zinc->{\bf addtag}(tag, 'below', tagOrId);} Selects the item just below the one given by {\tt tagOrId}. If {\tt tagOrId} names more than one item, the lowest of these items in the display list will be used. If {\tt tagOrId} does not refer to any item then nothing happen. \item{\tt\large pathname {\bf addtag} tag closest x y ?halo? ?startItem?, ?recursive?\\ \$zinc->{\bf addtag}(tag, 'closest', x, y, ?halo?, ?startItem?, ?recursive?);} Selects the item closest to the point {\tt x - y}. Any item overlapping the point is considered as closest and the topmost is selected. If {\tt halo} is given, it defines the size of the point {\tt x - y}. {\tt halo} must be a non negative integer. If {\tt start} is specified, it must be an item tag or id. If it names a group and this group is not atomic, the search starts with the first item of this group. If it names a non group item or an atomic group (for a tag, the lowest item with the tag is considered), the search starts with the item below {\tt start} instead of the first item in the display order. If {\tt startItem} does not name a valid item, it is ignored. If {\tt recursive} is specified it controls if the search should proceed down the item hierarchy or not. \item{\tt\large pathname {\bf addtag} tag enclosed xo yo xc yc ?inGroup? ?recursive?\\ \$zinc->{\bf addtag}(tag, 'enclosed', xo, yo, xc, yc, ?inGroup?, ?recursive?);} Selects all the items completely enclosed in the rectangle whose origin is at {\tt xo - yo} and corner at {\tt xc - yc}. {\tt xc} must be no greater than {\tt xo} and {\tt yo} must be no greater than {\tt yc}. All coordinates must be integers. inGroup specifies a group to start with instead of the top group and recursive tells 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 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). \item{\tt\large pathname {\bf addtag} tag overlapping xo yo xc yc ?inGroup? ?recursive?\\ \$zinc->{\bf addtag}(tag, 'overlapping', xo, yo, xc, yc, ?inGroup?, ?recursive?);} Selects all the items that overlaps or are enclosed in the rectangle whose origin is at {\tt xo - yo} and corner at {\tt xc - yc}. {\tt xc} must be no greater than {\tt xo} and {\tt yo} must be no greater than {\tt yc}. All coordinates must be integers. inGroup specifies a group to start with instead of the top group and recursive tells if the search should descend in the item tree or not. recursive is true by default. See also the {\tt enclosed} variant above for a discussion on updating the geometry. \item{\tt\large pathname {\bf addtag} tag withtag tagOrId\\ \$zinc->{\bf addtag}(tag, 'withtag', tagOrId);} Selects all the items given by {\tt tagOrId}. \item{\tt\large pathname {\bf addtag} tag withtype type ?tagOrId?\\ \$zinc->{\bf addtag}(tag, 'withtype', type, ?tagOrId?);} Selects all the items of type {\tt type}. The tagOrId optional parameter can be specified to restrict the search. It specifies a group to start with instead of the top group and it can be used to control if the search should be recursive or not (see path tags for more on this subject). \end{itemize} \end{blockindent} \zinccmd{anchorxy}{tagOrId anchor} {\tt\large (\$x, \$y) = \$zinc->{\bf anchorxy}(tagOrId, anchor);} \begin{blockindent} Returns the \emph{window coordinates} of an item anchor. If no item is named by {\tt tagOrId} or if the item doesn't support anchors, an error is raised. If more than one item match {\tt tagOrId}, the topmost in display list order is used. \end{blockindent} \zinccmd{bbox}{tagOrId ?tagOrId ...?} {\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} arguments. If no items are named by the {\tt tagOrId} or if the matching items have an empty bounding box, an empty string is returned. \end{blockindent} \zinccmd{becomes}{} {\tt\large \$zinc->{\bf becomes}();} \begin{blockindent} Not yet implemented. \end{blockindent} \zinccmd{bind}{tagOrId ?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);} \begin{blockindent} This command associates {\tt command} with the item tag, item id, part tag {\tt tagOrId}. If an event sequence matching {\tt sequence} occurs for an item, or an item part, the command will be invoked. If all parameters are specified a new binding between {\tt sequence} and {\tt command} is established, overriding any existing binding for the sequence. If the first character of {\tt command} is ``+'', then {\tt command} augments the existing binding instead of replacing it. In this case the command returns an empty string. If the {\tt command} parameter is omitted, the command return the {\tt command} associated with {\tt tagOrId} and {\tt sequence} or an error is raised if there is no such binding. If only {\tt tagOrId} is specified the command returns a list of all 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 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 accurate place to look for a definition of {\tt sequence} and {\tt command} and for a general understanding of how the binding mecanism works. The handling of events in the widget is done with respect to the current item and when applicable the current item part (see \conceptref{Item ids, tags and indices}{tagOrId} for a discussion of the \ident{current} tag and the special tags used in bindings). \ident{Enter} and \ident{Leave} events are trigerred for an item when it becomes or cease to be the current item. Mouse related events are reported with respect to the current item. Keyboard related events are reported with respect to the focus item if it exists (See the \cmdref{focus} command for more on this). It is possible that several bindings match a particular event sequence. When this occurs, all matching bindings are triggered. The order of invocation is as follow: the binding associated with the tag \ident{all} is invoked first, followed by the bindings associated with the item tags in order, followed by the binding associated with the item id, followed by bindings associated with the item part tags if relevant, followed by 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. 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. \end{blockindent} \zinccmd{cget}{option} {\tt\large \$val = \$zinc->{\bf cget}(option);} \begin{blockindent} Returns the current value of the widget option given by {\tt option}. {\tt option} may be any of the options described in the chapter \conceptref{Widget options}{options}. \end{blockindent} \zinccmd{chggroup}{tagOrId group ?adjustTransform?} {\tt\large \$zinc->{\bf chggroup}(tagOrId, group, ?adjustTransform.?);} \begin{blockindent} Move the item described by {\tt tagOrId} in the group described by {\tt group}. If {\tt tagOrId} or {\tt group} describes more than one item, the first in display list order will be used. If {\tt adjustTransform} is specified, it will be interpreted as a boolean. A true value will lead to an adjustment of the item transform in order to maintain an identical display rendering of the item regardless of its new position in the display hierarchy. If {\tt adjustTransform} is omitted, it defaults to false. \end{blockindent} \zinccmd{clone}{tagOrId ?attr value ...?} {\tt\large \$id = \$zinc->{\bf clone}(tagOrId, ?attr=>value, ...?);} \begin{blockindent} Create an exact copy of all the items described by {\tt tagOrId}. The copy goes recursively for group items (deep copy). After copying the pairs {\tt attr value} are used, if any, to reconfigure the items. Any attribute that as no meaning in the context of some item is ignored. The items down the hierarchy of group items are not concerned by the configuration phase. The command returns the list of cloned items id in creation order (display list order of the models). No item id will be returned for items cloned in the hierarchy of cloned groups. \end{blockindent} \zinccmd{configure}{?option? ?value? ?option value ...?} {\tt\large @options = \$zinc->{\bf configure}();}\\ {\tt\large @option = \$zinc->{\bf configure}(option);}\\ {\tt\large \$zinc->{\bf configure}(option=>value, ?option=>value,...?);} \begin{blockindent} Query or modify the options of the widget. If no {\tt option} is given, returns a list describing all the supported options in the standard format for Tk options (see the chapter \conceptref{Widget options}{options} for a list of available options). If an {\tt option} is specified without a {\tt value}, the command returns a list describing the named option in the standard Tk format. If some {\tt option - value} pairs are given, then the corresponding options are changed and the command return an empty string. \end{blockindent} \zinccmd{contour}{tagOrId ?operatorSpec coordListOrTagOrId?} {\tt\large \$zinc->{\bf contour}(tagOrId);} {\tt\large \$zinc->{\bf contour}(tagOrId, operatorSpec, coordListOrTagOrId);} \begin{blockindent} Manipulate contours on items that can handle multiples geometric contours. Currently only curve items can do this. {\tt tagOrId} specifies the item whose contours will be modified. If {\tt tagOrId} describes more than one item, the first in display list order will be used. If the command is invoked with only the tagOrId parameter, it returns the number of contours composing the item. In fact it always returns the number of contours after a command has been conducted, it happens that with this reduced form nothing is done except returning the number of contours.. On items that do not support the contour command, the returned value is 0 or 1 depending 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 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, bezier curve, icon, rectangle, tabular, text, window. The external shape of the item will be used as the contour. If {\tt 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: \begin{description} \item{\ident{diff}} Substract the given contour from the item contours \item{\ident{inter}} Intersect the given contour and the item contours, replacing the original contours by the intersection. \item{\ident{union}} Compute the union of the given contour and the item's contours, replacing the original contours by the union. \item{\ident{xor}} Compute the exclusive or of the given contour and the item's contours, replacing the original contours by the result. \end{description} 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. \emph{NB: This command is available only when GPC support has been built in Zinc.} \end{blockindent} \zinccmd{coords}{tagOrId ?add/remove? ?contour? ?index? ?coordList?} {\tt\large \$zinc->{\bf coords}(tagOrId, ?add/remove?, ?contour?, ?index?, ?coordList?);} \begin{blockindent} Query or changes the coordinates of the item described by {\tt tagOrId}. If {\tt 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. 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 icons, texts, windows, tabulars, the coordinates of the anchor can be modified or read. For groups, the coordinates of the origin of the transformation can be set or read. For tracks and waypoints, the coordinates of the current position can be set or 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 beziers, the coordinates of the vertices can be set or read and it is possible to remove or add vertices to an existing item. For curves, the capabilities of bezier are extended to support multiple contours. For all items that do not support multiple contours (currently all except curves) the {\tt contour} parameter should be omitted or specified as zero. The optional parameters must be combined to produce a given behavior. Here are the various form recognized by the command: \begin{itemize} \item{\tt\large pathname {\bf coords} tagOrId contourIndex\\ @coords = \$zinc->{\bf coords}(tagOrId, contourIndex);} Get all coordinates of contour at contourIndex. All items can answer if contourIndex is zero. Curves can handle other contours. \item{\tt\large pathname {\bf coords} tagOrId contourIndex coordList\\ \$zinc->{\bf coords}(tagOrId, contourIndex, coordList);} Set all coordinates of 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, only the first vertex will be used. For rectangles and arcs, only the first two vertices will be used. Beziers and curves can handle any number of vertices. \item{\tt\large pathname {\bf coords} tagOrId contourIndex coordIndex\\ (\$x, \$y) = \$zinc->{\bf coords}(tagOrId, contourIndex, coordIndex);} 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. \item{\tt\large pathname {\bf coords} tagOrId contourIndex coordIndex coordList\\ \$zinc->{\bf coords}(tagOrId, contourIndex, coordIndex, coordList);} 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. \item{\tt\large pathname {\bf coords} tagOrId remove contourIndex coordIndex\\ \$zinc->{\bf coords}(tagOrId, 'remove', contourIndex, coordIndex);} Remove coordinate at coordIndex in contour at contourIndex. Can only be handled by beziers and curves. Only curves can handle contourIndex other than zero. \item{\tt\large pathname {\bf coords} tagOrId add contourIndex coordList\\ \$zinc->{\bf coords}(tagOrId, 'add', contourIndex, coordList);} Add coordinates at the end of contour at contourIndex. Can only be handled by beziers and curves. Only curves can handle contourIndex other than zero. \item{\tt\large pathname {\bf coords} tagOrId add contourIndex coordIndex coordList\\ \$zinc->{\bf coords}(tagOrId, 'add', contourIndex, coordIndex, coordList);} Add coordinates at coordIndex in contour at contourIndex. Can only be handled by beziers and curves. Only curves can handle contourIndex other than zero. \end{itemize} And the slightly abbreviated forms: \begin{itemize} \item{\tt\large pathname {\bf coords} tagOrId\\ @coords = \$zinc->{\bf coords}(tagOrId);} Get all coordinates of contour 0. See first form. \item{\tt\large pathname {\bf coords} tagOrId coordList\\ \$zinc->{\bf coords}(tagOrId, coordList);} Set all coordinates of contour 0. See second form. \item{\tt\large pathname {\bf coords} tagOrId remove coordIndex\\ \$zinc->{\bf coords}(tagOrId, 'remove', coordIndex);} Remove coordinate at coordIndex in contour 0. See fifth form. \item{\tt\large pathname {\bf coords} tagOrId add coordList\\ \$zinc->{\bf coords}(tagOrId, 'add', coordList);} Add coordinates at the end of contour 0. See sixth form. \end{itemize} \end{blockindent} \zinccmd{currentpart}{} {\tt\large \$num = \$zinc->{\bf currentpart}();} \begin{blockindent} Returns a string specifying the item part that has the pointer. If the current item doesn't have parts or if the pointer is not over an item (no item has the \ident{current} tag) the command return {\tt ""}. The string can be either an integer describing a field index or the name of a special part of the item. Consult each item description to find out which part names can be reported. \end{blockindent} \zinccmd{cursor}{tagOrId index} {\tt\large \$zinc->{\bf cursor}(tagOrId, index);} \begin{blockindent} Set the position of the insertion cursor for the items described by {\tt tagOrId} to be just before the character at {\tt index}. If some of the items described by {\tt tagOrId} don't support an insertion cursor, the command doesn't change them. The possible values for {\tt index} are described in the section \conceptref{Text indices} {indices}. The command returns an empty string. \end{blockindent} \zinccmd{dchars}{tagOrId first ?last?} {\tt\large \$zinc->{\bf dchars}(tagOrId, first);}\\ {\tt\large \$zinc->{\bf dchars}(tagOrId, first, last);} \begin{blockindent} Delete the character range defined by the parameters {\tt first} and {\tt last} inclusive in all the items described by {\tt tagOrId}. Items that doesn't support text indexing are skipped by the command. If {\tt last} is not specified, the command deletes the character located at {\tt first}. The command returns an empty string. {\tt first} and {\tt last} are indices as described in \conceptref{Text indices}{indices}. \end{blockindent} \zinccmd{dtag}{tagOrId ?tagToDelete?} {\tt\large \$zinc->{\bf dtag}(tagOrId);}\\ {\tt\large \$zinc->{\bf dtag}(tagOrId, tagToDelete);} \begin{blockindent} Delete the tag {\tt tagToDelete} from the list of tags associated with each item named by {\tt tagOrId}. If an item doesn't have the tag then it is leaved unaffected. If {\tt tagToDelete} is omitted, {\tt tagOrId} is used instead. The command returns an empty string as result. \end{blockindent} \zinccmd{find}{searchCommand ?arg arg ...?} {\tt\large @items = \$zinc->{\bf find}(searchCommand, ?arg?, ...);} \begin{blockindent} This command returns the list of all items selected by {\tt searchCommand} and the {\tt args}. See the \cmdref{addtag} command for an explanation of {\tt searchCommand} and the various {\tt args}. The items are sorted in drawing order, topmost first. \\ For example:\\ \code{ \# to get the item under the mouse cursor:\\ \$item = \$zinc->find('withtag', 'current');\\ \# to get the closest item of a point:\\ \$closest = \$zinc->find ('closest', \$x, \$y);\\ \# to get direct children of an atomic group with a pathtag:\\ @children = \$zinc->find('withtag', ''.\$atomicGroup''); } As detailled in \cmdref{addtag} command the following searchCommands are possible: \begin{itemize} \item{\tt\large pathname {\bf find} above tagOrId \\ \$zinc->{\bf find}('above', tagOrId);} \item{\tt\large pathname {\bf find} all ?inGroup? ?recursive?\\ \$zinc->{\bf find}('all', ?inGroup?, ?recursive?);} \item{\tt\large pathname {\bf find} atpriority priority ?tagOrId?\\ \$zinc->{\bf find}('atpriority', priority, ?tagOrId?);} \item{\tt\large pathname {\bf find} ancestors tagOrId ?tagOrId2?\\ \$zinc->{\bf find}('ancestors', tagOrId, ?tagOrId2?);} \item{\tt\large pathname {\bf find} below tagOrId\\ \$zinc->{\bf find}('below', tagOrId);} \item{\tt\large pathname {\bf find} closest x y ?halo? ?startItem?, ?recursive?\\ \$zinc->{\bf find}('closest', x, y, ?halo?, ?startItem?, ?recursive?);} \item{\tt\large pathname {\bf find} enclosed xo yo xc yc ?inGroup? ?recursive?\\ \$zinc->{\bf find}('enclosed', xo, yo, xc, yc, ?inGroup?, ?recursive?);} \item{\tt\large pathname {\bf find} overlapping xo yo xc yc ?inGroup? ?recursive?\\ \$zinc->{\bf find}('overlapping', xo, yo, xc, yc, ?inGroup?, ?recursive?);} \item{\tt\large pathname {\bf find} withtag tagOrId\\ \$zinc->{\bf find}('withtag', tagOrId);} \item{\tt\large pathname {\bf find} withtype type ?tagOrId?\\ \$zinc->{\bf find}('withtype', type, ?tagOrId?);} \end{itemize} \end{blockindent} \zinccmd{fit}{coordList error} {\tt\large @controls = \$zinc->{\bf fit}(coordList, error);} \begin{blockindent} 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. \end{blockindent} \zinccmd{focus}{?tagOrId?} {\tt\large (\$item, \$part) = \$zinc->{\bf focus}();}\\ {\tt\large \$zinc->{\bf focus}(tagOrId);} \begin{blockindent} Set the keyboard focus to the item described by {\tt tagOrId}. If {\tt tagOrId} describes more than one item, the first item in display list order that accept the focus is used. If no such item exists, the command has no effect. If {\tt tagOrId} is an empty string the focus is reset and no item has the focus. If {\tt tagOrId} is not specified, the command returns a list of two elements. The first is the id of the item with the focus or an empty string if no item has the focus. The second is the item part or an empty string if not appliable. When the focus has been set to an item that support an insertion cursor, the item will display its cursor and the keyboard events will be directed to that item. The widget receive keyboard events only if it has the window focus. It may be necessary to use the Tk \ident{focus} command to force the focus to the widget window. \end{blockindent} \zinccmd{gdelete}{gradientName} {\tt\large \$zinc->{\bf gdelete}('fading');} \begin{blockindent} This command breaks the binding between the given gradient name and the named gradient. When the gradient will be no longer used it will be deallocated. \end{blockindent} \zinccmd{gettags}{tagOrId} {\tt\large @tags = \$zinc->{\bf gettags}(tagOrId);} \begin{blockindent} This command returns the list of all the tags associated with the item specified by {\tt tagOrId}. If more than one item is named by {\tt tagOrId}, then the topmost in display list order is used to return the result. If no item is named by {\tt tagOrId}, then the empty list is returned. \end{blockindent} \zinccmd{gname}{?gradientDesc? gradientName} {\tt\large \$zinc->{\bf gname}('black:100|white:0/0', 'fading');} {\tt\large \$exist = \$zinc->{\bf gname}('nameOrGradient');} \begin{blockindent} This command sets a name binding between the given gradient description and the given name. The name can be used in the same way the gradient description would be. The gradient will not be deallocated until the \cmdref{gdelete} command is invoqued on the name (and no item use the gradient). This feature can be a big performance gain when using many gradients in an animation, the name acts here as a caching mecanism. When gname is called with only one argument, it returns iehter false or the name of a named gradient if the argument is either a named gradient or the name of a named gradient. \end{blockindent} \zinccmd{group}{tagOrId} {\tt\large \$group = \$zinc->{\bf group}(tagOrId);} \begin{blockindent} Returns the group containing the item described by {\tt tagOrId}. If more than one item is named by {\tt tagOrId}, then the topmost in display list order is used to return the result. \end{blockindent} \zinccmd{hasanchors}{tagOrId} {\tt\large \$bool = \$zinc->{\bf hasanchor}(tagOrId);} \begin{blockindent} This command returns a boolean telling if the item specified by {\tt tagOrId} supports anchors. If more than one item is named by {\tt tagOrId}, then the topmost in display list order is used to return the result. If no items are named by {\tt tagOrId}, an error is raised. \end{blockindent} \zinccmd{hasfields}{tagOrId} {\tt\large \$bool = \$zinc->{\bf hasfields}(tagOrId);} \begin{blockindent} This command returns a boolean telling if the item specified by {\tt tagOrId} supports fields. If more than one item is named by {\tt tagOrId}, then the topmost in display list order is used to return the result. If no items are named by {\tt tagOrId}, an error is raised. \end{blockindent} \zinccmd{hastag}{tagOrId tag} {\tt\large \$bool = \$zinc->{\bf hastag}(tagOrId, tag);} \begin{blockindent} This command returns a boolean telling if the item specified by {\tt tagOrId} has the specified tag. If more than one item is named by {\tt tagOrId}, then the topmost in display list order is used to return the result. If no items are named by {\tt tagOrId}, an error is raised. \end{blockindent} \zinccmd{index}{tagOrId index} {\tt\large \$num = \$zinc->{\bf index}(tagOrId, index);} \begin{blockindent} This command returns a number which is the numerical index in the item described by {\tt tagOrId} corresponding to {\tt index}. The possible forms for {\tt index} are described in \conceptref{Text indices}{indices}. The command return a value between 0 and the number of character in the item. If {\tt tagOrId} describes more than one item, the index is processed in the first item supporting text indexing in display list order. \end{blockindent} \zinccmd{insert}{tagOrId before string} {\tt\large \$zinc->{\bf insert}(tagOrId, before, string);} \begin{blockindent} This command inserts {\tt string} in each item described by {\tt tagOrId} just before the text position described by {\tt before}. The possible values for {\tt before} are described in \conceptref{Text indices}{indices}. Items that doesn't support text indexing are skipped by the command. The command returns an empty string. \end{blockindent} \zinccmd{itemcget}{tagOrId ?fieldId? attr} {\tt\large \$val = \$zinc->{\bf itemcget}(tagOrId, attr);}\\ {\tt\large \$val = \$zinc->{\bf itemcget}(tagOrId, field, attr);} \begin{blockindent} Returns the current value of the attribute given by {\tt attr} for the item named by {\tt tagOrId}. If {\tt tagOrId} name more than one item, the topmost in display list order is used. If {\tt field} is given, it must be a valid field index for the item or an error will be reported. If a field index is given, the command will interpret {\tt attr} as a field attribute (see \objectref{field}), otherwise it will be interpreted as an item attribute (see the chapter \conceptref{Item types}{items}). If the attribute is not available for the field or item type, an error is reported. \end{blockindent} \zinccmd{itemconfigure}{tagOrId ?fieldId? ?attr? ?value? ?attr value ...?} {\tt\large @attribs = \$zinc->{\bf itemconfigure}(tagOrId);}\\ {\tt\large @attrib = \$zinc->{\bf itemconfigure}(tagOrId, attrib);}\\ {\tt\large \$zinc->{\bf itemconfigure}(tagOrId, attrib=>value, ?attrib=>value?, ...);}\\ {\tt\large @attrib = \$zinc->{\bf itemconfigure}(tagOrId, fieldId, attrib);}\\ {\tt\large \$zinc->{\bf itemconfigure}(tagOrId, fieldId, attrib=>value, ?attrib=>value?, ...);} \begin{blockindent} Query or modify the attributes of an item or field. If no attribute is given, returns a list of lists describing all the supported attributes in the same format as for a single attribute, as described next. If a single attribute is specified without a value, the command returns a list describing the named attribute. Each attribute is described by a list with the following content: the attribute name, the attribute type, a boolean telling if the attribute is read-only, an empty string, and the current value of the attribute. In the two querying forms of the command the topmost item described by {\tt tagOrId} is used. If at least one attribute - value pair is given, then the corresponding attributes are changed for all the items described by {\tt tagOrId} and the command return an empty string. If {\tt field} is given, it must be a valid field index for the item or an error will be reported. If a field index is given, the command will interpret the given attributes as field attributes, otherwise they will be interpreted as item attributes. If an attribute does not belong to the item or field, it will be silently ignored. This is done to preserve the usefulness of \cmdref{itemconfigure} on tags. \end{blockindent} \zinccmd{lower}{tagOrId ?belowThis?} {\tt\large \$zinc->{\bf lower}(tagOrId);}\\ {\tt\large \$zinc->{\bf lower}(tagOrId, belowThis);} \begin{blockindent} Reorder all the items given by {\tt tagOrId} so that they will be under the item given by {\tt belowThis}. If {\tt tagOrId} name more than one item, their relative order will be preserved. If {\tt tagOrId} doesn't name an item, an error is raised. If {\tt belowThis} name more than one item, the bottom most them is used. If {\tt belowThis} doesn't name an item, an error is raised. If {\tt belowThis} is omitted the items are put at the bottom most position of their respective groups. The command ignore all items named by {\tt tagOrId} that are not in the same group than {\tt belowThis} or, if not specified, in the same group than the first item named by {\tt tagOrId}. The command returns an empty string. As a side affect of this command, the \ident{-priority} attribute of all the reordered items is ajusted to match the priority of the {\tt belowThis} item (or the priority of the bottom most item). \end{blockindent} \zinccmd{monitor}{?onOff?} {\tt\large \$bool = \$zinc->{\bf monitor}();}\\ {\tt\large \$zinc->{\bf monitor}(onOff);} \begin{blockindent} This command controls the gathering of performance data. The data gathering is inited and turned on when the command is called with a boolean true parameter. The gathering is stopped if the command is called with a boolean false parameter. If the command is called with no parameters or with a boolean false parameter, it returns a string describing the currently collected data. The other form of the command returns the empty string. \end{blockindent} \zinccmd{numparts}{tagOrId} {\tt\large \$num = \$zinc->{\bf numparts}(tagOrId);} \begin{blockindent} This command tells how many fieldId are available for event bindings or for field configuration commands in the item specified by {\tt tagOrId}. If more than one item is named by {\tt tagOrId}, the topmost in display list order is used to return the result. If no items are named by {\tt tagOrId}, an error is raised. This command returns always 0 for items which do not support fields. The command \cmdref{hasfields} may be used to decide whether an item has fields. \end{blockindent} \zinccmd{postscript}{} {\tt\large \$zinc->{\bf postscript}();} \begin{blockindent} Not yet implemented. \end{blockindent} \zinccmd{raise}{tagOrId ?aboveThis?} {\tt\large \$zinc->{\bf raise}(tagOrId);}\\ {\tt\large \$zinc->{\bf raise}(tagOrId, aboveThis);} \begin{blockindent} Reorder all the items given by {\tt tagOrId} so that they will be above the item given by {\tt aboveThis}. If {\tt tagOrId} name more than one item, their relative order will be preserved. If {\tt tagOrId} doesn't name an item, an error is raised. If {\tt aboveThis} name more than one item, the topmost in display list order is used. If {\tt aboveThis} doesn't name an item, an error is raised. If {\tt aboveThis} is omitted the items are put at the top most position of their respective groups. The command ignore all items named by {\tt tagOrId} that are not in the same group than {\tt aboveThis} or, if not specified, in the same group than the first item named by {\tt tagOrId}. The command returns an empty string. As a side affect of this command, the \ident{-priority} attribute of all the reordered items is ajusted to match the priority of the {\tt aboveThis} item (or the priority of the top most item). \end{blockindent} \zinccmd{remove}{tagOrId ?tagOrId ...?} {\tt\large \$zinc->{\bf remove}(tagOrId, ?tagOrId?, ...);} \begin{blockindent} Delete all the items named by each {\tt tagOrId}. The command returns an empty string. \end{blockindent} \zinccmd{rotate}{tagOrId angle ?centerX centerY?} {\tt\large \$zinc->{\bf rotate}(tagOrId, angle);}\\ {\tt\large \$zinc->{\bf rotate}(tagOrId, angle, centerX, centerY);} \begin{blockindent} Add a rotation to the items or the transform described by {\tt tagOrId}. 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 angle is given in radians. The optional parameters describe the center of rotation, which defaults to the origin. \end{blockindent} \zinccmd{scale}{tagOrId xFactor yFactor} {\tt\large \$zinc->{\bf scale}(tagOrId, xFactor, yFactor);} \begin{blockindent} Add a scale factor to the items or the transform described by {\tt tagOrId}. 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 opration. If {\tt tagOrId} describes neither a named transform nor an item, an error is raised. A separate factor is specified for X and Y. \end{blockindent} \zinccmd{select}{option ?tagOrId? ?arg?} {\tt\large \$zinc->{\bf select}(option, ?tagOrId?, ?arg?);} \begin{blockindent} Manipulates the selection as requested by {\tt option}. {\tt tagOrId} describes the target item. This item must support text indexing and selection. If more than one item is referred to by {\tt tagOrId}, the first in display list order that support both text indexing and selection will be used. Some forms of the command include an {\tt index} parameter, this parameter describes a textual position within the item and should be a valid index as described in \conceptref{Text indices}{indices}. The valid forms of the command are : \begin{itemize} \item{\tt\large pathname {\bf select} adjust tagOrId index\\ \$zinc->{\bf select}('adjust', tagOrdId, index);} Adjust the end of the selection in {\tt tagOrId} that is nearest to the character given by {\tt index} so that it is at {\tt index}. The other end of the selection is made the anchor for future select to commands. If the selection is not currently in {\tt tagOrId}, this command behaves as the select to command. The command returns an empty string. \item{\tt\large pathname {\bf select} clear\\ \$zinc->{\bf select}('clear');} Clear the selection if it is in the widget. If the selection is not in the widget, the command has no effect. Return an empty string. \item{\tt\large pathname {\bf select} from tagOrId index\\ \$zinc->{\bf select}('from', tagOrdId, index);} Set the selection anchor point for the widget to be just before the character given by {\tt index} in the item described by {\tt tagOrId}. The command has no effect on the selection, it sets one end of the selection so that future select to can actually set the selection. The command returns an empty string. \item{\tt\large pathname {\bf select} item\\ (\$item, \$part) = \$zinc->{\bf select}('item');} Returns a list of two elements. The first is the id of the selected item if the selection is in an item on this widget; Otherwise the first element is an empty string. The second element is the part of the item (track, waypoint or tabular item only) or the empty string. \item{\tt\large pathname {\bf select} to tagOrId index\\ \$zinc->{\bf select}('to', tagOrdId, index);} Set the selection to be the characters that lies between the selection anchor and {\tt index} in the item described by {\tt tagOrId}. The selection includes the character given by {\tt index} and includes the character given by the anchor point if {\tt index} is greater or equal to the anchor point. The anchor point is set by the most recent select adjust or select from command issued for this widget. If the selection anchor point for the widget is not currently in {\tt tagOrId}, it is set to the character given by index. The command returns an empty string. \end{itemize} \end{blockindent} \zinccmd{smooth}{coordList} {\tt\large @coords = \$zinc->{\bf smooth}(coordList);} \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 item. \end{blockindent} \zinccmd{tapply}{} {\tt\large \$zinc->{\bf tapply}();} \begin{blockindent} Not yet implemented. \end{blockindent} \zinccmd{tdelete}{tName} {\tt\large \$zinc->{\bf tdelete}(tName);} \begin{blockindent} Destroy a named transform. If the given name is not found among the named transforms, an error is raised. \end{blockindent} \zinccmd{transform}{?tagOrIdFrom? tagOrIdTo coordList} {\tt\large @coords = \$zinc->{\bf transform}(tagOrIdTo, coordList);}\\ {\tt\large @coords = \$zinc->{\bf transform}(tagOrIdFrom, tagOrIdTo, coordList);} \begin{blockindent} This command returns a list of coordinates obtained by transforming the coordinates given in {\tt coordList} from the coordinate space of the transform or item described by {\tt tagOrIdFrom} to the coordinate space of the transform or item described by {\tt 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. 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. 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. For example: \begin{itemize} \item{\verb+($x, $y) = $zinc->transform($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]);+}\\ 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}; \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+;%$ \end{itemize} \end{blockindent} \zinccmd{translate}{tagOrId xAmount yAmount} {\tt\large \$zinc->{\bf translate}(tagOrdId, xAmount, yAmount);} \begin{blockindent} Add a translation to the items or the transform described by {\tt tagOrId}. 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 opration. If {\tt tagOrId} describes neither a named transform nor an item, an error is raised. A separate value is specified for X and Y. \end{blockindent} \zinccmd{treset}{tagOrId} {\tt\large \$zinc->{\bf treset}(tagOrdId);} \begin{blockindent} Set the named transform or the transform for the items described by {\tt tagOrId} to identity. If {\tt tagOrId} describes neither a named transform nor an item, an error is raised. \end{blockindent} \zinccmd{trestore}{tagOrId tName} {\tt\large \$zinc->{\bf trestore}(tagOrdId, tName);} \begin{blockindent} Set the transform for the items described by {\tt tagOrId} to the transform named by {\tt tName}. If {\tt tagOrId} doesn't describe any item or if the transform named {\tt tName} doesn't exist, an error is raised. \end{blockindent} \zinccmd{tsave}{?tagOrId? tName ?invert?} {\tt\large \$zinc->{\bf tsave}(tName);} {\tt\large \$zinc->{\bf tsave}(tagOrdId, tName);} {\tt\large \$zinc->{\bf tsave}(tagOrdId, tName, invert);} \begin{blockindent} Create (or reset) a transform associated with the name {\tt tName} which has for initial value the transform associated with the item {\tt tagOrId}. If {\tt tagOrId} describes more than one item, the topmost in display list order is used. If {\tt tagOrId} 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. If {\tt tagOrId} 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. \end{blockindent} \zinccmd{type}{tagOrId} {\tt\large \$name = \$zinc->{\bf type}(tagOrdId);} \begin{blockindent} This command returns the type of the item specified by {\tt tagOrId}. If more than one item is named by {\tt tagOrId}, then the type of the topmost item in display list order is returned. If no items are named by {\tt tagOrId}, an error is raised. \end{blockindent} \zinccmd{vertexat}{tagOrId x y} {\tt\large (\$contour, \$vertex, \$edgevertex) = \$zinc->{\bf vertexat}(tagOrdId, x, y);} \begin{blockindent} Return a list of values describing the vertex and edge closest to the \emph{window coordinates} {\tt x} and {\tt y} in the item described by {\tt tagOrId}. If {\tt tagOrId} describes more than one item, the first item in display list order that supports vertex picking is used. The list consists of the index of the contour containing the returned vertices, the index of the closest vertex and the index of a vertex next to the closest vertex that identify the closest edge (located between the two returned vertices). \end{blockindent} %% %% %% C h a p t e r : I t e m t y p e s %% %% \chapter{Item types} \concept{items} This chapter introduces the item types that can be used in Zinc. 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. %%% XXX CM : the two previous sentences are really not clear! \section{Group items} \object{group} Group items are used for grouping objects together. Their usage is very powerfull and their use is best described in the previous chapter \conceptref{Groups, Display List, Clipping and Transformations}{coordinates}. Applicable attributes for \ident{group} are: \attribute{group}{alpha}{alpha}{Specifies the transparency to compose with the children transparencies. Needs the openGL extension.} \attribute{group}{atomic}{boolean}{Specifies if the group should report itself or its components during a search or for binding related operations. This attribute enable the use of a group as a single complex object build from smaller parts. It is possible to search for this item or use it in bindings without dealing with its smaller parts. The defaut value is {\tt false}.} \attribute{group}{clip}{item}{The item used to clip the children of the group. The shape of this item define an area that is used as a clipping shape when drawing the children of the group. Most items can be used here but notable exceptions are the \objectref{reticle} and \objectref{map} items. The default value is {\tt ""} which means that no clipping will be performed.} \attribute{group}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group must be composed with the alpha of this group. The default value is {\tt true}.} \attribute{group}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{group}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{group}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 6}.} \attribute{group}{sensitive}{boolean}{Specifies if the item and all its children should react to events. The defaut value is {\tt true}.} \attribute{group}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{group}{visible}{boolean}{Specifies if the item and all its children is displayed. The defaut value is {\tt true}.} \section{Track items} \object{track} XXX A relire et reprendre Track items have been designed for figuring out typical radar information for Air Traffic Control. However they may certainly be used by other kinds of radar view and surely by other kind of plan view with many moving objects and associated textual information. A track is composed of two main parts: \begin{itemize} \item The first one is purely graphic and is composed of many parts, some of them being identified by their ``partName'': \begin{itemize} \item the {\bf current position} of the object. Its partName is \ident{position}. \item a {\bf speed vector} which size depends on the attribute \attributeref{track}{speedvector} for the track and the option \optref{speedvectorlength}. This speed vector may be set visible or not, sensitive or other attributes can be set such as color, width, ticks, mark at the end... Its partName is \ident{speedvector}. \item a {\bf leader} which links the current position to the label. The leader may be visible or not, sensitive or not, and other graphic caracteristics can be modified. Its partName is \ident{leader}. \item {\bf past positions} which are previous position after the track has been moved by the \cmdref{coords} command. The number of such past positions, their visibility and other graphic caracteristics can be be modified. This part is never sensitive. \item a {\bf marker}, which is a circle around the current position. This marker can be visible or not and other graphic caracteristics can be configured. The marker is never sensitive. \item a {\bf connection}, which is a link with another item. This connection may be visible or not, sensitive or not, and other graphic caracteristics can be be modified. Its partName is \ident{connection}. \end{itemize} \item the second part is a block of texts described by a labelformat (see chapter \conceptref{Labels, labelformats, and fields}{labelformat}. Each text can have its graphic decorations (alignment, background, images, borders...). These attributes are listed in the chapter \conceptref{Labels, label formats and fields}{labelformat} and can be changed by the command \cmdref{itemconfigure}. \end{itemize} The following picture shows a simple \ident{track} with a label of 5 fields and 5 past positions. This track also shows a marker, the circle around the current position. \fig{trackexample}{A track with a label composed of 5 fields}{1} %%% 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 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} 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}. Applicable attributes for \ident{track} are : \attribute{track}{circlehistory}{boolean}{If set to true the track history will be plotted as circles otherwise it will be plotted as squares. The default value is {\tt false}.} \attribute{track}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group must be composed with the alpha of this item. The default value is {\tt true}.} \attribute{track}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{track}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{track}{connecteditem}{item}{The item at the other end of the connection link. The default value is {\tt ""} which means that no connection link will be drawn.} \attribute{track}{connectioncolor}{gradient}{The color of the connection link. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{connectionsensitive}{boolean}{Specifies if the connection link is sensitive. The actual sensitivity is the logical \ident{and} of this attribute and of the item \attributeref{track}{sensitive} attribute. The default value is {\tt true}.} \attribute{track}{connectionstyle}{linestyle}{The line style of the connection link. The default value is {\tt simple}.} \attribute{track}{connectionwidth}{dimension}{The width of the connection link. The default value is {\tt 1}.} \attribute{track}{filledhistory}{boolean}{If set to true the track history will be filled otherwise it will be outlined. The default value is {\tt true}.} \attribute{track}{filledmarker}{boolean}{If set to true the circular marker will be filled otherwise it will be outlined. The default value is {\tt false}.} \attribute{track}{frozenlabel}{boolean}{Specifies if the label should be frozen at its current location to prevent the anti overlapping system from moving it. The default value is {\tt false}.} \attribute{track}{historycolor}{gradient}{The color of the track history. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{labelanchor}{anchor}{The anchor used in positionning the label. The default value is {\tt center}.} \attribute{track}{labelangle}{angle}{The angle in degrees between the label anchor and the normal to the speed vector. This attribute works with the {\tt labeldistance} attribute to specify a position for the label anchor with respect to the item origin. There is another alternative method for label positioning which is implemented with the {\tt labeldx} and {\tt labeldy} methods. Simultaneous use of the two methods should be done with care as there is no automatic update of values from the {\tt labeldx}, {\tt labeldy} set to the {\tt labeldistance}, {\tt labelangle} set. The default value is {\tt 20}.} \attribute{track}{labelconvergencestyle}{dimension}{XXX New. To be documented. The default value is ??.} \attribute{track}{labeldistance}{dimension}{The minimum distance in pixels between the track position and the label anchor. See the explanation of the {\tt labelangle} attribute for some more details. The default value is 50.} \attribute{track}{labeldx}{dimension}{The X offset between the track position and the label anchor. The default value is computed from the values in the {\tt labeldistance} and {\tt labelangle} attributes.} \attribute{track}{labeldy}{dimension}{The Y offset between the track position and the label anchor. The default value is computed from the values in the {\tt labeldistance} and {\tt labelangle} attributes.} \attribute{track}{labelformat}{labelformat}{Geometry of the label fields. The default value is {\tt ""} which means that no label will be displayed.} \attribute{track}{labelpreferredangle}{angle}{XXX New. To be documented. The default value is ??.} \attribute{track}{lastasfirst}{boolean}{If set to true, the last position in the history 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}{leadercolor}{gradient}{The color of the label leader. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{leaderfirstend}{lineend}{Describes the arrow shape at the current position end of the leader. The default value is {\tt ""}.} \attribute{track}{leaderlastend}{lineend}{Describes the arrow shape at the label end of the leader. The default value is {\tt ""}.} \attribute{track}{leadersensitive}{boolean}{Specifies if the label leader is sensitive. The actual sensitivity is the logical \ident{and} of this attribute and of the item \attributeref{track}{sensitive} attribute. The default value is {\tt true}.} \attribute{track}{leadershape}{lineshape}{The shape of the label leader. The default value is {\tt straight}.} \attribute{track}{leaderstyle}{linestyle}{The line style of the label leader. The default value is {\tt simple}.} \attribute{track}{leaderwidth}{dimension}{The width of the label leader. The default value is {\tt 1}.} \attribute{track}{markercolor}{gradient}{The color of the circular marker. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{markerfillpattern}{bitmap}{The pattern to use when filling the circular marker. The default value is {\tt ""}.} \attribute{track}{markersize}{dimension}{The (scale sensitive) size of the circular marker. The default value is {\tt 0} which turn off the display of the marker.} \attribute{track}{markerstyle}{linestyle}{The line style of the marker outline. The default value is {\tt simple}.} \attribute{track}{mixedhistory}{boolean}{If true the track history will be plotted with dots every other positions. The default value is {\tt false}.} \attribute{track}{numfields}{unsignedint}{Gives the number of fields available for the label. This attribute is read only.} \attribute{track}{position}{point}{The current location of the track. The default value is {\tt "0 0"}.} \attribute{track}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 5}.} \attribute{track}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{track}{speedvector}{point}{The speed vector $\Delta x$ and $\Delta y$ in unit / minute. The default value is {\tt "0 0"} which results in no speed vector displayed.} \attribute{track}{speedvectorcolor}{gradient}{The color of the track's speed vector. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{speedvectormark}{boolean}{If set a small point is drawn at the end of the speed vector. The point is drawn with the speed vector color. The default is {\tt false}.Not yet available without openGL} \attribute{track}{speedvectorsensitive}{boolean}{Specifies if the track's speed vector is sensitive. The actual sensitivity is the logical \ident{and} of this attribute and of the item \attributeref{track}{sensitive} attribute. The default value is {\tt true}. } \attribute{track}{speedvectorticks}{boolean}{If set a mark is drawn at each minute position. The default is {\tt false}. Not yet available without openGL} \attribute{track}{speedvectorwidth}{dimension}{New. XXX To be documented. The default value is {\tt 1}.} \attribute{track}{symbol}{bitmap}{The symbol displayed at the current position. The default value is {\tt AtcSymbol15}.} \attribute{track}{symbolcolor}{gradient}{The color of the symbol displayed at the current position. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{symbolsensitive}{boolean}{Specifies if the current position's symbol is sensitive to events. The actual sensitivity is the logical \ident{and} of this attribute and of the item \attributeref{track}{sensitive} attribute. The default value is {\tt true}.} \attribute{track}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{track}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \attribute{track}{visiblehistorysize}{unsignedint}{The number of past positions that should be displayed. The default value is {\tt 6}.} \section{WayPoint items} \object{waypoint} Waypoints items have been initially designed for figuring out typical fixed position objects (i.e. beacons or fixes in the ATC vocabulary) with associated block of texts on a radar display for Air Traffic Control. They supports mouse event handling and interactions. However they may certainly be used by other kinds of radar view or even by other kind of plan view with many geographical objects and associated textual information. A waypoint is composed of the following parts: \begin{itemize} \item the {\bf position} of the waypoint. Its partName is \ident{position}. \item a {\bf leader} which links the current position to the label. The leader may be visible or not, sensitive or not, and other graphic caracteristics can be be modified. Its partName is \ident{leader}. \item a {\bf label} which is a block of texts described by a labelformat (see chapter \conceptref{Labels, labelformat, and fields}{labelformat}. Each text can have its graphic decorations (alignment, background, images, borders...). These attributes are listed in the chapter \conceptref{Labels, label formats and fields}{labelformat} and can be changed by the command \cmdref{itemconfigure}. \item a {\bf connection}, which is a link with another item. This connection may be visible or not, sensitive or not, and other graphic caracteristics can be be modified. Its partName is \ident{connection}. \end{itemize} \fig{waypointexample}{A waypoint with a label composed of five fields; fields have borders}{1} Applicable attributes for \ident{waypoint} are: \attribute{waypoint}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group must be composed with the alpha of this item. The default value is {\tt true}.} \attribute{waypoint}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}. } \attribute{waypoint}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}. } \attribute{waypoint}{connecteditem}{item}{The item at the other end of the connection link. The default value is {\tt ""} which means that no connection link will be drawn.} \attribute{waypoint}{connectioncolor}{gradient}{The color of the connection link. The default value is the current value of the widget option \optref{forecolor}.} \attribute{waypoint}{connectionsensitive}{boolean}{Specifies if the connection link is sensitive. The actual sensitivity is the logical \ident{and} of this attribute and of the item \attributeref{waypoint}{sensitive} attribute. The default value is {\tt true}.} \attribute{waypoint}{connectionstyle}{linestyle}{The line style of the connection link. The default value is {\tt simple}.} \attribute{waypoint}{connectionwidth}{dimension}{The width of the connection link. The default value is {\tt 1}.} \attribute{waypoint}{filledmarker}{boolean}{If set to true the circular marker will be filled otherwise it will be outlined. The default value is {\tt false}.} \attribute{waypoint}{labelanchor}{anchor}{The anchor used in positionning the label. The default value is {\tt center}.} \attribute{waypoint}{labelangle}{angle}{The angle in degrees between the label anchor and the normal to the speed vector. This attribute works with the {\tt labeldistance} attribute to specify a position for the label anchor with respect to the item origin. There is another alternative method for label positioning which is implemented with the {\tt labeldx} and {\tt labeldy} methods. Simultaneous use of the two methods should be done with care as there is no automatic update of values from the {\tt labeldx}, {\tt labeldy} set to the {\tt labeldistance}, {\tt labelangle} set. The default value is {\tt 20}.} \attribute{waypoint}{labeldistance}{dimension}{The minimum distance in pixels between the way point position and the label anchor. See the explanation of the {\tt labelangle} attribute for some more details. The default value is {\tt 50}.} \attribute{waypoint}{labeldx}{dimension}{The X offset between the way point position and the label anchor. The default value is computed from the values in the \attributeref{waypoint}{labeldistance} and \attributeref{waypoint}{labelangle} attributes.} \attribute{waypoint}{labeldy}{dimension}{The Y offset between the way point position and the label anchor. The default value is computed from the values in the \attributeref{waypoint}{labeldistance} and \attributeref{waypoint}{labelangle} attributes.} \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}{leadercolor}{gradient}{The color of the label leader. The default value is the current value of the widget option \optref{forecolor}.} \attribute{waypoint}{leaderfirstend}{lineend}{Describes the arrow shape at the current position end of the leader. The default value is {\tt ""}.} \attribute{waypoint}{leaderlastend}{lineend}{Describes the arrow shape at the label end of the leader. The default value is {\tt ""}.} \attribute{waypoint}{leadersensitive}{boolean}{Specifies if the label leader is sensitive. The actual sensitivity is the logical \ident{and} of this attribute and of the item \attributeref{waypoint}{sensitive} attribute. The default value is {\tt true}.} \attribute{waypoint}{leadershape}{lineshape}{The shape of the label leader. The default value is {\tt straight}.} \attribute{waypoint}{leaderstyle}{linestyle}{The line style of the label leader. The default value is {\tt simple}.} \attribute{waypoint}{leaderwidth}{dimension}{The width of the label leader. The default value is {\tt 1}.} \attribute{waypoint}{markercolor}{gradient}{The color of the circular marker. The default value is the current value of the widget option \optref{forecolor}.} \attribute{waypoint}{markerfillpattern}{bitmap}{The pattern to use when filling the circular marker. The default value is {\tt ""}.} \attribute{waypoint}{markersize}{dimension}{The (scale sensitive) size of the circular marker. The default value is {\tt 0} which turn off the display of the marker.} \attribute{waypoint}{markerstyle}{linestyle}{The line style of the marker outline. The default value is {\tt simple}.} \attribute{waypoint}{numfields}{unsignedint}{Gives the number of fields available for the label. This attribute is read only.} \attribute{waypoint}{position}{point}{The current location of the way point. The default value is {\tt "0 0"}.} \attribute{waypoint}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 4}.} \attribute{waypoint}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{waypoint}{symbol}{bitmap}{The symbol displayed at the current position. The default value is {\tt AtcSymbol15}.} \attribute{waypoint}{symbolcolor}{gradient}{The color of the symbol displayed at the current position. The default value is the current value of the widget option \optref{forecolor}.} \attribute{waypoint}{symbolsensitive}{boolean}{Specifies if the current position's symbol is sensitive to events. The actual sensitivity is the logical \ident{and} of this attribute and of the item \attributeref{waypoint}{sensitive} attribute. The default value is {\tt true}.} \attribute{waypoint}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{waypoint}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Tabular items} \object{tabular} Tabular items have been initially designed for displaying block of textual information, organised in lists or spread out on a radar display. A tabular item is mainly composed of a \emph{label} which is a block of texts described by a labelformat (see chapter \conceptref{Labels, labelformats and fields}{labelformat}. Each text can have its graphic decorations (alignment, background, images, borders...). This attributes are listed in the chapter \conceptref{Labels, label formats and fields}{labelformat} and can be changed by the command \cmdref{itemconfigure}. Applicable attributes for \ident{tabular} are: \attribute{tabular}{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} \attribute{tabular}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{tabular}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{tabular}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{tabular}{connecteditem}{item}{Specifies the item relative to which this item is placed. The default value is {\tt ""}.} \attribute{tabular}{connectionanchor}{anchor}{Specifies the anchor on the connected item. The default value is {\tt sw}.} \attribute{tabular}{labelformat}{labelformat}{Geometry of the label fields. The default value is {\tt ""} which means that nothing will be displayed.} \attribute{tabular}{numfields}{unsignedint}{Gives the number of fields available for the label. This attribute is read only.} \attribute{tabular}{position}{point}{The item's position relative to the anchor (if no connected item specified). The default value is {\tt "0 0"}.} \attribute{tabular}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 3}. } \attribute{tabular}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{tabular}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{tabular}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Text items} \object{text} 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 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 (it can also be used for text input in labelled items such as \objectref{track}, \objectref{waypoints} or \objectref{tabular}). Applicable attributes for \ident{text} are: \attribute{text}{alignment}{alignment}{Specifies the horizontal alignment of the lines in the item. The default value is {\tt left}.} \attribute{text}{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} \attribute{text}{color}{gradient}{Specifies the color for drawing the text characters, the overstrike and underline lines. The default value is the current value of the widget option \optref{forecolor}.} \attribute{text}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{text}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{text}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{text}{connecteditem}{item}{Specifies the item relative to which this item is placed. The default value is {\tt ""}.} \attribute{text}{connectionanchor}{anchor}{Specifies the anchor on the connected item. The default value is {\tt sw}.} \attribute{text}{fillpattern}{bitmap}{Specifies the pattern used to draw the text characters, the overstrike and underline lines. The default value is {\tt ""}.} \attribute{text}{font}{font}{Specifies the font for the text. The default value is the current value of the widget option \optref{font}.} \attribute{text}{overstriked}{boolean}{If true, a thin line will be drawn horizontally across the text characters. The default value is {\tt false}.} \attribute{text}{position}{point}{The item's position relative to the anchor (if no connected item specified). The default value is {\tt "0 0"} (Tcl/Tk) or {\tt [0,0]} (Perl/Tk).} \attribute{text}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} \attribute{text}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{text}{spacing}{dimension}{Specifies a pixel value that will be added to the inter-line spacing specified in the font. The value can be positive to increase the spacing or negative to reduce it. The default value is {\tt 0}.} \attribute{text}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{text}{text}{string}{Specifies the text characters. Newline characters can be embedded to force line ends. The default value is {\tt ""}.} \attribute{text}{underlined}{boolean}{If true, a thin line will be drawn under the text characters. The default value is {\tt false}.} \attribute{text}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \attribute{text}{width}{dimension}{Specifies the maximum pixel width of the text, a line break will be automatically inserted at the closest character position to match this constraint. If the value is zero, the width is not under the item control and line breaks must be inserted in the text to have multiple lines. The default value is {\tt 0}.} \section{Icon items} \object{icon} Icon items are used for XXX. Applicable attributes for \ident{icon} are: \attribute{icon}{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} \attribute{icon}{color}{gradient}{Specifies the fill color used for drawing the bitmap. The default value is the current value of the widget option \optref{forecolor}.} \attribute{icon}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{icon}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt false}. If this attribute is set to {\tt true} without openGL rendering, it will be automatically set back to {\tt false}.} \attribute{icon}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt false}. If this attribute is set to {\tt true} without openGL rendering, it will be automatically set back to {\tt false}.} \attribute{icon}{connecteditem}{item}{Specifies the item relative to which this item is placed.} \attribute{icon}{connectionanchor}{anchor}{Specifies the anchor on the connected item. The default value is {\tt sw}.} \attribute{icon}{image}{image}{Specifies a Tk image that will be displayed by the item. The image may have a mask (depend on the image format) that clip some parts. This option has precedence over the {\tt mask} option if both are specified. The default value is {\tt ""}.} \attribute{icon}{mask}{bitmap}{Specifies a Tk bitmap that will be displayed by the item. The bitmap is filled with the color specified with the {\tt color} option. This option is inactive if an image has been specified with the {\tt image} option. The default value is {\tt ""}.} \attribute{icon}{position}{point}{The item's position relative to the anchor (if no connected item specified). The default value is {\tt "0 0"} (Tcl/Tk) or {\tt [0,0]} (Perl/Tk.} \attribute{icon}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} \attribute{icon}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{icon}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{icon}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Reticle items} \object{reticle} Reticle items are used for XXX. Applicable attributes for \ident{reticle} are: \attribute{reticle}{brightlinecolor}{gradient}{This is the color of the highlighted circles. The default value is the current value of the widget option \optref{forecolor}.} \attribute{reticle}{brightlinestyle}{linestyle}{This is the line style of the highlighted circles. The default value is {\tt simple}.} \attribute{reticle}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{reticle}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{reticle}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{reticle}{firstradius}{dimension}{This is the radius of the innermost circle of the reticle. The default value is {\tt 80}.} \attribute{reticle}{linecolor}{gradient}{This is the color of the regular (not highlighted) circles. The default value is the current value of the widget option \optref{forecolor}.} \attribute{reticle}{linestyle}{linestyle}{This is the line style of the regular (not highlighted) circles. The default value is {\tt simple}.} \attribute{reticle}{numcircles}{unsignedint}{Specifies how many circles should be drawn. The default value is {\tt -1} which means draw as many circles as needed to encompass the current widget window. This does not take into account any possible clipping that can mask part of the reticle. The idea behind this trick is to draw an infinite reticle that is optimized for the current scale.} \attribute{reticle}{period}{unsignedint}{Specifies the recurrence of the bright circles over the regulars. The default value is {\tt 5} which means that a bright circle is drawn then 4 regulars, etc.} \attribute{reticle}{position}{point}{Location of the center of the reticle. The default value is {\tt "0 0"}.} \attribute{reticle}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} \attribute{reticle}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt false} as the item cannot handle events.} \attribute{reticle}{stepsize}{dimension}{The (scale sensitive) size of the step between two consecutive circles. The default value is {\tt 80}.} \attribute{reticle}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{reticle}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Map items} \object{map} Map items are used for XXX. Applicable attributes for \ident{map} are: \attribute{map}{color}{gradient}{Specifies the color usedd to draw or fill the map. The texts and symbols that are part of the map are also drawn in this color. The default value is the current value of the widget option \optref{forecolor}.} \attribute{map}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{map}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{map}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{map}{filled}{boolean}{If set to true the map wil be filled otherwise it will be drawn as thin lines. The default is {\tt false}.} \attribute{map}{fillpattern}{bitmap}{Specifies the pattern to be used when filling the map. The value should be a legal Tk bitmap. The default value is {\tt ""}.} \attribute{map}{font}{font}{Specifies the font that will be used to drawn the texts of the map. The default value is the current value of the widget option \optref{maptextfont}.} \attribute{map}{mapinfo}{mapinfo}{Specifies the lines, texts, symbols and other various graphical components that should be displayed by the map item. All these graphical components will share the graphical attributes (color, font, etc) of the item and its coordinate system. The default value is {\tt ""} which means that nothing will be displayed by the map.} \attribute{map}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 1}.} \attribute{map}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt false} as the item cannot handle events.} \attribute{map}{symbols}{bitmaplist}{XXX to be detailed. The default value is {\tt ??}.} \attribute{map}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{map}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Rectangle items} \object{rectangle} Items of type \ident{rectangle} display a rectangular shape, optionally filled. The rectangle is described by its bottom-left and top-right corners. It is possible to use this item as a clip item for its group. It is also possible to use the rectangle in a \cmdref{contour} command to build a complex shape in a \objectref{curve} item. The two points describing the rectangle can be read and modified with the \cmdref{coords} command. %%%% XXX CM insert here two rectangles, one rotated and with a relief!! One used as a clipper! Applicable attributes for \ident{rectangle} are: \attribute{rectangle}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{rectangle}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{rectangle}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{rectangle}{fillcolor}{gradient}{Specifies the color that will be used to fill the rectangle if requested by the \attributeref{rectangle}{filled} attribute. The default value is a one color gradient based on the current value of the widget option \optref{forecolor}.} \attribute{rectangle}{filled}{boolean}{Specifies if the item should be filled. The default value is {\tt false}.} \attribute{rectangle}{fillpattern}{bitmap}{Specifies the pattern to use when filling the item. The default value is {\tt ""}.} \attribute{rectangle}{linecolor}{gradient}{Specifies the color that will be used to draw the item outline. The default value is the current value of the widget option \optref{forecolor}.} \attribute{rectangle}{linepattern}{bitmap}{Specifies the pattern to use when drawing the outline. The default value is {\tt ""}.} \attribute{rectangle}{linestyle}{linestyle}{Specifies the line style to use when drawing the outline. The default value is {\tt simple}.} \attribute{rectangle}{linewidth}{dimension}{Specifies the width of the item outline (not scalable). The default value is {\tt 1}.} \attribute{rectangle}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} \attribute{rectangle}{relief}{relief}{Specifies the relief used to drawn the rectangle outline. This attribute has priority over the \attributeref{rectangle}{linepattern} and \attributeref{rectangle}{linestyle} attributes. The color of the relief is derived from the color in \attributeref{rectangle}{linecolor}. The default value is {\tt flat}.} \attribute{rectangle}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{rectangle}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{rectangle}{tile}{image}{Specifies an image used for filling the item with tiles. This will be done only if filling is requested by the \attributeref{rectangle}{filled} attribute. This attribute has priority over the \attributeref{rectangle}{fillcolor} attribute and the \attributeref{rectangle}{fillpattern} attribute. The default value is {\tt ""}.} \attribute{rectangle}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Arc items} \object{arc} Items of type \ident{arc} display an oval section, optionally filled, delimited by two angles. The oval is described by its enclosing rectangle. The arc can be closed either by a straight line joining its end points or by two segments going throught the center to form a pie-slice. It is possible to use this item as a clip item for its group, the clip shape will be the polygon obtained by closing the arc. It is also possible to use this polygon in a \cmdref{contour} command to build a complex shape in a \objectref{curve} item. The two points describing the enclosing rectangle can be read and modified with the \cmdref{coords} command. The first point should be the top left vertex of the rectangle and the second should be the bottom right. Applicable attributes for \ident{arc} are: \attribute{arc}{closed}{boolean}{Specifies if the outline of the arc should be closed. This is only pertinent if the arc extent is less than 360 degrees. The default value is {\tt false}.} \attribute{arc}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{arc}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{arc}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{arc}{extent}{angle}{Specifies the angular extent of the arc relative to the start angle. The angle is expressed in degrees in the trigonometric system. The default value is {\tt 360}.} \attribute{arc}{fillcolor}{gradient}{ Specifies the color that will be used to fill the arc if requested by the \attributeref{arc}{filled} attribute. The default value is a one color gradient based on the current value of the widget option \optref{backcolor}.} \attribute{arc}{filled}{boolean}{Specifies if the item should be filled. The default value is {\tt false}.} \attribute{arc}{fillpattern}{bitmap}{Specifies the pattern to use when filling the item. The default value is {\tt ""}.} \attribute{arc}{firstend}{lineend}{Describes the arrow shape at the start end of the arc. This attribute is applicable only if the item is not closed and not filled. The default value is {\tt ""}.} \attribute{arc}{lastend}{lineend}{Describes the arrow shape at the extent end of the arc. This attribute is applicable only if the item is not closed and not filled. The default value is {\tt ""}.} \attribute{arc}{linecolor}{gradient}{Specifies the color that will be used to draw the item outline. The default value is the current value of the widget option \optref{forecolor}.} \attribute{arc}{linepattern}{bitmap}{Specifies the pattern to use when drawing the outline. The default value is {\tt ""}.} \attribute{arc}{linestyle}{linestyle}{Specifies the line style to use when drawing the outline. The default value is {\tt simple}.} \attribute{arc}{linewidth}{dimension}{Specifies the with of the item outline (not scalable). The default value is {\tt 1}.} \attribute{arc}{pieslice}{boolean}{This attribute tells how to draw an arc whose extent is less than 360 degrees. If this attribute is true the arc open end will be drawn as a pie slice otherwise it will be drawn as a chord. The default value is {\tt false}.} \attribute{arc}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} \attribute{arc}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{arc}{startangle}{angle}{Specifies the arc starting angle. The angle is expressed in degrees in the trigonometric system. The default value is {\tt 0}.} \attribute{arc}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{arc}{tile}{image}{Specifies an image used for filling the item with tiles. This will be done only if filling is requested by the \attributeref{arc}{filled} attribute. This attribute has priority over the \attributeref{arc}{fillcolor} attribute and the \attributeref{arc}{fillpattern} attribute. The default value is {\tt ""}.} \attribute{arc}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Curve items} \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 partially see the text through the holes. \fig{textthroughholes}{Two curves with 4 holes each. A text is visible behind}{0.8} It is possible to use this item as a clip item for its group, the clip shape will be the polygon obtained by closing the path. The vertices can be read, modified, added or removed with the \cmdref{coords} command. Applicable attributes for \ident{curve} are: \attribute{curve}{capstyle}{capstyle}{Specifies the form of the outline ends. This attribute is only applicable if the curve is not closed and the outline relief is flat. The default value is {\tt round}.} \attribute{curve}{closed}{boolean}{Specifies if the curve outline should be drawn between the first and last vertex or not. The default value is {\tt true}.} \attribute{curve}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{curve}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{curve}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{curve}{fillcolor}{gradient}{Specifies the color that will be used to fill the curve if requested by the \attributeref{curve}{filled} attribute. The default value is a one color gradient based on the current value of the widget option \optref{backcolor}.} \attribute{curve}{filled}{boolean}{Specifies if the item should be filled. The default value is {\tt false}.} \attribute{curve}{fillpattern}{bitmap}{Specifies the pattern to use when filling the item. The default value is {\tt ""}.} \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 ""}.} \attribute{curve}{joinstyle}{joinstyle}{Specifies the form of the joint between the curve segments. This attribute is only applicable if the curve outline relief is flat. The default value is {\tt round}.} \attribute{curve}{lastend}{lineend}{Describes the arrow shape at the end 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 ""}.} \attribute{curve}{linecolor}{gradient}{Specifies the color that will be used to draw the item outline. The default value is the current value of the widget option \optref{forecolor}.} \attribute{curve}{linepattern}{bitmap}{Specifies the pattern to use when drawing the outline. The default value is {\tt ""}.} \attribute{curve}{linestyle}{linestyle}{Specifies the line style to use when drawing the outline. The default value is {\tt simple}.} \attribute{curve}{linewidth}{dimension}{Specifies the with of the item outline (not scalable). The default value is {\tt 1}.} \attribute{curve}{marker}{bitmap}{Specifies a bitmap that will be used to draw a mark at each vertex of the curve. This attribute is not applicable if the outline relief is not flat. The default value is {\tt ""} which means do not draw markers.} \attribute{curve}{markercolor}{gradient}{Specifies the color of the markers. The default value is the current value of the widget option \optref{forecolor}.} \attribute{curve}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} \attribute{curve}{relief}{relief}{Specifies the relief used to drawn the curve outline. This attribute has priority over the \attributeref{curve}{linepattern} and \attributeref{curve}{linestyle} attributes. The color of the relief is derived from the color in \attributeref{curve}{linecolor}. The default value is {\tt flat}.} \attribute{curve}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{curve}{smoothrelief}{boolean}{Specifies if the relief should be smoothed along the curve. This is useful to obtain smooth curved reliefs instead of facets The default value is {\tt false}.} \attribute{curve}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{curve}{tile}{image}{Specifies an image used for filling the item with tiles. This will be done only if filling is requested by the \attributeref{curve}{filled} attribute. This attribute has priority over the \attributeref{curve}{fillcolor} attribute and the \attributeref{curve}{fillpattern} attribute. The default value is {\tt ""}.} \attribute{curve}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Bezier items} \object{bezier} Items of type \ident{bezier} display a path of Bezier cubic segments connected by their end points. Each segment is described by four control points, two located at the ends of the segment and two located off curve. The last segment can contain less than four points but at least two. If it contains two points a straight line segment is drawn, if it contains three points, the second point is used as the two off-curve control points. The polygon delimited by the path can optionally be filled. It is possible to use this item as a clip item for its group, the clip shape will be the polygon obtained by closing the path. It is also possible to use this polygon in a \cmdref{contour} command to build a complex shape in a \objectref{curve} item. The controls points can be read, modified, added or removed with the \cmdref{coords} command. Applicable attributes for \ident{bezier} are: \attribute{bezier}{capstyle}{capstyle}{Specifies the form of the outline ends. This attribute is only applicable if the bezier is not closed and the outline relief is flat. The default value is {\tt round}.} \attribute{bezier}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{bezier}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{bezier}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{bezier}{fillcolor}{gradient}{Specifies the color that will be used to fill the bezier if requested by the \attributeref{bezier}{filled} attribute. The default value is a one color gradient based on the current value of the widget option \optref{backcolor}.} \attribute{bezier}{filled}{boolean}{Specifies if the item should be filled. The default value is {\tt false}.} \attribute{bezier}{fillpattern}{bitmap}{Specifies the pattern to use when filling the item. The default value is {\tt ""}.} \attribute{bezier}{firstend}{lineend}{Describes the arrow shape at the start of the bezier. This attribute is applicable only if the item is not filled and the relief of the outline is flat. The default value is {\tt ""}.} \attribute{bezier}{lastend}{lineend}{Describes the arrow shape at the end of the bezier. This attribute is applicable only if the item is not filled and the relief of the outline is flat. The default value is {\tt ""}.} \attribute{bezier}{linecolor}{gradient}{Specifies the color that will be used to draw the item outline. The default value is the current value of the widget option \optref{forecolor}.} \attribute{bezier}{linepattern}{bitmap}{Specifies the pattern to use when drawing the outline. The default value is {\tt ""}.} \attribute{bezier}{linestyle}{linestyle}{Specifies the line style to use when drawing the outline. The default value is {\tt simple}.} \attribute{bezier}{linewidth}{dimension}{Specifies the with of the item outline (not scalable). The default value is {\tt 1}.} \attribute{bezier}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} \attribute{bezier}{relief}{relief}{Specifies the relief used to drawn the bezier outline. This attribute has priority over the \attributeref{bezier}{linepattern} and \attributeref{bezier}{linestyle} attributes. The color of the relief is derived from the color in \attributeref{bezier}{linecolor}. The default value is {\tt flat}.} \attribute{bezier}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{bezier}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{bezier}{tile}{image}{Specifies an image used for filling the item with tiles. This will be done only if filling is requested by the \attributeref{bezier}{filled} attribute. This attribute has priority over the \attributeref{bezier}{fillcolor} attribute and the \attributeref{bezier}{fillpattern} attribute. The default value is {\tt ""}.} \attribute{bezier}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Triangles items} \object{triangles} XXX A relire et reprendre Triangles items are used for XXX. This item has been added to provide access to a basic openGL geometric construction but it is also available in the X environment albeit with less features. Applicable attributes for \ident{triangles} are: \attribute{triangles}{colors}{gradientlist}{Specifies the colors of each vertex of the triangles XXX.} \attribute{triangles}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{triangles}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{triangles}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{triangles}{fan}{boolean}{ If true, triangles are created with a fan like layout. Otherwise triangles are arranged like a strip. The default value is {\tt true}.} \attribute{triangles}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} \attribute{triangles}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{triangles}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{triangles}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \section{Window items} \object{window} Items of type \ident{window} display an X11 window at a given position in the widget. It is possible to use this item as a clip item for its group, the clip shape will be the window rectangle. It is also possible to use the rectangular shape of the window item in a \cmdref{contour} command to build a complex shape in a \objectref{curve} item. The 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 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 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 frame id. Applicable attributes for \ident{window} items are: \attribute{window}{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} \attribute{window}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} \attribute{window}{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} \attribute{window}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} \attribute{window}{connecteditem}{item}{Specifies the item relative to which this item is placed. The default value is {\tt ""}.} \attribute{window}{connectionanchor}{anchor}{Specifies the anchor on the connected item used for the placement. The default value is {\tt sw}.} \attribute{window}{height}{dimension}{Specifies the height of the item window in screen units. The default value is {\tt 0}.} \attribute{window}{position}{point}{The item's position relative to the anchor (if no connected item specified). The default value is {\tt "0 0"} (Tcl/Tk) or {\tt [0,0]} (Perl/Tk).} \attribute{window}{priority}{priority}{Constraints of the underlying window sytem dictate the stacking order of window items. They can't be lowered under the other items. Additionally, to manipulate their stacking order, you must use the raise and lower Tk commands on the associated Tk window. The value of this attribute is meaningless.} \attribute{window}{sensitive}{boolean}{This option has no effect on window items. The default value is {\tt false}.} \attribute{window}{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} \attribute{window}{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} \attribute{window}{width}{dimension}{Specifies the width of the item window in screen units. The default value is {\tt 0}.} \attribute{window}{window}{window}{Specifies the X id of the window that is displayed by the item. This id can be obtained by the Tk command \ident{winfo id widgetname}. The default value is {\tt ""}.} %% %% %% C h a p t e r : L a b e l s , l a b e l f o r m a t s a n d f i e l d s %% %% \chapter{Labels, label formats and fields} \concept{labelsandfields} Zinc 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 of 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. 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. \section {Labels and labelformats} \concept{label} \concept{labelformat} A label is a set of many textual parts attached to the following types of items: \objectref{track}, \objectref{waypoint} and \objectref{tabular}. The textual parts of a label are called fields. The label and the geometry (size and position)of the text fields are described by a labelformat. The number of fields is a characteristic set at item creation time (see the command \cmdref{add}). This characteristic cannot be modified after creation of the item. However it can be read with the command \cmdref{numparts}. The labelformat is an attribute of the item types supporting labels. As any other item attribute, labelformat can be set at creation time. It can be set/modified at any time by the command \cmdref{itemconfigure} and read with the command \cmdref{itemcget}. The value of the labelformat attribute is a string (see the \attrtyperef{labelformat} type) describing the geometry (position and size) of the label and the fields.\\ By modifying a labelformat, you can : \begin{itemize} \item make appear a hidden field, \item hide a visible field, \item enlarge or reduce the size of a field \item switch between two fields \item etc. \end{itemize} Fields can have bindings (see command \cmdref{bind}). It is also possible to know which field the mouse cursor is over with the command \cmdref{currentpart}. Fields can be configured by modifying their attributes as described by next section. A perl module, called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext}) is provided for easing text input in text fields (it can also be used for text input in \objectref{text} item). \section{Attributes for fields} \object{field} Fields are item parts of items supporting labelformat (i.e. \objectref{track}, \objectref{waypoint} and \objectref{tabular}). They can be configured in a similar way of items themselves, with the command \cmdref{itemconfigure}, but this command requires an additionnal parameter (in second position) the \ident{fieldId}. To get the value of a field attribute, you can use the command {itemcget} with the \ident{fieldId} as an additionnal second parameter.\\ NB: Field attributes cannot be configured at item creation with the command \cmdref{add}. Applicable attributes for fields are: \attribute{field}{alignment}{alignment}{ The horizontal alignment of both the text and the image. The default value is {\tt left}.} \attribute{field}{autoalignment}{autoalignment}{ The dynamic horizontal alignments used depending on the label orientation. The default value is {\tt "-"} which means do not use dynamic alignment.} \attribute{field}{backcolor}{gradient}{ The field background color. The default value is the current value of the widget option \optref{backcolor}.} \attribute{field}{border}{edgelist}{ The border description edge by edge. The border is a one pixel wide outline that is drawn around the field outside the relief. Some border edges can be omitted, this attribute describes the edges that should be displayed as part of the border. The default value is {\tt ""}.} \attribute{field}{bordercolor}{gradient}{ The border color. The default value is the current value of the widget option \optref{forecolor}.} \attribute{field}{color}{gradient}{ The text color. The default value is the current value of the widget option \optref{forecolor}.} \attribute{field}{filled}{boolean}{ Specifies if the field background should be filled. The default value is {\tt false}.} \attribute{field}{fillpattern}{bitmap}{ The fill pattern used when filling the background. This attribute is overrided by the tile attribute. The default value is {\tt ""}.} \attribute{field}{font}{font}{ The text font. The default value is the current value of the widget option \optref{font}.} \attribute{field}{image}{image}{ An image to be displayed in the field. The image will be centered vertically in the field. The default value is {\tt ""}.} \attribute{field}{relief}{relief}{ Specifies the relief to be drawn around the field, inside the border. The color of the relief is derived from the color in \attributeref{field}{backcolor}. The default value is {\tt flat}.} \attribute{field}{reliefthickness}{dimension}{ Width of the relief drawn around the field. The default value is {\tt 0} which means that no relief should be drawn around the field.} \attribute{field}{sensitive}{boolean}{ Specifies if the field should react to input events. The default value is {\tt true}.} \attribute{field}{text}{string}{ A line of text to be displayed in the field. The text will be centered vertically in the field. The default value is {\tt ""}.} \attribute{field}{tile}{image}{ Specifies an image that will be tiled over the field background is the field is filled. This attribute has precedence over the \attributeref{field}{fillpattern} attribute. The default value is {\tt ""}.} \attribute{field}{visible}{boolean}{ Specifies if the field is displayed. The default value is {\tt true}.} %% %% %% C h a p t e r : A t t r i b u t e t y p e s %% %% \chapter{Attribute types} \concept{types} We describe in this chapter all the available types in Zinc. 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}.} \attrtype{alignment} \begin{blockindent} Specifies the horizontal alignment of an entity. The legal values are: {\tt left}, {\tt right}, {\tt center}. \end{blockindent} \attrtype{alpha} \begin{blockindent} Specifies the transparency of an item. The value must be an integer from 0 (fully transparent) to 100 (fully opaque). \end{blockindent} \attrtype{anchor} \begin{blockindent} Specifies one of the nine caracteristic points of a rectangle or a bounding box that will be used to position the object. These points include the four corners, the four edge centers, and the center of the rectangle. The possible values are: {\tt nw}, {\tt n}, {\tt ne}, {\tt e}, {\tt se}, {\tt s}, {\tt sw}, {\tt w}, {\tt center}. \end{blockindent} \attrtype{angle} \begin{blockindent} Specifies an angle in degrees, the value must be an integer from 0 to 360 inclusive. \end{blockindent} \attrtype{autoalignment} \begin{blockindent} Specifies the horizontal alignments that should be used for track or way point fields depending on the label position relative to the position of the item. The attribute may have two forms: a single dash {\tt -} means turning of the automatic alignment feature for the field; The other form consists in three letters which describe in order: the alignment to be used when the label is to the left of the item position, above or below the item position and to the right of the item position. The possible values for each letter is: {\tt l} for left alignment, {\tt c} for center alignment and {\tt r} for right alignment. Here is an example: {\tt rll} means right align the field if the label is on the left side of the item, and left align if the label is above, below or on the right of the item. \end{blockindent} \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 attribute (see \ref{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}. \end{blockindent} \attrtype{bitmaplist} \begin{blockindent} This is an extension of the \attrtyperef{bitmap} attribute type. It describes a list of bitmaps that will be the value of the attribute. \end{blockindent} \attrtype{boolean} \begin{blockindent} This is the description of a standard Tcl boolean value. The possible values are {\tt 0}, {\tt false}, {\tt no} or {\tt off} for the false value and {\tt 1}, {\tt true}, {\tt yes} or {\tt on} for the true value. \end{blockindent} \attrtype{capstyle} \begin{blockindent} This the description of a line cap. The possible values are {\tt butt}, {\tt projecting} and {\tt round}. \end{blockindent} \attrtype{color} \begin{blockindent} This is a string that describes a color. The description may have one of two forms, a colorname such as {\tt green} or {\tt LemonChiffon} or an rgb specification in one of the following formats, {\tt \#rgb}, {\tt \#rrggbb}, {\tt \#rrrgggbbb} or {\tt \#rrrrggggbbbb}. If less than four digits are provided for a color component, they represent the most significant bits of the component. For example {\tt \#3a7} is equivalent to {\tt \#3000a0007000}. \end{blockindent} \attrtype{dimension} \begin{blockindent} This is a string that represent distance. The string consists in a floating point signed number. \end{blockindent} \attrtype{edgelist} \begin{blockindent} This is a list describing the edges of a border that should be considered for processing (e.g for drawing). The possible values are {\tt left}, {\tt right}, {\tt top}, {\tt bottom}, {\tt contour}, {\tt oblique} and {\tt counteroblique}. The {\tt contour} value is the same as the {\tt "left top right bottom"} list. The {\tt oblique} and {\tt counteroblique} values describe diagonal segments from top-left to bottom-right and from top-right to bottom-left respectively. The following picture gives some edges examples. \fig{alledges}{edgelist examples}{0.5} \end{blockindent} \attrtype{font} \begin{blockindent} This is a string describing a font. For an exhaustive description of what is legal as a font description, refer to the Tk \ident{font} command man page. Just to mention to 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}. \end{blockindent} \attrtype{gradient} \begin{blockindent} This is a string describing a color gradient to be used for example to fill a surface. The string may consist in a single color name that will be used to paint a solid surface or can be a list of gradient steps separated by \verb+|+ characters. The general pattern is: \verb+gradient_step1|...|gradient_stepn/angle+ for an axial gradient, \verb+gradient_step1|...|gradient_stepn(x y+ for a radial gradient and \verb+gradient_step1|...|gradient_stepn[x y+ for a path gradient. The \verb+/angle+ section tells that the gradient is an axial gradient and give the angle of the gradient. The \verb+(x y+ section tells that the gradient is a radial gradient and give the center of the gradient. The \verb+[x y+ section tells that the gradient is a path gradient and give the center of the gradient. If none of the above gradient type specification is given, the gradient will be drawn as an axial gradient with a null angle. Each gradient segment section has the general form: \verb+color_name:alpha color_position mid_span_position+ Each color can be specified as a valid X color (either name or \#value). An alpha value can be applied to the color using the optional \verb+:alpha+ parameter. The color position tells where in the gradient surface, measured as a percentage of the total gradient distance, the color should start. The first gradient segment has its position set to 0 and the last segment has its position set to 100, regardless of the specification. The position can thus be safely omitted for these segments. The in between segments must have a position explicitly set. If not given, a position will default to 0. The mid span position tells where in the current gradient segment should be the median color. The position is given in percentage of the current gradient segment distance. The mid span position can be used to obtain a non linear gradient segment, this is useful to describe relief shapes. This parameter can be omitted in which case it defaults to 50 and the gradient segment is perfectly linear. A gradient segment can be specified as a single color. In this case a flat uniform fill will result. The following picture gives many examples of gradients. They correspond to the following values: \verb+axial 1 : 'black|white/90'+ \verb+axial 2 : 'black|white/90'+ \verb+axial 3 : 'black|white/30'+ \verb+axial 4 : 'black|black:0/30'+ \verb+radial 1 : 'white|black(25 15'+ \verb+radial 2 : 'white:50 0 70|black 50|white 100(35 25'+ \verb+path 1 : 'white|black:80[25 15'+ \verb+path 2 : 'white|white 30|black:80[25 15'+ \fig{allgradients}{Examples of axial, radial and path gradients}{0.5} \end{blockindent} \attrtype{gradientlist} \begin{blockindent} This is an extension of the \attrtyperef{gradient} attribute type. It describes a list of gradients that will be the value of the attribute. \end{blockindent} \attrtype{image} \begin{blockindent} This should be the name of a previously registered Tk image. In pure 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. \end{blockindent} \attrtype{item} \begin{blockindent} Describes an item id or a tag. If a tag is provided an item will be searched for the tag and the first matching in display list order will be used. \end{blockindent} \attrtype{joinstyle} \begin{blockindent} Describes a join style. The possible values are {\tt bevel}, {\tt miter} and {\tt round}. \end{blockindent} \attrtype{labelformat} \begin{blockindent} The new format is as follow. Parameters between \verb+[]+ are optional and take default values when omitted. The spaces can appear between blocks but not inside. \verb+[WidthxHeight] [] [] ... []+ \verb+Width+ and \verb+Height+ are strictly positive integers. They set the size of the clipping box surrounding the label. If not specified, there will be no clipping. If specified alone, they specify the size of the only displayed field (0). \verb+ ::= []+ Each fieldiSpec specify the size and position of the field numbered i. \verb+ ::= + \verb+ ::= x|f|i|a|l+ \verb++ specifies the meaning of the following \verb++ or \verb++. Those are positive integers. Values for \verb++ have the following meaning : \begin{itemize} \item \verb+'x'+ : the corresponding dimension (either width or height) is in pixel, according to the value of the \verb++ or \verb++ \item \verb+'f'+ : the corresponding dimension is in percentage of the mean width/height of a character (in the field font). The following \verb++ or \verb++ gives the percentage. The value must be an integer between 0 and 100. %%% XXX CM How is computed ``the mean width/height of a character'' \item \verb+'i'+ : the corresponding dimension is in percentage of the size of the image in the field. The following \verb++ or \verb++ gives the percentage. The value must be an integer between 0 and 100. If the field contains no image, the dimension is 0. \item \verb+'a'+ : the corresponding dimension is automatically adjusted to match the field's content plus the given value in pixels. \item \verb+'l'+ : the corresponding dimension is automatically adjusted to match the global size of the label (not counting fields with \verb+'l'+ size specs). The corresponding integer parameter is not used with this size specification and it is not possible to reference the field in another \verb++ (see below). \end{itemize} \verb+ ::= +. \verb- ::= +|<|>|^|$- %$ this comment if for emacs coloring only! \verb++ and \verb++ are either integer or index refering an other field of the labelformat. Values for \verb+pChar+ have the following meaning : \begin{itemize} \item \verb-'+'- : the position, either on the X or Y axis, is in pixel, possibly negative. XXX what does it mean if negative? The value is given by the corresponding \verb++ or \verb++. \item \verb+'<'+ : The field will be at the left (or top) of the field refered by the corresponding index \verb++ (or \verb++) \item \verb+'>'+ : The field will be at the right (or bottom) of the field refered by the corresponding index \verb++ (or \verb++) \item \verb+'^'+ : The field will be left (or top) aligned with the field refered by the corresponding index \verb++ (or \verb++). \item \verb+'$'+ : The field will be right (or bottom) aligned with the field refered by the corresponding index \verb++ (or \verb++). %$ this comment if for emacs coloring only! \end{itemize} \verb++ can be omitted if there is only one field. \end{blockindent} \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. The format is: \verb+lChar leftLeaderAnchor [lChar rightLeaderAnchor]+ If \verb+lChar+ is a \verb+|+, \verb+leftLeaderAnchor+ and \verb+rightLeaderAnchor+ are the indices of the field that serve to anchor the label's leader. More specifically the bottom right corner is used when \verb+leftLeaderAnchor+ is active and the bottom left corner is used when \verb+rightLeaderAnchor+ is active. If \verb+lChar+ is \verb+%+, \verb+leftLeaderAnchor+ and \verb+rightLeaderAnchor+ should be specified as \verb+widthPercentxheightPercent+, each value being a percentage (between 1 and 100) of the width or height of the label bounding box. If \verb+rightLeaderAnchor+ is not specified it defaults to \verb+leftLeaderAnchor+. If neither are specified, the center of the label is used as an anchor. \end{blockindent} \attrtype{lineend} \begin{blockindent} Describes the shape of the arrow at the beginning or end of a path. This is a list of three numbers describing the arrow shape in the following order: distance along the axis from neck to tip of the arrowhead, distance from trailing points to tip and distance from outside edge of the line to the trailing points (see canvas). If an empty list is given, there is no arrow. \end{blockindent} \attrtype{lineshape} \begin{blockindent} Describes the shape of a path connecting two points. The possible values are {\tt straight}, {\tt rightlightning}, {\tt leftlightning}, {\tt rightcorner}, {\tt leftcorner}, {\tt doublerightcorner} and {\tt doubleleftcorner}. The following figure shows these different line shapes \fig{alllineshapes}{Examples of all available line shapes}{0.4} \end{blockindent} \attrtype{linestyle} \begin{blockindent} Describes the style of the dashes that should be used to draw a line. The possible values are {\tt simple}, {\tt dashed}, {\tt mixed} and {\tt dotted}. \end{blockindent} \attrtype{mapinfo} \begin{blockindent} This is the name of a previously registered mapinfo object (see the chapter \conceptref{The mapinfo related commands}{mapinfocmds}) that will define the lines, arcs, symbols, and texts displayed in a map item. \end{blockindent} \attrtype{point} \begin{blockindent} This is a list of two floating point values that describes a point position or some two dimensional delta (used for example to describe the speed vector of a track item). \end{blockindent} \attrtype{priority} \begin{blockindent} A strictly positive integer value for the display priority. \end{blockindent} \attrtype{relief} \begin{blockindent} Describes a border relief. The possible values, illustrated in the following figure are {\tt flat}, {\tt raised}, {\tt sunken}, {\tt ridge}, {\tt groove}, {\tt roundraised}, {\tt roundsunken}, {\tt roundridge}, {\tt roundgroove}, {\tt raisedrule}, {\tt sunkenrule}. \fig{allreliefs}{Examples of all available non-flat reliefs}{0.5} \end{blockindent} \attrtype{string} \begin{blockindent} Just what its name implies, a string. \end{blockindent} \attrtype{taglist} \begin{blockindent} This should be a list of strings describing the tags that are set for an item. \end{blockindent} \attrtype{unsignedint} \begin{blockindent} Describes an unsigned integer value. \end{blockindent} \attrtype{window} \begin{blockindent} A string describing an X window id. This id can be returned by the {\tt winfo id a-widget-path} command. \end{blockindent} %% %% %% C h a p t e r : T h e m a p i n f o c o m m a n d s %% %% \chapter{The mapinfo related commands} \concept{mapinfocmds} MapInfo objects are used to describe graphical primitives that will be displayed in map items. It is possible to describe lines, arcs, symbols and texts as part of a MapInfo. The \ident{mapinfo} and \ident{videomap} commands are provided to create and manipulate the mapinfo objects. \section{The mapinfo command} \mapinfocmd{name}{create}{} \begin{blockindent} Create a new empty map description. The new mapinfo object named {\tt name}. \end{blockindent} \mapinfocmd{mapInfoName}{delete}{} \begin{blockindent} Delete the mapinfo object named by {\tt mapInfoName}. All maps that refer to the deleted mapinfo are updated to reflect the change. \end{blockindent} \mapinfocmd{mapInfoName}{duplicate}{newName} \begin{blockindent} Create a new mapinfo that is a exact copy of the mapinfo named {\tt mapInfoName}. The new mapinfo object will be named {\tt newName}. \end{blockindent} \mapinfocmd{name}{add}{type args} \begin{blockindent} Add a new graphical element to the mapinfo object named by {\tt name}. The {\tt type} parameter select which element should be added while the {\tt args} arguments provide some type specific values such as coordinates. Here is a description of recognized types and their associated parameters. \begin{description} \item{line} \\ This element describes a line segment. Its parameters consists in a line style ({\tt simple}, {\tt dashed}, {\tt dotted}, {\tt mixed}, {\tt marked}), an integer value setting the line width in pixels and four integer values setting the X and Y coordinates of the two end vertices. \item{arc} \\ This element describes an arc segment. Its parameters consists in a line 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. \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. \item{text} \\ This element describes a line of text. Its parameters consists in a text style ({\tt normal}, {\tt underlined}), a line style ({\tt simple}, {\tt dashed}, {\tt dotted}, {\tt mixed}, {\tt marked}) to be used for the underline, two integer values setting the X and Y of the text position and a string describing the text. \end {description} \end{blockindent} \mapinfocmd{name}{count}{type} \begin{blockindent} Return an integer value that is the number of elements matching {\tt type} in the mapinfo named {\tt name}. {\tt type} may be one the legal element types as described in the {\tt mapinfo add} command. \end{blockindent} \mapinfocmd{name}{get}{type index} \begin{blockindent} Return the parameters of the element at {\tt index} with type {\tt type} in the mapinfo named {\tt name}. The returned value is a list. The exact number of parameters in the list and their meaning depend on {\tt type} and is accurately described in \ident{mapinfo add}. {\tt type} may be one the legal element types as described in the {\tt mapinfo add} command. Indices are zero based and elements are listed by type. \end{blockindent} \mapinfocmd{name}{replace}{type index args} \begin{blockindent} Replace all parameters for the element at {\tt index} with type {\tt type} in the mapinfo named {\tt name}. The exact number and content for {\tt args} depend on {\tt type} and is accurately described in \ident{mapinfo add}. {\tt type} may be one the legal element types as described in the {\tt mapinfo add} command. Indices are zero based and elements are listed by type. \end{blockindent} \mapinfocmd{name}{remove}{type index} \begin{blockindent} Remove the element at {\tt index} with type {\tt type} in the mapinfo named {\tt name}. {\tt type} may be one the legal element types as described in the {\tt mapinfo add} command. Indices are zero based and elements are listed by type. \end{blockindent} \mapinfocmd{name}{scale}{factor} \begin{blockindent} Scale all coordinates of all the elements described in the mapinfo named {\tt name} by {\tt factor}. The same value is used for X and Y axes. \end{blockindent} \mapinfocmd{name}{translate}{xAmount yAmount} \begin{blockindent} Translate all coordinates of all the elements described in the mapinfo named {\tt name}. The {\tt xAmount} value is used for the X axis and the {\tt yAmount} value is used for the Y axis. \end{blockindent} \section{The videomap command} \concept{videomapcmd} This section describes the videomap command, used to create a mapinfo from a proprietary file format for simple maps, in use in french Air Traffic Control Centres. \command{videomap}{ids}{fileName} \begin{blockindent} Return all sub-map ids that are described in the videomap file described by {\tt fileName}. The ids are listed in file order. This command makes possible to iterate through a videomap file one sub-map at a time, to know how much sub-maps are there and to sort them according to their ids. \end{blockindent} \command{videomap}{load}{fileName index mapInfoName} \begin{blockindent} Load the videomap sub-map located at position {\tt index} in the file named {\tt fileName} into a mapinfo object named {\tt mapInfoName}. It is possible, if needed, to use the \ident{videomap ids} command to help translate a sub-map id into a sub-map file index. \end{blockindent} %% %% %% C h a p t e r : O t h e r r e s o u r c e s p r o v i d e d %% %% \chapter{Other resources provided by the widget} \concept{otherresources} In this chapter we describe resources included in Zinc widget. This include bitmaps sets (used as symbols for some items or used as stipples), Perl modules goodies and Zinc simple demonstrations. \section{Bitmaps} \label{builtinbitmaps} Zinc 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. \fig{atcsymb}{Bitmaps available for position of tracks, waypoints, and maps}{0.5} The second set provides stipples that can be used to implement transparency, they are named AlphaStipple0 to AlphaStipple15, AlphaStipple0 being the most transparent. \fig{alphastip}{Bitmaps available for creating stipples}{0.5} \latexhtml{\tolerance 2000 %allow somewhat looser lines. \hbadness 10000}{} %don't complain about underfull lines. \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 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 \ident{ZincDebug.pm}, you can get a short reminder by depressing the {\tt Esc} key in the main window of this application. Please refer to the \ident{ZincDebug.pm} man pages with the classical command {\tt man ZincDebug} \section{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. \section{ZincText.pm} \concept{zinctext} The Tk::ZincText perl module implements bindings for text input 'a la emacs'. It works for text item or for text fields of track, waypoint or tabular items. The item which require text input must just be tagged with the 'text' tag. 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 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. We will try to further document this feature in the future. %\listoftables \listoffigures \printindex \label{interne:DernierePage} \end{document}