path: root/doc/refman.tex

\documentclass[11pt,twoside,a4paper]{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, Christophe Mertz, Centre d'Étude de la Navigation Aérienne},
    pdfsubject={The pre-3.4 Reference Manual.},
    pdfkeywords={tk tcl perl x11 canvas opengl script gui TkZinc},
    pagebackref,
    pdfpagemode=None,
    bookmarksopen=true
  ]{hyperref}
%  \pdfpagewidth=210truemm
%  \pdfpageheight=297truemm
  \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[widemargins]{a4}
\usepackage{calc}
\usepackage{makeidx}


\newcommand{\cident}[1] {%
  {\tt #1}}

\newcommand{\code}[1] {%
  {\tt #1}}

\newcommand{\ident}[1] {%
  {\tt\large #1}}

\newenvironment{blockindent}{\begin{quote}\vspace{-0.8\baselineskip}}{\end{quote}\vspace{-0.5\baselineskip}}

\newcommand{\option}[4]{%
  \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}
  \begin{blockindent}{#4}\end{blockindent} }

\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{quote}\vspace{-\baselineskip}#4\vspace{-0.8\baselineskip}\end{quote}
  }

% 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.4 pre-release Reference Manual.\\\small{[CENA technical Note NT03-532]} }
\author{Patrick Lecoanet, Christophe Mertz}
\date{25 February 2003}


\begin{document}
%pdfpagewidth: \the\pdfpagewidth pdfpageheight: \the\pdfpageheight voffset: \the\voffset ~topmargin: \the\topmargin ~textheight: \the\textheight \linebreak
\voffset=-0.5in  \setlength\textheight{ (\textheight+0.5in) }
%voffset: \the\voffset ~topmargin: \the\topmargin ~textheight: \the\textheight \linebreak


\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 TkZinc ?}

TkZinc widgets are very similar to Tk Canvases in that they support
structured graphics. Like the Canvas, TkZinc implements items used to
display graphical entities. Those items can be manipulated and bindings can be
associated with them to implement interaction behaviors. But unlike the
Canvas, TkZinc can structure the items in a hierarchy (with the use of
group items), has support for affine 2D transforms (i.e.\ translation, scaling, and
rotation), clipping can be set for sub-trees of the item hierarchy, the item set
is quite more powerful including field specific items for Air Traffic systems and
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, TkZinc also offers as a runtime option, the support
for openGL rendering, giving access to features such as antialiasing, transparency,
color gradients and even a new, openGL oriented, item type : \objectref{triangles}.
In order to use the openGL features, you need the support of the GLX extension on
your X11 server. Of course, performances will be dependant of your graphic card.  At
the time of writing, NVidia drivers for XFree86 R4.1 are doing a nice job. A laptop
with a GeForce GO graphic card works nice for non trivial applications.  We also
succeeded in using TkZinc with openGL on the Exceed X11 server (running on windows and
developped by Hummingbird) with the 3D extension.

As an example of TkZinc capabilities when combined with openGL, we implemented
the TkZinc logo as a Perl module (available as a goodie in \ident{LogoZinc.pm}).
This logo (see below) was designed with Adobe Illustrator and then programmed in perl.


%\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 TkZinc focuses on the notion of script language. We strongly
believe that the script environments are very powerful for rapid prototyping and for
developping small to medium scale field specific applications. In these cases
developper know-how and time are a scarce resource and the application either has few
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 TkZinc widget is available for the Tcl/Tk and the Perl/Tk scripting
environments.  A binding over Tcl/Tk is also provided for Python. It should be easy
to do the same for Ruby, a binding for Tk is provided in the standard distribution of
Ruby. Other scripting languages may be used as well depending on the availability
of a Tk interface.

This document is Tcl/Tk and Perl/Tk oriented but it should be easy for Python or Ruby
programmers to adapt. Every time a TkZinc command is described in this
document, it is given first in Tcl/Tk idiom and then in Perl/Tk idiom.

This document is also referenced as CENA technical note NT03-532.

\section{Differences with previous version}

\subsection{Differences between 3.4 pre-release and 3.2.6 release}
\begin{itemize}
\item  bezier items have been suppressed; they can now be easily replaced by curve items.
\item  curve items support now a higher level of description: they may be composed of line
segments, and bezier segments. In the future they may also support other kinds of segments
(such as arcs...).
\item  the coords method accepts a list of arrays as well as flat list of coordinates.
When coords returns more than one point it is always a list of arrays.
(and no more a flat list of x y x y ...). {\bf Beware this is an small incompatible change in the API}.
\item  operators of the contour command have been replaced by a flag which indicates
if the contour must be taken as counterclockwise, clockwise or unchanged.
Contours ids are now predictable. The GPC ``not-so-free'' library is no more used.
It has been replaced by the GLU library. So TkZinc is again fully free software.
\item  curve item have a new -fillrule attribute. 
\item  the syntax of radial and path gradient has been changed.
\item  TkZinc comes now with a Zinctrace.pm module to trace every TkZinc method call
\item  the hierarchical view in ZincDebug.pm can now display some choosen attributes
in a choosen format.
\item  3 new perl demos in zinc-demos: ``tiger'' and ``curve with bezier control points''
and ``fillrule''
\item  pathTags introduced in 3.2.6 have been documented. Label and label
format documentation has been enhanced.
\end{itemize}

\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 TkZinc command may return the version number
\item  icom items may be scaled and rotated (needs openGL)
\item  anti-overlapping of tracks labels works again
\item  tsave can now be used to know if a named transformation is already defined 
\item  gname can now be used to know if a named gradient is already defined 
\item  new tags can now be used : ``pathTags'' to go through groups. 
\item  find and addtag commands have been modified to be ``pathTag'' compliant
\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  TkZinc can now use openGL capablities
\item  many new item options (due to openGL capablilites) and a new triangles item
\item  a new perl module : ZincDebug.pm to interactively browse the item hierarchy
\item  as color are all gradient (with alpha transparency) the -alpha option has been removed
\item  a set of TkZinc demontrations are available with the zinc-demos command
\item  many new explanations in this doc: groups, item ids and tags ... 
\item  the postscript version of this doc has been replaced by a pdf version
\item  configuring an unexisting option of an item is no more an error (this was a design mistake)
\item  a perl module ZincText.pm make it easier to implement text input
\end{itemize}

\section{Where can I find TkZinc 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 TkZinc source code through
a private CVS server. Please contact directly {\tt lecoanet@cena.fr} for more informations.

This documentation is available as part of the TkZinc software.  It is also
available separately on the web sites. This document is formatted with \LaTeX\ 
and is distributed as either html pages or a pdf file.

As a complement to this reference manual, small Perl/Tk demos of TkZinc are
also available through a small application named \conceptref{zinc-demos}{zinc-demos},
highly inspired from the \emph{widget} application included in Tk. The aim of these demos
are both to demonstrates the power of TkZinc and to help newcomers start using
Zinc with small examples.


\section{What is this document about ?}

This reference manual describes the TkZinc widget interface. It shows how to
create and configure a TkZinc widget, and how to use the commands it provides to
create and manipulate items. The next chapter \conceptref{Widget creation and
options}{options} describes how to create a new widget and which options and resources are
available to configure it.
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 TkZinc along
with their attributes.
The chapter \conceptref{Labels, fields and labelformat}{labelsandfields} describes the
use of labels, the possible attributes of fields and finally the labelformat syntax.
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 TkZinc.


\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 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 TkZinc. This documentation has been enriched by Christophe Mertz.


\section{How can I find help with TkZinc}

If you are stuck with a feature you don't understand. If you don't know how to
do something with TkZinc. If you think you have found a bug or a mismatch between
the documentation and the behavior of the widget. Please feel free to contact us.
Mail either {\tt lecoanet@cena.fr} or the TkZinc mailing list. To subscribe to the mailing
list, please consult the site \anurl{http://www.openatc.org/zinc/}.


\section{How may I contribute to TkZinc development}

If you think TkZinc is an interesting tool, they are many ways to help with TkZinc
development. First of all, subscribe to the TkZinc mailing list and get in touch with us. To
subscribe, please consult the site \anurl{http://www.openatc.org/zinc/}.

\begin{itemize}
\item The very first way to contribute is to use TkZinc and to report
any bug or problem you may experiment. Of course, if you send a script that
exhibits the problem or even better a patch, your problem will have more
chance to find a solution.
\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 TkZinc if they are worth it.
\item The fourth way to contribute, and may be the most difficult, is to enrich the set
of items (see section \conceptref{C api for adding new items}{Capi}) in an separate
dynamic library. Then send us source code (with appropriate copyright and licence)
if you want them to be integrated in a future release of TkZinc.
\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 TkZinc command creates a new TkZinc widget, the general form are in Tcl and Perl:

\begin{quote}
{\tt\large zinc}\medskip

{\tt\large \$version = \$mainwindow->zinc();}\smallskip

{\tt\large \$Tk::Zinc::VERSION;}
\end{quote}

These expressions can be used to get the version of TkZinc. The string returned by the last expression also details the graphic head available. For example : ``zinc-version-3205d X11 GL''.

\begin{quote}
{\tt\large zinc pathname ?options?}\medskip

{\tt\large \$mainwindow->Zinc(?option=>value?, ..., ?option=>value?);}
\end{quote}

{\tt pathname} name the new widget and specifies where in the widget hierarchy
it will be located.

Any new TkZinc widget comes with a root group item, always identified by
the item id 1. This group will contain all other items, either directly or through
groups created themselves in the root group. Together the items form a tree rooted
at the root group, hence its name.
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 TkZinc objects. But they are private to TkZinc and do not benefit from Tk
support. They have been named differently to avoid confusion.

Any number of options may be specified on the command line or in the option
database to modify the global behavior of the widget. Available options are
described below.


\option{backcolor}{backColor}{BackColor}
{
This is the color that will
be used to fill the TkZinc window. It is also used as a default color
for some item color attributes. See each color attribute for the
actual source of the default color. Its default value is
{\tt \#c3c3c3}, a light grey.
}

\option{borderwidth}{borderWidth}{BorderWidth}
{
  Specifies the width of the 3d border that should be displayed around the widget
  window. This border does overlap the active TkZinc display area. The area
  requested from the geometry manager (or the window manager if applicable)
  is the area defined by \optref{width} and \optref{height}, the border is not
  taken into account. This value can be given in any of the forms valid for
  coordinates (See \cident{TkGet\_Pixels}). The default value is {\tt 2}.
}

\option{cursor}{cursor}{Cursor}
{
  Specifies the cursor to use when the pointer is in the TkZinc window.  The default
  value is set to preserve the cursor inherited at widget creation.
}

\option{font}{font}{Font}
{
  The font specified by this option is used as a default font for item attributes of
  type font. Its default value is {\tt -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*}.
}

\option{forecolor}{foreColor}{ForeColor} %% XXX CM Foreground ?!
{
  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 {\tt black}.
}

\option{fullreshape}{fullReshape}{FullReshape}
{
  If this option is True, the shape applied to the TkZinc window will propagate up the
  window hierarchy to the toplevel window. The result will be a shaped toplevel.
  See also the \optref{reshape} option, it controls whether a shape is applied
  to the TkZinc window or not.  The default is {\tt true}.
}

\option{height}{height}{Height}
{
  Specifies the height of the TkZinc window. This value can be given in any of the
  forms valid for coordinates (See \cident{Tk\_GetPixels}). The default is {\tt 100}
  pixels.
}

\option{highlightbackground}{highlightBackground}{HighlightBackground}
{
  Specifies the color to display in the traversal highlight region when the
  widget does not have the input focus. The default value is {\tt \#c3c3c3}.
}

\option{highlightcolor}{highlightColor}{HighlightColor}
{
  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 {\tt black}.
}

\option{highlightthickness}{highlightThickness}{HighlightThickness}
{
  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 {\tt 2}.
}

\option{insertbackground}{insertBackground}{InsertBackground}  %% XXX CM Foreground ?!
{
  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 {\tt black}.
}

\option{insertofftime}{insertOffTime}{InsertOffTime}  %% XXX CM OffTime ?!
{
  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 {\tt 300}.
}

\option{insertontime}{insertOnTime}{InsertOnTime}  %% XXX CM OnTime ?!
{
  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 {\tt 600}.
}

\option{insertwidth}{insertWidth}{InsertWidth}
{
  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 {\tt 2}.
}

\option{lightangle}{lightAngle}{LightAngle}
{
  Specifies the lighting angle used when displaying relief. The default value is {\tt 120}. %%% XXX CM to be completed!
}

\option{mapdistancesymbol}{mapDistanceSymbol}{MapDistanceSymbol}
{
  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 {\tt AtcSymbol19} (see \conceptref{Other resources provided by the widget}{otherresources}).
}

\option{maptextfont}{mapTextFont}{MapTextFont}
{
  Specifies the font used to draw the texts contained in maps. The default is
  {\tt -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*}.
}

\option{overlapmanager}{overlapManager}{OverlapManager}
{
  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 root group (id 1). To disable the algorithm this option should
  be set to {\tt 0}.
}

\option{pickaperture}{pickAperture}{PickAperture}
{
  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
  {\tt 1}.
}

\option{relief}{relief}{Relief}
{
  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 {\tt flat}.
}

\option{render}{render}{Render}
{
  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 {\tt false}.
}

\option{reshape}{reshape}{Reshape}
{
  Specifies if the clipping shape that can be set in the root group item should clip
  the root group children or be used to reshape the TkZinc window. This option can be
  used with the fullreshape option to reshape the toplevel window as well. The
  default value is {\tt true}.
}

\option{selectbackground}{selectBackground}{SelectBackground}  %% XXX CM Foreground ?!
{
  Specifies the background color to use for displaying the selection in text
  items. The default value is {\tt \#a0a0a0}.
}

\option{speedvectorlength}{speedVectorLength}{SpeedVectorLength}
{
  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 {\tt 3}.
}

\option{takefocus}{takeFocus}{TakeFocus}
{
  (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.

}

\option{tile}{tile}{Tile}
{
  Specifies an image name to be used as a tile for painting the TkZinc window
  background. The default value is {\tt ""} (the empty string).
}

\option{trackmanagedhistorysize}{trackManagedHistorySize}{TrackManagedHistorySize}
{
  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 {\tt 6}.
}

\option{trackmanagehistory}{trackManageHistory}{TrackManageHistory}
{
  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.
}

\option{width}{width}{Width}
{
  Specifies the width of the TkZinc window. This value can be given in any of
  the forms valid for coordinates (See \cident{Tk\_GetPixels}). The default is
  {\tt 100} pixels.
}



%%
%%
%% 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 TkZinc 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 its 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 TkZinc. By
convention, the root group is its own parent. It is not possible to change the parent
of the root group and it is not possible to delete it. However, it is possible to
change the group of all other items after creation, and thus modify the item tree at
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, TkZinc
will try to trigger bindings associated with the atomic group not with the item under the
pointer. This improves greatly the metaphor of an indivisible item.

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
\conceptref{zinc-demos}{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 items of a group are
stacked between the items that are under the group and the items that are on top of the
group. Thus, 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 TkZinc each item is geometrically defined in its own coordinate space. So
each time a new item is created, a new coordinate system is attached to it.
This coordinate system must be related to the coordinate systems of the other
items to place the items with respect to each other. This relationship is
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}, and \objectref{curve} 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 \conceptref{zinc-demos}{zinc-demos}
to demonstrate the transformation capabilities of TkZinc. This is also a great resource
to understand how it works and to tame its complexity. It is possible to use this program
to test one's idea on a given transformation problem before coding it as part of a
complex application.


\section{Clipping and groups}
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.

It is also possible to clip the root group. Depending on the value of TkZinc options
\optref{reshape} and \optref{fullreshape}, the clipping form can be used either to
clip all items in the TkZinc widget, or reshape the TkZinc widget, or to propagate
the TkZinc widget shape to the parent windows. In the latter case, this allows to build
non-rectangulaire applications. Example:

\code{
  use Tk::Zinc;\\

  my \$mw = MainWindow->new();\\
  my \$zinc = \$mw->Zinc(-reshape => 1, -fullreshape => 1)->pack;\\

  \# creating a triangulaire curve\\
  my \$triangle= \$zinc->add('curve',1, [ [0,0], [100,0], [50,100] ], -closed => 1);\\
  \# using the triangulaire curve to reshape both TkZinc and Mainwindow widgets\\
  \$zinc->itemconfigure(1, -clip => \$triangle);\\

  \$zinc->add('arc',1, [ [0,0], [100,100] ], -filled => 1, -fillcolor => 'darkblue');
  ...\\
  \&Tk::MainLoop;
}


%%
%%
%% 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 TkZinc session two
items cannot have the same id. This property can be quite useful when used
in conjonction with tags, which are described below.

\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). However the
following characters may not be used to form a tag: \verb+. * ! ( ) & | :+.
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 TkZinc. The tag \ident{all} is
associated with all items in TkZinc. The tag \ident{current} is always
associated with the topmost item that lies under the mouse pointer. If no
such item exists, no item has this tag.

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. For example:
\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{PathTags}
\concept{pathTags}
A special form of tag called a pathTag can be used as a tagOrId argument in all
commands except \cmdref{bind}. This special tag describes an item or a group of
items in the absolute item hierarchy. The pathTag consists in a path down the
group hierarchy followed by an (optionnal) effective tag, in the usual sense.

The path is an ordered list of tags set up on groups that drives the search
from the root group down the group hierarchy. The path starts with either a dot
or a star, and the tags in the path are separated by dots or stars. The dot
means that the next tag selects a group item that is a direct child of the
current group, starting with the root group. The star selects a group item that
is a possibly indirect child of the current group, the candidate is found
in display list order. The first tag in the path, the one just after the first
dot or star, can be a group id; This is useful in order to limit the search in a
specific sub-hierarchy.

The last tag of a pathTag, the one not followed by a dot or a star, is the
effective tag searched for. It can be omitted, in this case the search
proceed with the tag all. The dot or star just before the effective tag,
even if the tag is implied, controls how the tag is searched. If a dot is
present, the search is limited to the current group level. If a star is
present, the search proceed from the current group level down the whole
group subtree.

Here are some commonly used pathTags idioms:

\begin{description}

\item{\ident{.group1Tag.group2Tag.aTag}}\\
Selects all {\bf direct} children with the tag \ident{aTag} in the group obtained by
following the path \ident{.group1Tag.group2Tag} from the root group.
The search proceed from the root group to the first direct child group in display
list order with tag \ident{group1Tag}. Then it searches for the first direct child group
with tag \ident{group2Tag}. Finally in this group, the search ends by finding all direct
children items (including groups) with tag \ident{aTag}. If a tag is not found the whole
search is aborted and no item is selected.

\item{\ident{.group1Tag.group2Tag*aTag}}\\
Selects all children, {\bf direct or indirect}, with the tag \ident{aTag} in
the group obtained by following the path \ident{.group1Tag.group2Tag} from the root group.

\item{\ident{.group1Tag*group2Tag.aTag}}\\
Selects all {\bf direct} children with the tag \ident{aTag} in
the group obtained by following the path \ident{.group1Tag*group2Tag} from the root group.
The search proceed from the root group to the first direct child group in display
list order with tag \ident{group1Tag}. Then it searches in display list order down the
hierearchy for the first group with tag \ident{group2Tag} . Finally in this group, the
search ends by finding all direct children items (including groups) with tag \ident{aTag}.
If a tag is not found the whole search is aborted and no item is selected.

\item{\ident{.group1Tag*group2Tag*aTag}}\\
Selects all items with the tag \ident{aTag} in the hierarchy
of the group obtained by following the path \ident{.group1Tag*group2Tag} from the root
group. The search proceed from the root group to the first direct child group in
display list order with tag \ident{group1Tag}. Then it searches in display list order down
the hierearchy for the first group with tag \ident{group2Tag} . Finally in this group, the
search ends by finding all direct children items (including groups) with tag \ident{aTag}.
If a tag is not found the whole search is aborted and no item is selected.

\item{\ident{.group1Tag.group2Tag.}}\\
Selects all {\bf direct} children of the group obtained
by following the path \ident{.group1Tag.group2Tag} from the root group. If a tag is not
found the whole search is aborted and no item is selected.

\item{\ident{.group1Tag.group2Tag*}}\\
Selects all items in the hierarchy of the group obtained
by following the path \ident{.group1Tag.group2Tag} from the root group. If a tag is not
found the whole search is aborted and no item is selected.

\item{\ident{.groupId.aTag}}\\
Selects all {\bf direct} children with tag \ident{aTag} of the group with id \ident{groupId}.
If \ident{groupId} is not found or is not a group id, the search is aborted and no item
is selected. This form together with the next is specially useful with cloned
items hierarchies where only the topmost group item is known after cloning. Using
pathTags it is now possible to make use of designs using components with named
sub-components. It is possible to clone a component and afterward to change the
behavior of named sub-components with pathTags of the form
\ident{.componentId.subComponentName} or perhaps better {.componentId*subComponentName} . Some
care is needed in order to avoid sub-component name clash. Remember that the search for
tags proceed in {\bf display list order}, not in hierarchy order. In other more
technical words the search walks the item tree {\bf depth first} not breadth first.

\item{\ident{.groupId*aTag}}\\
Selects all items with tag \ident{aTag} in the hierarchy of the
group with id \ident{groupId}. If \ident{groupId} is not found or is not a group id, the search
is aborted and no item is selected.

\item{\ident{.groupId.}}\\
Selects all {\bf direct} children of the group with id \ident{groupId}. It is the only
way to get direct children of a group.

\item{\ident{.groupId*}}\\
Selects all items in the hierarchy of the group with id \ident{groupId}.

\item{\ident{.}}\\
Selects all {\bf direct} children of the root group.

\item{\ident{*}}\\
Selects all items in the hierarchy (not counting the root group itself).

\item{\ident{.aTag}}\\
Selects all {\bf direct} children of the root group with the tag \ident{aTag}.

\item{\ident{*aTag}}\\
Selects all items in the whole hierarchy (starting a the root group)
with the tag \ident{aTag}. It is the same as using the simple tag \ident{aTag}.

\end{description}


\section{Tags and bindings}
\concept{tagsAndBindings}
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 TkZinc collects which tags are related to a given event and
then use the bindings established by \cmdref{bind} to activate the related scripts. Event
dispatching operates on three event sources: mouse events, keyboard events and internally
generated enter/leave events. Mouse events are dispatched to the item under the mouse
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}} refers to the beginning of line
\item{\ident{eol}} refers to the end of line
\item{\ident{bow}} refers to the beginning of word
\item{\ident{eow}} refers to the end of word
\item{\ident{up}}  refers to previous line
\item{\ident{down}} refers to next line
\end{description}


%%
%%
%% 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{transform} \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 TkZinc widget is much inspired by the Canvas command set. Someone
comfortable with the Canvas should not have much trouble using the TkZinc's commands.
Eventually, the command set will be a superset of the Canvas command set. Anyway
some commands depart radically from the equivalent in the Canvas. For example, the user
should be aware that \cmdref{scale} and \cmdref{translate} do not behave in the same
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 TkZinc widget. It can be called with no
  parameters to return the list of all item types currently known by TkZinc. It can also be
  called with a valid item type as first parameter and a group item as second parameter to
  create a new item of this type in the given group.

  After these first two parameters come some item type specific arguments.  Here is
  detailed description of these arguments by type:
  \begin{description}
  \item{\objectref{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{\objectref{curve}}\\
    The curve type expects either a flat list or a list of lists. In the first case, the flat list
    must be a list of floating point numbers \verb+x0 y0 x1 y1 ... xn yn+,
    giving the coordinates of the curve vertices. The number of values should be
    even (or the last value will be discarded) but the list can be empty to build
    an empty invisible curve. In the second case, the list must contain lists of 2 or 3
    elements: xi, yi and and an optionnal point type. Currently, the only available point type
    is 'c' for a cubic bezier control point. For example in perl/Tk, the following list
    is an example of 2 beziers segments with a straight segment in between:

\code{
( [x0, y0], [x1, y1, 'c'], [x2, y2, 'c'], [x3, y3],
  [x4, y4, 'c'], [x5, y5] )
}

    As there is only on control point, \code{[x4, y4, 'c']} , for the second cubic bezier,
    the omitted second control point will be defaulted to the same point.
    A curve can be defined later with the \cmdref{contour}
    or \cmdref{coords} commands. As a side effect of the curve behavior, a one vertex
    curve is essentially the same as an empty curve, it only waste some more memory.
  \item{\objectref{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{\objectref{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.
  \item{\objectref{tabular}, \objectref{track}, \objectref{waypoint}}\\
    These types expect the number of fields they will manage in the label or
    tabular form. This number must be greater or equal to zero.
  \item{\objectref{group}, \objectref{icon}, \objectref{map}, \objectref{reticle}, \objectref{text}, \objectref{window}}\\
    These types do not 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 root group is assumed. In any cases, the starting
  group will not be reported in the search result. This means that the
  root 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 TkZinc.
    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 root group and it can be used to
    control if the search should be recursive or not (see \conceptref{PathTags}{pathTags} 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 root 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 TkZinc internal geometry with a call
    to {\tt update} if the current state is not stable (i.e before calling
    the main loop or in a callback after modifying the transform or doing
    something else affecting the geometry of items).

  \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 root 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 root group and it can be used to
    control if the search should be recursive or not (see \conceptref{PathTags}{pathTags} 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.
\code{
\# for example to get the lower right corner of a text item\\
(\$x ,\$y) = \$zinc->anchorxy('myTextTag', 'se');
}

\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 returns 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
  TkZinc items instead of widgets. Another difference with the \ident{bind} command
  is that only mouse and keyboard related events can be specified (such as \ident{Enter},
  \ident{Leave}, \ident{ButtonPress}, \ident{ButtonRelease}, \ident{Motion},
  \ident{KeyPress}, \ident{KeyRelease}). The \ident{bind} manual page is the most
  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 returns an empty
  string.
\end{blockindent}


\zinccmd{contour}{tagOrId ?operatorSpec coordListOrTagOrId?}

{\tt\large \$contourNum = \$zinc->{\bf contour}(tagOrId);}\\
{\tt\large \$contourNum = \$zinc->{\bf contour}(tagOrId, operatorAndFlag, 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 multiple contours, the returned value is 0 or 1 depending
  on the item having a contour or not. \objectref{track}, \objectref{waypoint},
  \objectref{reticle}, \objectref{group},  \objectref{map}, and yield 0
  while \objectref{rectangle}, \objectref{tabular}, \objectref{arc}, \objectref{icon},
  \objectref{triangles}, \objectref{text}, and \objectref{window} yield 1.

  {\tt coordListOrTagOrId} specifies a list of coordinates (either a flat list of X and Y, or
  a list similar to the one allowed for a curve item) or an item describing a
  contour. If a flat list is specified it should contain an even number of floating point values
  specifying the contour vertices X and Y in order. If a tag or an id is specified, it is
  should be from one of these classes: arc, curve, icon, rectangle, tabular, text,
  window. The external shape of the item will be used as the contour. If {\tt
  coordListOrTagOrId} describes more than one item, the first in display list order will
  be used.

  {\tt operatorAndFlag} specifies the operation that will be carried. This can be:
  
  \begin{description}
  \item{\ident{add}} to extend the surface of the curve. In this case there is a mandatory
  flag describing the way the contour will be added. It may take the following values:
  \begin{description}
        \item{0} the list of points is taken unchanged. In this case, the {\tt coordListOrTagOrId}
        parameter cannot be a tag and must be an explicit list of points.
        \item{1} the list of points is reverted, if needed, so that the points defines
                 a {\bf counterclockwise} contour.
        \item{-1} the list of points is reverted,if needed, so that the points  defines
                 a {\bf clockwise} contour.
  \end{description}
  The exact graphical effect depends on the value of the \attributeref{curve}{fillrule}
  as described in the \attrtyperef{fillrule} type description.
  \item{\ident{remove}} to remove an existing contour
  \end{description}

  The following operations are no more available: \ident{diff},
  \ident{inter}, \ident{union}, \ident{xor}; 
  An error is generated if the items are not of a correct type or if the coordinate list
  is malformed.

\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 either a flat list (of
  one or more vertices described as X, Y floating point values) or a list of lists
  [X Y ?type?] such as described in the curve item. The coordinates will be used to
  replace or add coordinates to the current contour.

  Almost all items can be manipulated by this command, the map item is the only current
  exception. The effect of the command can be quite different depending on the item. For
  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 curves and triangles, coordinates of all points defining the item can be set or
  read. For all items that do not support multiple contours (currently all except curves)
  the {\tt contour} parameter should be omitted or specified as zero.

  When {\tt coords} is used to get more than one point, the return value is {\bf always} a
  list of lists. Each sub list contains X, Y, and 'c' if the point is a bezier control point.

  The optional parameters must be combined to produce a given behavior. Here are the
  various form recognized by the command:

  \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. 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, coordIndex 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.  {\bf WARNING:} coordList must be a
    list of one list describing x, y and optionnaly the point type.
    
  \item{\tt\large
        pathname {\bf coords} tagOrId remove contourIndex coordIndex\\
        \$zinc->{\bf coords}(tagOrId, 'remove', contourIndex, coordIndex);}
  
    Remove coordinate at coordIndex in contour at contourIndex. Can only be handled by
    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 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
    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 returns {\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.");\\

	\# to get all groups recursevely contained in a group\\
	@groups = \$zinc->find('withtype', 'group', ".aGroup*");
  }

  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 lists describing the points and 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 be either a flat list of an even
  number of coordinates in x, y order or a list of lists of point coordinates X, Y.
  The returned list can be directly used to create or change a curve item contour.
\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 returns 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 returns 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, an error is reported. When configuring
  a set of item defiend by a tag, all items must then accept these attributes.
\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 topmost 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
  operation. 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 that will smooth the polygon
  described by the vertices in {\tt coordList} and returns a list of lists describing
  thr points and control points for the generated segments. {\tt coordList} should be either a
  flat list of an even number of coordinates in x, y order, or a list of lists of point
  coordinates X, Y. The returned list can be used to create or change the contour of a
  curve 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 tagOrIdFrom} or {\tt tagOrIdTo} describes more than one item,
  the topmost in display list order is used.  If either {\tt tagOrIdFrom} or {\tt tagOrIdTo}
  doesn't describe either a transform or an item, an error is raised.
  The {\tt coordList} should either be a flat list containing an even number of
  coordinates each point having two coordinates, or a list of lists each sublist of the form
  [ X Y ?pointtype? ]. The returned coordinates list will be isomorphic to the list given
  as argument.

  It is possible to convert from window coordinate space to the coordinate space of any
  item. This is done by omitting {\tt ?tagOrIdFrom?} and specifying in {\tt tagOrIdTo},
  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 TkZinc. Each item type
provides a set of options that may be used to query or change the item behavior. Some item
types cannot be used with some widget commands, or use special parameters with some
commands. Those cases are noted in the description of the item.

%%% 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}

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 TkZinc offers an
anti-overlap manager. This manager tries to avoid any overlap of tracks labels. It also
avoids that the label overlap the speedvector. This manager is stable over time: there
should be few cases where labels are moved to a very different position. This manager
applies to all tracks included in a group (by default the group 1). It can be
enabled/disabled with the attributes XXX. New labels positions are computed by the overlap
manager every time a track is moved, a track is created or destroyed and every time the
TkZinc widget is resized. Due to software licence limitation, TkZinc \emph{do not include}
the very last version of this anti-overlap manager. If you are interested
in this anti-overlap manager, please contact Didier Pavet at {\tt pavet@cena.fr}.

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 uniform (possibly transparent)
color of the connection link. The first color of a real gradient color
will be used. 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 uniform (possibly transparent) color of the
track history. The first color of a real gradient color will be used. 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 uniform (possibly transparent) color of the label
leader. The first color of a real gradient color will be used. 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 uniform (possibly transparent) color of the
circular marker. The first color of a real gradient color will be used. 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 position. 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 uniform (possibly transparent) color of
the track's speed vector. The first color of a real gradient color will be used.
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 uniforme (possibly transparent) color of the symbol
displayed at the current position. The first color of a real gradient color will be used.
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 uniform (possibly transparent) color of
the connection link. The first color of a real gradient color will be used. 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 uniform (possibly transparent) color of the
label leader. The first color of a real gradient color will be used. 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 uniform (possibly transparent) color of the
circular marker. The first color of a real gradient color will be used. 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 uniform (possibly transparent) color of the
symbol displayed at the current position. The first color of a real gradient color will be used.
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
TkZinc options (see chapter \conceptref{Widget options}{options} can be used for
configuring the text input (for example : \optref{insertbackground},
\optref{insertofftime} \optref{insertontime}, \optref{insertwidth}).
A perl module, called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext}) is provided for easing text input in text items
(it can also be used for text input in labelled items such as \objectref{track},
\objectref{waypoint} 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 uniform (possibly transparent) color for
drawing the text characters, the overstrike and underline lines. The first color of a
real gradient color will be used. 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 displaying bitmap images. Any bitmap file format
supported by Tk can be used. If the bitmap file supports transparency
(not alpha-blending, only full transparency), TkZinc will render this transparent area.
With openGL, icons can be rotated or scaled. However, attributes \attributeref{icon}{composerotation}
and \attributeref{icon}{composescale} must be set before rotation and scaling.

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 uniform (possibly transparent) fill color
used for drawing the bitmap. The first color of a real gradient color will be used.
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 set of concentric circles. The number of circles can be either
finite or not. Some periodic circles may be different, they are called bright circles; they
can be configured differently from other circles. This item has mainly be designed for
radar display images, to help user evaluationg distances from the central point.
Reticle cannot handle events.

Applicable attributes for \ident{reticle} are:

\attribute{reticle}{brightlinecolor}{gradient}{This is the uniform (possibly transparent)
color of highlighted circles. The first color of a real gradient color will be used.
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 uniform (possibly transparent) color of
regular (not highlighted) circles. The first color of a real gradient color will be used.
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 typically used for displaying maps on a radar display view. Maps are
not be sensitive to mouse or keyboard events, but have been designed to efficiently display
large set of points, segments, arcs, and simple texts. A map item is associated to a mapinfo.
This mapinfo entity can be either initialized with the \conceptref{videomap}{videomapcmd}
command or more generally created and edited with a set of commands described in the  
\conceptref{The mapinfo related commands}{mapinfocmds} section.

  Applicable attributes for \ident{map} are:

\attribute{map}{color}{gradient}{Specifies the uniform (possibly transparent) color used
to draw or fill the map. The texts and symbols that are part of the map are also drawn in
this color. The first color of a real gradient color will be used. 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 uniform (possibly transparent)
color used to draw the item outline. The first color of a real gradient color
will be used. 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 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 uniform (possibly transparent) color
used to draw the item outline. The first color of a real gradient color
will be used. 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 and/or cubic bezier connected
  by their end points. The polygon delimited by the path can optionally be filled.
  It is possible to build curve items with more than one path to
  describe complex shapes with the \cmdref{contour} command. This command can be used to
  perform boolean operations between a curve and almost any other item available in TkZinc
  including another curve. The exact appearance of a multi-contour curve (i.e. which parts
  are filled and which are holes) depends on the value of an attribute, called
  \attributeref{curve}{fillrule}. 
  In the following figure (a snapshot of \conceptref{zinc-demos}{zinc-demos}) two curves
  with four holes each are in front of a text. You can partially see the text through the holes.

\fig{textthroughholes}{Two curves with 4 holes each. A text is visible behind}{0.8}
  
  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 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}{fillrule}{fillrule}{Specifies the way contours are combined together to
specify complex surfaces, with holes and disjoint surfaces. The default value is {\tt "odd"}.
This means that a point of the space is considered inside the curve surface if an odd number
of contours are surrounding the point. This attribute should only be modified for curves with
multiple or complicated contours.}

\attribute{curve}{firstend}{lineend}{Describes the arrow shape at the start of the curve.
This attribute is applicable only if the item is not closed, not filled and the relief of
the outline is flat. The default value is {\tt ""}.}

\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 uniform (possibly transparent) color
used to draw the item outline. The first color of a real gradient color will be used.
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 uniform (possibly transparent) color of the
markers. The first color of a real gradient color will be used.
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{Triangles items}
\object{triangles}

Triangles items are used for displaying complexe surfaces with variables colors
and transparencies. For example, it can be used to create a circular color selector
displaying a range of colors. The way triangles composing a triangle item are arranged
is defined by the \attributeref{triangles}{fan} option.
 
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 what if less/more colors than vertex?

\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 TkZinc,
  including, of course, another TkZinc instance. Another less obvious use is to embed a
  whole Tk application into TkZinc, here is how to do it: The embedding application should
  create a frame with the \ident{-container} option set to true; Add a window item to the
  relevant TkZinc widget with the \attributeref{window}{window} attribute set to the id of
  the container frame; The embedded application should create its toplevel with the
  \ident{-use} option set to the id of the container frame; Or, as an alternative, the
  embedded \cident{wish} can be launched with the \ident{-use} option set to the container
  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}

TkZinc was initially developed for building interactive radar image working on X
server. This requires very good performances, for displaying many hundred tracks and
moving them every few second. Tracks are typically composed of some geometric parts and
some textual parts. These two parts are connected together with a leader. The geometric
parts are subject to scaling. For example the speed vector length in pixel depends on the
scale. But the textual part must not be zoomed. Managing parts which are scaled and others
which are not, can be a real challenge. Usual toolkits or widget are not suited to such
behaviours, but TkZinc is.

To be able to manage many items mixing geometric parts and non-geometric parts,
TkZinc introduces the concepts of label, labelformat, fields and fields attributes.

\section {Labels and labelformats}
\concept{label} \concept{labelformat}

A label is a set of rectangular fields attached to the following item types :
\objectref{track}, \objectref{waypoint} and \objectref{tabular}. The fields of a
label may contain either text or bitmaps or images. A label cannot be identified
or manipulated by itself; There is no function nor method to get or manipulate a
label as an object or an item. A label is always associated to an item and
is manipulated through this item.

Some label global characteristics are set/get at the item level:

\begin{itemize}
\item The maximum number of fields is defined at item creation, as the second
argument of the \cmdref{add} method. The field number can not be changed after creation.
These fields will be indexed from 0 to n-1. The number of fields can be read
with the command \cmdref{numparts}. For example:
\begin{verbatim}
 $track = $zinc->add('track', 4, ....);
 # this creates a track item with 4 fields, indexed from 0 to 3
\end{verbatim}
\item The rectangular geometries of displayable fields are defined through
the item attribut \ident{-labelformat}. The value is a string following
the syntax of the \attrtyperef{labelformat} type. This attribute can be set at any time;
thus modifying its value is a way to quickly change the geometry (or the visibility) of
some fields. Fields may overlap. They are drawn according to the index order:
field 0 is drawn before (thus under) field 1. The labelformat also optionnaly
describes a clipping rectangle. For example:
\begin{verbatim}
 $zinc->itemconfigure($track, -labelformat => 'a12a0+0+ x20x100>0 a2a0>1>0');
                                      ##       ^        ^         ^
                                      ##       field0   field1    field2
 # the labelformat indicates that only the first 3 fields will be displayed:
 #  field 0 expands for the size of the text + 12 pixels.
 #       It starts at the top left point
 #  field 1 has a size of 20x10 pixels.
 #       It is left aligned with field 0, just under field 0
 #  field 2 expands for the size of the text + 2 pixels.
 #       It is adjacent to the right of field 1, just under field 0
\end{verbatim}
\end{itemize}

Characteristics of each individual field are called field attributes. They are all
described in next section \conceptref{Attributes for fields}{fieldAttributes}.
They may be set or get with the \cmdref{itemcget} and \cmdref{itemconfigure} command.
These commands require as a second argument the field number. By configuring
field attributes you can modify :
\begin{itemize}
\item the field content : \attributeref{field}{text}, \attributeref{field}{image},
\attributeref{field}{tile}, \attributeref{field}{fillpattern},
\item the field colors : \attributeref{field}{backcolor}, \attributeref{field}{bordercolor},
\attributeref{field}{color},
\item the text general appearance : \attributeref{field}{alignment},
\attributeref{field}{autoalignment}, \attributeref{field}{font},
\item the field border : \attributeref{field}{border}, \attributeref{field}{relief},
\attributeref{field}{reliefthickness},
\item and the field visibility and sensitivity: \attributeref{field}{sensitive},
\attributeref{field}{visible}. 
\end{itemize}

As an example:
\begin{verbatim}
 $zinc->itemconfigure($track, 0, -text => 'Hello World',
                                 -color => 'white',
                                 -backcolor => 'black',
                                 -filled => 1);
 # this should display "Hello World" in white on black in field 0
\end{verbatim}

It is possible to bind callbacks to fields, with the command \cmdref{bind} and
special tags (described \conceptref{Tags and bindings}{tagsAndBindings}).
As an example:
\begin{verbatim}
 $zinc->bind("$track:1", '<1>', \&acallback);
 # this binds &acallback to field 1
\end{verbatim}

Inside a callback function, it is possible to know which field the mouse cursor is over
with the command \cmdref{currentpart}.

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 easing text input
in \objectref{text} item).



\section{Attributes for fields}
\object{field}
\concept{fieldAttributes}

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 uniform (possibly transparent) color.
The first color of a real gradient color will be used.
The default value is the current value of the widget option \optref{forecolor}.}

\attribute{field}{color}{gradient}{ The text uniform (possibly transparent) color.
The first color of a real gradient color will be used.
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 TkZinc. They are listed by
alphabetical order.

\emph{NB: Two types are very important and their existence should be known
by any new user of TkZinc: \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. TkZinc registers a set of bitmaps that can be used for any bitmap valued
  attribute (see section \conceptref{Bitmaps}{builtinbitmaps}). Extensions to Tk are available to create or
  manipulate bitmaps from a script. The value may also name a file containing a valid X11
  bitmap description. The syntax in this case is {\tt @filename}.
\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{fillrule}
\begin{blockindent}
  This is a string describing the rule used to compose the different contours or pathes of
  a curve. The allowed values are directly inspired from the openGL GLU tesselators as
described for example in the chapter 11 of the ``The OpenGL Programming Guide 3rd Edition
The Official Guide to Learning OpenGL Version 1.2'',  ISBN 0201604582. You can also refer to
the example fillrule provided with TkZinc in \conceptref{zinc-demos}{zinc-demos}. The allowed values are
{\tt odd}, {\tt nonzero}, {\tt positive}, {\tt negative}, and {\tt abs\_geq\_2}.
The following figure shows the effect of fillrule value on curves with multiple contours:

\fig{fillrule}{Examples of fillrule on curves}{0.4}

\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.
  Gradient are also used to describe color of lines, even if in this case the lines are
  limited to one color with and additionnal alpha percentage.

  The string may consist in a single color name that will be used to paint a solid surface
  or a simple color with an alpha valuecan 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 in degres.

  The \verb+(x y+ section tells that the gradient is a radial gradient and give the center
  of the gradient. The center is expressed in percentage of the bounding box, centered on the middle.
  so \verb+(0 0+ means the center point of the bounding box, and \verb+(-50 -50+ means
  the lower left corner of the bounding box.

  The \verb+[x y+ section tells that the gradient is a path gradient and give the center
  of the gradient. The center is expressed in % of the bounding box, centered on the middle.
  See just above for more explanation.

  If none of the above gradient type specification is given, the gradient will be drawn as
  an axial gradient with a null angle.

  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/0'  :=  'black|white'+

\verb+axial 2 :  'black|white/90'+

\verb+axial 3 :  'black|white/30'+

\verb+axial 4 :  'black|black:0/30'+

\verb+radial 1 : 'white|black(-14 -20'+

\verb+radial 2 : 'white:50 0 70|black 50|white 100(0 0'+

\verb+path 1 :   'white|black:80[-14 -20'+

\verb+path 2 :   'white|white 30|black:80[-14 -20'+

\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 format is as follow. Parameters between \verb+[]+ are optional and take default values
  when omitted. Spaces can appear between blocks but not inside.
  
  \verb+[WidthxHeight] [<field0Spec>] [<field1Spec>] ... [<fieldnSpec>]+
  
  \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 which index is 0.

  \verb+<fieldiSpec> ::= <fieldiSize>[<fieldiPos>]+

  Each fieldiSpec specify the size and position of the field numbered i.

  \verb+<fieldiSize> ::= <sChar><fieldWidth><sChar><fieldHeight>+

  \verb+<sChar> ::= x|f|i|a|l+

  \verb+<sChar>+ specifies the meaning of the following \verb+<fieldWidth>+ or
  \verb+<fieldHeight>+. Those are positive integers. Values for \verb+<sChar>+
  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+<fieldWidth>+ or \verb+<fieldHeight>+
  \item \verb+'f'+ : the corresponding dimension is in percentage of the mean
   width/height of a character (in the field font). The following \verb+<fieldWidth>+
   or \verb+<fieldHeight>+ 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+<fieldWidth>+ or \verb+<fieldHeight>+ 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+<fieldiPos>+ (see below).
  \end{itemize}
  
  \verb+<fieldiPos> ::= <pChar><fieldX><pChar><fieldY>+.

  \verb-<pChar> ::= +|<|>|^|$-
%$ this comment if for emacs coloring only!

  \verb+<fieldX>+  and \verb+<fieldY>+ 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+<fieldX>+ or \verb+<fieldY>+.
  \item \verb+'<'+ : The field will be at the left (or top) of the field refered
  by the corresponding index \verb+<fieldX>+ (or \verb+<fieldY>+)
  \item \verb+'>'+ : The field will be at the right (or bottom) of the field refered
  by the corresponding index \verb+<fieldX>+ (or \verb+<fieldY>+)
  \item \verb+'^'+ :  The field will be left (or top) aligned with the field refered
  by the corresponding index \verb+<fieldX>+ (or \verb+<fieldY>+).
  \item \verb+'$'+ : The field will be right (or bottom) aligned with the field refered
  by the corresponding index \verb+<fieldX>+ (or \verb+<fieldY>+).
%$ this comment if for emacs coloring only!
  \end{itemize}
  
  \verb+<fieldiPos>+ 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 (in degree) and the angular extent of the arc (in degree).
  \item{symbol} \\ This element describes a symbol. Its parameters consists in two integer
  values setting the X and Y of the symbol position and an integer setting the symbol
  index in the {\tt -symbols} list of the map item.
  \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 TkZinc widget. This include
bitmaps sets (used as symbols for some items or used as stipples), Perl modules goodies
and TkZinc simple demonstrations.

\section{Bitmaps}
\concept{builtinbitmaps}

TkZinc creates two sets of bitmaps.

The first set contains symbols for ATC tracks position, waypoints position and maps
symbols. These bitmaps are named AtcSymbol1 to AtcSymbol22.

\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 TkZinc to display the hierarchical tree of items, to display
items selected by their id or tags, 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 a list of items, with many interesting attributes such as position, priority,
visibility, group...\ and even more information on request. Much of the selected items
attributes can be interactively modified. 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. For more information, please refer to the
\ident{ZincDebug.pm} man pages with the classical command {\tt man ZincDebug}

To use this module, you can import it either by adding, for example, the following
statements in your source code:
\code{\\use ZincDebug;\\
finditems(\$zinc);\\
tree(\$zinc, -optionsToDisplay => '-tags', -optionsFormat => 'row');\\}
or simply by using the -M option of Perl:
\code{\\perl -MZincDebug yourscript.pl\\}

\section{Tracing TkZinc methods call in perl/Tk}

Because you some time get some errors inside \ident{TkZinc} with a cryptic message
like {\tt ".... errors in Tk.pm line 228"} it may be usefull to know where exactly
in your code is this error. There is a simple and convenient mean to do this, just
by using a small module called \ident{ZincTrace.pm}, released with \ident{TkZinc}.
It will trace every call of a TkZinc method. It will trace on the standard output
the following informations:
\begin{itemize}
\item the TkZinc method name
\item the full filename where this method has been invoked
\item the line number in the source file
\item the list of arguments in a human-readable form
\end{itemize}

To use this module you can import it either by adding the following
statement in your source code:
\code{\\use ZincTrace;\\} or better, by using the -M option of Perl:
\code{\\perl -MZincTrace yourscript.pl\\}

\section{zinc-demos}
\concept{zinc-demos}

Starting at version 3.2.4 of TkZinc small applications are included as demos. They
are all accessible through an application called \ident{zinc-demos}. These numerous
(about 30) tiny demos are useful for newcomers and as starting points for developing
real applications. They consists in toy applications, graphically advanced examples
or even a TkZinc port of \ident{TkTetris} from Slaven Rezic.

\section{ZincText.pm}
\concept{zinctext}

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 TkZinc, can be used to extent
the default set of items in TkZinc in an additionnal dynamic library. The AddItemClass C
function is extensively used for implementing the core item set. So please refer to the source
code for examples or send email for more information on precise problems.

We will try to further document this feature in the future.

%\listoftables

\listoffigures

\printindex

\label{interne:DernierePage}


\end{document}