diff options
| author | mertz | 2002-10-15 15:58:46 +0000 |
|---|---|---|
| committer | mertz | 2002-10-15 15:58:46 +0000 |
| commit | 1afbd60b83f67245f87ca083e5b288cee99979f7 (patch) | |
| tree | 35a63fdd496e806fb80bb38dd52087fe02561942 /doc | |
| parent | a271191ba7c4b0921d38c15d0de9044b15ab97b2 (diff) | |
| download | tkzinc-1afbd60b83f67245f87ca083e5b288cee99979f7.zip tkzinc-1afbd60b83f67245f87ca083e5b288cee99979f7.tar.gz tkzinc-1afbd60b83f67245f87ca083e5b288cee99979f7.tar.bz2 tkzinc-1afbd60b83f67245f87ca083e5b288cee99979f7.tar.xz | |
- utilisation de \quote au lieu de \quotation pour eviter les
indentations de la premiere ligne de paragraphe
- ajout d'un parametre � \option pour y mettre la description
- la hauteur utile de la page a �t� augment�e de 0.5 pouces et
la marge en haut a �t� r�duite d'autant
- le top group est devenu le root group partout
- path tag ou pathtag sont devenus "pathTag"
- petites mises en forme du paragrpahe sur les pathTags
- am�lioration du paragrpahe sur les labelformats
- quelques corrections de typos
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/refman.tex | 799 |
1 files changed, 448 insertions, 351 deletions
diff --git a/doc/refman.tex b/doc/refman.tex index 44b87e8..cb28a5e 100644 --- a/doc/refman.tex +++ b/doc/refman.tex @@ -1,4 +1,4 @@ -\documentclass[11pt,twoside]{book} +\documentclass[11pt,twoside,a4paper]{book} %---------------------------------------------------------------------- % $Revision$ @@ -42,6 +42,8 @@ pdfpagemode=None, bookmarksopen=true ]{hyperref} +% \pdfpagewidth=210truemm +% \pdfpageheight=297truemm \pdfcompresslevel=9 \usepackage[pdftex]{graphicx} \usepackage{thumbpdf} @@ -56,6 +58,7 @@ \usepackage{html} \usepackage[widemargins]{a4} +\usepackage{calc} \usepackage{makeidx} @@ -68,9 +71,9 @@ \newcommand{\ident}[1] {% {\tt\large #1}} -\newenvironment{blockindent}{\begin{quotation}\vspace{-0.8\baselineskip}}{\end{quotation}\vspace{\parskip}} +\newenvironment{blockindent}{\begin{quote}\vspace{-0.8\baselineskip}}{\end{quote}\vspace{-0.5\baselineskip}} -\newcommand{\option}[3]{% +\newcommand{\option}[4]{% \label{opt:#1} \index{#1} \latexhtml{\ifpdf\hyperdef{opt}{#1}{}\fi}{\htmlrule[WIDTH="300" left]} @@ -78,7 +81,8 @@ Command line switch: & \ident{-#1} \\ Database name: & \ident{#2} \\ Database class: & \ident{#3} \\ - \end{tabular}} + \end{tabular} + \begin{blockindent}{#4}\end{blockindent} } \newcommand{\command}[3]{% \label{cmd:#2} @@ -137,7 +141,7 @@ \index{#2} \latexhtml{\ifpdf\hyperlink{attrtype.#3}{\ident{#3}}\hyperdef{attribute}{#1#2}{}\fi}{% \hyperref[no]{\tt \bf #3}{\ident{#3}}{attrtype:#3}} - \begin{quotation}\vspace{-\baselineskip}#4\vspace{-0.8\baselineskip}\end{quotation} + \begin{quote}\vspace{-\baselineskip}#4\vspace{-0.8\baselineskip}\end{quote} } % first argument : item type or 'option' @@ -203,10 +207,14 @@ \title{Zinc, an advanced scriptable Canvas.\\The 3.2.6 Reference Manual.\\\small{[CENA technical Note NT02-782]} } \author{Patrick Lecoanet} -\date{4 July 2002} +\date{10 October 2002} \begin{document} +%pdfpagewidth: \the\pdfpagewidth pdfpageheight: \the\pdfpageheight voffset: \the\voffset ~topmargin: \the\topmargin ~textheight: \the\textheight \linebreak +\voffset=-0.5in \setlength\textheight{ (\textheight+0.5in) } +%voffset: \the\voffset ~topmargin: \the\topmargin ~textheight: \the\textheight \linebreak + \latex{\DeclareGraphicsExtensions{.png,.ps,.eps,.pdf}} @@ -230,7 +238,7 @@ structured graphics. Like the Canvas, Zinc implements items used to display graphical entities. Those items can be manipulated and bindings can be associated with them to implement interaction behaviors. But unlike the Canvas, Zinc can structure the items in a hierarchy (with the use of -group items), has support for affine 2D transforms (i.e. translation, scaling, and +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 @@ -247,7 +255,7 @@ with a GeForce GO graphic card works nice for non trivial applications. We also succeeded in using Zinc with openGL on the Exceed X11 server (running on windows and developped by Hummingbird) with the 3D extension. -As an exemple of Zinc capabilities when combined with openGL, we implemented +As an example of Zinc capabilities when combined with openGL, we implemented the tk Zinc logo as a Perl module (available as a goodie in \ident{LogoZinc.pm}). This logo (see below) was designed with Adobe Illustrator and then programmed in perl. @@ -278,6 +286,11 @@ This document is also referenced as the CENA technical note NT02-782. \section{Differences with previous version} +\subsection{Differences current release and 3.2.6 release} +\begin{itemize} +\item pathTags introduced in 3.2.6 has been examplified and documented. Label and label format documentation has been enhanced. +\end{itemize} + \subsection{Differences between 3.2.6 and 3.2.4 release} \begin{itemize} \item many bug corrections, of course! @@ -290,8 +303,8 @@ This document is also referenced as the CENA technical note NT02-782. \item anti-overlapping of tracks labels works again \item tsave can now be used to know if a named transformation is already defined \item gname can now be used to know if a named gradient is already defined -\item new tags can now be used : ``pathtags'' to go through groups. Yet to be documented! -\item find and addtag commands have been modified to be ``pathtag'' compliant +\item new tags can now be used : ``pathTags'' to go through groups. Yet to be documented! +\item find and addtag commands have been modified to be ``pathTag'' compliant \item the clone command only clone one item when using a tag. \item all items have now a -composealpha option \item it is again an error to configure an unexisting option of an item @@ -393,7 +406,7 @@ 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 +license by The Regents of the University of California and Sun Microsystems, Inc.\ The general polygon clipper, GPC, is copyrighted by the Advanced Interfaces Group, Department of Computer Science, University of Manchester. GPC can't be used for commercial purposes without the agreement of the University of Manchester and a monetary @@ -472,29 +485,30 @@ if you want them to be integrated in a future release of Zinc. \chapter{Widget creation and options} \concept{options} -The Zinc command creates a new Zinc widget, the general form is +The Zinc command creates a new Zinc widget, the general form are in Tcl and Perl: -\begin{quotation} -{\tt\large zinc}\bigskip +\begin{quote} +{\tt\large zinc}\medskip + +{\tt\large \$version = \$mainwindow->zinc();}\smallskip -{\tt\large \$version = \$mainwindow->zinc();} {\tt\large \$Tk::Zinc::VERSION;} -\end{quotation} +\end{quote} -These two expressions can be used to get the version of Zinc. The string returned by the second expression also details the graphic head available. For example : ``zinc-version-3205d X11 GL''. +These expressions can be used to get the version of Zinc. The string returned by the last expression also details the graphic head available. For example : ``zinc-version-3205d X11 GL''. -\begin{quotation} -{\tt\large zinc pathname ?options?}\bigskip +\begin{quote} +{\tt\large zinc pathname ?options?}\medskip {\tt\large \$mainwindow->Zinc(?option=>value?, ..., ?option=>value?);} -\end{quotation} +\end{quote} {\tt pathname} name the new widget and specifies where in the widget hierarchy it will be located. Any new Zinc widget comes with a root group item, always identified by the item id 1. This group will contain all other items, either directly or through -groups created themselves in the top group. Together the items form a tree rooted +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} @@ -516,178 +530,180 @@ described below. \option{backcolor}{backColor}{BackColor} -\begin{blockindent} - This is the color that will be used to fill the Zinc window. It is also used as a - default color for some item color attributes. See each color attribute for the - actual source of the default color. Its default value is \verb+#c3c3c3+, a light grey. -\end{blockindent} +{ +This is the color that will +be used to fill the Zinc window. It is also used as a default color +for some item color attributes. See each color attribute for the +actual source of the default color. Its default value is +{\tt \#c3c3c3}, a light grey. +} \option{borderwidth}{borderWidth}{BorderWidth} -\begin{blockindent} +{ Specifies the width of the 3d border that should be displayed around the widget window. This border does overlap the active Zinc display area. The area requested from the geometry manager (or the window manager if applicable) is the area defined by \optref{width} and \optref{height}, the border is not taken into account. This value can be given in any of the forms valid for - coordinates (See \cident{TkGet\_Pixels}). The default value is \verb+2+. -\end{blockindent} + coordinates (See \cident{TkGet\_Pixels}). The default value is {\tt 2}. +} \option{cursor}{cursor}{Cursor} -\begin{blockindent} +{ Specifies the cursor to use when the pointer is in the Zinc window. The default value is set to preserve the cursor inherited at widget creation. -\end{blockindent} +} \option{font}{font}{Font} -\begin{blockindent} +{ The font specified by this option is used as a default font for item attributes of - type font. Its default value is \verb+-adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*+. -\end{blockindent} + type font. Its default value is {\tt -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*}. +} \option{forecolor}{foreColor}{ForeColor} %% XXX CM Foreground ?! -\begin{blockindent} +{ The color specified by this option is used as a default color for many item color attributes. See each each color attribute for the actual source of the default - color. Its default value is \verb+black+. -\end{blockindent} + color. Its default value is {\tt black}. +} \option{fullreshape}{fullReshape}{FullReshape} -\begin{blockindent} +{ If this option is True, the shape applied to the Zinc window will propagate up the - window hierarchy to the top level window. The result will be a shaped top - level. See also the \optref{reshape} option, it controls whether a shape is applied - to the Zinc window or not. The default is \verb+true+. -\end{blockindent} + window hierarchy to the toplevel window. The result will be a shaped toplevel. + See also the \optref{reshape} option, it controls whether a shape is applied + to the Zinc window or not. The default is {\tt true}. +} \option{height}{height}{Height} -\begin{blockindent} +{ Specifies the height of the Zinc window. This value can be given in any of the - forms valid for coordinates (See \cident{Tk\_GetPixels}). The default is \verb+100+ + 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 \verb+\#c3c3c3+. -\end{blockindent} + widget does not have the input focus. The default value is {\tt \#c3c3c3}. +} \option{highlightcolor}{highlightColor}{HighlightColor} -\begin{blockindent} +{ Specifies the color to use for the traversal highlight rectangle that is drawn - around the widget when it has the input focus. The default value is \verb+black+. -\end{blockindent} + around the widget when it has the input focus. The default value is {\tt black}. +} \option{highlightthickness}{highlightThickness}{HighlightThickness} -\begin{blockindent} +{ Specifies a non-negative value indicating the width of the highlight rectangle drawn around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to \cident{Tk\_GetPixels}. If the value is zero, - no focus highlight is drawn around the widget. The default value is \verb+2+. -\end{blockindent} + no focus highlight is drawn around the widget. The default value is {\tt 2}. +} \option{insertbackground}{insertBackground}{InsertBackground} %% XXX CM Foreground ?! -\begin{blockindent} +{ Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the - selection). The default value is \verb+black+. -\end{blockindent} + selection). The default value is {\tt black}. +} \option{insertofftime}{insertOffTime}{InsertOffTime} %% XXX CM OffTime ?! -\begin{blockindent} +{ Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain off in each blink cycle. If this option is zero - then the cursor is on all the time. The default value is \verb+300+. -\end{blockindent} + then the cursor is on all the time. The default value is {\tt 300}. +} \option{insertontime}{insertOnTime}{InsertOnTime} %% XXX CM OnTime ?! -\begin{blockindent} +{ Specifies a non-negative integer value indicating the number of milliseconds the - insertion cursor should remain on in each blink cycle. The default value is \verb+600+. -\end{blockindent} + insertion cursor should remain on in each blink cycle. The default value is {\tt 600}. +} \option{insertwidth}{insertWidth}{InsertWidth} -\begin{blockindent} +{ Specifies a value indicating the width of the insertion cursor. The value may have - any of the forms acceptable to \cident{Tk\_GetPixels}. The default value is \verb+2+. -\end{blockindent} + any of the forms acceptable to \cident{Tk\_GetPixels}. The default value is {\tt 2}. +} \option{lightangle}{lightAngle}{LightAngle} -\begin{blockindent} - Specifies the lighting angle used when displaying relief. The default value is \verb+120+. %%% XXX CM to be completed! -\end{blockindent} +{ + Specifies the lighting angle used when displaying relief. The default value is {\tt 120}. %%% XXX CM to be completed! +} \option{mapdistancesymbol}{mapDistanceSymbol}{MapDistanceSymbol} -\begin{blockindent} +{ This option specifies the symbol to be used as a milestone along map lines. This option can be given any Tk bitmap which can be obtained by \cident{Tk\_GetBitmap}. The spacing between markers is 10 nautic miles. The default - value is \verb+AtcSymbol19+ (see \conceptref{Other resources provided by the widget}{otherresources}). -\end{blockindent} + value is {\tt AtcSymbol19} (see \conceptref{Other resources provided by the widget}{otherresources}). +} \option{maptextfont}{mapTextFont}{MapTextFont} -\begin{blockindent} +{ Specifies the font used to draw the texts contained in maps. The default is - \verb+-adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*+. -\end{blockindent} + {\tt -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*}. +} \option{overlapmanager}{overlapManager}{OverlapManager} -\begin{blockindent} +{ This option accepts an item id. It specifies if the label overlapping avoidance algorithm should be allowed to do its work on the track labels and which group should be considered to look for tracks. The default is to enable the avoidance - algorithm in the top group (id 1). To disable the algorithm this option should - be set to \verb+0+. -\end{blockindent} + algorithm in the root group (id 1). To disable the algorithm this option should + be set to {\tt 0}. +} \option{pickaperture}{pickAperture}{PickAperture} -\begin{blockindent} +{ Specifies the size of an area around the pointer that is used to tell if the pointer is inside an item. This is useful to lessen the precision required when picking graphical elements. This value must be a positive integer. It defaults to - \verb+1+. -\end{blockindent} + {\tt 1}. +} \option{relief}{relief}{Relief} -\begin{blockindent} +{ Specifies the border relief. This option can be given any legal value for a relief (See \attrtyperef{relief} for a description of possible values). XXX what is the meaning - of this option. The default value is \verb+flat+. -\end{blockindent} + of this option. The default value is {\tt flat}. +} \option{render}{render}{Render} -\begin{blockindent} +{ Specifies whether to use or not the openGL rendering. When True, requires the GLX extension to the X server. Must be defined at widget creation time. This option is readonly and can be used to ask if the widget is drawing with the GLX extension or - in plain X (to adapt the application code for example). The default value is \verb+false+. -\end{blockindent} + in plain X (to adapt the application code for example). The default value is {\tt false}. +} \option{reshape}{reshape}{Reshape} -\begin{blockindent} - Specifies if the clipping shape that can be set in the top group item should clip - the top group children or be used to reshape the Zinc window. This option can be +{ + Specifies if the clipping shape that can be set in the root group item should clip + the root group children or be used to reshape the Zinc window. This option can be used with the fullreshape option to reshape the toplevel window as well. The - default value is \verb+true+. -\end{blockindent} + default value is {\tt true}. +} \option{selectbackground}{selectBackground}{SelectBackground} %% XXX CM Foreground ?! -\begin{blockindent} +{ Specifies the background color to use for displaying the selection in text - items. The default value is \verb+\#a0a0a0+. -\end{blockindent} + items. The default value is {\tt \#a0a0a0}. +} \option{speedvectorlength}{speedVectorLength}{SpeedVectorLength} -\begin{blockindent} +{ Specifies the duration of track speed vectors. This option is expressed using a time unit that should be chosen by the application (usually minutes) and kept coherent with the unit of the track attribute \attributeref{track}{speedvector} (usually nautic - mile / minute). The default value is \verb+3+. -\end{blockindent} + mile / minute). The default value is {\tt 3}. +} \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 @@ -708,24 +724,24 @@ described below. redefine the keyboard traversal scripts.} The default value is empty. -\end{blockindent} +} \option{tile}{tile}{Tile} -\begin{blockindent} +{ Specifies an image name to be used as a tile for painting the Zinc window - background. The default value is \verb+""+ (the empty string). -\end{blockindent} + background. The default value is {\tt ""} (the empty string). +} \option{trackmanagedhistorysize}{trackManagedHistorySize}{TrackManagedHistorySize} -\begin{blockindent} +{ This option accepts only positive integers. It specifies the size of the past position list that should be maintained by the track items. See also the \optref{trackmanagehistory} option and the \attributeref{track}{visiblehistorysize} track - attribute. The default value is \verb+6+. -\end{blockindent} + attribute. The default value is {\tt 6}. +} \option{trackmanagehistory}{trackManageHistory}{TrackManageHistory} -\begin{blockindent} +{ This option accepts any form valid for a boolean. It specifies if the track items should maintain a list of their past positions to be displayed as trailing speckles. If this option is turned off and then back on, the history list is erased @@ -736,14 +752,14 @@ described below. number of past positions actually displayed if specified for each track by the \attributeref{track}{visiblehistorysize} attribute. The default is to enable the history collection. -\end{blockindent} +} \option{width}{width}{Width} -\begin{blockindent} +{ Specifies the width of the Zinc window. This value can be given in any of the forms valid for coordinates (See \cident{Tk\_GetPixels}). The default is - \verb+100+ pixels. -\end{blockindent} + {\tt 100} pixels. +} @@ -771,7 +787,7 @@ are: 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, + 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. @@ -811,16 +827,16 @@ resulting attribute value in the leaf items: \section{Atomic groups} -It may seem at first that there is a contradiction in this title, but there is not. It is +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 +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 +bindings. Not exactly what we meant. So groups have a feature, the \attributeref{group}{atomic} attribute, that is used to seal a group so that events cannot propagate past it downward. If an item part of an atomic group is under the pointer, Zinc will try to trigger bindings associated with the atomic group not with the item under the @@ -849,9 +865,9 @@ event is done in the opposite direction. In this way, items are drawn according their relative stacking order and events are dispatched to the most visible item at a given location. -It is important to note as a consequence of this structuring, that a group's items are +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. Items of two groups cannot be intertwinned, they stack exactly as their groups +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. @@ -909,7 +925,7 @@ kept in place in another group. Another very interesting use of a group as a transformation tool is to manage a window coordinate space where the origin is not in the top left corner and where the Y axis goes -from bottom to top. It is quite simple to write a function that is triggerred on the +from bottom to top. It is quite simple to write a function that is triggerred on the window resize event whose only goal is to compute a new transformation for the group. Other parts of the application and the other items are not aware of this happening. A good factorisation example. @@ -925,7 +941,7 @@ 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 +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 @@ -940,7 +956,7 @@ 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 +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 @@ -951,7 +967,7 @@ practice to apply these transformations to different groups. For example, a grou 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 +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. @@ -977,7 +993,7 @@ to the scale and rotation factors of the transformation. 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 +(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 @@ -995,8 +1011,8 @@ a given transformation problem before coding it as part of a complex application 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}, +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 @@ -1043,7 +1059,7 @@ 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 +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 @@ -1054,16 +1070,15 @@ 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. - +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)"); + ($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 +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} @@ -1075,87 +1090,119 @@ 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} -A special form of tag called a pathtag can be used as a tagOrId argument in all +\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 the effective tag, in the usual sense. - - The path is an ordered list of tags set up on groups that drives the search - from the top 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 top 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 the search in a - specific sub-hierarchy. - - The last tag of a pathtag, the one not followed by a dot or star is the - effective tag searched for. It can be omitted, in this case the search - proceed with the tag all. The dot or star just before the effective tag, - even if the tag is implied, controls how the tag is searched. If a dot is - present, the search is limited to the current group level. If a star is - present, the search proceed from the current group level down the whole - group subtree. - -Here are some commonly used pathtags idioms: +items in the absolute item hierarchy. The pathTag consists in a path down the +group hierarchy followed by an (optionnal) effective tag, in the usual sense. + +The path is an ordered list of tags set up on groups that drives the search +from the root group down the group hierarchy. The path starts with either a dot +or a star, and the tags in the path are separated by dots or stars. The dot +means that the next tag selects a group item that is a direct child of the +current group, starting with the root group. The star selects a group item that +is a possibly indirect child of the current group, the candidate is found +in display list order. The first tag in the path, the one just after the first +dot or star, can be a group id; This is useful in order to limit the search in a +specific sub-hierarchy. + +The last tag of a pathTag, the one not followed by a dot or a star, is the +effective tag searched for. It can be omitted, in this case the search +proceed with the tag all. The dot or star just before the effective tag, +even if the tag is implied, controls how the tag is searched. If a dot is +present, the search is limited to the current group level. If a star is +present, the search proceed from the current group level down the whole +group subtree. + +Here are some commonly used pathTags idioms: -\begin{itemize} -\item{\bf .group1Tag.group2Tag.aTag} Selects all direct children with the tag aTag in -the group obtained by following the path .group1Tag.group2Tag from the top group. -The search proceed from the top group to the first direct child group in display -list order with tag group1Tag. Then it searches for the first direct child group -with tag group2Tag. Finally in this group, the search ends by finding all direct -children items (including groups) with tag aTag. If a tag is not found the whole +\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{\bf .group1Tag.group2Tag*aTag} Selects all children with the tag aTag in -the group obtained by following the path .group1Tag.group2Tag from the top group. -\item{\bf .group1Tag*group2Tag.aTag} Selects all direct children with the tag aTag in -the group obtained by following the path .group1Tag*group2Tag from the top group. -The search proceed from the top group to the first direct child group in display -list order with tag group1Tag. Then it searches in display list order down the -hierearchy for the first group with tag group2Tag . Finally in this group, the -search ends by finding all direct children items (including groups) with tag aTag. - If a tag is not found the whole search is aborted and no item is selected. -\item{\bf .group1Tag*group2Tag*aTag} Selects all items with the tag aTag in the hierarchy -of the group obtained by following the path .group1Tag*group2Tag from the top -group. The search proceed from the top group to the first direct child group in -display list order with tag group1Tag. Then it searches in display list order down -the hierearchy for the first group with tag group2Tag . Finally in this group, the -search ends by finding all direct children items (including groups) with tag aTag. - If a tag is not found the whole search is aborted and no item is selected. -\item{\bf .group1Tag.group2Tag.} Selects all direct children of the group obtained - by following the path .group1Tag.group2Tag from the top group. If a tag is not - found the whole search is aborted and no item is selected. -\item{\bf .group1Tag.group2Tag*} Selects all items in the hierarchy of the group obtained - by following the path .group1Tag.group2Tag from the top group. If a tag is not - found the whole search is aborted and no item is selected. -\item{\bf .groupId.aTag} Selects all direct children with tag aTag of the group with - id groupId. - If 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 + +\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 -componentId.subComponentName or perhaps better componentId*subComponentName. Some -care is in order to avoid sub-component name clash, remember that the search for -tags proceed in display list order, not in hierarchy order. In other more -technical words the search walks the item tree depth first not breadth first. -\item{\bf .groupId*aTag} Selects all items with tag aTag in the hierarchy of the - group with id groupId. If groupId is not found or is not a group id, the search - is aborted and no item is selected. -\item{\bf .} Selects all direct children of the top group -\item{\bf *} Selects all items in the hierarchy (not counting the top group - itself). -\item{\bf .aTag} Selects all direct children of the top group with the tag aTag. -\item{\bf *aTag} Selects all items in the whole hierarchy (starting a the top group) - with the tag aTag. It is the same as using the simple tag aTag. -\end{itemize} +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. @@ -1168,7 +1215,7 @@ pointer, if any; keyboard events are dispatched to the focus item, if any; leave 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 +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. @@ -1233,7 +1280,7 @@ item. Indices are accepted as parameters by commands managing text: \cmdref{curs \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 + \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}} @@ -1386,9 +1433,9 @@ reference) and all list parameters are given as array references. string. Many commands take a group as a starting point for the search. If no - group is given, the top group is assumed. In any cases, the starting + group 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 - top group will never be reported in a search and that tags cannot be + 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 @@ -1417,15 +1464,15 @@ reference) and all list parameters are given as array references. Selects all the items at the given priority. The tagOrId optional parameter can be specified to restrict the search. It specifies a - group to start with instead of the top group and it can be used to - control if the search should be recursive or not (see pathtags for + 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 + 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. @@ -1464,7 +1511,7 @@ reference) and all list parameters are given as array references. origin is at {\tt xo - yo} and corner at {\tt xc - yc}. {\tt xc} must be no greater than {\tt xo} and {\tt yo} must be no greater than {\tt yc}. All coordinates must be integers. inGroup specifies - a group to start with instead of the top group and recursive tells + a group to start with instead of the root group and recursive tells if the search should descend in the item tree or not. recursive is true by default. @@ -1481,7 +1528,7 @@ reference) and all list parameters are given as array references. whose origin is at {\tt xo - yo} and corner at {\tt xc - yc}. {\tt xc} must be no greater than {\tt xo} and {\tt yo} must be no greater than {\tt yc}. All coordinates must be integers. inGroup specifies - a group to start with instead of the top group and recursive tells + a group to start with instead of the root group and recursive tells if the search should descend in the item tree or not. recursive is true by default. @@ -1499,8 +1546,8 @@ reference) and all list parameters are given as array references. Selects all the items of type {\tt type}. The tagOrId optional parameter can be specified to restrict the search. It specifies a - group to start with instead of the top group and it can be used to - control if the search should be recursive or not (see pathtags for + 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} @@ -1548,10 +1595,10 @@ reference) and all list parameters are given as array references. \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 + 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 + augments the existing binding instead of replacing it. In this case the command returns an empty string. If the {\tt command} parameter is omitted, the command return the {\tt command} associated with {\tt tagOrId} and {\tt sequence} or an error is raised if there is no such binding. If only {\tt tagOrId} is specified the command returns a list of all @@ -1561,7 +1608,7 @@ reference) and all list parameters are given as array references. Zinc items instead of widgets. Another difference with the \ident{bind} command is that only mouse and keyboard related events can be specified (such as \ident{Enter}, \ident{Leave}, \ident{ButtonPress}, \ident{ButtonRelease}, \ident{Motion}, - \ident{KeyPress}, \ident{KeyRelease}). The \ident{bind} manual page is the most + \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. @@ -1573,7 +1620,7 @@ reference) and all list parameters are given as array references. 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 + 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 @@ -1604,7 +1651,7 @@ reference) and all list parameters are given as array references. \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 +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 @@ -1617,12 +1664,12 @@ false. {\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 + 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 + order (display list order of the models). No item id will be returned for items cloned in the hierarchy of cloned groups. \end{blockindent} @@ -1654,7 +1701,7 @@ false. 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} + {\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 @@ -1705,7 +1752,7 @@ false. {\tt\large \$zinc->{\bf coords}(tagOrId, ?add/remove?, ?contour?, ?index?, ?coordList?);} \begin{blockindent} - Query or changes the coordinates of the item described by {\tt tagOrId}. If {\tt + Query or changes the coordinates of the item described by {\tt tagOrId}. If {\tt tagOrId} describes more than one item, the first in display list order is used. The optional {\tt contour} gives the contour, if available, that should be operated. The default contour is 0. The optional {\tt index} gives the vertex index that should be @@ -1727,7 +1774,7 @@ false. contours (currently all except curves) the {\tt contour} parameter should be omitted or specified as zero. - The optional parameters must be combined to produce a given behavior. Here are the + The optional parameters must be combined to produce a given behavior. Here are the various form recognized by the command: \begin{itemize} @@ -1743,7 +1790,7 @@ false. \$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, + zero. Curves can handle other contours. For groups, icons, texts, windows, tabulars, reticles, tracks, waypoints, only the first vertex will be used. For rectangles and arcs, only the first two vertices will be used. Beziers and curves can handle any number of vertices. @@ -1753,8 +1800,8 @@ false. (\$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 + contourIndex is zero. Curves can handle other contours. For groups, icons, texts, + windows, tabulars, reticles, tracks, waypoints, coordIndex must be zero. For rectangles and arcs, index must zero or one. \item{\tt\large @@ -1762,8 +1809,8 @@ false. \$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 + 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 @@ -1823,9 +1870,9 @@ false. {\tt\large \$num = \$zinc->{\bf currentpart}();} \begin{blockindent} - Returns a string specifying the item part that has the pointer. If the current item + Returns a string specifying the item part that has the pointer. If the current item doesn't have parts or if the pointer is not over an item (no item has the - \ident{current} tag) the command return {\tt ""}. The string can be either an integer + \ident{current} tag) the command return {\tt ""}. The string can be either an integer describing a field index or the name of a special part of the item. Consult each item description to find out which part names can be reported. \end{blockindent} @@ -1851,8 +1898,8 @@ false. \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 + 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} @@ -1878,13 +1925,12 @@ false. \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:\\ + 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:\\ + \# to get direct children of an atomic group with a pathTag:\\ @children = \$zinc->find('withtag', ''.\$atomicGroup.''); } @@ -1933,9 +1979,9 @@ false. in {\tt coordList} and returns a list of vertices describing the control points for the generated segments. All the points on the fitted segments will be within {\tt error} distance from the given curve. {\tt coordList} should contain a pair number of - coordinates in x, y order. The returned control point list consists of four control + coordinates in x, y order. The returned control point list consists of four control points per Bezier segment with two consecutive segments sharing their last/first control - point. The control points are in x, y order and can be used to create or change a + point. The control points are in x, y order and can be used to create or change a Bezier item. \end{blockindent} @@ -1948,8 +1994,8 @@ false. \begin{blockindent} Set the keyboard focus to the item described by {\tt tagOrId}. If {\tt tagOrId} describes more than one item, the first item in display list order that accept the focus is - used. If no such item exists, the command has no effect. If {\tt tagOrId} is an empty - string the focus is reset and no item has the focus. If {\tt tagOrId} is not specified, + 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. @@ -2008,7 +2054,7 @@ false. {\tt\large \$group = \$zinc->{\bf group}(tagOrId);} \begin{blockindent} - Returns the group containing the item described by {\tt tagOrId}. If more than one item + 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} @@ -2057,7 +2103,7 @@ false. \begin{blockindent} This command returns a number which is the numerical index in the item described by {\tt tagOrId} corresponding to {\tt index}. The possible forms for {\tt index} are described - in \conceptref{Text indices}{indices}. The command return a value between 0 and the + in \conceptref{Text indices}{indices}. The command return a value between 0 and the number of character in the item. If {\tt tagOrId} describes more than one item, the index is processed in the first item supporting text indexing in display list order. \end{blockindent} @@ -2070,8 +2116,8 @@ false. \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. + 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} @@ -2086,7 +2132,7 @@ false. 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 + 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} @@ -2102,7 +2148,7 @@ false. \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 + 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 @@ -2111,7 +2157,7 @@ false. If at least one attribute - value pair is given, then the corresponding attributes are changed for all the items described by {\tt tagOrId} and the command return an empty - string. If {\tt field} is given, it must be a valid field index for the item or an + string. If {\tt field} is given, it must be a valid field index for the item or an error will be reported. If a field index is given, the command will interpret the given attributes as field attributes, otherwise they will be interpreted as item attributes. If an attribute does not belong to the item or field, it will be silently ignored. This @@ -2128,12 +2174,12 @@ false. 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} + 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} + 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} @@ -2160,7 +2206,7 @@ false. \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 + 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} @@ -2191,9 +2237,9 @@ false. 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} + command returns an empty string. As a side affect of this command, the \ident{-priority} attribute of all the reordered items is ajusted to match the priority of the {\tt - aboveThis} item (or the priority of the top most item). + aboveThis} item (or the priority of the topmost item). \end{blockindent} @@ -2216,7 +2262,7 @@ false. tagOrId} describes a named transform then this transform is used to do the operation. If {\tt tagOrId} describes more than one item then all the items are affected by the operation. If {\tt tagOrId} describes neither a named transform nor an item, an error is - raised. The angle is given in radians. The optional parameters describe the center of + raised. The angle is given in radians. The optional parameters describe the center of rotation, which defaults to the origin. \end{blockindent} @@ -2229,7 +2275,7 @@ false. Add a scale factor to the items or the transform described by {\tt tagOrId}. If {\tt tagOrId} describes a named transform then this transform is used to do the operation. If {\tt tagOrId} describes more than one item then all the items are affected by the - opration. If {\tt tagOrId} describes neither a named transform nor an item, an error is + operation. If {\tt tagOrId} describes neither a named transform nor an item, an error is raised. A separate factor is specified for X and Y. \end{blockindent} @@ -2244,7 +2290,7 @@ false. 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 + valid index as described in \conceptref{Text indices}{indices}. The valid forms of the command are : \begin{itemize} @@ -2305,10 +2351,10 @@ false. \begin{blockindent} This command computes a sequence of Bezier segments in order to smooth the curve described by the vertices in {\tt coordList} and returns a list of vertices describing - the control points for the generated segments. {\tt coordList} should contain a pair - number of coordinates in x, y order. The returned control point list consists of four + the control points for the generated segments. {\tt coordList} should contain a pair + number of coordinates in x, y order. The returned control point list consists of four control points per Bezier segment with two consecutive segments sharing their last/first - control point. The control points are in x, y order and can be used to create or change + control point. The control points are in x, y order and can be used to create or change a Bezier item. \end{blockindent} @@ -2341,7 +2387,7 @@ false. 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 + tagOrIdTo}. If {\tt tagOrIdFrom} is omitted it defaults to the window coordinate space. If either {\tt tagOrId} describes more than one item, the topmost in display list order is used. If {\tt tagOrId} doesn't describe either a transform or an item, an error is raised. The {\tt coordList} should contains an even number of coordinates each point @@ -2433,9 +2479,9 @@ false. {\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 + 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. + is returned. If no items are named by {\tt tagOrId}, an error is raised. \end{blockindent} @@ -2445,7 +2491,7 @@ false. \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 + 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 @@ -2564,13 +2610,13 @@ positions. This track also shows a marker, the circle around the current positio %%% XXX CM add here an image with a openGL track (end ticks,... antialising...) An other very important feature of \ident{track} item is that Zinc offers an -anti-overlap manager. This manager tries to avoid any overlap of tracks labels. It also +anti-overlap manager. This manager tries to avoid any overlap of tracks labels. It also avoids that the label overlap the speedvector. This manager is stable over time: there should be few cases where labels are moved to a very different position. This manager applies to all tracks included in a group (by default the group 1). It can be enabled/disabled with the attributes XXX. New labels positions are computed by the overlap manager every time a track is moved, a track is created or destroyed and every time the -Zinc widget is resized. Due to software licence limitation, Zinc \emph{do not include} +Zinc widget is resized. Due to software licence limitation, Zinc \emph{do not include} the very last version of this anti-overlap manager. If you are interested in this anti-overlap manager, please contact Didier Pavet at {\tt pavet@cena.fr}. @@ -2599,7 +2645,7 @@ default value is the current value of the widget option \optref{forecolor}.} 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 +\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 @@ -2704,7 +2750,7 @@ is {\tt "0 0"}.} \attribute{track}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 5}.} -\attribute{track}{sensitive}{boolean}{Specifies if the item should react to events. The +\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 @@ -2723,7 +2769,7 @@ sensitive. The actual sensitivity is the logical \ident{and} of this attribute a 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} +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}.} @@ -2755,7 +2801,7 @@ displayed. The default value is {\tt 6}.} 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 +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: @@ -2791,7 +2837,7 @@ composed with the local transform. The default value is {\tt true}. } composed with the local transform. The default value is {\tt true}. } \attribute{waypoint}{connecteditem}{item}{The item at the other end of the connection -link. The default value is {\tt ""} which means that no connection link will be drawn.} +link. The default value is {\tt ""} which means that no connection link will be drawn.} \attribute{waypoint}{connectioncolor}{gradient}{The color of the connection link. The default value is the current value of the widget option \optref{forecolor}.} @@ -2818,7 +2864,7 @@ attribute to specify a position for the label anchor with respect to the item or There is another alternative method for label positioning which is implemented with the {\tt labeldx} and {\tt labeldy} methods. Simultaneous use of the two methods should be done with care as there is no automatic update of values from the {\tt labeldx}, {\tt -labeldy} set to the {\tt labeldistance}, {\tt labelangle} set. The default value is {\tt +labeldy} set to the {\tt labeldistance}, {\tt labelangle} set. The default value is {\tt 20}.} \attribute{waypoint}{labeldistance}{dimension}{The minimum distance in pixels between the @@ -2869,12 +2915,12 @@ default value is the current value of the widget option \optref{forecolor}.} 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.} +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.} +label. This attribute is read only.} \attribute{waypoint}{position}{point}{The current location of the way point. The default value is {\tt "0 0"}.} @@ -2947,7 +2993,7 @@ connected item specified). The default value is {\tt "0 0"}.} \attribute{tabular}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 3}. } -\attribute{tabular}{sensitive}{boolean}{Specifies if the item should react to events. The +\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 @@ -2960,14 +3006,14 @@ 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 +Text items are used for displaying text. They can also be used for text input. In this +case, they must get the focus for keyboards events with the command \cmdref{focus}. Many Zinc options (see chapter \conceptref{Widget options}{options} can be used for configuring the text input (for example : \optref{insertbackground}, \optref{insertofftime} \optref{insertontime}, \optref{insertwidth}). A perl module, called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext}) is provided for easing text input in text items (it can also be used for text input in labelled items such as \objectref{track}, -\objectref{waypoints} or \objectref{tabular}). +\objectref{waypoint} or \objectref{tabular}). Applicable attributes for \ident{text} are: @@ -3012,7 +3058,7 @@ connected item specified). The default value is {\tt "0 0"} (Tcl/Tk) or {\tt [0, \attribute{text}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} -\attribute{text}{sensitive}{boolean}{Specifies if the item should react to events. The +\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 @@ -3034,7 +3080,7 @@ 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}.} +must be inserted in the text to have multiple lines. The default value is {\tt 0}.} \section{Icon items} @@ -3075,7 +3121,7 @@ has precedence over the {\tt mask} option if both are specified. The default val ""}.} \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 +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 ""}.} @@ -3085,7 +3131,7 @@ connected item specified). The default value is {\tt "0 0"} (Tcl/Tk) or {\tt [0, \attribute{icon}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} -\attribute{icon}{sensitive}{boolean}{Specifies if the item should react to events. The +\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 @@ -3127,7 +3173,7 @@ highlighted) circles. The default value is the current value of the widget optio \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 +\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 @@ -3143,7 +3189,7 @@ value is {\tt "0 0"}.} \attribute{reticle}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} -\attribute{reticle}{sensitive}{boolean}{Specifies if the item should react to events. The +\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 @@ -3165,7 +3211,7 @@ Map items are used for XXX. Applicable attributes for \ident{map} are: \attribute{map}{color}{gradient}{Specifies the color usedd to draw or fill the -map. The texts and symbols that are part of the map are also drawn in this color. The +map. The texts and symbols that are part of the map are also drawn in this color. The default value is the current value of the widget option \optref{forecolor}.} \attribute{map}{composealpha}{boolean}{Specifies if the alpha value inherited from @@ -3184,7 +3230,7 @@ drawn as thin lines. The default is {\tt false}.} 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}.} +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 @@ -3195,7 +3241,7 @@ displayed by the map.} \attribute{map}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 1}.} -\attribute{map}{sensitive}{boolean}{Specifies if the item should react to events. The +\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 ??}.} @@ -3212,7 +3258,7 @@ value is {\tt ""}.} Items of type \ident{rectangle} display a rectangular shape, optionally filled. The - rectangle is described by its bottom-left and top-right corners. + 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} @@ -3282,7 +3328,7 @@ value is {\tt true}.} \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 + 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. @@ -3296,7 +3342,7 @@ value is {\tt true}.} 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 +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 @@ -3323,11 +3369,11 @@ is {\tt false}.} 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 +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 +arc. This attribute is applicable only if the item is not closed and not filled. The default value is {\tt ""}.} \attribute{arc}{linecolor}{gradient}{Specifies the color that will be used to draw @@ -3350,7 +3396,7 @@ slice otherwise it will be drawn as a chord. The default value is {\tt false}.} \attribute{arc}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} -\attribute{arc}{sensitive}{boolean}{Specifies if the item should react to events. The +\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 @@ -3360,7 +3406,7 @@ expressed in degrees in the trigonometric system. The default value is {\tt 0}.} 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 +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 ""}.} @@ -3419,7 +3465,7 @@ This attribute is applicable only if the item is not closed, not filled and the 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 +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. @@ -3443,7 +3489,7 @@ scalable). The default value is {\tt 1}.} each vertex of the curve. This attribute is not applicable if the outline relief is not flat. The default value is {\tt ""} which means do not draw markers.} -\attribute{curve}{markercolor}{gradient}{Specifies the color of the markers. The +\attribute{curve}{markercolor}{gradient}{Specifies the color of the markers. The default value is the current value of the widget option \optref{forecolor}.} \attribute{curve}{priority}{priority}{The absolute position in the stacking order among @@ -3454,7 +3500,7 @@ outline. This attribute has priority over the \attributeref{curve}{linepattern} \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 +\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 @@ -3543,7 +3589,7 @@ outline. This attribute has priority over the \attributeref{bezier}{linepattern} \attributeref{bezier}{linestyle} attributes. The color of the relief is derived from the color in \attributeref{bezier}{linecolor}. The default value is {\tt flat}.} -\attribute{bezier}{sensitive}{boolean}{Specifies if the item should react to events. The +\attribute{bezier}{sensitive}{boolean}{Specifies if the item should react to events. The default value is {\tt true}.} \attribute{bezier}{tags}{taglist}{The list of tags associated with the item. The default @@ -3621,7 +3667,7 @@ value is {\tt true}.} Applicable attributes for \ident{window} items are: -\attribute{window}{anchor}{anchor}{The anchor used in positionning the item. The default +\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 @@ -3650,7 +3696,7 @@ 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 +\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 @@ -3663,7 +3709,7 @@ is {\tt true}.} 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 +the item. This id can be obtained by the Tk command \ident{winfo id widgetname}. The default value is {\tt ""}.} @@ -3679,7 +3725,7 @@ Zinc was initially developed for building interactive radar image working on X server. This requires very good performances, for displaying many hundred tracks and moving them every few seconds. Tracks are typically composed of some geometric parts and some textual parts. These two parts are connected together with a leader. The geometric -parts are subject to scaling. For example the speed vector length in pixel depends of the +parts are subject to scaling. For example the speed vector length in pixel depends on the scale. But the textual part must not be zoomed. Managing parts which are scaled and others which are not, can be a real challenge. Usual toolkits or widget are not suited to such behaviours, but Zinc is. @@ -3690,43 +3736,95 @@ Zinc introduces the concepts of label, labelformat, fields and fields attributes \section {Labels and labelformats} \concept{label} \concept{labelformat} -A label is a set of many textual parts attached to the following types of items: -\objectref{track}, \objectref{waypoint} and \objectref{tabular}. +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. -The textual parts of a label are called fields. The label and the geometry (size and -position)of the text fields are described by a labelformat. +Some label global characteristics are set/get at the item level: -The number of fields is a characteristic set at item creation time (see the command -\cmdref{add}). This characteristic cannot be modified after creation of the item. However -it can be read with the command \cmdref{numparts}. +\begin{itemize} +\item The maximum number of fields is defined at item creation, as the second +argument of the \cmdref{add} method. The field number can not be changed after creation. +These fields will be indexed from 0 to n-1. The number of fields can be read +with the command \cmdref{numparts}. For example: +\begin{verbatim} + $track = $zinc->add('track', 4, ....); + # this creates a track item with 4 fields, indexed from 0 to 3 +\end{verbatim} +\item The rectangular geometries of displayable fields are defined through +the item attribut \ident{-labelformat}. The value is a string following +the syntax of the \attrtyperef{labelformat} type. This attribute can be set at any time; +thus modifying its value is a way to quickly change the geometry (or the visibility) of +some fields. Fields may overlap. They are drawn according to the index order: +field 0 is drawn before (thus under) field 1. The labelformat also optionnaly +describes a clipping rectangle. For example: +\begin{verbatim} + $zinc->itemconfigure($track, -labelformat => 'a12a0+0+ x20x100>0 a2a0>1>0'); + ## ^ ^ ^ + ## field0 field1 field2 + # the labelformat indicates that only the first 3 fields will be displayed: + # field 0 expands for the size of the text + 12 pixels. + # It starts at the top left point + # field 1 has a size of 20x10 pixels. + # It is left aligned with field 0, just under field 0 + # field 2 expands for the size of the text + 2 pixels. + # It is adjacent to the right of field 1, just under field 0 +\end{verbatim} +\end{itemize} -The labelformat is an attribute of the item types supporting labels. As any other item -attribute, labelformat can be set at creation time. It can be set/modified at any time by -the command \cmdref{itemconfigure} and read with the command \cmdref{itemcget}. The value -of the labelformat attribute is a string (see the \attrtyperef{labelformat} type) -describing the geometry (position and size) of the label and the fields.\\ By modifying a -labelformat, you can : +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 make appear a hidden field, -\item hide a visible field, -\item enlarge or reduce the size of a field -\item switch between two fields -\item etc. +\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} -Fields can have bindings (see command \cmdref{bind}). It is also possible to know which -field the mouse cursor is over with the command \cmdref{currentpart}. Fields can be -configured by modifying their attributes as described by next section. A perl module, -called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext}) is provided for easing text input in text fields (it can also be -used for text input in \objectref{text} item). +As an example: +\begin{verbatim} + $zinc->itemconfigure($track, 0, -text => 'Hello World', + -color => 'white', + -backcolor => 'black', + -filled => 1); + # this should display ``Hello World'' in white on black in field 0 +\end{verbatim} + +It is possible to bind callbacks to fields, with the command \cmdref{bind} and +special tags (described \conceptref{Tags and bindings}{tagsAndBindings}). +As an example: +\begin{verbatim} + $zinc->bind("$track:1", '<1>', \&acallback); + # this binds &acallback to field 1 +\end{verbatim} + +Inside a callback function, it is possible to know which field the mouse cursor is over +with the command \cmdref{currentpart}. + +A perl module, called Tk::ZincText (see the section \conceptref{ZincText.pm}{zinctext}) +is provided for easing text input in text fields (it can also be used for easing text input +in \objectref{text} item). \section{Attributes for fields} \object{field} +\concept{fieldAttributes} -Fields are item parts of items supporting labelformat (i.e. \objectref{track}, -\objectref{waypoint} and \objectref{tabular}). They can be configured in a similar way of +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 @@ -3740,7 +3838,7 @@ Applicable attributes for fields are: 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 +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 @@ -3749,7 +3847,7 @@ 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 ""}.} +of the border. The default value is {\tt ""}.} \attribute{field}{bordercolor}{gradient}{ The border color. The default value is the current value of the widget option \optref{forecolor}.} @@ -3786,7 +3884,7 @@ 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 ""}.} +\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}.} @@ -3809,7 +3907,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{alignment} \begin{blockindent} - Specifies the horizontal alignment of an entity. The legal values are: {\tt left}, {\tt + Specifies the horizontal alignment of an entity. The legal values are: {\tt left}, {\tt right}, {\tt center}. \end{blockindent} @@ -3822,7 +3920,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{anchor} \begin{blockindent} Specifies one of the nine caracteristic points of a rectangle or a bounding box that will - be used to position the object. These points include the four corners, the four edge + 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} @@ -3850,7 +3948,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \begin{blockindent} This should be a string naming a valid Tk bitmap. The bitmap should be known to Tk prior to its use. Zinc registers a set of bitmaps that can be used for any bitmap valued - attribute (see \ref{builtinbitmaps}). Extensions to Tk are available to create or + 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} @@ -3916,7 +4014,6 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{gradient} \begin{blockindent} This is a string describing a color gradient to be used for example to fill a surface. - The string may consist in a single color name that will be used to paint a solid surface or can be a list of gradient steps separated by \verb+|+ characters. @@ -3929,7 +4026,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \verb+gradient_step1|...|gradient_stepn[x y+ for a path gradient. The \verb+/angle+ section tells that the gradient is an axial gradient and give the - angle of the gradient. + angle of the gradient in degres. The \verb+(x y+ section tells that the gradient is a radial gradient and give the center of the gradient. @@ -3950,14 +4047,14 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} 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 + specification. The position can thus be safely omitted for these segments. The in between segments must have a position explicitly set. If not given, a position will default to 0. The mid span position tells where in the current gradient segment should be the median color. The position is given in percentage of the current gradient segment distance. The mid span position can be used to obtain a non linear gradient segment, this is - useful to describe relief shapes. This parameter can be omitted in which case it + 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 @@ -3965,7 +4062,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} The following picture gives many examples of gradients. They correspond to the following values: -\verb+axial 1 : 'black|white/90'+ +\verb+axial 1 : 'black|white/0' := 'black|white'+ \verb+axial 2 : 'black|white/90'+ @@ -3994,7 +4091,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{image} \begin{blockindent} This should be the name of a previously registered Tk image. In pure Tk only GIF, PPM - and bitmap formats are available as source for images. With the Img extension many + and bitmap formats are available as source for images. With the Img extension many others popular formats are added including JPEG, XPM and PNG. \end{blockindent} @@ -4012,15 +4109,15 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{labelformat} \begin{blockindent} - The new format is as follow. Parameters between \verb+[]+ are optional and take default values - when omitted. The spaces can appear between blocks but not inside. + 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 (0). + the only displayed field which index is 0. \verb+<fieldiSpec> ::= <fieldiSize>[<fieldiPos>]+ @@ -4103,10 +4200,10 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{lineend} \begin{blockindent} - Describes the shape of the arrow at the beginning or end of a path. This is a list of + 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 + from outside edge of the line to the trailing points (see canvas). If an empty list is given, there is no arrow. \end{blockindent} @@ -4123,7 +4220,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \attrtype{linestyle} \begin{blockindent} - Describes the style of the dashes that should be used to draw a line. The possible + 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} @@ -4208,7 +4305,7 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} \mapinfocmd{mapInfoName}{duplicate}{newName} \begin{blockindent} - Create a new mapinfo that is a exact copy of the mapinfo named {\tt mapInfoName}. The + 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} @@ -4253,14 +4350,14 @@ by any new user of Zinc: \attrtyperef{gradient} and \attrtyperef{labelformat}.} 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. + {\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 + 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} @@ -4323,7 +4420,7 @@ bitmaps sets (used as symbols for some items or used as stipples), Perl modules and Zinc simple demonstrations. \section{Bitmaps} -\label{builtinbitmaps} +\concept{builtinbitmaps} Zinc creates two sets of bitmaps. @@ -4347,11 +4444,11 @@ named AlphaStipple0 to AlphaStipple15, AlphaStipple0 being the most transparent. \ident{ZincDebug.pm} is a Perl module useful for debugging purpose. It can be used in a Perl application using Zinc to grab items with the mouse and to get the list of -items enclosed or overlapped by a rectangle designated by the mouse. You will be +items enclosed or overlapped by a rectangle designated by the mouse. You will be presented an item list, with many interesting attributes such as position, priority, -visibility, group... and even more information on request. When an application uses +visibility, group...\ and even more information on request. When an application uses \ident{ZincDebug.pm}, you can get a short reminder by depressing the {\tt Esc} key in -the main window of this application. Please refer to the \ident{ZincDebug.pm} man pages +the main window of this application. Please refer to the \ident{ZincDebug.pm} man pages with the classical command {\tt man ZincDebug} \section{zinc-demos} |