diff options
| -rw-r--r-- | doc/refman.tex | 547 |
1 files changed, 460 insertions, 87 deletions
diff --git a/doc/refman.tex b/doc/refman.tex index 3a515cd..59a3573 100644 --- a/doc/refman.tex +++ b/doc/refman.tex @@ -1,9 +1,44 @@ \documentclass[11pt,twoside]{book} + +\newif\ifpdf +\ifx\pdfoutput\undefined + \pdffalse % we are not running PDFLaTeX +\else + \pdfoutput=1 % we are running PDFLaTeX + \pdftrue +\fi +%---------------------------------------------------------------------- + +\ifpdf + \usepackage[pdftex, + colorlinks=true, + urlcolor=rltblue, + anchorcolor=rltbrightblue, + filecolor=rltgreen, + linkcolor=rltred, + menucolor=webdarkblue, + citecolor=webbrightgreen, + pdftitle={Zinc, an advanced scriptable Canvas.}, + pdfauthor={Patrick Lecoanet, Centre d'étude de la Navigation Aérienne}, + pdfsubject={The 3.2 Reference Manual.}, + pdfkeywords={tk tcl perl x11 canvas opengl script gui zinc}, + pagebackref, + pdfpagemode=None, + bookmarksopen=true + ]{hyperref} + \pdfcompresslevel=9 + \usepackage[pdftex]{graphicx} + \usepackage{thumbpdf} +\else + \usepackage{graphicx} + \usepackage{html} +\fi \usepackage{a4wide} -\usepackage{html} \usepackage{makeidx} -\usepackage{graphicx} - +\usepackage{color} +\definecolor{rltred}{rgb}{0.75,0,0.20} +\definecolor{rltgreen}{rgb}{0,0.5,0} +\definecolor{rltblue}{rgb}{0,0,0.75} \newcommand{\cident}[1] {% {\tt #1}} @@ -19,7 +54,11 @@ \newcommand{\option}[3]{% \label{opt:#1} \index{#1} + \ifpdf + \hyperdef{opt}{#1}{} + \else \htmlrule[WIDTH="300" left] + \fi \begin{tabular}{rl} Command line switch: & \ident{-#1} \\ Database name: & \ident{#2} \\ @@ -29,7 +68,11 @@ \newcommand{\command}[3]{% \label{cmd:#2} \index{#2} + \ifpdf + \hyperdef{cmd}{#2}{} + \else \htmlrule[WIDTH="300" left] + \fi {\tt\large #1 {\bf #2} #3}} \newcommand{\zinccmd}[2]{% @@ -38,47 +81,96 @@ \newcommand{\mapinfocmd}[3]{% \label{mpcmd:#2} \index{#2} + \ifpdf + \hyperdef{mapcmd}{#2}{} + \else \htmlrule[WIDTH="300" left] + \fi {\tt\large mapinfo #1 {\bf #2} #3}} \newcommand{\attrtype}[1]{% \label{attrtype:#1} \index{#1} + \ifpdf + \hyperdef{attrtype}{#1}{} + \else \htmlrule[WIDTH="300" left] + \fi {\tt {\bf #1}} \vspace{-2\parskip}} \newcommand{\available}[1]{% - \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{obj:#1}} + \ifpdf + \hyperlink{obj.#1}{\ident{#1}} + \else + \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{obj:#1} + \fi + } -\newcommand{\optref}[1]{% +\newcommand{\refopt}[1]{% + \ifpdf + \hyperlink{opt.#1}{\ident{#1}} + \else \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{opt:#1} + \fi } \newcommand{\cmdref}[1]{% \index{#1} + \ifpdf + \hyperlink{cmd.#1}{\ident{#1}} + \else \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{cmd:#1} + \fi } \newcommand{\attribute}[3]{% - \ident{-#1} \hyperref[no]{\tt \bf #2}{\ident{#1}}{attrtype:#2} + \label{attribute:#1} + \ident{-#1 }% + \ifpdf% + \hyperlink{attrtype.#2}{\ident{#2}} + \else% + \hyperref[no]{\tt \bf #2}{\ident{#2}}{attrtype:#2}% + \fi% \begin{quotation}#3\end{quotation} } +\newcommand{\attributeref}[1]{% + \ifpdf% + \hyperlink{attribute.#1}{\ident{-#1}} + \else% + \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{attribute:#1} + \fi% + } + \newcommand{\object}[1]{% \label{obj:#1} + \ifpdf + \hyperdef{obj}{#1}{} + \fi } \newcommand{\concept}[1]{% \label{concept:#1} + \ifpdf + \hyperdef{concept}{#1}{} + \fi } \newcommand{\objectref}[1]{% + \ifpdf + \hyperlink{obj.#1}{\ident{#1}} + \else \hyperref[page]{\ident{#1}}{\ident{#1} (}{)}{obj:#1} + \fi } \newcommand{\conceptref}[2]{% + \ifpdf + \hyperlink{concept.#2}{\ident{#1}} + \else \hyperref[page]{#1}{#1 (page }{)}{concept:#2} + \fi } @@ -88,22 +180,129 @@ \parindent 0cm \parskip 0.2cm -\title{Zinc reference manual\\Version 3.0} +\title{Zinc, an advanced scriptable Canvas.\\The 3.2 Reference Manual.} \author{Patrick Lecoanet} -\date{21 Sep 2000} +\date{8 March 2002} \begin{document} +\DeclareGraphicsExtensions{.png,.ps,.eps,.pdf} + \maketitle +\tableofcontents + +\concept{introduction} +\chapter{Introduction} + +\section{What is this document about?} + This reference manual describes the Tk \ident{zinc} widget interface. It shows how to create and configure a \ident{zinc} widget, and how to use the commands -it provides to create and manipulate items. +it provides to create and manipulate items. As the \ident{zinc} widget is very similar +to the Tk canvas widget, this document is structured in a very similar way. The next chapter +\conceptref{Widget options}{options} describes how to create a new widget and which options +and resources are available. The chapter \conceptref{Groups, Display List and Transformations}{coordinates} +describes the use of groups and coordinates transformations. The chapter +\concept{Item IDs and Tags}{tagOrId} describes the Items ID as well as tags and some special +tags. It also describes the notion of field tags used with some items (such as \objectref{track}, +\objectref{waypoint}, \objectref{tabular}) and the notion of partNames for items (\objectref{track}, +\objectref{waypoint}). Then the chapter \conceptref{Indices}{indices} describes the use of indices XXX. +The important {\bf chapter \conceptref{Widget commands}{commands} } describes the commands which +apply to a \ident{zinc} widget. There are about 50 such commands and they are used for +creating, modifying or deleting objects, applying transformation... The chapter +\conceptref{Attributes Types}{types} describes the type of all attributes (or options) +available for the items described in the important {\bf chapter \conceptref{Item types}{items}}. +The chapter \conceptref{Labels, fields and label}{labelsandfields} describes the use of labels, +the possible attributes of label fields and finally the labelformat syntax. The chapter +\conceptref{The mapinfo commands}{mapinfocmds} describes the use of mapinfo, a kind of +simple map, which can be build by commands listed in this chapter. The chapter +\conceptref{The videomap commands}{videomapcmds} describes the use of videomap, +a proprietary format of simple map file used in french Air Traffic Control Centres. +Finally the chapter \conceptref{Other resources provided by the widget}{otherresources} +describes some resources provided by \ident{zinc}. + +\section{What is \ident{zinc}?} + +\ident{Zinc} widgets are very similar to Tk \ident{canvas}es in that they support +structured graphics. Like the \ident{canvas}, \ident{zinc} implements items used to +display graphical entities. Those items can be manipulated and bindings can be +associated with them to implement interaction behaviors. But unlike the \ident{canvas}, +\ident{zinc} can structure the items in a hierarchy (with the use of group items), +has support for affine 2D transforms (i.e. translating, scaling, and rotating), +clipping can be set for sub-trees of the item hierarchy and the item +set is quite more powerful including field specific items for Air Traffic systems. + +Since the 3.2.3 version, \ident{zinc} also offers the support of some openGL +features such as transparency, color variation and even a new item type : \objectref{triangles}. +You need the support of the GLX extension on your X11 server. Of course performance +will be dependant of your graphic card. At time of writing, NVidia drivers +for XFree86 R4.1 are doing a nice job. A labtop with an ATI mobility graphic card works nice. +We also succeded in using zinc with openGL on the Exceed X11 server +(running on windows and developped by Hummingbird) with the 3D extension. + The \ident{zinc} widget is available for the Tcl/Tk and the Perl/Tk environment. -A binding over Tcl/Tk is also provided for Python. This document is Tcl/Tk -oriented but it should be easy for Perl and Python programmers to adapt. +A binding over Tcl/Tk is also provided for Python. This document is Tcl/Tk and Perl/Tk +oriented but it should be easy for Python programmers to adapt. Every time a +\ident{zinc} command is described in this document, it is given first in Tcl/Tk +idiom and then in Perl/Tk idiom. + +\section{Where can I find zinc and documentation?} + +\ident{Zinc} is available at http://www.openatc.org/zinc or +http://freshmeat.net/projects/zincisnotcanvas/. The software is available as +tar.gz files and as Debian or RedHat/Mandrake packages. + +For people from CENA, its possible to get the zinc source code through +a private CVS server. Please contact directly lecoanet@cena.fr for mùore informations. + +This documentation is available as a part of the \ident{zinc} software. +It is also available apart on those web sites. The source of +this document is \ident{latex}, and its current format +is either html pages or a pdf file. + +As a complement to this ``Reference Manual'', small Perl/Tk demos +of \ident{zinc} are also available +through a small application named \ident{zinc-demos}, highly inspired +from the ``widget'' application included in Perl/Tk. The aims of these +demos are both to demonstrates the power of \ident{zinc} and to help +newcomers starting using \ident{zinc} with small examples. + +\section{Copyright and Licence} + +\ident{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. + +\section{Authors and credits} + +\ident{Zinc} has been developed by Patrick Lecoanet. He also developed two previous version called ``Radar Widget'' which share some caracteristics of this version. The release 2 of the ``Radar Widget'' was even enhanced and then used in two main Air Traffic Control Centres in France 24 hours a day. Dominique Ruiz, Frederic Lepied, and Didier Pavet helped a lot in the developement of \ident{zinc} and its previous versions. \ident{Zinc} also benefits from many discussion with 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 could never or hardly be implemented without \ident{zinc}. And \ident{zinc} would have been less interesting without his ideas. Didier Pavet and his team as well as Daniel Etienne and Herve Damiano were first users and cope with Patrick either by reporting bugs or problems. 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 \ident{zinc}. This documentation has been re-read +and slightly corrected by Christophe Mertz and others. + + +\concept{options} +\chapter{Widget options} The \ident{zinc} command creates a new \ident{zinc} widget, the general form is \begin{quotation} @@ -112,20 +311,15 @@ The \ident{zinc} command creates a new \ident{zinc} widget, the general form is {\tt pathname} name the new widget and specifies where in the widget hierarchy it will be located. 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 in the \ident{Widget options} chapter. - -\ident{Zinc} widgets are very similar to Tk \ident{canvas}es in that they support -structured graphics. Like the \ident{canvas}, \ident{zinc} implements items used to -display graphical entities. Those items can be manipulated and bindings can be -associated with them to implement interaction behaviors. But unlike the \ident{canvas}, -\ident{zinc} can structure the items in a hierarchy, has support for affine 2D -transforms, clipping can be set for sub-trees of the item hierarchy and the item -set is quite more powerful including field specific items for Air Traffic systems. +options are described below in this chapter. +Any new \ident{zinc} widget comes with an initial group, always identified by +the same ID: 1. This group will contain all other items, either directly or +indirectly through other groups created themselves (directly or in other groups... ) +in group 1. The chapter \conceptref{Groups, Display List and Transformations}{coordinates} +describes the use of groups) -\chapter{Widget options} -\concept{options} \option{borderwidth}{borderWidth}{BorderWidth} \begin{blockindent} Specifies the width of the 3d border that should be displayed around the widget @@ -138,10 +332,10 @@ set is quite more powerful including field specific items for Air Traffic system \option{backcolor}{backColor}{BackColor} \begin{blockindent} - This the color that will be used to fill the zinc window. It is also + This is the color that will be used to fill the zinc window. It is also used as a default color for some item attributes of type color. See each color attribute for the actual source of the default color. Its default - value is white. + value is white XXX. \end{blockindent} \option{cursor}{cursor}{Cursor} @@ -170,7 +364,7 @@ set is quite more powerful including field specific items for Air Traffic system \begin{blockindent} If this option is True, the shape applied to the zinc window will propagate up the window hierarchy to the top level window. The - result will be a shaped top level. See also the \optref{reshape} option, + result will be a shaped top level. See also the \refopt{reshape} option, it controls whether a shape is applied to the zinc window or not. The default is True. \end{blockindent} @@ -271,6 +465,13 @@ set is quite more powerful including field specific items for Air Traffic system for a relief (See \cident{Tk\_GetRelief} for a description of possible values). \end{blockindent} +\option{render}{render}{render} +\begin{blockindent} + Specifies whether to use or not the openGL rendering. When True, requires + the GLX extension to the X server. Must be defined at widget creation time. + This option is readonly. The default value is False +\end{blockindent} + \option{reshape}{reshape}{Reshape} \begin{blockindent} Specifies if the clipping shape that can be set in the top group item @@ -327,7 +528,7 @@ set is quite more powerful including field specific items for Air Traffic system \begin{blockindent} This option accepts only positive integers. It specifies the size of the past position list that can be maintained by the track items. See - also the \optref{trackmanagehistory} option and the \ident{visiblehistorysize} + also the \refopt{trackmanagehistory} option and the \ident{visiblehistorysize} track attribute. The default value is 6. \end{blockindent} @@ -339,7 +540,7 @@ set is quite more powerful including field specific items for Air Traffic system displayed as trailing speckles. If this option is turned off and then back on, the history list is erased and the collection is resumed at the next available position. The number of position collected in the - history list is specified by the option \optref{trackmanagedhistorysize}. + history list is specified by the option \refopt{trackmanagedhistorysize}. When this many positions are collected, the oldest is dropped to make room for the new one on a first in first out basis. The number of past positions actually displayed if specified for each track by the @@ -357,15 +558,17 @@ set is quite more powerful including field specific items for Air Traffic system \end{blockindent} -\chapter{Groups, Display List and Transformations} \concept{coordinates} +\chapter{Groups, Display List and Transformations} + la liaison groupe transformation l'empilage des groupes et la composition de transfo coordonnées du top group -\chapter{Item IDs and Tags} \concept{tagOrId} +\chapter{Item IDs and Tags} + id tag all tag current @@ -373,14 +576,17 @@ tags speciaux dans les items textes tags tags dans bind (syntaxe pour spécifier les parties et les champs). -Décrire les ids, tags, field tags et part tags. Les deux derniers +Décrire les ids, tags, fieldIds et partNames. Les deux derniers n'étant employes que par bind doit-on les décrire ici ou dans la commande ? Parler de current, all. +\concept{indices} \chapter{Indices} +XXX c'est quoi? +\concept{commands} \chapter{Widget commands} The available commands are listed in alphabetical order. @@ -438,6 +644,11 @@ reference) and all list parameters are given as array references. \item{\bf rectangle} \\ The rectangle type expects a list of four floating point numbers ``xo yo xc yc'', giving the coordinates of the origin and the corner of the rectangle. + \item{\bf triangles} \\ + The triangles type expects a list of (at least 6) floating point numbers ``x0 y0 x1 y1 ... xn yn'', + giving the coordinates of the corner of the triangles composing this item. The way + of placing the triangles is defined by the attribute \ident{fan}. This item requires that + \ident{zinc} uses openGL (see the option \ident{-render}). \item{\bf tabular, track, waypoint} \\ These types expects the number of fields they will manage in the label or tabular form. This number must be greater or equal to zero. @@ -953,6 +1164,9 @@ reference) and all list parameters are given as array references. 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: \$zinc->find('withtag', 'current'); \# returns the item under the mousxe cursor. XXX + \end{blockindent} \zinccmd{fit}{coordList error} @@ -971,7 +1185,6 @@ reference) and all list parameters are given as array references. Bezier item. \end{blockindent} -\zinccmd{focus}{?tagOrId?} {\tt\large \$item = \$zinc->{\bf focus}();}\\ {\tt\large \$zinc->{\bf focus}(tagOrId);} @@ -984,10 +1197,16 @@ reference) and all list parameters are given as array references. If {\tt tagOrId} is not specified, the command returns the id of the item with the focus or an empty string if no item has the focus. - When the focus has been set to an item, the item will display an insertion cursor - and the keyboard events will be directed to that item. The widget receive keyboards + When the focus has been set to a text item, the text item will display an insertion cursor + and the keyboard events will be directed to that item. + + The widget receive keyboards events only if it has the window focus. It may be necessary to use the Tk focus command to force the focus to the widget window. + + NB: currently (Version 3.2.3e) only text item are really getting the focus. Focus will + be extended to many/all other items in a near future. + \end{blockindent} \zinccmd{gdelete}{name} @@ -1082,24 +1301,24 @@ reference) and all list parameters are given as array references. should be a textual description of a text index that can have the following forms: \begin{description} - \item{number} This should be an integer giving the character position + \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{end} Refers to the position past the last character in the + \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{insert} Refers to the character just before the insertion + \item{\ident{insert}} Refers to the character just before the insertion cursor in the item. - \item{sel.first} Refers to the first character of the selection in + \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{sel.last}Refers to the last character of the selection in + \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{@x,y} Refers to the character at the point given by x and y, + \item{\ident{@x,y}} Refers to the character at the point given by x and y, x and y are interpreted as device 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. @@ -1123,7 +1342,7 @@ reference) and all list parameters are given as array references. The command returns an empty string. \end{blockindent} -\zinccmd{itemcget}{tagOrId ?field? attr} +\zinccmd{itemcget}{tagOrId ?fieldId? attr} {\tt\large \$val = \$zinc->{\bf itemcget}(tagOrId, attr);}\\ {\tt\large \$val = \$zinc->{\bf itemcget}(tagOrId, field, attr);} @@ -1140,11 +1359,13 @@ reference) and all list parameters are given as array references. reported. \end{blockindent} -\zinccmd{itemconfigure}{tagOrId ?field? ?attr? ?value? ?attr value ...?} +\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 @@ -1208,10 +1429,14 @@ reference) and all list parameters are given as array references. {\tt\large \$bool = \$zinc->{\bf numparts}(tagOrId);} \begin{blockindent} - This command tells how many private parts are available for event bindings - in the item specified by {\tt tagOrId}. If more than one item is named + This command tells how many private 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 should only be used for items supporting labelformat (i.e. + \objectref{track}, \objectref{waypoint} and \objectref{tabular}). \end{blockindent} \zinccmd{postscript}{} @@ -1267,6 +1492,24 @@ reference) and all list parameters are given as array references. nor an item, an error is raised. The angle is given in radians. The optional parameters describe the center of rotation, which defaults to the origin. + + When applying a rotation, items do not behave exactly the same maners. Textual elements do not + rotate. Only their anchor position moves according to the rotation: + + \begin{itemize} + \item \ident{group} propagates the rotation to its children. + \item \ident{track} : the graphical part (i.e position, past positions, speedvector, marker) rotate. The label only move according to its new anchor position. + \item \ident{waypoint} : the position ``rotates''. The label move according to its new anchor position. + \item \ident{tabular} : The label move according to its new anchor position. + \item \ident{text} moves according to its new anchor position. + \item \ident{icon} moves according to its new anchor position. + \item \ident{reticle} rotates. + \item \ident{map} : lines and arcs rotate. Texts and symbols move according to their new anchor position. + \item \ident{rectangle} keeps being a rectangle (i.e. with vertice parallele to the X and Y axes, but its corners rotate. + \item \ident{arc}, \ident{curve}, and \ident{bezier} rotates. + \item \ident{window} DO NOT ROTATE. + \end{itemize} + \end{blockindent} \zinccmd{scale}{tagOrId xFactor yFactor} @@ -1392,6 +1635,12 @@ reference) and all list parameters are given as array references. space. If either {\tt tagOrId} describe more than one item, the topmost in display list order is used. If {\tt tagOrId} doesn't describe either a transform or an item, an error is raised. + + This command is the only one available to convert from/to device coordinates. + To do this conversion it is higly recommended not to apply a transformation to the + group 1, so that coordinates of group 1 map the device coordinates. + + For example: XXX \end{blockindent} \zinccmd{translate}{tagOrId xAmount yAmount} @@ -1460,7 +1709,7 @@ reference) and all list parameters are given as array references. \begin{blockindent} Return a list of values describing the vertex and edge closest to the - device coordinates {\tt x} and {\tt y} in the item described by {\tt tagOrId}. + {\bf device 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 @@ -1469,6 +1718,7 @@ reference) and all list parameters are given as array references. \end{blockindent} +\concept{types} \chapter{Attribute types} \attrtype{alignment} @@ -1743,8 +1993,8 @@ reference) and all list parameters are given as array references. \attrtype{mapinfo} \begin{blockindent} This is the name of a previously registered mapinfo object - (see \ref{mapinfocmd}) that will define the lines, symbols, - texts an other graphical parts displayed in a map item. + (see the chapter \conceptref{The mapinfo commands}{mapinfocmds}) that will define + the lines, symbols, texts an other graphical parts displayed in a map item. \end{blockindent} \attrtype{number} @@ -1785,11 +2035,25 @@ reference) and all list parameters are given as array references. -\chapter{Labels, fields and label formats} +\concept{labelsandfields} +\chapter{Labels, label formats and fields} + \concept{label} \concept{labelformat} +\section {Labels, label formats} + \object{field} -Applicable attributes for fields: +\section{Attributes for fields} + +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 addtionnal second paramter. + +Applicable attributes for fields are: \attribute{alignment}{alignment}{ @@ -1844,8 +2108,8 @@ Applicable attributes for fields: Specifies if the field is displayed. The default value is {\tt true}.} -\chapter{Item types} \concept{items} +\chapter{Item types} This chapter introduces the item types that can be used in \ident{zinc}. Each item type provides a set of options that may be used to query or change the @@ -1854,11 +2118,16 @@ use special parameters with some command. Those cases are noted in the descripti of the item. +\object{group} \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 a previous chapter +\conceptref{Groups, Display List and Transformations}{coordinates}. + Applicable attributes for \ident{group}: +\attribute{alpha}{alpha}{Specifies the transparency to apply to the group children. Needs the openGL extension. XXX alpha type to be defined} \attribute{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 @@ -1883,10 +2152,38 @@ Applicable attributes for \ident{group}: displayed. The defaut value is {\tt true}.} -\section{Track and WayPoint items} - \object{track} -Applicable attributes for \ident{track}: +\section{Track items} + +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{speedvector} for the track and the option \refopt{speedvectorlength}. +This speed vector may be set visible or not, sensitive or other attributes can +be set such as color, width, ticks... Its partName is \ident{speedvector} +\item a {\bf leader} which links the current position to the label. The leader may be visible or not, sensitive or not, and other graphic caracteristics can be be modified. Its partName is \ident{leader} +\item {\bf past positions} which are previous position after the track has been moved by the \cmdref{coords} command. The number of such past positions, their visibility and other graphic caracteristics can be be modified. This part is never sensitive. +\item a {\bf marker}, which is a circle around the current position. This marker can be visible or not and other graphic caracteristics can be configured. The marker is never sensitive. +\item a {\bf connection}, which is a link with another item. This connection may be visible or not, sensitive or not, and other graphic caracteristics can be be modified. Its partName is \ident{connection}. +\end{itemize} +\begin{itemize} +\item the second part is a block of texts described by a labelformat (see chapter \conceptref{Labels, fields and Label formats}{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} +\end{itemize} + +An other very important feature of \ident{track} is that \ident{zinc} offers an anti-overlap manager. This manager tries to avoid any overlap of tracks labels. It also avoids that the label overlap the speedvector. This manager is stable over time: there should be few cases where labels are moved to a very different position. This manager applies to all tracks included in a group (by default the group 1). It can be enabled/disabled with the attributes XXX. New labels positions are computed by the overlap manager every time a track is moved, a track is created or destroyed and every time the \ident{zinc} widget is resized. +Due to software licence limitation, \ident{zinc} {\bf DO NOT include} the very last version of this anti-overlap manager. + +Applicable attributes for \ident{track} are: \attribute{circlehistory}{boolean}{If set to true the track history will be plotted as cricles otherwise it will be plotted as squares. The default @@ -1900,8 +2197,8 @@ Applicable attributes for \ident{track}: \attribute{connectioncolor}{color}{The color of the connection link. The default value is the current value of the widget option \ident{-foreground}.} \attribute{connectionsensitive}{boolean}{Specifies if the connection link - is sensitive. The actual sensitivity is the logical and of this attribute and - of the item {\tt sensitive}{boolean} attribute. The default value is {\tt true}.} + is sensitive. The actual sensitivity is the logical \ident{and} of this attribute and + of the item {\tt sensitive} attribute. The default value is {\tt true}.} \attribute{connectionstyle}{linestyle}{The line style of the connection link. The default value is {\tt simple}.} \attribute{connectionwidth}{dimension}{The width of the connection link. The @@ -1949,7 +2246,7 @@ Applicable attributes for \ident{track}: \attribute{leaderlastend}{lineend}{Describe the arrow shape at the label end of the leader. The default value is {\tt ""}.} \attribute{leadersensitive}{boolean}{Specifies if the label leader is sensitive. - The actual sensitivity is the logical and of this attribute and of the item + The actual sensitivity is the logical \ident{and} of this attribute and of the item {\tt sensitive} attribute. The default value is {\tt true}.} \attribute{leadershape}{lineshape}{The shape of the label leader. The default value is {\tt straight}.} @@ -1984,7 +2281,7 @@ Applicable attributes for \ident{track}: the speed vector. The point is drawn with the speed vector color. The default is {\tt false}.} \attribute{speedvectorsensitive}{boolean}{Specifies if the track's speed vector - is sensitive. The actual sensitivity is the logical and of this attribute and of + is sensitive. The actual sensitivity is the logical \ident{and} of this attribute and of the item {\tt sensitive} attribute. The default value is {\tt true}. } \attribute{speedvectorticks}{boolean}{If set a mark is drawn at each minute position. The default is {\tt false}.} @@ -1994,7 +2291,7 @@ The default is {\tt false}.} position. The default value is the current value of the widget option \ident{-foreground}.} \attribute{symbolsensitive}{boolean}{Specifies if the current position's symbol - is sensitive to events. The actual sensitivity is the logical and of this attribute + is sensitive to events. The actual sensitivity is the logical \ident{and} of this attribute and of the item {\tt sensitive} attribute. The default value is {\tt true}.} \attribute{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} @@ -2005,7 +2302,24 @@ The default is {\tt false}.} \object{waypoint} -Applicable attributes for \ident{waypoint}: +\section{WayPoint items} + +Waypoints items have been initially designed for figuring out typical fixed position +objects (i.e. beacons or fixes in the ATC vocabulary) with +associated block of texts on a radar display for Air Traffic Control. They supports +mouse event handling and interactions. +However they may certainly be used by other kinds of radar view or even by other kind +of plan view with many geographical objects and associated textual information. + +A waypoint is composed of the following parts: +\begin{itemize} +\item the {\bf position} of the waypoint. Its partName is \ident{position} +\item a {\bf leader} which links the current position to the label. The leader may be visible or not, sensitive or not, and other graphic caracteristics can be be modified. Its partName is \ident{leader} +\item a {\bf label} which is a block of texts described by a labelformat (see chapter \conceptref{Labels, fields and Label formats}{labelformat}. Each text can have its graphic decorations (alignment, background, images, borders...). These attributes are listed in the chapter \conceptref{Labels, label formats and fields}{labelformat} and can be changed by the command \cmdref{itemconfigure}. +\item a {\bf connection}, which is a link with another item. This connection may be visible or not, sensitive or not, and other graphic caracteristics can be be modified. Its partName is \ident{connection}. +\end{itemize} + +Applicable attributes for \ident{waypoint} are: \attribute{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}. } @@ -2016,7 +2330,7 @@ Applicable attributes for \ident{waypoint}: \attribute{connectioncolor}{color}{The color of the connection link. The default value is the current value of the widget option \ident{-foreground}.} \attribute{connectionsensitive}{boolean}{Specifies if the connection link is - sensitive. The actual sensitivity is the logical and of this attribute and of the + sensitive. The actual sensitivity is the logical \ident{and} of this attribute and of the item {\tt sensitive} attribute. The default value is {\tt true}.} \attribute{connectionstyle}{linestyle}{The line style of the connection link. The default value is {\tt simple}.} @@ -2055,7 +2369,7 @@ Applicable attributes for \ident{waypoint}: \attribute{leaderlastend}{lineend}{Describe the arrow shape at the label end of the leader. The default value is {\tt ""}.} \attribute{leadersensitive}{boolean}{Specifies if the label leader is sensitive. - The actual sensitivity is the logical and of this attribute and of the item + The actual sensitivity is the logical \ident{and} of this attribute and of the item {\tt sensitive} attribute. The default value is {\tt true}.} \attribute{leadershape}{lineshape}{The shape of the label leader. The default value is {\tt straight}.} @@ -2085,7 +2399,7 @@ Applicable attributes for \ident{waypoint}: position. The default value is the current value of the widget option \ident{-foreground}.} \attribute{symbolsensitive}{boolean}{Specifies if the current position's symbol - is sensitive to events. The actual sensitivity is the logical and of this attribute + is sensitive to events. The actual sensitivity is the logical \ident{and} of this attribute and of the item {\tt sensitive} attribute. The default value is {\tt true}.} \attribute{tags}{taglist}{The list of tags associated with the item. The default value is {\tt ""}.} @@ -2093,10 +2407,15 @@ Applicable attributes for \ident{waypoint}: value is {\tt true}.} +\object{tabular} \section{Tabular items} -\object{tabular} -Applicable attributes for \ident{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 waypoint is composed of a {\bf label} which is a block of texts described by a labelformat (see chapter \conceptref{Labels, fields and Label formats}{labelformat}. Each text can have its graphic decorations (alignment, background, images, borders...). This attributes are listed in the chapter \conceptref{Labels, label formats and fields}{labelformat} and can be changed by the command \cmdref{itemconfigure}. + +Applicable attributes for \ident{tabular} are: \attribute{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} @@ -2124,10 +2443,12 @@ Applicable attributes for \ident{tabular}: value is {\tt true}.} +\object{text} \section{Text items} -\object{text} -Applicable attributes for \ident{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 \ident{zinc} options (see chapter \conceptref{Widget options}{options} can be used for configuring the text input (for example : \refopt{insertbackground} \refopt{insertofftime} \refopt{insertontime} \refopt{insertwidth}). + +Applicable attributes for \ident{text} are: \attribute{alignment}{alignment}{Specifies the horizontal alignment of the lines in the item. The default value is {\tt left}.} @@ -2174,10 +2495,12 @@ Applicable attributes for \ident{text}: The default value is {\tt 0}.} +\object{icon} \section{Icon items} -\object{icon} -Applicable attributes for \ident{icon}: +Icon items are used for XXX. + +Applicable attributes for \ident{icon} are: \attribute{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} @@ -2210,10 +2533,12 @@ Applicable attributes for \ident{icon}: value is {\tt true}.} +\object{reticle} \section{Reticle items} -\object{reticle} -Applicable attributes for \ident{reticle}: +Reticle items are used for XXX. + +Applicable attributes for \ident{reticle} are: \attribute{brightlinecolor}{color}{This is the color of the highlighted circles. The default value is the current value of the widget option @@ -2253,12 +2578,13 @@ Applicable attributes for \ident{reticle}: value is {\tt true}.} +\object{map} \section{Map items} -\object{map} +Map items are used for XXX. - Applicable attributes for \ident{map}: + Applicable attributes for \ident{map} are: \attribute{color}{color}{Specifies the color usedd to draw or fill the map. The texts and symbols that are part of the map are also drawn in this color. @@ -2289,9 +2615,9 @@ Applicable attributes for \ident{reticle}: value is {\tt true}.} +\object{rectangle} \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. @@ -2301,7 +2627,7 @@ Applicable attributes for \ident{reticle}: shape in a \ident{curve} item. The two points describing the rectangle can be read and modified with the \ident{coords} command. - Applicable attributes for \ident{rectangle}: + Applicable attributes for \ident{rectangle} are: \attribute{composerotation}{boolean}{Specifies if the current rotation should be composed with the local transform. The default value is {\tt true}.} @@ -2340,9 +2666,9 @@ Applicable attributes for \ident{reticle}: value is {\tt true}.} +\object{arc} \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. @@ -2357,7 +2683,7 @@ Applicable attributes for \ident{reticle}: should be the top left vertex of the rectangle and the second should be the bottom right. - Applicable attributes for \ident{arc}: + Applicable attributes for \ident{arc} are: \attribute{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. @@ -2412,9 +2738,9 @@ Applicable attributes for \ident{reticle}: value is {\tt true}.} +\object{curve} \section{Curve items} -\object{curve} Items of type \ident{curve} display a path of line segments connected by their end points. It is possible to build curve items with more than one path @@ -2427,7 +2753,7 @@ Applicable attributes for \ident{reticle}: be the polygon obtained by closing the path. The vertices can be read, modified, added or removed with the \ident{coords} command. - Applicable attributes for \ident{curve}: + Applicable attributes for \ident{curve} are: \attribute{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 @@ -2486,9 +2812,9 @@ Applicable attributes for \ident{reticle}: value is {\tt true}.} +\object{bezier} \section{Bezier items} -\object{bezier} Items of type \ident{bezier} display a path of Bezier cubic segments connected by their end points. Each segment is described by four control points, two @@ -2504,7 +2830,7 @@ Applicable attributes for \ident{reticle}: in a \ident{curve} item. The controls points can be read, modified, added or removed with the \ident{coords} command. -Applicable attributes for \ident{bezier}: +Applicable attributes for \ident{bezier} are: \attribute{capstyle}{capstyle}{Specifies the form of the outline ends. This attribute is only applicable if the bezier is not closed and the outline relief is @@ -2553,9 +2879,32 @@ Applicable attributes for \ident{bezier}: value is {\tt true}.} +\object{triangles} +\section{Triangles items} + + + Triangles items are used for XXX. + + Applicable attributes for \ident{triangles} are: + +\attribute{colors}{gradientarray}{Specifies the colors of each vertex of the triangles XXX.} +\attribute{composerotation}{boolean}{Specifies if the current rotation should + be composed with the local transform. The default value is {\tt true}.} +\attribute{composescale}{boolean}{Specifies if the current scale should be + composed with the local transform. The default value is {\tt true}.} +\attribute{fan}{fantype}{XXX. The default value is {\tt XXX}.} +\attribute{priority}{integer}{The absolute position in the stacking order among + siblings of the same parent group. The default value is {\tt 2}.} +\attribute{sensitive}{boolean}{Specifies if the item should react to events. + The default value is {\tt true}.} +\attribute{tags}{taglist}{The list of tags associated with the item. The default + value is {\tt ""}.} +\attribute{visible}{boolean}{Specifies if the item is displayed. The default + value is {\tt true}.} + -\section{Window items} \object{window} +\section{Window items} Items of type \ident{window} display an X11 window at a given position in the widget. @@ -2577,7 +2926,7 @@ Applicable attributes for \ident{bezier}: 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}: +Applicable attributes for \ident{window} are: \attribute{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} @@ -2611,8 +2960,8 @@ Applicable attributes for \ident{window}: The default value is {\tt ""}.} -\chapter{The \ident{mapinfo} command} -\label{mapinfocmd} +\concept{mapinfocmds} +\chapter{The mapinfo commands} MapInfo objects are used to describe graphical primitives that will be displayed in map items. It is possible to describe lines, arcs, symbols @@ -2720,7 +3069,8 @@ Applicable attributes for \ident{window}: -\chapter{The \ident{videomap} command} +\concept{videomapcmds} +\chapter{The videomap commands} \command{videomap}{ids}{fileName} \begin{blockindent} @@ -2740,6 +3090,7 @@ Applicable attributes for \ident{window}: +\concept{otherresources} \chapter{Other resources provided by the widget} \section{Bitmaps} @@ -2750,24 +3101,46 @@ Zinc creates two sets of bitmaps. The first set contains symbols for ATC tracks, maps and waypoints, these bitmaps are named AtcSymbol1 to AtcSymbol22. +\ifpdf + \includegraphics{atcsymb} +\else \latexhtml{% \includegraphics{atcsymb.ps}}{% \htmladdimg{atcsymb.png} } +\fi The second set provides stipples that can be used to implement transparency, they are named AlphaStipple0 to AlphaStipple15, AlphaStipple0 being the most transparent. +\ifpdf + \includegraphics{alphastip} +\else \latexhtml{% \includegraphics{alphastip.ps}}{% \htmladdimg{alphastip.png} } +\fi -\latex {\tolerance 2000 %allow somewhat looser lines. +\ifpdf\else\latex {\tolerance 2000 %allow somewhat looser lines. \hbadness 10000 } %don't complain about underfull lines. +\fi + + +\section{ZincDebug.pm} + +\ident{ZincDebug.pm} is a perl module useful for debugging purpose. It can be used +in a perl application using \ident{zinc} to grab items with the mouse and to get +the list of items enclosed or overlapped by a rectangle designated by the mouse. +Please refer to the \ident{ZincDebug.pm} with the classical command \tt{man ZincDebug} + +\section{zinc-demo} + +Starting at version 3.2.3f of \ident{zinc} small applications are included as demos. They are all +accessible through an application called \ident{zinc-demos}. These tiny demos are +usefull for newcomers and as starting points. -\tableofcontents \listoftables \listoffigures |