diff options
Diffstat (limited to 'doc/refman.tex')
| -rw-r--r-- | doc/refman.tex | 4914 |
1 files changed, 0 insertions, 4914 deletions
diff --git a/doc/refman.tex b/doc/refman.tex deleted file mode 100644 index ea242d0..0000000 --- a/doc/refman.tex +++ /dev/null @@ -1,4914 +0,0 @@ -\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 3.3 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}\latexhtml{\ifpdf\vspace{-0.8\baselineskip}\fi}{}} {\end{quote}\latexhtml{\ifpdf\vspace{-0.5\baselineskip}\fi}{}} -%\newenvironment{blockindent}{\begin{quote}\vspace{-0.8\baselineskip}}{\end{quote}\vspace{-0.5\baselineskip}} - - -\newcommand{\option}[3]{% - \label{opt:#1} - \index{#1} - \latexhtml{\ifpdf\hyperdef{opt}{#1}{}\fi}{\htmlrule[WIDTH="70\%" 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="70\%" 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="70\%" 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 pre 3.3 Reference Manual.\\\small{[CENA technical Note NT03-532]} } -\author{Patrick Lecoanet, Christophe Mertz} -\date{1 Septembre 2004} - - -\begin{document} -%pdfpagewidth: \the\pdfpagewidth pdfpageheight: \the\pdfpageheight voffset: \the\voffset ~topmargin: \the\topmargin ~textheight: \the\textheight \linebreak - -\latexhtml{\ifpdf\voffset=-0.5in \setlength\textheight{ (\textheight+0.5in) }\fi} - -%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 versions} - -\subsection{Differences between 3.3 and 3.2.97 release} -This release has been mainly focused on producing a stable code -base that compile and run on all three supported platforms with -as little effort as possible. - -The only functional change is the integration of the fieldbbox -command into the bbox command. - - -\subsection{Differences between 3.2.97 and 3.2.6 release} -\begin{itemize} -\item TkZinc now works with Perl ptk 8.4 and utf8; However there remains -some serious performance hit at launch time, when combinig openGL and ptk8.4, -due to utf8 fonts management. -\item text and icons can now be scaled and rotated in X (i.e. without openGL) -\item translate method accepts an additionnal argument 'absolute' -\item scale method accepts additionnal arguments: unit and rotation center -\item find and addtag methods can now search inside atomic group -\item the bbox method accepts into account the clipping area of a group -\item TkZinc option -trackmanagehistory is replaced by -trackvisiblehistorysize -and in for track items the attribute -visiblehistorysize has been removed and -replaced by -historyvisible. {\bf Beware: Incompatible change} -\item Default value of -composescale and -composerotation of texts -and icons is now false. This is coherent with the default behavior -of these items (being rigids). The impact of this change is -greatly minored by the new processing of the -position attribute. -\item transformation of items with a -position has been slightly -modified. The point described by -position is no longer considered -in the coordinate space of the item but in the coordinate space -of its parent group. The item is always located in 0,0 of its -own coordinate space. This is so to make use of -composescale and --composerotation a lot more useful (and compatible). -\item The fieldbbox method has been added to get item filed bounding box. -\item Four new methods are now available for managing the transforms: -tcompose, tget, tset and skew. A predefined named transformation is also available -'identity' to be used with tsave. A predefined tag 'device' can be used to -convert coordinates in or from device coordinates (with transform method). -\item TkZinc with Tcl/Tk now works on windows and MacOS X (with X11 and fink). -\item compilation on Linux works fine now, and TkZinc for Perl is on the CPAN -\item A powerful perl module Tk::Zinc::Graphics has been added to help creating -complex curves. French man pages are available. A port in Tcl is also available. -\item png images with transparencies can now be displayed (requires openGL rendering) -\item bezier items have been suppressed; they can now be easily replaced by curve items. -\item curve items support now a higher level of description: they may be composed of line -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 a 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 gradient has been changed, mainly to accomodate with any color specification -defined for X. {\bf Beware that old gradient are no more compatible} -\item conical gradient type has been added; gradient paramaters has been extended. -\item Perl modules ZincText, ZincDebug, ZincTrace and ZincTraceErrors have been renamed Tk::Zinc::Text Tk::Zinc::Debug -Tk::Zinc::Trace and Tk::Zinc::Trace. -\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 6 new Perl demos in zinc-demos: ``testGraphics'', ``magic Lens'', ``pathTags'', ``tiger'' and ``curve with bezier control points'' -and ``fillrule''. Many Perl/Tk demos have been ported to Tcl/Tk. -\item pathTags introduced in 3.2.6 have been documented. Label and label -format documentation has been enhanced. -\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.tkzinc.org/} 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 -transforms ... -The chapter \conceptref{Item types}{items} describes all the items provided by TkZinc along -with their attributes. -The chapter \conceptref{Labels, fields and labelformat}{labelsandfields} describes the -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 characteristics 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.tkzinc.org/}. - - -\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.tkzinc.org/}. - -\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! Some -documentation (currently Tk::Zinc::Graphics) are in French only. Translating it in -english would be great. -\item The third way to contribute, and may be the funniest way, is to enrich the set -of demos (see chapter \conceptref{Other resources provided by the -widget}{otherresources}). Feel free to send us your productions. They may be simple -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. - -You can set the {\tt \$ZINC\_GLX\_INFO} environment variable in order to display some information about the OpenGL instance used by TkZinc \textit{(New since TkZinc v3.2.6i)}. - -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} -\begin{blockindent} -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. -\end{blockindent} - -\option{borderwidth}{borderWidth}{BorderWidth} -\begin{blockindent} - Specifies the width of the 3d border that should be displayed around the widget - window. This border does overlap the active 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}. -\end{blockindent} - -\option{confine}{confine}{Confine} -\begin{blockindent} - Specifies a boolean value that indicates whether or not it should be allowable - to set the TkZinc's view outside the region defined by the \optref{scrollregion}. - Defaults to true, which means that the view will be constrained within the scroll region. -\end{blockindent} - -\option{cursor}{cursor}{Cursor} -\begin{blockindent} - 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. -\end{blockindent} - -\option{font}{font}{Font} -\begin{blockindent} - The font specified by this option is used as a default font for item attributes of - type font. Its default value is {\tt -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*}. -\end{blockindent} - -\option{forecolor}{foreColor}{ForeColor} %% XXX CM Foreground ?! -\begin{blockindent} - The color specified by this option is used as a default color for many item color - attributes. See each each color attribute for the actual source of the default - color. Its default value is {\tt black}. -\end{blockindent} - -\option{fullreshape}{fullReshape}{FullReshape} -\begin{blockindent} - 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}. -\end{blockindent} - -\option{height}{height}{Height} -\begin{blockindent} - 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. -\end{blockindent} - -\option{highlightbackground}{highlightBackground}{HighlightBackground} -\begin{blockindent} - Specifies the color to display in the traversal highlight region when the - widget does not have the input focus. The default value is {\tt \#c3c3c3}. -\end{blockindent} - -\option{highlightcolor}{highlightColor}{HighlightColor} -\begin{blockindent} - Specifies the color to use for the traversal highlight rectangle that is drawn - around the widget when it has the input focus. The default value is {\tt black}. -\end{blockindent} - -\option{highlightthickness}{highlightThickness}{HighlightThickness} -\begin{blockindent} - Specifies a non-negative value indicating the width of the highlight rectangle - drawn around the outside of the widget when it has the input focus. The value may - have any of the forms acceptable to \cident{Tk\_GetPixels}. If the value is zero, - no focus highlight is drawn around the widget. The default value is {\tt 2}. -\end{blockindent} - -\option{insertbackground}{insertBackground}{InsertBackground} %% XXX CM Foreground ?! -\begin{blockindent} - Specifies the color to use as background in the area covered by the insertion - cursor. This color will normally override either the normal background for the - widget (or the selection background if the insertion cursor happens to fall in the - selection). The default value is {\tt black}. -\end{blockindent} - -\option{insertofftime}{insertOffTime}{InsertOffTime} %% XXX CM OffTime ?! -\begin{blockindent} - Specifies a non-negative integer value indicating the number of milliseconds the - insertion cursor should remain off in each blink cycle. If this option is zero - then the cursor is on all the time. The default value is {\tt 300}. -\end{blockindent} - -\option{insertontime}{insertOnTime}{InsertOnTime} %% XXX CM OnTime ?! -\begin{blockindent} - Specifies a non-negative integer value indicating the number of milliseconds the - insertion cursor should remain on in each blink cycle. The default value is {\tt 600}. -\end{blockindent} - -\option{insertwidth}{insertWidth}{InsertWidth} -\begin{blockindent} - Specifies a value indicating the width of the insertion cursor. The value may have - any of the forms acceptable to \cident{Tk\_GetPixels}. The default value is {\tt 2}. -\end{blockindent} - -\option{lightangle}{lightAngle}{LightAngle} -\begin{blockindent} - Specifies the lighting angle in degre used when displaying relief. The default value is {\tt 120}. %%% XXX CM to be completed! -\end{blockindent} - -\option{mapdistancesymbol}{mapDistanceSymbol}{MapDistanceSymbol} -\begin{blockindent} - This option specifies the symbol to be used as a milestone along map lines. This - option can be given any Tk bitmap which can be obtained by - \cident{Tk\_GetBitmap}. The spacing between markers is 10 nautic miles. The default - value is {\tt AtcSymbol19} (see \conceptref{Other resources provided by the widget}{otherresources}). -\end{blockindent} - -\option{maptextfont}{mapTextFont}{MapTextFont} -\begin{blockindent} - Specifies the font used to draw the texts contained in maps. The default is - {\tt -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*}. -\end{blockindent} - -\option{overlapmanager}{overlapManager}{OverlapManager} -\begin{blockindent} - This option accepts an item id. It specifies if the label overlapping avoidance - algorithm should be allowed to do its work on the track labels and which group - should be considered to look for tracks. The default is to enable the avoidance - algorithm in the root group (id 1). To disable the algorithm this option should - be set to {\tt 0}. -\end{blockindent} - -\option{pickaperture}{pickAperture}{PickAperture} -\begin{blockindent} - Specifies the size of an area around the pointer that is used to tell if the - pointer is inside an item. This is useful to lessen the precision required when - picking graphical elements. This value must be a positive integer. It defaults to - {\tt 1}. -\end{blockindent} - -\option{relief}{relief}{Relief} -\begin{blockindent} - Specifies the border relief. This option can be given any legal value for a relief - (See \attrtyperef{relief} for a description of possible values). The default - value is {\tt flat}. -\end{blockindent} - -\option{render}{render}{Render} -\begin{blockindent} - Specifies whether to use or not the openGL rendering. The value is - a positive integer that can have the values 0, 1 and 2. The value 0 - specifies a X11 rendering while the other two ask for an OpenGL - rendering and as such requires the GLX extension to the X server. - A value of 1 asks for direct OpenGL rendering which is the faster but - is limited to a local session with the display while a value of 2 - requests an indirect rendering which is slower but can be streamed - to a distant display (at least under X11). If a direct rendering - mode is requested but can't be achieved the indirect render mode - will be tried automatically. If neither OpenGL modes are available - the X11 mode is used as a fallback. - This option must be defined at widget creation time and is readonly - for the rest of the session. It can be used to ask if the widget is - drawing in OpenGL mode or in plain X mode (to adapt the - application code for example). The default value is {\tt 0}. -\end{blockindent} - -\option{reshape}{reshape}{Reshape} -\begin{blockindent} - 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}. -\end{blockindent} - -\option{scrollregion}{scrollRegion}{ScrollRegion} -\begin{blockindent} - Specifies a list with four coordinates describing the left, top, right, and bottom - coordinates of a rectangular region. This region is used for scrolling purposes and - is considered to be the boundary of the information in the TkZinc. -\end{blockindent} - -\option{selectbackground}{selectBackground}{SelectBackground} %% XXX CM Foreground ?! -\begin{blockindent} - Specifies the background color to use for displaying the selection in text - items. The default value is {\tt \#a0a0a0}. -\end{blockindent} - -\option{speedvectorlength}{speedVectorLength}{SpeedVectorLength} -\begin{blockindent} - Specifies the duration of track speed vectors. This option is expressed using a - time unit that should be chosen by the application (usually minutes) and kept - coherent with the unit of the track attribute \attributeref{track}{speedvector} (usually nautic - mile / minute). The default value is {\tt 3}. -\end{blockindent} - -\option{takefocus}{takeFocus}{TakeFocus} -\begin{blockindent} - (Slightly adapted from the Tk options manpage). - - Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and - Shift-Tab). Before setting the focus to a window, the traversal scripts consult the - value of the takeFocus option. A value of 0 means that the window should be skipped - entirely during keyboard traversal. 1 means that the window should receive the input - focus as long as it is viewable (it and all of its ancestors are mapped). An empty - value for the option means that the traversal scripts make the decision about whether or - not to focus on the window: the current algorithm is to skip the window if it is - disabled, if it has no key bindings, or if it is not viewable. If the value has any - other form, then the traversal scripts take the value, append the name of the window to - it (with a separator space), and evaluate the resulting string as a callback. The - script must return 0, 1, or an empty string: a 0 or 1 value specifies whether the window - will receive the input focus, and an empty string results in the default decision - described above. \emph{Note: this interpretation of the option is defined entirely by - the callbacks (part of the keyboard traversal scripts) that implement traversal; the - widget implementations ignore the option entirely, so you can change its meaning if you - redefine the keyboard traversal scripts.} - The default value is empty. -\end{blockindent} - -\option{tile}{tile}{Tile} -\begin{blockindent} - Specifies an image name to be used as a tile for painting the TkZinc window - background. The default value is {\tt ""} (the empty string). -\end{blockindent} - -\option{trackmanagedhistorysize}{trackManagedHistorySize}{TrackManagedHistorySize} -\begin{blockindent} - This option accepts only positive integers. It specifies the number of positions - collected in the history list by the track items. When this many positions have - been collected, the oldest is dropped to make room for a new one on a first-in - first-out basis. See also the \optref{trackvisibehistorysize} option and the - \attributeref{track}{historyvisible} track attribute. The default value is {\tt 6}. -\end{blockindent} - - -\option{trackvisiblehistorysize}{trackVisibleHistorySize}{TrackVisibleHistorySize} -\begin{blockindent} - This option accepts only positive integers. It specifies the number of - past positions to display for tracks. It is a widget wide control. Users - of previous releases used the {\tt -visiblehistorysize} track attribute - for the same effect. The number of past positions displayed can not exceed - the accumulated positions controlled by the option \optref{trackmanagedhistorysize}. - The track \attributeref{track}{historyvisible} attribute controls whether - a track should display its history. The default value is {\tt 6}. -\end{blockindent} - - -\option{tracksymbol}{trackSymbol}{TrackSymbol} -\begin{blockindent} - Specifies the symbol displayed at the current position of a track. This option - accepts a \attrtyperef{bitmap}. The default value is {\tt AtcSymbol15}. -\end{blockindent} - - -\option{xscrollcommand}{xScrollCommand}{ScrollCommand} -\begin{blockindent} - Specifies a callback used to communicate with horizontal scrollbars. When - the view in the widget's window changes (or whenever anything else occurs - that could change the display in a scrollbar, such as a change in the total - size of the widget's contents), the widget will make a callback passing two - numeric arguments in addition to any specified in the callback. Each of the - numbers is a fraction between 0 and 1, which indicates a position in the - document. 0 indicates the beginning of the document, 1 indicates the end, - .333 indicates a position one third the way through the document, and so on. - The first fraction indicates the first information in the document that is - visible in the window, and the second fraction indicates the information - just after the last portion that is visible. Typically the xScrollCommand - option consists of the scrollbar widget object and the method ``set'' i.e. - [set => \$sb]: this will cause the scrollbar to be updated whenever the view - in the window changes. If this option is not specified, then no command - will be executed. -\end{blockindent} - -\option{xscrollincrement}{scrollincrement}{xScrollIncrement} -\begin{blockindent} - Specifies an increment for horizontal scrolling. If the value of this option - is greater than zero, the horizontal view in the window will be constrained - so that the TkZinc x coordinate at the left edge of the window is always an - even multiple of {\tt xScrollIncrement}; furthermore, the units for scrolling - (e.g., the change in view when the left and right arrows of a scrollbar are - selected) will also be {\tt xScrollIncrement}. If the value of this option - is less than or equal to zero, then horizontal scrolling is unconstrained. -\end{blockindent} - -\option{yscrollcommand}{yScrollCommand}{ScrollCommand} -\begin{blockindent} - Specifies a callback used to communicate with vertical scrollbars. This option - is treated in the same way as the xScrollCommand option, except that it is used - for vertical scrollbars and is provided by widgets that support vertical - scrolling. See the description of xScrollCommand for details on how this option is used. -\end{blockindent} - -\option{yscrollincrement}{scrollincrement}{yScrollIncrement} -\begin{blockindent} - Specifies an increment for vertical scrolling. If the value of this option - is greater than zero, the vertical view in the window will be constrained - so that the TkZinc y coordinate at the left edge of the window is always an - even multiple of {\tt yScrollIncrement}; furthermore, the units for scrolling - (e.g., the change in view when the top and bottom arrows of a scrollbar are - selected) will also be {\tt yScrollIncrement}. If the value of this option - is less than or equal to zero, then vertical scrolling is unconstrained. -\end{blockindent} - -\option{width}{width}{Width} -\begin{blockindent} - 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. -\end{blockindent} - - - -%% -%% -%% C h a p t e r : G r o u p s , D i s p l a y l i s t s , C l i p p i n g -%% -%% -\chapter{Groups, Display lists, Clipping and Transformations} -\concept{coordinates} - -Groups are very powerful items. They have no graphics of their own but are used to -bundle items together so that they can be manipulated easily as a whole. Groups can -modify in several way how items are displayed and how they react to events. They have -many uses in 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} {\tt 'enclosed'/'overlapping'} or -\cmdref{addtag} {\tt 'enclosed'/'overlapping'} {\bf act differently on an atomic group}. -Such search command will not traverse an atomic group. So if a part of the atomic -group is enclosed or overlapping, the search command will return the atomic group -and not its part. - -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 top-most 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. - \objectref{map} and \objectref{reticle} default priority is 0. \objectref{window} - item attribute is meaningless. All other items default priority is 1. -\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{Event sensitivity} - -An item will catch an event if all the following conditions are satisfied: -\begin{itemize} -\item - the item \ident{-sensitive} must be set to true (this is the default). -\item - the item must be under the pointer location. -\item - the item must be on top of the display list (at the pointer location). Beware - that an other item with its \ident{-visible} set to false DOES catch event - before any underneath items. -\item - the item must not be clipped (at the pointer location) -\item - the item must not belong to an atomic group, since an atomic group catchs the event - instead of the item. -\end{itemize} - -An item satisfying all the above conditions can have its \ident{-visible} set -to false, or can be fully transparent (when using openGL). It will still catch -the events. - - -\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} , \cmdref{skew} can be -used to modify this relationship to the effect of translating, enlarging, shrinking, -rotating or skewing the item. It must be emphasized that those commands act on the -relation between two coordinate spaces, \emph{not} on the item geometry itself. -If the goal is to change the item (except for groups, see next paragraph) geometry, -the command \cmdref{coords} may be more appropriate (but see below the command -\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. For the developper convenience, the \cmdref{coords} -method on a group change its transformation. It defines the absolute translation -applied to the 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 factorization example. - -In fact, transformation are so useful that a whole set of functions are available -to help use them in full. Apart from the already mentioned \cmdref{translate}, -\cmdref{scale}, \cmdref{rotate}, and \cmdref{skew} commands, it is also possible -to restore a transformation to its initial state, identity, with the -\cmdref{treset} command. -It is also possible to compose a transformation with another name transform with -the \cmdref{tcompose} command. - -An item transformation can be saved under a name, in fact creating -a named transformation which can be manipulated just as an item transformation (i.e -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. - -A predefined named transformation exists. Its name is \ident{identity} and refers to the -identity transform. it can not be modified by the user. - -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 (only on X11 system. Does not work on windows -systems). 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. This -requires both the SHAPE X11 extension and a compliant Window Manager (fvwm is known -to support non rectangulaire top windows). The clipping form should have a bounding box -with the same ratio as the topwindow or some normalisation will occur. 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. - -A demo called ``Using pathTags'' in zinc-demos may help you better understand pathTags. -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{chggroup} \cmdref{configure} -\cmdref{coords} \cmdref{gettags} \cmdref{group} \cmdref{itemcget} \cmdref{itemconfigure} - -\item{Accessing field attributes of track, waypoint and tabular} : \cmdref{currentpart} -\cmdref{hasfields} \cmdref{itemcget} \cmdref{itemconfigure} \cmdref{numparts} - -\item{Transformations} : \cmdref{coords} \cmdref{rotate} \cmdref{scale} \cmdref{skew} \cmdref{tapply} -\cmdref{tcompose} \cmdref{tdelete} \cmdref{tget} \cmdref{transform} \cmdref{translate} \cmdref{treset} -\cmdref{tsave} \cmdref{tset} - -\item{Groups, Display list and Priorities} : \cmdref{chggroup} \cmdref{find}('ancestors') \cmdref{group} \cmdref{lower} -\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{hasanchor} \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 false the search is limited to - the starting group. If set to true, not specified or ``override'', - the search proceed from the starting group down the hierarchy - rooted at this group. ``override'' forces the search to explore - atomic groups and report the most specific item instead of the - group itself. - - \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. {\tt inGroup} specifies - a group to start with instead of the root group. - If {\tt recursive} is false the search is limited to - the starting group. If set to true, not specified or ``override'', - the search proceed from the starting group down the hierarchy - rooted at this group. ``override'' forces the search to explore - atomic groups and report the most specific item instead of the - group itself. - - 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. {\tt inGroup} specifies - a group to start with instead of the root group. - If {\tt recursive} is false, the search is limited to the starting - group. If set to true, not specified or ``override'', - the search proceed from the starting group down the hierarchy - rooted at this group. ``override'' forces the search to explore - atomic groups and report the most specific item instead of the - group itself. - - 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}{?-field fieldNo? ?-label? tagOrId ?tagOrId ...?} - -{\tt\large (\$xo, \$yo, \$xc, \$yc) = \\ -\$zinc->{\bf bbox}(?-field fieldNo? ?-label? 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 {\tt tagOrId} or if the matching items have an empty bounding - box, an empty string is returned. - The {\tt -field} and {\tt -label} options can be used to query the bounding box - of an item's field or an item's label. These two options are mutually exclusives. - When one of these options is specified, the bbox command is applied to the first - item selected by the tagOrId arguments. If no labelformat has been set for the item, - bbox will return an empty array. -\end{blockindent} - - -\zinccmd{becomes}{} - -{\tt\large \$zinc->{\bf becomes}();} - -\begin{blockindent} - Not yet implemented. -\end{blockindent} - - -\zinccmd{bind}{tagOrId ?part? ?sequence? ?command?} - -{\tt\large @bindings = \$zinc->{\bf bind}(tagOrId, ?part?);}\\ -{\tt\large @binding = \$zinc->{\bf bind}(tagOrId, ?fpart?, sequence);}\\ -{\tt\large \$zinc->{\bf bind}(tagOrId, ?part?, sequence, '');}\\ -{\tt\large \$zinc->{\bf bind}(tagOrId, ?part?, sequence, command);} - -\begin{blockindent} - This command associates {\tt command} with the item tag, item id, part tag {\tt - 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. - - Two syntaxes are available for addressing item parts (for items having part ie. - \objectref{track} \objectref{waypoint} and \objectref{tabular}): either an Id - of the following form: {\tt id:part} or by using the optionnal {\tt part} argument. - - If bindings have been registered for the widget window using the \ident{bind} command, - they are invoked in addition to bindings registered for the items using this widget - command. The bindings for items will be invoked before the bindings for the window. -\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 the - item is a group, query or set the translation applied to the group. 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 potentially more than one point, it returns {\bf always} - a list of lists. Each sub list contains X, Y, and 'c' if the point is a - bezier control point. - - When {\tt coords} is used to get exactly one point (either because it is used to - get the nth point of an item or because the item always has exactly one point (e.g. - the item is a group, track, waypoint, map, or reticle)), it returns - a flat list of 2 (or may be 3 for control points of curve items) values. - - 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 recursively 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} 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? ?itemPart?} - -{\tt\large (\$item, \$part) = \$zinc->{\bf focus}();}\\ -{\tt\large \$zinc->{\bf focus}(tagOrId, ?itemPart?);} - -\begin{blockindent} - Set the keyboard focus to the item described by {\tt tagOrId}, and to - its {\tt itemPart} if the item has parts. 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 hasanchors}(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 ?degree? ?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 radian if {\tt degree} is omitted or false, if it is - specified as true, the angle is in degrees. The last two optional parameters describe - the center of rotation, which defaults to the origin. -\end{blockindent} - - -\zinccmd{scale}{tagOrIdOrTName xFactor yFactor ?centerX centerY?} - -{\tt\large \$zinc->{\bf scale}(tagOrIdOrTName, xFactor, yFactor);}\\ -{\tt\large \$zinc->{\bf scale}(tagOrIdOrTName, xFactor, yFactor, centerX, centerY);} - -\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. The optional parameters - describe the center of scaling, which defaults to the origin. -\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{skew}{tagOrIdOrTName xSkewAngle ySkewAngle} - -{\tt\large \$zinc->{\bf skew}(tagOrIdOrTName, xSkewAngle, ySkewAngle);} - -\begin{blockindent} - Add a skew (or shear) transform to the to the items or the transform described - by {\tt tagOrIdOrTName}. If {\tt tagOrId} describes a named transform then this - transform is used to do the operation. If {\tt tagOrId} describes more than - one item then all the items are affected by the operation. - If {\tt tagOrId} describes neither a named transform nor an item, an - error is raised. The angles are given in radian. -\end{blockindent} - - -\zinccmd{smooth}{coordList} - -{\tt\large @coords = \$zinc->{\bf smooth}(coordList);} - -\begin{blockindent} - This command computes a sequence of segments that will smooth the polygon - described by the vertices in {\tt coordList} and returns a list of lists describing - points of the generated segments. These segments are approximating a Bezier 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 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{tcompose}{tagOrIdOrTName tName ?invert?} - -{\tt\large \$zinc->{\bf tcompose}(tagOrIdOrTName, tName);}\\ -{\tt\large \$zinc->{\bf tcompose}(tagOrIdOrTName, tName, invert);} - -\begin{blockindent} - Modify either the named transform {\tt tagOrIdOrTName} or the corresponding - item by composing the {\tt tName} transform. The {\tt invert} boolean, if specified, - causes the {\tt tName} transform to be inverted prior composition. - - If {\tt tagOrIdOrTName} describes neither a named transform nor an item, an error is - raised. If {\tt tName} does not describe a named transform an error is raised. -\end{blockindent} - - -\zinccmd{tdelete}{tName} - -{\tt\large \$zinc->{\bf tdelete}(tName);} - -\begin{blockindent} - Destroy a named transform. If the given name is not found among the named transforms, an - error is raised. -\end{blockindent} - - -\zinccmd{tget}{tagOrIdOrTName ?selector?} - -{\tt\large (\$m00, \$m01, \$m10, \$m11, \$m20, \$m21) = \$zinc->{\bf tget}(tagOrIdOrTName);}\\ -{\tt\large (\$xtranslate, \$ytranslate, \$xscale, \$yscale, \$angle, \$xskew) =\\ - \$zinc->{\bf tget}(tagOrIdOrTName, 'all');}\\ -{\tt\large (\$xtranslate, \$ytranslate) = \$zinc->{\bf tget}(tagOrIdOrTName, 'translate');}\\ -{\tt\large (\$xscale, \$yscale) = \$zinc->{\bf tget}(tagOrIdOrTName, 'scale');}\\ -{\tt\large (\$angle) = \$zinc->{\bf tget}(tagOrIdOrTName, 'rotate');}\\ -{\tt\large (\$xskew) = \$zinc->{\bf tget}(tagOrIdOrTName, 'skew');} - -\begin{blockindent} - With only one argument, get the six elements of the 3x4 matrix used in affine - transformation for {\tt tagOrIdOrTName}. The result is compatible with the tset method. - With optional second parameter 'all' returns the transform decomposed in translation, - scale, rotation, skew and return the list in this order, - With 'translation', 'scale', 'rotation', 'skew' optional second parameter, - returns the corresponding values. -\end{blockindent} - - -\zinccmd{transform}{?tagOrIdFrom? tagOrIdTo coordList} - -{\tt\large @coords = \$zinc->{\bf transform}(tagOrIdTo, coordList);}\\ -{\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 can also be done by using the predefined tag 'device' as first argument. - - It is also possible to convert from the coordinate space of an item to the window - coordinate space by using the predefined tag 'device' as second argument. - - For example: - - \begin{itemize} - \item{\verb+($x, $y) = $zinc->transform('device', $mygroup, [$xdev, $ydev]);+}\\ - transforms the point described by \verb+$xdev,$ydev+ in window coordinates, - to \verb+$mygroup+ coordinates in \verb+$x,$y+; - \item{\verb+($xdev, $ydev) = $zinc->transform($mygroup, 'device', [$x, $y]);+}\\ - transforms the point described by \verb+$x,$y+ in \verb+$mygroup+ - coordinates, to window coordinates in \verb+$xdev,$ydev+ - \item{\verb+($x2, $y2) = $zinc->transform($group1, $group2, [$x1, $y1]);+}\\ - transforms the point described by \verb+$x1,$y1+ in \verb+$group1+ coordinates, - to \verb+$group2+ coordinates in \verb+$x2,$y2+;%$ - \end{itemize} -\end{blockindent} - - -\zinccmd{translate}{tagOrIdOrTName xAmount yAmount ?absolute?} - -{\tt\large \$zinc->{\bf translate}(tagOrdIdOrTName, xAmount, yAmount, ?absolute?);} - -\begin{blockindent} - Add a translation to the items or the transform described by {\tt tagOrIdOrTName}. If {\tt - tagOrIdOrTName} describes a named transform then this transform is used to do the operation. If - {\tt tagOrIdOrTName} describes more than one item then all the items are affected by the - opration. If {\tt tagOrIdOrTName} describes neither a named transform nor an item, an error is - raised. A separate value is specified for X and Y. - If the optionnal {\tt ?absolute?} parameter is true, it will set an absolute translation to - the {\tt tagOrIdOrTName} -\end{blockindent} - - -\zinccmd{treset}{tagOrIdOrTName} - -{\tt\large \$zinc->{\bf treset}(tagOrdIdOrTName);} - -\begin{blockindent} - Set the named transform or the transform for the items described by {\tt tagOrIdOrTName} to - identity. If {\tt tagOrIdOrTName} 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}{?tagOrIdOrTName? tName ?invert?} - -{\tt\large \$zinc->{\bf tsave}(tName);}\\ -{\tt\large \$zinc->{\bf tsave}(tagOrdIdOrTName, tName);}\\ -{\tt\large \$zinc->{\bf tsave}(tagOrdIdOrTName, tName, invert);} - -\begin{blockindent} - Create (or reset) a transform associated with the name {\tt tName} with initial - value the transform associated with the item {\tt tagOrIdOrTName}. If {\tt tagOrIdOrTName} describes - more than one item, the topmost in display list order is used. If {\tt tagOrIdOrTName} doesn't - describe any item or named transformation, an error is raised. If {\tt tName} already exists, - the transform is set to the new value. This command is the only way to create a named transform. - If {\tt tagOrIdOrTName} is not specified, the command returns a boolean telling if the - name is already in use. The {\tt invert} boolean, if specified, cause the transform - to be inverted prior to be saved. - - It is possible to create a new named transformation from the identity by using the predefined tag 'identity': {\verb+$zinc->tsave('identity', 'myTransfo');+} -% $ this comment is for emacs colorization only! -\end{blockindent} - -\zinccmd{tset}{tagOrIdOrTName m00 m01 m10 m11 m20 m21} - -{\tt\large \$zinc->{\bf tset}(tagOrIdOrTName, m00, m01, m10, m11, m20, m21);} - -\begin{blockindent} - Set the six elements of the 3x4 matrix used in affine transformation for - {\tt tagOrIdOrTName}. \bf{ BEWARE that depending on mij values, it is possible - to define a not inversible matrix which will end up in core dump. This - method must BE USED CAUTIOUSLY. } -\end{blockindent} - - -\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 1}.} - -\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 characteristics 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 characteristics 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 characteristics can be configured. The marker is never -sensitive. -\item a {\bf connection}, which is a link with another track or waypoint item; links are -drawn between their {\bf current position}. This connection may be visible or not, -sensitive or not, and other graphic characteristics 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 TkZinc attribute \optref{overlapmanager}. -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}. - -Track items can be linked together or to waypoint items. The line figuring the link -is configurable. - -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 \ident{track} or \ident{waypoint} 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 \attributeref{track}{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 \attributeref{track}{labeldx} and -\attributeref{track}{labeldy} methods. Simultaneous use of the two methods should be done with care as -there is no automatic update of values from the \attributeref{track}{labeldx}, -\attributeref{track}{labeldy} set to the \attributeref{track}{labeldistance}, -\attributeref{track}{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 \attributeref{track}{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 \attributeref{track}{labeldistance} and -\attributeref{track}{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 \attributeref{track}{labeldistance} and -\attributeref{track}{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 attachment of the leader on the label -left or right side (whether the label is on the right or left of the current position). -The default value is {\tt ""} which means that the leader anchor is at the label -center, whatever the label position.} - -\attribute{track}{leadercolor}{gradient}{The uniform (possibly transparent) color of the label -leader. The first color of a real gradient color will be used. The default -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 1}.} - -\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 the current value of the widget option \optref{tracksymbol}.} - -\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}{historyvisible}{boolean}{Specifies whether the item should display -its history according to the options \optref{trackvisiblehistorysize} and -\optref{trackmanagedhistorysize}. The default value is {\tt true}.} - - -\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 characteristics 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 \ident{waypoint} or \ident{track} item. -This connection may be visible or not, sensitive or not, and other graphic characteristics -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 \ident{track} or \ident{waypoint} 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 \attributeref{track}{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 -\attributeref{track}{labeldx} and \attributeref{track}{labeldy} methods. Simultaneous use -of the two methods should be done with care as there is no automatic update of values from the -\attributeref{track}{labeldx}, \attributeref{track}{labeldy} set to the -\attributeref{track}{labeldistance}, \attributeref{track}{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 \attributeref{waypoint}{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 attachment of the leader on the label -left or right side (whether the label is on the right or left of the current position). -The default value is {\tt ""} which means that the leader anchor is at the label -center, whatever the label position.} - -\attribute{waypoint}{leadercolor}{gradient}{The uniform (possibly transparent) color of the -label leader. The first color of a real gradient color will be used. The -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 1}.} - -\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}. -A tabular can be attached with the \attributeref{tabular}{connecteditem} attribute to the -label of a \objectref{track}, \objectref{waypoint} or another \objectref{tabular}. - -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 The \ident{track}, \ident{waypoint} or -\ident{tabular} item relative to which this item is -placed. Connected item should be in the same group. 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 1}. } - -\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}). - -With and without openGL, text items can be rotated or scaled. However, -attributes \attributeref{text}{composerotation} and \attributeref{text}{composescale} -must be set before rotation and scaling. - -A Tcl module, zincText is available, it provides simple bindings for interactive -text input. For enabling interactive text editing on an item, the item should -be sensitive and should have the tag ``text''. - -A Perl module, called Tk::Zinc::Text (see the section -\conceptref{Tk::Zinc::Text}{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 false}.} - -\attribute{text}{composescale}{boolean}{Specifies if the current scale should be composed -with the local transform. The default value is {\tt false}.} - -\attribute{text}{connecteditem}{item}{Specifies the item relative to which this item is -placed. Connected item should be in the same group. 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 1}.} - -\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 and without openGL, icons can be rotated or scaled. However, -attributes \attributeref{icon}{composerotation} and \attributeref{icon}{composescale} -must be set before rotation and scaling. - -Applicable attributes for \ident{icon} are: - -\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. If -The icon contains an image, only the transparency of the color is used and -defines the alpha transparency of the image when \optref{render} is set to true. -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}.} - -\attribute{icon}{composescale}{boolean}{Specifies if the current scale should be composed -with the local transform. The default value is {\tt false}.} - -\attribute{icon}{connecteditem}{item}{Specifies the item relative to which this item is -placed. Connected item should be in the same group. The default value is {\tt ""}.} - -\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 1}.} - -\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 0}.} - -\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 0}.} - -\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 1}.} - -\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 1}.} - -\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 pathes of line segments and/or cubic bezier connected - by their end points. A cubic Bezier is defined by four points. The first and last - ones are the extremities of the cubic Bezier. The second and the third ones are control point - (i.e. they must have a third ``coordinate'' with the value 'c'). If both control points - are identical, one may be omitted. As a consequence, it is an error to have more than - two succcessive control points or to start or finish a curve with a control point. - - 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 false}.} - -\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 1}.} - -\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 1}.} - -\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. Connected item should be in the same group. 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 system 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',1, 4, ....); - # this creates a track item in root group with 4 fields, indexed from 0 to 3 -\end{verbatim} -% $ comment for emacs colorization only! -\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::Zinc::Text (see the section \conceptref{Tk::Zinc::Text}{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 characteristic 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}. - - {\bf Please note, that some font data are cached by TkZinc, on the application level. - This is specially usefull with openGL}. To avoid breaking the cache mecanism, you - should avoid using a font once on only one item, then modifiy this item font - and repeat this again and again. -\end{blockindent} - -\attrtype{gradient} -\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 optionnal alpha percentage. - - The string may consist in a single color specification that will be used to paint a solid surface - or a color with an alpha value or a list of gradient steps separated by \verb+|+ characters. - - \begin{itemize} - \item The general pattern for an axial gradient is : - - \verb+"=axial degre | gradient_step1 | ... | gradient_stepn"+ or - - \verb+"=axial x1 y1 x2 y2 | gradient_step1 | ... | gradient_stepn"+ - - The \verb+degre+ parameter defines the angle of the axe in the usual - trigonometric sense. It defaults to 0. The \verb+x1 y1 x2 y2+ parameters - define both the angle and the extension of the axe. - - - \item The general pattern for a radial gradient is : - - \verb+"=radial x y | gradient_step1 | ... | gradient_stepn"+ or - - \verb+"=radial x1 y1 x2 y2 | gradient_step1 | ... | gradient_stepn"+ - - The \verb+x y+ parameters define the center of the radial. The \verb+x1 y1 x2 y2+ - parameters define both the center and the extension of the radial. - - - \item The general pattern for a path gradient is : - - \verb+"=path x y | gradient_step1 | ... | gradient_stepn"+ - - The \verb+x y+ parameters define the center of the gradient. - - - \item The general pattern for a conical gradient is : - - \verb+"=conical degre | gradient_step1 | ... | gradient_stepn"+ or - - \verb+"=conical degre x y | gradient_step1 | ... | gradient_stepn"+ or - - \verb+"=conical x1 y1 x2 y2 | gradient_step1 | ... | gradient_stepn"+ - - The \verb+degre+ parameter defines the angle of the cone in the usual - trigonometric sense. The optional \verb+x y+ parameters define the center of - the cone. By default, it is the center of the bounding-box. - The \verb+x1 y1 x2 y2+ parameters define the center and the angle of the cone. - - \end{itemize} - - All x and y coordinates are expressed in percentage of the bounding box, relatively - to the center of the bounding box. So \verb+0 0+ means the center while \verb+-50 -50+ - means the lower left corner of the bounding box. - - 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;alpha color_position mid_span_position+ - - Each color can be specified as a valid X color : either a named color or \#rrggbb value - or any valid X color specification such as standard device-independent color specification - (e.g. \verb+CIEuvY:<u>/<v>/<Y>+ as defined in the X man page). An alpha value - can be applied to the color using the optional \verb+;alpha+ parameter whose value should be in the - 0..100 intervalle. - - 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, the 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 : '=axial 0 | black|white' := 'black|white'+ - -\verb+axial 2 : '=axial 90 | black|white'+ - -\verb+axial 3 : '=axial 30 |black|white'+ - -\verb+axial 4 : '=axial 30|black|black;0'+ - -\verb+radial 1 : '=radial -14 -20|white|black'+ - -\verb+radial 2 : '=radial 0 0 | white;50 0 70|black 50|white 100'+ - -\verb+path 1 : '=path -14 -20|white|black;80'+ - -\verb+path 2 : '=path -14 -20 |white|white 30|black;80'+ - -\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 Tcl-Tk only GIF, PPM - and bitmap formats are available as source for images. With the Img extension many - others popular formats are added including JPEG, XPM and PNG. - - In Perl/Tk most image formats can be used, specially with Tk::JPEG or Tk::PNG modules. - - {\bf Please note, that some image data are cached by TkZinc, on the application level. - This is specially usefull with openGL}. To avoid breaking the cache mecanism, you - should avoid using an image once on only one item option, then modifiy this item option - and repeat this again and again. - -\end{blockindent} - -\attrtype{item} -\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 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. - The global size of the label is considered when the labelformat is set. If some fields - sizes change afterwards, you should set again the labelformat so that fields using - a \verb+'l'+ specification are re-computed. - 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. Two positions can be defined: one - when the label is at the right of current position and the other when the label is at the - left of current position. {\bf Not to be confused with the regular rectangular anchors}. - - The format is: \verb+lChar leftLeaderAnchor [lChar rightLeaderAnchor]+ - - 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. The format is the - binary cautra4 (with x and y in 1/8nm units) - -\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{Tk::Zinc::Debug Perl module} - -\ident{Tk::Zinc::Debug.pm} is a Perl module useful for debugging purpose. It can be used in a -Perl application using TkZinc to display the hierarchical tree of items, to display -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{Tk::Zinc::Debug.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{Tk::Zinc::Debug.pm} man pages with the classical command {\tt man Tk::Zinc::Debug} - -To use this module, you can import it either by adding, for example, the following -statements in your source code: -\code{\\use Tk::Zinc::Debug;\\ -finditems(\$zinc);\\ -tree(\$zinc, -optionsToDisplay => '-tags', -optionsFormat => 'row');\\} -or simply by using the -M option of Perl: -\code{\\perl -MTk::Zinc::Debug yourscript.pl\\} - -\section{Tracing TkZinc methods call in Perl/Tk} - -TkZinc package includes two tools for helping you debugging your Perl/Tk scripts -or tracking some nasty segfault which should never occure since TkZinc is -(almost) totally bugfree. - -\subsection{Tracking Perl/Tk script errors} - -Because you sometime 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 the error. There is a simple and convenient mean to do this, just -by using a small module called \ident{Tk::Zinc::TraceErrors}, released with \ident{TkZinc}. -It traces every call of a TkZinc method inducing a Tk error. It prints on -the standard output the following informations: -\begin{itemize} -\item the filename where the method has been invoked -\item the line number in the source file -\item the TkZinc method name -\item the list of arguments in a human-readable form -\item the error message -\end{itemize} - -To use this module you can import it either by adding the following -statement in your source code: -\code{\\use Tk::Zinc::TraceErrors;\\} or better, by using the -M option of Perl: -\code{\\perl -MTk::Zinc::TraceErrors yourscript.pl\\} - -\subsection{Tracking TkZinc segfaults in Perl/Tk} - -If you encounters a segfault in one Perl/Tk script and you suspects -that TkZinc might be responsible, you should use a small module called -\ident{Tk::Zinc::Trace}, released with \ident{TkZinc}. -It traces every call of a TkZinc method. The method call is printed -on the standard output before the effective call, and the -result of the invokation is printed after the call. To be sure -to identify a segfault at the proper time, it forces an update of TkZinc -widget. Thus, this might slow down your script, but should dramatically -speed up the identification of the call which makes TkZinc segfaulting. -It prints on the standard output the following informations: -\begin{itemize} -\item the filename where the method has been invoked -\item the line number in the source file -\item the TkZinc method name -\item the list of arguments in a human-readable form -\item the returned value -\end{itemize} - -To use this module you can import it either by adding the following -statement in your source code: -\code{\\use Tk::Zinc::Trace;\\} or better, by using the -M option of Perl: -\code{\\perl -MTk::Zinc::Trace 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{Tk::Zinc::Graphics Perl module} -\concept{zincGraphics} - -The Tk::Zinc::Graphics Perl module implements many high level functions for -building high quality graphic objects with TkZinc. - -Please read the man page for more details: {\tt man Tk::Zinc::Graphics}, french -version only currently. Any volontear to translate it in English? - -NB: There is also a tcl version of this module. - -\section{Tk::Zinc::Text Perl module} -\concept{zinctext} - -The Tk::Zinc::Text Perl module implements bindings for text input 'a la emacs'. -It works for text item or for text fields of track, waypoint or tabular items. -The item which requires text input must just be tagged with the 'text' tag. - -Please read the man page for more details: {\tt man Tk::Zinc::Text} - -\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} |