diff options
| -rw-r--r-- | doc/refman.tex | 173 |
1 files changed, 117 insertions, 56 deletions
diff --git a/doc/refman.tex b/doc/refman.tex index 1f01e5d..3be4b21 100644 --- a/doc/refman.tex +++ b/doc/refman.tex @@ -241,11 +241,14 @@ Since the 3.2.3 version, \ident{zinc} also offers the support of some openGL features such as transparency, color gradient and even a new item type : \objectref{triangles}. You need the support of the GLX extension on your X11 server. Of course, performances will be dependant of your graphic card. At time of writing, NVidia drivers -for XFree86 R4.1 are doing a nice job. A labtop with an ATI mobility graphic card works nice. +for XFree86 R4.1 are doing a nice job. A laptop with an ATI mobility graphic card works nice. We also succeded in using zinc with openGL on the Exceed X11 server (running on windows and developped by Hummingbird) with the 3D extension. -As an exemple to \ident{zinc} capabilities when combined with openGL, we reproduced in \ident{ZincLogo.pm} a perl module, the tk Zinc logo. This logo (see just below) was designed with Illustrator (from Adobe) and then programmed as a perl module. It is now part delivered as a \ident{zinc} goodies. +As an exemple of \ident{zinc} capabilities when combined with openGL, we reproduced in + \ident{ZincLogo.pm} a perl module, the tk Zinc logo. This logo (see just below) was designed + with Illustrator (from Adobe) and then programmed as a perl module. It is now delivered + as a \ident{zinc} goodies. \ifpdf \includegraphics{tkzinclogo} @@ -378,7 +381,7 @@ or in the option database to modify the global behavior of the widget. Available options are described below in this chapter. Any new \ident{zinc} widget comes with an initial group, always identified by -the same ID: 1. This group will contain all other items, either directly or +the id 1. This group will contain all other items, either directly or indirectly through other groups created themselves (directly or in other groups... ) in group 1. The chapter \conceptref{Groups, Display List and Transformations}{coordinates} describes the use of groups) @@ -399,7 +402,7 @@ describes the use of groups) This is the color that will be used to fill the zinc window. It is also used as a default color for some item attributes of type color. See each color attribute for the actual source of the default color. Its default - value is white XXX. + value is white. \end{blockindent} \option{cursor}{cursor}{Cursor} @@ -498,7 +501,8 @@ describes the use of groups) 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 AtcSymbol19 (see \conceptref{Resources}{otherresources}). + 10 nautic miles. The default value is AtcSymbol19 + (see \conceptref{Resources}{otherresources}). \end{blockindent} \option{maptextfont}{mapTextFont}{MapTextFont} @@ -533,7 +537,9 @@ describes the use of groups) \begin{blockindent} Specifies whether to use or not the openGL rendering. When True, requires the GLX extension to the X server. Must be defined at widget creation time. - This option is readonly. The default value is False + This option is readonly and can be used to ask if the widget is running + GLX or X (to adapt the application code for example). + The default value is False. \end{blockindent} \option{reshape}{reshape}{Reshape} @@ -708,7 +714,7 @@ Parler de current, all. \concept{indices} \chapter{Indices} -XXX c'est quoi? +XXX c'est quoi? Voir la commande index. \concept{commands} \chapter{Widget commands} @@ -770,9 +776,11 @@ reference) and all list parameters are given as array references. giving the coordinates of the origin and the corner of the rectangle. \item{\bf triangles} \\ The triangles type expects a list of (at least 6) floating point numbers ``x0 y0 x1 y1 ... xn yn'', - giving the coordinates of the corner of the triangles composing this item. The way - of placing the triangles is defined by the attribute \ident{fan}. This item requires that - \ident{zinc} uses openGL (see the option \ident{-render}). + giving the coordinates of the vertices of the triangles composing this item. The triangles layout + is defined by the attribute \ident{fan}. If \ident{fan} is true, the triangles are arranged in + a fan with the first point being the center and the other points defining the perimeter. + If \ident{fan} is false, the triangles are arranged in a strip. (Afficher un diagramme avec l'ordre + des sommets). \item{\bf tabular, track, waypoint} \\ These types expects the number of fields they will manage in the label or tabular form. This number must be greater or equal to zero. @@ -823,7 +831,7 @@ reference) and all list parameters are given as array references. \item{\bigskip {\tt\large pathname {\bf addtag} tag all ?inGroup? ?recursive?\\ \$zinc->{\bf addtag}(tag, 'all', tagOrId, ?inGroup?, ?recursive?);\\ - }} + }} Selects all the items in the widget. The inGroup and recursive can be specified to restrict the search. inGroup specifies a group to start with instead of the top group and recursive tells @@ -881,7 +889,7 @@ reference) and all list parameters are given as array references. \item{\bigskip {\tt\large pathname {\bf addtag} tag overlapping xo yo xc yc\\ \$zinc->{\bf addtag}(tag, 'overlapping', xo, yo, xc, yc);\\ - }} + }} Selects all the items that overlaps or are enclosed in the rectangle whose origin is at {\tt xo - yo} and corner at {\tt xc - yc}. {\tt xc} must be no greater than {\tt xo} and {\tt yo} must be no greater than @@ -1289,7 +1297,7 @@ reference) and all list parameters are given as array references. {\tt searchCommand} and the various {\tt args}. The items are sorted in drawing order, topmost first. - For example: \$zinc->find('withtag', 'current'); \# returns the item under the mousxe cursor. XXX + For example: \$zinc->find('withtag', 'current'); \# returns the item under the pointer. \end{blockindent} @@ -1309,6 +1317,7 @@ reference) and all list parameters are given as array references. Bezier item. \end{blockindent} +\zinccmd{focus}{?tagOrId?} {\tt\large \$item = \$zinc->{\bf focus}();}\\ {\tt\large \$zinc->{\bf focus}(tagOrId);} @@ -1321,15 +1330,14 @@ reference) and all list parameters are given as array references. If {\tt tagOrId} is not specified, the command returns the id of the item with the focus or an empty string if no item has the focus. - When the focus has been set to a text item, the text item will display an insertion cursor - and the keyboard events will be directed to that item. + When the focus has been set to a text item, the text item will display an + insertion cursor and the keyboard events will be directed to that item. - The widget receive keyboards - events only if it has the window focus. It may be necessary to use the Tk focus - command to force the focus to the widget window. + The widget receive keyboard events only if it has the window focus. It may be + necessary to use the Tk focus command to force the focus to the widget window. - NB: currently (Version 3.2.3e) only text item are really getting the focus. Focus will - be extended to many/all other items in a near future. + NB: currently (Version 3.2.3) only text items are really getting the focus. Focus + will be extended to many/all other items in a near future. \end{blockindent} @@ -1553,14 +1561,11 @@ reference) and all list parameters are given as array references. {\tt\large \$bool = \$zinc->{\bf numparts}(tagOrId);} \begin{blockindent} - This command tells how many private fieldId are available for event bindings - or for field configuration commands - in the item specified by {\tt tagOrId}. - If more than one item is named - by {\tt tagOrId}, the topmost in display list order is used to return the - result. If no items are named by {\tt tagOrId}, an error is raised. - This command should only be used for items supporting labelformat (i.e. - \objectref{track}, \objectref{waypoint} and \objectref{tabular}). + This command tells how many fieldId are available for event bindings + or for field configuration commands in the item specified by {\tt tagOrId}. + If more than one item is named by {\tt tagOrId}, the topmost in display + list order is used to return the result. If no items are named by + {\tt tagOrId}, an error is raised. \end{blockindent} \zinccmd{postscript}{} @@ -1612,26 +1617,26 @@ reference) and all list parameters are given as array references. {\tt tagOrId}. If {\tt tagOrId} describe a named transform then this transform is used to do the operation. If {\tt tagOrId} describe more than one item then all the items are affected by - the opration. If {\tt tagOrId} describe neither a named transform + the operation. If {\tt tagOrId} describe neither a named transform nor an item, an error is raised. The angle is given in radians. The optional parameters describe the center of rotation, which defaults to the origin. - When applying a rotation, items do not behave exactly the same maners. Textual elements do not - rotate. Only their anchor position moves according to the rotation: + When a rotation appears in a transformation, all items do not behave + exactly in the same manner. Textual and icon elements do not rotate. + Only their anchor position moves according to the rotation: \begin{itemize} - \item \ident{group} propagates the rotation to its children. - \item \ident{track} : the graphical part (i.e position, past positions, speedvector, marker) rotate. The label only move according to its new anchor position. - \item \ident{waypoint} : the position ``rotates''. The label move according to its new anchor position. - \item \ident{tabular} : The label move according to its new anchor position. - \item \ident{text} moves according to its new anchor position. - \item \ident{icon} moves according to its new anchor position. - \item \ident{reticle} rotates. - \item \ident{map} : lines and arcs rotate. Texts and symbols move according to their new anchor position. - \item \ident{rectangle} keeps being a rectangle (i.e. with vertice parallele to the X and Y axes, but its corners rotate. - \item \ident{arc}, \ident{curve}, and \ident{bezier} rotates. - \item \ident{window} DO NOT ROTATE. + \item \ident{track} The graphical part (i.e position, past positions, speedvector, marker) is fully + transformed. The label is computed relative to the new position. + \item \ident{waypoint} The position is fully transformed. The label is computed relative to the + new position. + \item \ident{tabular}, \item \ident{text}, \ident{icon} Only the anchor position is affected. + \item \ident{reticle} Only the center and the spacing between circles are affected. + \item \ident{map} lines and arcs are fully transformed. For texts and symbols only the position + is affected. + \item \ident{rectangle}, \ident{arc}, \ident{curve}, and \ident{bezier} are fully transformed. + \item \ident{window} Only the position is affected. \end{itemize} \end{blockindent} @@ -1760,9 +1765,16 @@ reference) and all list parameters are given as array references. in display list order is used. If {\tt tagOrId} doesn't describe either a transform or an item, an error is raised. - This command is the only one available to convert from/to device coordinates. - To do this conversion it is higly recommended not to apply a transformation to the - group 1, so that coordinates of group 1 map the device coordinates. + It is possible to convert from device coordinate space (i.e window coordinate + space) to the coordinate space of any item. This is done by omitting ?tagOrIdFrom? + an specifying in tagOrIdTo, the id of the item. + + It is also possible to convert from the coordinate space of an item to the + device coordinate space but it is a bit more tricky. In order to be able + to do so, the root group (the initial group of id 1) must not have any + transform. Its coordinate space is thus the device coordinate space. In this + case it is possible to use this group as the tagOrIdTo of the transform command to + obtain the desired effect. For example: XXX \end{blockindent} @@ -1851,18 +1863,22 @@ reference) and all list parameters are given as array references. The legal values are: {\tt left}, {\tt right}, {\tt center}. \end{blockindent} -\attrtype{alignment} -\begin{blockindent} - Specifies the horizontal alignment of an entity. - The legal values are: {\tt left}, {\tt right}, {\tt center}. -\end{blockindent} - \attrtype{alpha} \begin{blockindent} Specifies the transparency of an item. The value must be an integer from 0 (fully transparent) to 100 (fully opaque). \end{blockindent} +\attrtype{anchor} +\begin{blockindent} + Specifies one of the nine caracteristic points of a rectangle + or bounding box that will be used to position the object. + These points include the four corners the four edge centers + and the center of the rectangle. The possible values are: {\tt nw}, + {\tt n}, {\tt ne}, {\tt e}, {\tt se}, {\tt s}, {\tt sw}, {\tt w}, + {\tt center}. +\end{blockindent} + \attrtype{angle} \begin{blockindent} Specifies an angle in degrees, the value must be an integer from @@ -2251,7 +2267,7 @@ Group items are used for grouping objects together. Their usage is very powerfull and their use is best described in a previous chapter \conceptref{Groups, Display List and Transformations}{coordinates}. -Applicable attributes for \ident{group}: +Applicable attributes for \ident{group} are: \attribute{alpha}{alpha}{Specifies the transparency to apply to the group children. Needs the openGL extension. XXX alpha type to be defined} \attribute{atomic}{boolean}{Specifies if the group should report itself @@ -2319,7 +2335,7 @@ The following picture shows a simple \ident{track} with a label of 5 fields and An other very important feature of \ident{track} is that \ident{zinc} offers an anti-overlap manager. This manager tries to avoid any overlap of tracks labels. It also avoids that the label overlap the speedvector. This manager is stable over time: there should be few cases where labels are moved to a very different position. This manager applies to all tracks included in a group (by default the group 1). It can be enabled/disabled with the attributes XXX. New labels positions are computed by the overlap manager every time a track is moved, a track is created or destroyed and every time the \ident{zinc} widget is resized. Due to software licence limitation, \ident{zinc} {\bf DO NOT include} the very last version of this anti-overlap manager. -Applicable attributes for \ident{track} are: +Applicable attributes for \ident{track} \attribute{circlehistory}{boolean}{If set to true the track history will be plotted as cricles otherwise it will be plotted as squares. The default @@ -2552,7 +2568,12 @@ Applicable attributes for \ident{waypoint} are: Tabular items have been initially designed for displaying block of textual information, organised in lists or spread out on a radar display. -A tabular item is mainly composed waypoint is composed of a {\bf label} which is a block of texts described by a labelformat (see chapter \conceptref{Labels, fields and Label formats}{labelformat}. Each text can have its graphic decorations (alignment, background, images, borders...). This attributes are listed in the chapter \conceptref{Labels, label formats and fields}{labelformat} and can be changed by the command \cmdref{itemconfigure}. +A tabular item is mainly composed of a {\bf label} which + is a block of texts described by a labelformat (see chapter + \conceptref{Labels, fields and Label formats}{labelformat}. + Each text can have its graphic decorations (alignment, background, images, borders...). + This attributes are listed in the chapter \conceptref{Labels, label formats and fields}{labelformat} + and can be changed by the command \cmdref{itemconfigure}. Applicable attributes for \ident{tabular} are: @@ -2585,7 +2606,11 @@ Applicable attributes for \ident{tabular} are: \object{text} \section{Text items} -Text items are used for displaying text. They can also be used for text input. In this case, they must get the focus for keyboards events with the command \cmdref{focus}. Many \ident{zinc} options (see chapter \conceptref{Widget options}{options} can be used for configuring the text input (for example : \refopt{insertbackground} \refopt{insertofftime} \refopt{insertontime} \refopt{insertwidth}). +Text items are used for displaying text. They can also be used for text input. + In this case, they must get the focus for keyboards events with the command \cmdref{focus}. + Many \ident{zinc} options (see chapter \conceptref{Widget options}{options} can be used + for configuring the text input (for example : \refopt{insertbackground}, \refopt{insertofftime} + \refopt{insertontime}, \refopt{insertwidth}). Applicable attributes for \ident{text} are: @@ -3099,8 +3124,16 @@ Applicable attributes for \ident{window} are: The default value is {\tt ""}.} +<<<<<<< variant A \concept{mapinfocmds} \chapter{The mapinfo commands} +>>>>>>> variant B +\chapter{The mapinfo command} +\label{mapinfocmd} +####### Ancestor +\chapter{The \ident{mapinfo} command} +\label{mapinfocmd} +======= end MapInfo objects are used to describe graphical primitives that will be displayed in map items. It is possible to describe lines, arcs, symbols @@ -3213,8 +3246,14 @@ Applicable attributes for \ident{window} are: +<<<<<<< variant A \concept{videomapcmds} \chapter{The videomap commands} +>>>>>>> variant B +\chapter{The videomap command} +####### Ancestor +\chapter{The \ident{videomap} command} +======= end \command{videomap}{ids}{fileName} \begin{blockindent} @@ -3245,10 +3284,21 @@ Zinc creates two sets of bitmaps. The first set contains symbols for ATC tracks, maps and waypoints, these bitmaps are named AtcSymbol1 to AtcSymbol22. +<<<<<<< variant A \ifpdf \includegraphics{atcsymb} \else \latexhtml{ +>>>>>>> variant B +\ifpdf + \includegraphics{atcsymb} +\else +\latexhtml{% + \includegraphics{atcsymb.ps}}{% +####### Ancestor +\latexhtml{% + \includegraphics{atcsymb.ps}}{% +======= end \htmladdimg{atcsymb.png} } \fi @@ -3257,10 +3307,21 @@ The second set provides stipples that can be used to implement transparency, they are named AlphaStipple0 to AlphaStipple15, AlphaStipple0 being the most transparent. +<<<<<<< variant A \ifpdf \includegraphics{alphastip} \else \latexhtml{ +>>>>>>> variant B +\ifpdf + \includegraphics{alphastip} +\else +\latexhtml{% + \includegraphics{alphastip.ps}}{% +####### Ancestor +\latexhtml{% + \includegraphics{alphastip.ps}}{% +======= end \htmladdimg{alphastip.png} } \fi @@ -3279,7 +3340,7 @@ Please refer to the \ident{ZincDebug.pm} with the classical command \tt{man Zinc \section{zinc-demo} -Starting at version 3.2.3f of \ident{zinc} small applications are included as demos. They are all +Starting at version 3.2.4 of \ident{zinc} small applications are included as demos. They are all accessible through an application called \ident{zinc-demos}. These tiny demos are usefull for newcomers and as starting points. |