diff options
| -rw-r--r-- | doc/refman.tex | 485 |
1 files changed, 363 insertions, 122 deletions
diff --git a/doc/refman.tex b/doc/refman.tex index 3329c2a..ad6ba28 100644 --- a/doc/refman.tex +++ b/doc/refman.tex @@ -390,8 +390,17 @@ command set. Someone comfortable with the \ident{canvas} should not have much tr using the \ident{zinc}'s commands. Eventually, the command set will be a superset of the \ident{canvas} command set. -\vspace{.5cm} -\zinccmd{add}{?type group? ?args? ?option value? ... ?option? value?} +In the perl/tk version, the commands returning a list, return a perl array (not a +reference) and all list parameters are given as array references. + +\vspace{.5cm} +\zinccmd{add}{?type group? ?initargs? ?option value? ... ?option? value?} + +{\tt\large @types = \$zinc->{\bf add}();}\\ +{\tt\large \$id = \$zinc->{\bf add}(type, group);}\\ +{\tt\large \$id = \$zinc->{\bf add}(type, group, initargs);}\\ +{\tt\large \$id = \$zinc->{\bf add}(type, group, initargs, option=>value, ..., ?option=>value?);} + \begin{blockindent} This command is used to create new items in a zinc widget. It can be called with no parameters to return the list of all item types currently known by @@ -402,10 +411,12 @@ of the \ident{canvas} command set. After these first two parameters come some item type specific arguments. Here is detailed description of these arguments by type: \begin{description} - \item{arc} \\ + \item{\bf arc} \\ The arc type expects a list of four floating point numbers ``xo yo xc yc'', giving the coordinates of the origin and the corner of the enclosing rectangle. - \item{bezier} \\ + The origin should be the top left vertex of the enclosing rectangle and the + corner the bottom right vertex of the rectangle. + \item{\bf bezier} \\ The bezier type expects a list of floating point numbers ``x0 y0 x1 y1 ... xn yn'', giving the coordinates of the bezier segment controls. The number of values should be pair (or the last value will be discarded), and there should be at @@ -417,20 +428,20 @@ of the \ident{canvas} command set. If three points are left, a segment is drawn using the second point for the two off-curve controls. If two points are left, a line segment is drawn between the two. - \item{curve} \\ + \item{\bf curve} \\ The curve type expects a list of floating point numbers ``x0 y0 x1 y1 ... xn yn'', giving the coordinates of the curve vertices. The number of values should be pair (or the last value will be discarded) but the list can be empty to build an empty invisible curve. This curve can be defined later with the \cmdref{contour} or \cmdref{coords} commands. As a side effect of the curve behavior, a one vertex curve is essentially the same as an empty curve, it only waste some more memory. - \item{rectangle} \\ + \item{\bf rectangle} \\ The rectangle type expects a list of four floating point numbers ``xo yo xc yc'', giving the coordinates of the origin and the corner of the rectangle. - \item{tabular, track, waypoint} \\ + \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. - \item{group, icon, map, reticle, text, window} \\ + \item{\bf group, icon, map, reticle, text, window} \\ These types doesn't expect type specific arguments. \end{description} @@ -441,6 +452,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{addtag}{tag searchSpec ?arg arg ...?} + +{\tt\large \$zinc->{\bf addtag}(tag, searchSpec);} + \begin{blockindent} This command add the given tag to all items matching the search specification. If the tag is already present on some item, @@ -458,7 +472,10 @@ of the \ident{canvas} command set. take the following forms: \begin{description} - \item{\tt above tagOrId ?inGroup? ?recursive?} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag above tagOrId ?inGroup? ?recursive?\\ + \$zinc->{\bf addtag}(tag, 'above', tagOrId, ?inGroup?, ?recursive?); + \smallskip}} Selects the item just above the one given by {\tt tagOrId}. If {\tt tagOrId} names more than one item, the topmost of these items in the display list will be used. If {\tt tagOrId} does @@ -468,19 +485,28 @@ of the \ident{canvas} command set. group to start with instead of the top group and recursive tells if the search should descend in the item tree or not. - \item{\tt all ?inGroup? ?recursive?} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag all ?inGroup? ?recursive?\\ + \$zinc->{\bf addtag}(tag, 'all', tagOrId, ?inGroup?, ?recursive?); + \smallskip}} 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 if the search should descend in the item tree or not. - \item{\tt atpriority priority ?inGroup? ?recursive?} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag atpriority priority ?inGroup? ?recursive?\\ + \$zinc->{\bf addtag}(tag, 'atpriority', priority, ?inGroup?, ?recursive?); + \smallskip}} Selects all the items at the given priority. 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 if the search should descend in the item tree or not. - \item{\tt below tagOrId ?inGroup? ?recursive?} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag below tagOrId ?inGroup? ?recursive?\\ + \$zinc->{\bf addtag}(tag, 'below', tagOrId, ?inGroup?, ?recursive?); + \smallskip}} Selects the item just below the one given by {\tt tagOrId}. If {\tt tagOrId} names more than one item, the lowest of these items in the display list will be used. If {\tt tagOrId} does @@ -490,7 +516,10 @@ of the \ident{canvas} command set. group to start with instead of the top group and recursive tells if the search should descend in the item tree or not. - \item{\tt closest x y ?halo? ?start?} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag closest x y ?halo? ?startItem?\\ + \$zinc->{\bf addtag}(tag, 'closest', x, y, ?halo?, ?startItem?); + \smallskip}} Selects the item closest to the point {\tt x - y}. Any item overlapping the point is considered as closest and the topmost is selected. If {\tt halo} is given, it defines the size of the point {\tt x - y}. {\tt halo} must @@ -498,9 +527,12 @@ of the \ident{canvas} command set. an item tag or id. If it names a valid item (for a tag, the lowest item with the tag is considered), the search starts with the item below {\tt start} instead of the first item in the display - order. If {\tt start} does not name a valid item, it is ignored. + order. If {\tt startItem} does not name a valid item, it is ignored. - \item{\tt enclosed xo yo xc yc} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag enclosed xo yo xc yc\\ + \$zinc->{\bf addtag}(tag, 'enclosed', xo, yo, xc, yc); + \smallskip}} Selects all the items completely enclosed in the rectangle whose origin is at {\tt xo - yo} and corner at {\tt xc - yc}. {\tt xc} must be no greater than {\tt xo} and {\tt yo} must be no greater @@ -511,20 +543,29 @@ of the \ident{canvas} command set. the main loop or in a callback after modifying the transform or doing something else affecting the geometry of items). - \item{\tt overlapping xo yo xc yc} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag overlapping xo yo xc yc\\ + \$zinc->{\bf addtag}(tag, 'overlapping', xo, yo, xc, yc); + \smallskip}} Selects all the items that overlaps or are enclosed in the rectangle whose origin is at {\tt xo - yo} and corner at {\tt xc - yc}. {\tt xc} must be no greater than {\tt xo} and {\tt yo} must be no greater than {\tt yc}. All coordinates must be integers. See also the {\tt enclosed} variant above for a discussion on updating the geometry. - \item{\tt withtag tagOrId ?inGroup? ?recursive?} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag withtag tagOrId ?inGroup? ?recursive?\\ + \$zinc->{\bf addtag}(tag, 'withtag', tagOrId, ?inGroup?, ?recursive?); + \smallskip}} Selects all the items given by {\tt tagOrId}. 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 if the search should descend in the item tree or not. - \item{\tt withtype type ?inGroup? ?recursive?} \\ + \item{\bigskip + {\tt\large pathname {\bf addtag} tag withtype type ?inGroup? ?recursive?\\ + \$zinc->{\bf addtag}(tag, 'withtype', tagOrId, ?inGroup?, ?recursive?); + \smallskip}} Selects all the items of type {\tt type}. 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 @@ -533,14 +574,20 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{anchorxy}{tagOrId anchor} + +{\tt\large @(\$x, \$y) = \$zinc->{\bf anchorxy}(tagOrId, anchor);} + \begin{blockindent} - Returns the (device) coordinate of an item anchor. If no item is + Returns the (device) coordinates of an item anchor. If no item is named by {\tt tagOrId} or if the item doesn't support anchors, an error is raised. If more than one item match {\tt tagOrId}, the topmost in display list order is used. \end{blockindent} \zinccmd{bbox}{tagOrId ?tagOrId ...?} + +{\tt\large @(xo, yo, xc, yc) = \$zinc->{\bf bbox}(tagOrId, ?tagOrId, ...?);} + \begin{blockindent} Returns a list of 4 numbers describing the (device) coordinates of the origin and corner of a rectangle bounding all the items named by the {\tt tagOrId} @@ -549,11 +596,20 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{becomes}{} + +{\tt\large \$zinc->{\bf becomes}();} + \begin{blockindent} Not yet implemented. \end{blockindent} \zinccmd{bind}{tagOrId ?sequence? ?command?} + +{\tt\large @bindings = \$zinc->{\bf bind}(tagOrId);}\\ +{\tt\large @binding = \$zinc->{\bf bind}(tagOrId, sequence);}\\ +{\tt\large \$zinc->{\bf bind}(tagOrId, sequence, '');}\\ +{\tt\large \$zinc->{\bf bind}(tagOrId, sequence, command);}\\ + \begin{blockindent} This command associates {\tt command} with the item tag, item id, part tag {\tt tagOrId}. If an event sequence matching {\tt sequence} @@ -604,6 +660,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{cget}{option} + +{\tt\large \$val = \$zinc->{\bf cget}(option);} + \begin{blockindent} Returns the current value of the widget option given by {\tt option}. {\tt option} may be any of the options described in the @@ -611,6 +670,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{chggroup}{tagOrId group ?adjustTransform?} + +{\tt\large \$zinc->{\bf chggroup}(tagOrId, group, ?adjustTransform.?);} + \begin{blockindent} Move the item described by {\tt tagOrId} in the group described by {\tt group}. If {\tt tagOrId} or {\tt group} describe more @@ -624,6 +686,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{clone}{tagOrId ?attr value ...?} + +{\tt\large \$id = \$zinc->{\bf clone}(tagOrId, ?attr=>value, ...?);} + \begin{blockindent} Create an exact copy of all the items described by {\tt tagOrId}. The copy goes recursively for group items (deep copy). After copying @@ -638,17 +703,27 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{configure}{?option? ?value? ?option value ...?} + +{\tt\large @options = \$zinc->{\bf configure}();}\\ +{\tt\large @option = \$zinc->{\bf configure}(option);}\\ +{\tt\large \$zinc->{\bf configure}(option=>value, ?option=>value, ...?);} + \begin{blockindent} Query or modify the options of the widget. If no {\tt option} - is given, returns a list describing all the supported options (see the - chapter \conceptref{Widget options}{options}). If an {\tt option} is - specified without any {\tt value}, the command returns a list - describing the named option. If some - {\tt option - value} pairs are given, then the corresponding options - are changed and the command return an empty string. + is given, returns a list describing all the supported options in the + standard format for Tk options (see the + chapter \conceptref{Widget options}{options} for a list of available + options). If an {\tt option} is specified without a {\tt value}, the + command returns a list describing the named option in the standard Tk + format. If some {\tt option - value} pairs are + given, then the corresponding options are changed and the command return + an empty string. \end{blockindent} -\zinccmd{contour}{tagOrId operator coordListOrTagOrId} +\zinccmd{contour}{tagOrId operatorSpec coordListOrTagOrId} + +{\tt\large \$zinc->{\bf contour}(tagOrId, operatorSpec, coordListOrTagOrId);} + \begin{blockindent} Manipulate contours on items that can handle multiples geometric contours. Currently only curve items can do this. @@ -697,6 +772,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{coords}{tagOrId ?add/remove? ?contour? ?index? ?coordList?} + +{\tt\large \$zinc->{\bf coords}(tagOrId, ?add/remove?, ?contour?, ?index?, ?coordList?);} + \begin{blockindent} Query or changes the coordinates of the item described by {\tt tagOrId}. If {\tt tagOrId} describes more than one item, the first in display @@ -727,63 +805,99 @@ of the \ident{canvas} command set. Here are the various form recognized by the command: \begin{description} - \item{\code{.r coords tagOrId contour}}\\ - Get all coordinates of contour. All items can answer if contour - is zero. Curves can handle other contours. + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId contourIndex\\ + @coords = \$zinc->{\bf coords}(tagOrId, contourIndex); + \smallskip}} + Get all coordinates of contour at contourIndex. All items can answer if + contourIndex is zero. Curves can handle other contours. - \item{\code{.r coords tagOrId contour coordList}}\\ - Set all coordinates of contour. All items can do it if contour - is zero. Curves can handle other contours. + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId contourIndex coordList\\ + \$zinc->{\bf coords}(tagOrId, contourIndex, coordList); + \smallskip}} + Set all coordinates of contour at contourIndex. All items can do it if + contourIndex is zero. Curves can handle other contours. For groups, icons, texts, windows, tabulars, reticles, tracks, waypoints, only the first vertex will be used. For rectangles and arcs, only the first two vertices will be used. Beziers and curves can handle any number of vertices. - \item{\code{.r coords tagOrId contour index}}\\ - Get coordinate at index in contour. All items can answer if contour - is zero. Curves can handle other contours. For groups, icons, texts, - windows, tabulars, reticles, tracks, waypoints, index mst be zero. + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId contourIndex coordIndex\\ + @(\$x, \$y) = \$zinc->{\bf coords}(tagOrId, contourIndex, coordIndex); + \smallskip}} + Get coordinate at coordIndex in contour at contourIndex. All items can answer if + contourIndex is zero. Curves can handle other contours. For groups, icons, texts, + windows, tabulars, reticles, tracks, waypoints, coordIndex must be zero. For rectangles and arcs, index must zero or one. - \item{\code{.r coords tagOrId contour index coordList}}\\ - Set coordinate at index in contour. All items can do it if contour - is zero. Curves can handle other contours. For groups, icons, texts, - windows, tabulars, reticles, tracks, waypoints, index must be zero. - For rectangles and arcs, index must zero or one. + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId contourIndex coordIndex coordList\\ + \$zinc->{\bf coords}(tagOrId, contourIndex, coordIndex, coordList); + \smallskip}} + Set coordinate at coordIndex in contour at contourIndex. All items can do it + if contourIndex is zero. Curves can handle other contours. For groups, icons, texts, + windows, tabulars, reticles, tracks, waypoints, coordIndex must be zero. + For rectangles and arcs, coordIndex must zero or one. - \item{\code{.r coords tagOrId remove contour index}}\\ - Remove coordinate at index in contour. Can only be handled by beziers - and curves. Only curves can handle contours other than zero. + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId remove contourIndex coordIndex\\ + \$zinc->{\bf coords}(tagOrId, 'remove', contourIndex, coordIndex); + \smallskip}} + Remove coordinate at coordIndex in contour at contourIndex. Can only be handled + by beziers and curves. Only curves can handle contourIndex other than zero. - \item{\code{.r coords tagOrId add contour coordList}}\\ - Add coordinates at the end of contour. Can only be handled by beziers - and curves. Only curves can handle contours other than zero. + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId add contourIndex coordList\\ + \$zinc->{\bf coords}(tagOrId, 'add', contourIndex, coordList); + \smallskip}} + Add coordinates at the end of contour at contourIndex. Can only be handled by beziers + and curves. Only curves can handle contourIndex other than zero. - \item{\code{.r coords tagOrId add contour index coordList}}\\ - Add coordinates at index in contour. Can only be handled by beziers - and curves. Only curves can handle contours other than zero. + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId add contourIndex coordIndex coordList\\ + \$zinc->{\bf coords}(tagOrId, 'add', contourIndex, coordIndex, coordList); + \smallskip}} + Add coordinates at coordIndex in contour at contourIndex. Can only be handled by beziers + and curves. Only curves can handle contourIndex other than zero. \end{description} And the slightly abbreviated forms: \begin{description} - \item{\code{.r coords tagOrId}}\\ + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId\\ + @coords = \$zinc->{\bf coords}(tagOrId); + \smallskip}} Get all coordinates of contour 0. See first form. - \item{\code{.r coords tagOrId coordList}}\\ + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId coordList\\ + \$zinc->{\bf coords}(tagOrId, coordList); + \smallskip}} Set all coordinates of contour 0. See second form. - \item{\code{.r coords tagOrId remove index}}\\ - Remove coordinate at index in contour 0. See fifth form. + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId remove coordIndex\\ + \$zinc->{\bf coords}(tagOrId, 'remove', coordIndex); + \smallskip}} + Remove coordinate at coordIndex in contour 0. See fifth form. - \item{\code{.r coords tagOrId add coordList}}\\ + \item{\bigskip + {\tt\large pathname {\bf coords} tagOrId add coordList\\ + \$zinc->{\bf coords}(tagOrId, 'add', coordList); + \smallskip}} Add coordinates at the end of contour 0. See sixth form. \end{description} \end{blockindent} \zinccmd{currentpart}{} + +{\tt\large \$num = \$zinc->{\bf currentpart}();} + \begin{blockindent} - Returns a string specifying the item part over which the pointer is. + 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 describing a field index or the @@ -792,6 +906,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{cursor}{tagOrId index} + +{\tt\large \$zinc->{\bf cursor}(tagOrId, index);} + \begin{blockindent} Set the position of the insertion cursor for the items described by {\tt tagOrId} to be just before the character at {\tt index}. If @@ -802,6 +919,10 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{dchars}{tagOrId first ?last?} + +{\tt\large \$zinc->{\bf dchars}(tagOrId, first);}\\ +{\tt\large \$zinc->{\bf dchars}(tagOrId, first, last);} + \begin{blockindent} Delete the character range defined by the parameters {\tt first} and {\tt last} inclusive in all the items described by {\tt tagOrId}. @@ -811,6 +932,10 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{dtag}{tagOrId ?tagToDelete?} + +{\tt\large \$zinc->{\bf dtag}(tagOrId);}\\ +{\tt\large \$zinc->{\bf dtag}(tagOrId, tagToDelete);} + \begin{blockindent} Delete the tag {\tt tagToDelete} from the list of tags associated with each item named by {\tt tagOrId}. If an item doesn't have @@ -820,6 +945,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{find}{searchCommand ?arg arg ...?} + +{\tt\large @items = \$zinc->{\bf find}(searchCommand, ?arg?, ...);} + \begin{blockindent} This command returns the list of all items selected by {\tt searchCommand} and the {\tt args}. See the \cmdref{addtag} command for an explanation of @@ -828,6 +956,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{fit}{coordList error} + +{\tt\large @controls = \$zinc->{\bf fit}(coordList, error);} + \begin{blockindent} This command fits a sequence of Bezier segments on the curve described by the vertices in {\tt coordList} and returns a list of vertices describing @@ -840,7 +971,11 @@ of the \ident{canvas} command set. Bezier item. \end{blockindent} -\zinccmd{focus}{focus ?tagOrId?} +\zinccmd{focus}{?tagOrId?} + +{\tt\large \$item = \$zinc->{\bf focus}();}\\ +{\tt\large \$zinc->{\bf focus}(tagOrId);} + \begin{blockindent} Set the keyboard focus to the item describe by {\tt tagOrId}. If {\tt tagOrId} describe more than one item, the first item in display list order that supports @@ -856,6 +991,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{gettags}{tagOrId} + +{\tt\large @tags = \$zinc->{\bf gettags}(tagOrId);} + \begin{blockindent} This command returns the list of all the tags associated with the item specified by {\tt tagOrId}. If more than one item is @@ -865,6 +1003,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{group}{tagOrId} + +{\tt\large \$group = \$zinc->{\bf group}(tagOrId);} + \begin{blockindent} Returns the group containing the item described by {\tt tagOrId}. If more than one item is named by {\tt tagOrId}, then the topmost @@ -872,6 +1013,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{hasanchors}{tagOrId} + +{\tt\large \$bool = \$zinc->{\bf hasanchor}(tagOrId);} + \begin{blockindent} This command returns a boolean telling if the item specified by {\tt tagOrId} supports anchors. If more than one item is named by @@ -881,6 +1025,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{hasfields}{tagOrId} + +{\tt\large \$bool = \$zinc->{\bf hasfields}(tagOrId);} + \begin{blockindent} This command returns a boolean telling if the item specified by {\tt tagOrId} supports fields. If more than one item is named by @@ -890,6 +1037,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{hastag}{tagOrId tag} + +{\tt\large \$bool = \$zinc->{\bf hastag}(tagOrId, tag);} + \begin{blockindent} This command returns a boolean telling if the item specified by {\tt tagOrId} has the specified tag. If more than one item is @@ -899,6 +1049,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{index}{tagOrId index} + +{\tt\large \$num = \$zinc->{\bf index}(tagOrId, index);} + \begin{blockindent} This command returns a number which is the numerical index in the item described by {\tt tagOrId} corresponding to {\tt index}. {\tt index} @@ -934,7 +1087,10 @@ of the \ident{canvas} command set. order. \end{blockindent} -\zinccmd{insert}{insert tagOrId before string} +\zinccmd{insert}{tagOrId before string} + +{\tt\large \$zinc->{\bf insert}(tagOrId, before, string);} + \begin{blockindent} This command inserts {\tt string} in each item described by {\tt tagOrId} just before the text position described by {\tt before}. The possible @@ -944,6 +1100,10 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{itemcget}{tagOrId ?field? attr} + +{\tt\large \$val = \$zinc->{\bf itemcget}(tagOrId, attr);}\\ +{\tt\large \$val = \$zinc->{\bf itemcget}(tagOrId, field, attr);} + \begin{blockindent} Returns the current value of the attribute given by {\tt attr} for the item named by {\tt tagOrId}. If {\tt tagOrId} name more than @@ -957,9 +1117,15 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{itemconfigure}{tagOrId ?field? ?attr? ?value? ?attr value ...?} + +{\tt\large @attribs = \$zinc->{\bf itemconfigure}(tagOrId);}\\ +{\tt\large @attrib = \$zinc->{\bf itemconfigure}(tagOrId, attrib);}\\ +{\tt\large \$zinc->{\bf itemconfigure}(tagOrId, attrib=>value, ?attrib=>value, ...?);} + \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. + is given, returns a list of lists describing all the supported attributes + in the same format as for a single attribute, as described next. If a single attribute is specified without a value, the command returns a list describing the named attribute. Each attribute is described by a list with the following content: the attribute name, the attribute type, @@ -977,6 +1143,10 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{lower}{tagOrId ?belowThis?} + +{\tt\large \$zinc->{\bf lower}(tagOrId);}\\ +{\tt\large \$zinc->{\bf lower}(tagOrId, belowThis);} + \begin{blockindent} Reorder all the items given by {\tt tagOrId} so that they will be under the item given by {\tt belowThis}. If {\tt tagOrId} name more @@ -995,6 +1165,10 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{monitor}{?onOff?} + +{\tt\large \$bool = \$zinc->{\bf monitor}();}\\ +{\tt\large \$zinc->{\bf lower}(onOff);} + \begin{blockindent} This command controls the gathering of performance data. The data gathering is inited and turned on when the command is called with @@ -1006,6 +1180,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{numparts}{tagOrId} + +{\tt\large \$bool = \$zinc->{\bf numparts}(tagOrId);} + \begin{blockindent} This command tells how many private parts are available for event bindings in the item specified by {\tt tagOrId}. If more than one item is named @@ -1014,11 +1191,18 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{postscript}{} + +{\tt\large \$zinc->{\bf postscript}();} + \begin{blockindent} Not yet implemented. \end{blockindent} \zinccmd{raise}{tagOrId ?aboveThis?} + +{\tt\large \$zinc->{\bf raise}(tagOrId);}\\ +{\tt\large \$zinc->{\bf raise}(tagOrId, aboveThis);} + \begin{blockindent} Reorder all the items given by {\tt tagOrId} so that they will be above the item given by {\tt aboveThis}. If {\tt tagOrId} name more @@ -1037,12 +1221,19 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{remove}{tagOrId ?tagOrId ...?} + +{\tt\large \$zinc->{\bf remove}(tagOrId, ?tagOrId?, ...);} + \begin{blockindent} Delete all the items named by each {\tt tagOrId}. The command returns an empty string. \end{blockindent} \zinccmd{rotate}{tagOrId angle ?centerX centerY?} + +{\tt\large \$zinc->{\bf rotate}(tagOrId, angle);}\\ +{\tt\large \$zinc->{\bf rotate}(tagOrId, angle, centerX, centerY);} + \begin{blockindent} Add a rotation to the items or the transform described by {\tt tagOrId}. If {\tt tagOrId} describe a named transform @@ -1055,6 +1246,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{scale}{tagOrId xFactor yFactor} + +{\tt\large \$zinc->{\bf scale}(tagOrId, xFactor, yFactor);} + \begin{blockindent} Add a scale factor to the items or the transform described by {\tt tagOrId}. If {\tt tagOrId} describe a named transform @@ -1066,6 +1260,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{select}{option ?tagOrId? ?arg?} + +{\tt\large \$zinc->{\bf select}(option, ?tagOrId?, ?arg?);} + \begin{blockindent} Manipulates the selection as requested by {\tt option}. {\tt tagOrId} Describe the target item. This item must support text indexing and @@ -1077,26 +1274,41 @@ of the \ident{canvas} command set. The valid forms of the command are : \begin{description} - \item{\code{.r select adjust tagOrId index}} \\ + \item{\bigskip + {\tt\large pathname {\bf select} adjust tagOrId index\\ + \$zinc->{\bf select}('adjust', tagOrdId, index); + \smallskip}} \\ Adjust the end of the selection in {\tt tagOrId} that is nearest to the character given by {\tt index} so that it is at {\tt index}. The other end of the selection is made the anchor for future select to commands. If the selection is not currently in {\tt tagOrId}, this command behaves as the select to command. The command returns an empty string. - \item{\code{.r select clear}} \\ + \item{\bigskip + {\tt\large pathname {\bf select} clear\\ + \$zinc->{\bf select}('clear'); + \smallskip}} \\ Clear the selection if it is in the widget. If the selection is not in the widget, the command has no effect. Return an empty string. - \item{\code{.r select from tagOrId index}} \\ + \item{\bigskip + {\tt\large pathname {\bf select} from tagOrId index\\ + \$zinc->{\bf select}('from', tagOrdId, index); + \smallskip}} \\ Set the selection anchor point for the widget to be just before the character given by {\tt index} in the item described by {\tt tagOrId}. The command has no effect on the selection, it sets one end of the selection so that future select to can actually set the selection. The command returns an empty string. - \item{\code{.r select item}} \\ + \item{\bigskip + {\tt\large pathname {\bf select} item\\ + \$item = \$zinc->{\bf select}('item'); + \smallskip}} \\ Returns the id of the selected item, if the selection is in an item on this widget. Otherwise the command returns an empty string. - \item{\code{.r select to tagOrId index}} \\ + \item{\bigskip + {\tt\large pathname {\bf select} to tagOrId index\\ + \$zinc->{\bf select}('to', tagOrdId, index); + \smallskip}} \\ Set the selection to be the characters that lies between the selection anchor and {\tt index} in the item described by {\tt tagOrId}. The selection includes the character given by {\tt index} and includes the @@ -1111,6 +1323,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{smooth}{coordList} + +{\tt\large @coords = \$zinc->{\bf smooth}(coordList);} + \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 @@ -1123,17 +1338,27 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{tapply}{} + +{\tt\large \$zinc->{\bf tapply}();} + \begin{blockindent} Not yet implemented. \end{blockindent} \zinccmd{tdelete}{tName} + +{\tt\large \$zinc->{\bf tdelete}(tName);} + \begin{blockindent} Destroy a named transform. If the given name is not found among the named transforms, an error is raised. \end{blockindent} \zinccmd{transform}{?tagOrIdFrom? tagOrIdTo coordList} + +{\tt\large @coords = \$zinc->{\bf transform}(tagOrIdTo, coordList);}\\ +{\tt\large @coords = \$zinc->{\bf transform}(tagOrIdFrom, tagOrIdTo, coordList);} + \begin{blockindent} This command returns a list of coordinates obtained by transforming the coordinates given in {\tt coordList} from the coordinate space @@ -1146,6 +1371,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{translate}{tagOrId xAmount yAmount} + +{\tt\large \$zinc->{\bf translate}(tagOrdId, xAmount, yAmount);} + \begin{blockindent} Add a translation to the items or the transform described by {\tt tagOrId}. If {\tt tagOrId} describe a named transform @@ -1157,6 +1385,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{treset}{tagOrId} + +{\tt\large \$zinc->{\bf treset}(tagOrdId);} + \begin{blockindent} Set the named transform or the transform for the items described by {\tt tagOrId} to identity. If {\tt tagOrId} describe neither @@ -1164,6 +1395,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{trestore}{tagOrId tName} + +{\tt\large \$zinc->{\bf trestore}(tagOrdId, tName);} + \begin{blockindent} Set the transform for the items described by {\tt tagOrId} to the transform named by {\tt tName}. If {\tt tagOrId} doesn't describe @@ -1172,6 +1406,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{tsave}{tagOrId tName} + +{\tt\large \$zinc->{\bf tsave}(tagOrdId, tName);} + \begin{blockindent} Create (or reset) a transform associated with the name {\tt tName} which has for initial value the transform associated with the item @@ -1183,6 +1420,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{type}{tagOrId} + +{\tt\large \$name = \$zinc->{\bf type}(tagOrdId);} + \begin{blockindent} This command returns the type of the item specified by {\tt tagOrId}. If more than one item is named by {\tt tagOrId}, then the type of @@ -1191,6 +1431,9 @@ of the \ident{canvas} command set. \end{blockindent} \zinccmd{vertexat}{tagOrId x y} + +{\tt\large (\$contour, \$vertex, \$edgevertex) = \$zinc->{\bf vertexat}(tagOrdId, x, y);} + \begin{blockindent} Return a list of values describing the vertex and edge closest to the device coordinates {\tt x} and {\tt y} in the item described by {\tt tagOrId}. @@ -1314,28 +1557,52 @@ of the \ident{canvas} command set. \attrtype{gradientcolor} \begin{blockindent} - This is a string describing a color span to be used for example to fill - a surface. The string consists of the first color of the span, the last - color of the span and the number of steps that it should take to go from - the first color to the last. The three elements are sperated by spaces. - The two colors can take any form legal in a color context (see the - \ident{color} attribute type). The number of steps should be a non negative - integer. The intermediate colors are generated by linear interpolation - between the two specified colors. A simplified form consists in only one - color, this is useful when no gradient filling is needed. When the full - description is used and only one color is used by the item (e.g when - filling with a solid color) then the span median color is used. -\end{blockindent} + This is a string describing a color gradient to be used for example to fill + a surface. -\attrtype{gradientgeometry} -\begin{blockindent} - This is a string describing the geometry that should be used to fill a - surface with a color gradient. The string should have one of the forms - {\tt threshold1-threshold2/angle}, {\tt threshold/angle}, - {\tt threshold1-threshold2} or {\tt threshold}. The threshold values - are a percentage along the gradient axis where the mid color should - be reached (first threshold) or leaved (second threshold). The angle - is an unsigned value in degrees specifying the gradient axis orientation. + 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 + '|' characters. + + The general pattern is: + {\tt\large gradient\_step1|...|gradient\_stepn/angle\%steps} for an axial gradient + and: {\tt\large gradient\_step1|...|gradient\_stepn(x y\%steps} for a radial + gradient. + + The steps section describes how many steps should be used for each + gradient segment. This section is optional and the default number of steps is 6. + The last gradient segment has only one step which is exactly the specified color. + Thus a gradient with two segments and the default number of steps will have a total + of seven shades while a gradient with three segments will have a total of thirteen + shades. + + The /angle section describe the optional angle in degrees for an axial gradient, + its default value is zero. For the moment only angles of 0, 90, 180 and 270 + can be specified, the others values are unimplemented. + + The (x y section describes the center for a radial + gradient and at the same it specifies that the gradient should be radial. The default + gradient is axial. + + Each gradient segment section has the general form: + {\tt\large color\_name color\_position mid\_span\_position} + + The color position tells where in the gradient surface, measured + as a percentage of the total gradient distance, the color should start (excepted for + the last segment which describes the end color). The first gradient segment + has its position set to zero and the last segment has its position set to 100. + + The mid span position tells where in the current gradient segment should be the median + color. The position is given in percentage of the current gradient segment distance. + The mid span position can be used to obtain a non linear gradient segment, this is useful + to describe relief shapes. + This parameter can be omitted in which case it defaults to 50 and the gradient segment + is perfectly linear. + + A gradient segment can be specified as a single color. In this case the color position + is automatically set to 0 for the first segment and to 100 for the last. All intermediate + segments have their color psotion set to zero. It is of no use with these rules to + use more than two segments. \end{blockindent} \attrtype{image} @@ -2020,12 +2287,6 @@ Applicable attributes for \ident{reticle}: value is {\tt false}.} \attribute{fillpattern}{bitmap}{Specifies the pattern to use when filling the item. The default value is {\tt ""}.} -\attribute{gradient}{gradientgeometry}{Specifies the type and geometry of the - gradient that should be drawn to fill the item. This will be done only if filling is - requested by the \ident{filled} attribute. The default value is {\tt ""} which means - no gradient geometry, fill with solid color. When a value other than the default is - specified, this attribute has priority over the \ident{tile} and \ident{fillpattern} - attributes.} \attribute{linecolor}{color}{Specifies the color that will be used to draw the item outline. The default value is the current value of the widget option \ident{-foreground}.} @@ -2046,9 +2307,8 @@ Applicable attributes for \ident{reticle}: value is {\tt ""}.} \attribute{tile}{image}{Specifies an image used for filling the item with tiles. This will be done only if filling is requested by the \ident{filled} attribute. - This attribute has priority over the \ident{gradient} attribute when no gradient is - specified (paint solid) and the \ident{fillpattern} attribute. The default value is - {\tt ""}.} + This attribute has priority over the \ident{fillcolor} attribute and the \ident{fillpattern} + attribute. The default value is {\tt ""}.} \attribute{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} @@ -2066,7 +2326,9 @@ Applicable attributes for \ident{reticle}: shape will be the polygon obtained by closing the arc. It is also possible to use this polygon in a \ident{contour} command to build a complex shape in a \ident{curve} item. The two points describing the enclosing rectangle - can be read and modified with the \ident{coords} command. + can be read and modified with the \ident{coords} command. The first point + should be the top left vertex of the rectangle and the second should be the + bottom right. Applicable attributes for \ident{arc}: @@ -2091,12 +2353,6 @@ Applicable attributes for \ident{reticle}: \attribute{firstend}{lineend}{Describe the arrow shape at the start end of the arc. This attribute is applicable only if the item is not closed and not filled. The default value is {\tt ""}.} -\attribute{gradient}{gradientgeometry}{Specifies the type and geometry of the - gradient that should be drawn to fill the item. This will be done only if filling is - requested by the \ident{filled} attribute. The default value is {\tt ""} which means - no gradient geometry, fill with solid color. When a value other than the default is - specified, this attribute has priority over the \ident{tile} and \ident{fillpattern} - attributes.} \attribute{lastend}{lineend}{Describe the arrow shape at the extent end of the arc. This attribute is applicable only if the item is not closed and not filled. The default value is {\tt ""}.} @@ -2123,9 +2379,8 @@ Applicable attributes for \ident{reticle}: value is {\tt ""}.} \attribute{tile}{image}{Specifies an image used for filling the item with tiles. This will be done only if filling is requested by the \ident{filled} attribute. - This attribute has priority over the \ident{gradient} attribute when no gradient is - specified (paint solid) and the \ident{fillpattern} attribute. The default value is - {\tt ""}.} + This attribute has priority over the \ident{fillcolor} attribute and the \ident{fillpattern} + attribute. The default value is {\tt ""}.} \attribute{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} @@ -2167,12 +2422,6 @@ Applicable attributes for \ident{reticle}: \attribute{firstend}{lineend}{Describe the arrow shape at the start of the curve. This attribute is applicable only if the item is not closed, not filled and the relief of the outline is flat. The default value is {\tt ""}.} -\attribute{gradient}{gradientgeometry}{Specifies the type and geometry of the - gradient that should be drawn to fill the item. This will be done only if filling is - requested by the \ident{filled} attribute. The default value is {\tt ""} which means - no gradient geometry, fill with solid color. When a value other than the default is - specified, this attribute has priority over the \ident{tile} and \ident{fillpattern} - attributes.} \attribute{joinstyle}{joinstyle}{Specifies the form of the joint between the curve segments. This attribute is only applicable if the curve outline relief is flat. The default value is {\tt round}.} @@ -2204,9 +2453,8 @@ Applicable attributes for \ident{reticle}: value is {\tt ""}.} \attribute{tile}{image}{Specifies an image used for filling the item with tiles. This will be done only if filling is requested by the \ident{filled} attribute. - This attribute has priority over the \ident{gradient} attribute when no gradient is - specified (paint solid) and the \ident{fillpattern} attribute. The default value is - {\tt ""}.} + This attribute has priority over the \ident{fillcolor} attribute and the + \ident{fillpattern} attribute. The default value is {\tt ""}.} \attribute{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} @@ -2249,12 +2497,6 @@ Applicable attributes for \ident{bezier}: \attribute{firstend}{lineend}{Describe the arrow shape at the start of the bezier. This attribute is applicable only if the item is not filled and the relief of the outline is flat. The default value is {\tt ""}.} -\attribute{gradient}{gradientgeometry}{Specifies the type and geometry of the - gradient that should be drawn to fill the item. This will be done only if filling is - requested by the \ident{filled} attribute. The default value is {\tt ""} which means - no gradient geometry, fill with solid color. When a value other than the default is - specified, this attribute has priority over the \ident{tile} and \ident{fillpattern} - attributes.} \attribute{lastend}{lineend}{Describe the arrow shape at the end of the bezier. This attribute is applicable only if the item is not filled and the relief of the outline is flat. The default value is {\tt ""}.} @@ -2278,9 +2520,8 @@ Applicable attributes for \ident{bezier}: value is {\tt ""}.} \attribute{tile}{image}{Specifies an image used for filling the item with tiles. This will be done only if filling is requested by the \ident{filled} attribute. - This attribute has priority over the \ident{gradient} attribute when no gradient is - specified (paint solid) and the \ident{fillpattern} attribute. The default value is - {\tt ""}.} + This attribute has priority over the \ident{fillcolor} attribute and the + \ident{fillpattern} attribute. The default value is {\tt ""}.} \attribute{visible}{boolean}{Specifies if the item is displayed. The default value is {\tt true}.} |