[tail]

Chapter 5
Widget commands

In this chapter, we first list all commands by categories, then we details each command, by alphabetical order.

5.1 Categories of commands

5.2 Commands by alphabetical order

The available commands are listed in alphabetical order.

The command set for the TkZinc widget is much inspired by the Canvas command set. Someone comfortable with the Canvas should not have much trouble using the TkZinc’s commands. Eventually, the command set will be a superset of the Canvas command set. Anyway some commands depart radically from the equivalent in the Canvas. For example, the user should be aware that scale and translate do not behave in the same way at all; find and addtag have been extended to support groups, etc. So use the available knowledge with some care.

In the Perl/Tk version, the commands returning a list, return a Perl array (not a reference) and all list parameters are given as array references.

5.2.1 add

pathname add ?type group? ?initargs? ?option value? ... ?option value?

@types = $zinc->add();
$id = $zinc->add(type, group);
$id = $zinc->add(type, group, initargs);
$id = $zinc->add(type, group, initargs, option=>value, ..., ?option=>value?);

This command is used to create new items in a TkZinc widget. It can be called with no parameters to return the list of all item types currently known by TkZinc. It can also be called with a valid item type as first parameter and a group item as second parameter to create a new item of this type in the given group.

After these first two parameters come some item type specific arguments. Here is detailed description of these arguments by type:

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. The origin should be the top left vertex of the enclosing rectangle and the corner the bottom right vertex of the rectangle.
curve
The curve type expects either a flat list or a list of lists. In the first case, the flat list must be a list of floating point numbers x0 y0 x1 y1 ... xn yn, giving the coordinates of the curve vertices. The number of values should be even (or the last value will be discarded) but the list can be empty to build an empty invisible curve. In the second case, the list must contain lists of 2 or 3 elements: xi, yi and and an optionnal point type. Currently, the only available point type is ’c’ for a cubic bezier control point. For example in Perl/Tk, the following list is an example of 2 beziers segments with a straight segment in-between:
( [x0, y0], [x1, y1, 'c'], [x2, y2, 'c'], [x3, y3], [x4, y4, 'c'], [x5, y5] )  
    

As there is only on control point, [x4, y4, 'c'] , for the second cubic bezier, the omitted second control point will be defaulted to the same point. A curve can be defined later with the contour or 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.

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.
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 vertices of the triangles composing this item. The triangles layout is defined by the attribute -fan . If -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 -fan is false, the triangles are arranged in a strip.
tabular , track , waypoint
These types expect the number of fields they will manage in the label or tabular form. This number must be greater or equal to zero.
group , icon , map , reticle , text , window
These types do not expect type specific arguments.

Following the creation args the command accept any number of attributes - values pairs to configure the newly created item. All the configurable item type attributes are valid in this context. The command returns the item id.

5.2.2 addtag

pathname addtag tag searchSpec ?arg arg ...?

$zinc->addtag(tag, searchSpec);

This command add the given tag to all items matching the search specification. If the tag is already present on some item, nothing is done for that item. The command has no effect if no item satisfy the given criteria. The command returns an empty string.

Many commands take a group as a starting point for the search. If no group is given, the root group is assumed. In any cases, the starting group will not be reported in the search result. This means that the root group will never be reported in a search and that tags cannot be attached to it except in specifying its id.

The search specification and the associated arguments can take the following forms:

  • pathname addtag tag above tagOrId
    $zinc->addtag(tag, 'above', tagOrId);

    Selects the item just above the one given by tagOrId. If tagOrId names more than one item, the topmost of these items in the display list will be used. If tagOrId does not refer to any item then nothing happen.

  • pathname addtag tag all ?inGroup? ?recursive?
    $zinc->addtag(tag, 'all', ?inGroup?, ?recursive?);

    This form is no more allowed since version 3.2.6 of TkZinc. Please use a form ’”withtag”, ”all”’ as documented below.

  • pathname addtag tag atpriority priority ?tagOrId?
    $zinc->addtag(tag, 'atpriority', priority, ?tagOrId?);

    Selects all the items at the given priority. The tagOrId optional parameter can be specified to restrict the search. It specifies a group to start with instead of the root group and it can be used to control if the search should be recursive or not (see PathTags for more on this subject).

  • pathname addtag tag ancestors tagOrId ?tagOrId2?
    $zinc->addtag(tag, 'ancestors', tagOrId, ?tagOrId2?);

    Selects all ancestors (i.e. parent groups) of tagOrId. If 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.

  • pathname addtag tag below tagOrId
    $zinc->addtag(tag, 'below', tagOrId);

    Selects the item just below the one given by tagOrId. If tagOrId names more than one item, the lowest of these items in the display list will be used. If tagOrId does not refer to any item then nothing happen.

  • pathname addtag tag closest x y ?halo? ?startItem?, ?recursive?
    $zinc->addtag(tag, 'closest', x, y, ?halo?, ?startItem?, ?recursive?);

    Selects the item closest to the point x - y. Any item overlapping the point is considered as closest and the topmost is selected. If halo is given, it defines the size of the point x - y. halo must be a non negative integer. If start is specified, it must be an item tag or id. If it names a group and this group is not atomic, the search starts with the first item of this group. If it names a non group item or an atomic group (for a tag, the lowest item with the tag is considered), the search starts with the item below start instead of the first item in the display order. If startItem does not name a valid item, it is ignored. If recursive is false the search is limited to the starting group. If set to true, not specified or “override”, the search proceed from the starting group down the hierarchy rooted at this group. “override” forces the search to explore atomic groups and report the most specific item instead of the group itself.

  • pathname addtag tag enclosed xo yo xc yc ?inGroup? ?recursive?
    $zinc->addtag(tag, 'enclosed', xo, yo, xc, yc, ?inGroup?, ?recursive?);

    Selects all the items completely enclosed in the rectangle whose origin is at xo - yo and corner at xc - yc. xc must be no greater than xo and yo must be no greater than yc. All coordinates must be integers. inGroup specifies a group to start with instead of the root group. If recursive is false the search is limited to the starting group. If set to true, not specified or “override”, the search proceed from the starting group down the hierarchy rooted at this group. “override” forces the search to explore atomic groups and report the most specific item instead of the group itself.

    It may be necessary to update the TkZinc internal geometry with a call to update if the current state is not stable (i.e before calling the main loop or in a callback after modifying the transform or doing something else affecting the geometry of items).

  • pathname addtag tag overlapping xo yo xc yc ?inGroup? ?recursive?
    $zinc->addtag(tag, 'overlapping', xo, yo, xc, yc, ?inGroup?, ?recursive?);

    Selects all the items that overlaps or are enclosed in the rectangle whose origin is at xo - yo and corner at xc - yc. xc must be no greater than xo and yo must be no greater than yc. All coordinates must be integers. inGroup specifies a group to start with instead of the root group. If recursive is false, the search is limited to the starting group. If set to true, not specified or “override”, the search proceed from the starting group down the hierarchy rooted at this group. “override” forces the search to explore atomic groups and report the most specific item instead of the group itself.

    See also the enclosed variant above for a discussion on updating the geometry.

  • pathname addtag tag withtag tagOrId
    $zinc->addtag(tag, 'withtag', tagOrId);

    Selects all the items given by tagOrId.

  • pathname addtag tag withtype type ?tagOrId?
    $zinc->addtag(tag, 'withtype', type, ?tagOrId?);

    Selects all the items of type type. The tagOrId optional parameter can be specified to restrict the search. It specifies a group to start with instead of the root group and it can be used to control if the search should be recursive or not (see PathTags for more on this subject).

5.2.3 anchorxy

pathname anchorxy tagOrId anchor

($x, $y) = $zinc->anchorxy(tagOrId, anchor);

Returns the window coordinates of an item anchor. If no item is named by tagOrId or if the item doesn’t support anchors, an error is raised. If more than one item match tagOrId, the topmost in display list order is used.

  # for example to get the lower right corner of a text item  
  ($x ,$y) = $zinc->anchorxy('myTextTag', 'se');  
  

5.2.4 bbox

pathname bbox ?-field fieldNo? ?-label? tagOrId ?tagOrId ...?

($xo, $yo, $xc, $yc) =
$zinc->bbox(?-field fieldNo? ?-label? tagOrId, ?tagOrId ...?);

Returns a list of 4 numbers describing the window coordinates of the origin and corner of a rectangle bounding all the items named by the tagOrId arguments. If no items are named by tagOrId or if the matching items have an empty bounding box, an empty string is returned. The -field and -label options can be used to query the bounding box of an item’s field or an item’s label. These two options are mutually exclusives. When one of these options is specified, the bbox command is applied to the first item selected by the tagOrId arguments. If no labelformat has been set for the item, bbox will return an empty array.

5.2.5 becomes

pathname becomes

$zinc->becomes();

Not yet implemented.

5.2.6 bind

pathname bind tagOrId ?part? ?sequence? ?command?

@bindings = $zinc->bind(tagOrId, ?part?);
@binding = $zinc->bind(tagOrId, ?fpart?, sequence);
$zinc->bind(tagOrId, ?part?, sequence, '');
$zinc->bind(tagOrId, ?part?, sequence, command);

This command associates command with the item tag, item id, part tag tagOrId. If an event sequence matching sequence occurs for an item, or an item part, the command will be invoked. If all parameters are specified a new binding between sequence and command is established, overriding any existing binding for the sequence. If the first character of command is “+”, then command augments the existing binding instead of replacing it. In this case the command returns an empty string. If the command parameter is omitted, the command returns the command associated with tagOrId and sequence or an error is raised if there is no such binding. If only tagOrId is specified the command returns a list of all the sequences for which there are bindings for tagOrId.

This widget command is similar to the Tk bind command except that it operates on TkZinc items instead of widgets. Another difference with the bind command is that only mouse and keyboard related events can be specified (such as Enter, Leave, ButtonPress, ButtonRelease, Motion, KeyPress, KeyRelease). The bind manual page is the most accurate place to look for a definition of sequence and command and for a general understanding of how the binding mecanism works.

The handling of events in the widget is done with respect to the current item and when applicable the current item part (see Item ids, tags and indices for a discussion of the current tag and the special tags used in bindings). Enter and Leave events are trigerred for an item when it becomes or cease to be the current item. Mouse related events are reported with respect to the current item. Keyboard related events are reported with respect to the focus item if it exists (See the focus command for more on this).

It is possible that several bindings match a particular event sequence. When this occurs, all matching bindings are triggered. The order of invocation is as follow: the binding associated with the tag all is invoked first, followed by the bindings associated with the item tags in order, followed by the binding associated with the item id, followed by bindings associated with the item part tags if relevant, followed by the binding associated with the item part if relevant. If there are more than one binding for a single tag or id, only the most specific is triggered.

Two syntaxes are available for addressing item parts (for items having part ie. track waypoint and tabular ): either an Id of the following form: id:part or by using the optionnal part argument.

If bindings have been registered for the widget window using the bind command, they are invoked in addition to bindings registered for the items using this widget command. The bindings for items will be invoked before the bindings for the window.

5.2.7 cget

pathname cget option

$val = $zinc->cget(option);

Returns the current value of the widget option given by option. option may be any of the options described in the chapter Widget options .

5.2.8 chggroup

pathname chggroup tagOrId group ?adjustTransform?

$zinc->chggroup(tagOrId, group, ?adjustTransform.?);

Move the item described by tagOrId in the group described by group. If tagOrId or group describes more than one item, the first in display list order will be used. If 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 adjustTransform is omitted, it defaults to false.

5.2.9 clone

pathname clone tagOrId ?attr value ...?

$id = $zinc->clone(tagOrId, ?attr=>value, ...?);

Create an exact copy of all the items described by tagOrId. The copy goes recursively for group items (deep copy). After copying the pairs attr value are used, if any, to reconfigure the items. Any attribute that as no meaning in the context of some item is ignored. The items down the hierarchy of group items are not concerned by the configuration phase. The command returns the list of cloned items id in creation order (display list order of the models). No item id will be returned for items cloned in the hierarchy of cloned groups.

5.2.10 collapsemotions

pathname collapsemotions ?boolean?

$current = $zinc->collapsemotions(?boolean?);

This command controls how the motion events are handled by the Tk event loop. Pass a boolean true to ask for compression of consecutive motion events accumulated in the event queue. Pass a boolean false to suspend the compression process. The change affects all the windows opened by the application on the same display, so use with care. The command returns the previous state as a boolean. If the parameter is omitted the command simply returns the current state.

5.2.11 configure

pathname configure ?option? ?value? ?option value ...?

@options = $zinc->configure();
@option = $zinc->configure(option);
$zinc->configure(option=>value, ?option=>value,...?);

Query or modify the options of the widget. If no option is given, returns a list describing all the supported options in the standard format for Tk options (see the chapter Widget options for a list of available options). If an option is specified without a value, the command returns a list describing the named option in the standard Tk format. If some option - value pairs are given, then the corresponding options are changed and the command returns an empty string.

5.2.12 contour

pathname contour tagOrId ?operatorSpec coordListOrTagOrId?

$contourNum = $zinc->contour(tagOrId);
$contourNum = $zinc->contour(tagOrId, operatorAndFlag, coordListOrTagOrId);

Manipulate contours on items that can handle multiples geometric contours. Currently only curve items can do this.

tagOrId specifies the item whose contours will be modified. If tagOrId describes more than one item, the first in display list order will be used.

If the command is invoked with only the tagOrId parameter, it returns the number of contours composing the item. In fact it always returns the number of contours after a command has been conducted, it happens that with this reduced form nothing is done except returning the number of contours.

On items that do not support multiple contours, the returned value is 0 or 1 depending on the item having a contour or not. track , waypoint , reticle , group , map , and yield 0 while rectangle , tabular , arc , icon , triangles , text , and window yield 1.

coordListOrTagOrId specifies a list of coordinates (either a flat list of X and Y, or a list similar to the one allowed for a curve item) or an item describing a contour. If a flat list is specified it should contain an even number of floating point values specifying the contour vertices X and Y in order. If a tag or an id is specified, it is should be from one of these classes: arc, curve, icon, rectangle, tabular, text, window. The external shape of the item will be used as the contour. If coordListOrTagOrId describes more than one item, the first in display list order will be used.

operatorAndFlag specifies the operation that will be carried. This can be:

add to extend the surface of the curve. In this case there is a mandatory flag describing the way the contour will be added. It may take the following values:
0 the list of points is taken unchanged. In this case, the coordListOrTagOrId parameter cannot be a tag and must be an explicit list of points.
1 the list of points is reverted, if needed, so that the points defines a counterclockwise contour.
-1 the list of points is reverted,if needed, so that the points defines a clockwise contour.

The exact graphical effect depends on the value of the -fillrule as described in the fillrule type description.

remove to remove an existing contour

The following operations are no more available: diff, inter, union, xor; An error is generated if the items are not of a correct type or if the coordinate list is malformed.

5.2.13 coords

pathname coords tagOrId ?add/remove? ?contour? ?index? ?coordList?

$zinc->coords(tagOrId, ?add/remove?, ?contour?, ?index?, ?coordList?);

Query or changes the coordinates of the item described by tagOrId. If the item is a group, query or set the translation applied to the group. If tagOrId describes more than one item, the first in display list order is used. The optional contour gives the contour, if available, that should be operated. The default contour is 0. The optional index gives the vertex index that should be operated in the given contour. The optional coordList is either a flat list (of one or more vertices described as X, Y floating point values) or a list of lists [X Y ?type?] such as described in the curve item. The coordinates will be used to replace or add coordinates to the current contour.

Almost all items can be manipulated by this command, the map item is the only current exception. The effect of the command can be quite different depending on the item. For icons, texts, windows, tabulars, the coordinates of the anchor can be modified or read. For groups, the coordinates of the origin of the transformation can be set or read. For tracks and waypoints, the coordinates of the current position can be set or read. For tracks setting the current position this way will make the previous position shift into the history. For reticles, the coordinates of the center can be set or read. For arcs and rectangles, the coordinates of the origin and corner can be set or read. For curves and triangles, coordinates of all points defining the item can be set or read. For all items that do not support multiple contours (currently all except curves) the contour parameter should be omitted or specified as zero.

When coords is used to get potentially more than one point, it returns always a list of lists. Each sub list contains X, Y, and ’c’ if the point is a bezier control point.

When coords is used to get exactly one point (either because it is used to get the nth point of an item or because the item always has exactly one point (e.g. the item is a group, track, waypoint, map, or reticle)), it returns a flat list of 2 (or may be 3 for control points of curve items) values.

The optional parameters must be combined to produce a given behavior. Here are the various form recognized by the command:

  • pathname coords tagOrId contourIndex
    @coords = $zinc->coords(tagOrId, contourIndex);

    Get all coordinates of contour at contourIndex. All items can answer if contourIndex is zero. Curves can handle other contours.

  • pathname coords tagOrId contourIndex coordList
    $zinc->coords(tagOrId, contourIndex, coordList);

    Set all coordinates of contour at contourIndex. All items can do it if contourIndex is zero. Curves can handle other contours. For groups, icons, texts, windows, tabulars, reticles, tracks, waypoints, only the first vertex will be used. For rectangles and arcs, only the first two vertices will be used. Curves can handle any number of vertices.

  • pathname coords tagOrId contourIndex coordIndex
    ($x, $y) = $zinc->coords(tagOrId, contourIndex, coordIndex);

    Get coordinate at coordIndex in contour at contourIndex. All items can answer if contourIndex is zero. Curves can handle other contours. For groups, icons, texts, windows, tabulars, reticles, tracks, waypoints, coordIndex must be zero. For rectangles and arcs, coordIndex must zero or one.

  • pathname coords tagOrId contourIndex coordIndex coordList
    $zinc->coords(tagOrId, contourIndex, coordIndex, coordList);

    Set coordinate at coordIndex in contour at contourIndex. All items can do it if contourIndex is zero. Curves can handle other contours. For groups, icons, texts, windows, tabulars, reticles, tracks, waypoints, coordIndex must be zero. For rectangles and arcs, coordIndex must zero or one. WARNING: coordList must be a list of one list describing x, y and optionnaly the point type.

  • pathname coords tagOrId remove contourIndex coordIndex
    $zinc->coords(tagOrId, 'remove', contourIndex, coordIndex);

    Remove coordinate at coordIndex in contour at contourIndex. Can only be handled by curves. Only curves can handle contourIndex other than zero.

  • pathname coords tagOrId add contourIndex coordList
    $zinc->coords(tagOrId, 'add', contourIndex, coordList);

    Add coordinates at the end of contour at contourIndex. Can only be handled by curves. Only curves can handle contourIndex other than zero.

  • pathname coords tagOrId add contourIndex coordIndex coordList
    $zinc->coords(tagOrId, 'add', contourIndex, coordIndex, coordList);

    Add coordinates at coordIndex in contour at contourIndex. Can only be handled by curves. Only curves can handle contourIndex other than zero.

And the slightly abbreviated forms:

  • pathname coords tagOrId
    @coords = $zinc->coords(tagOrId);

    Get all coordinates of contour 0. See first form.

  • pathname coords tagOrId coordList
    $zinc->coords(tagOrId, coordList);

    Set all coordinates of contour 0. See second form.

  • pathname coords tagOrId remove coordIndex
    $zinc->coords(tagOrId, 'remove', coordIndex);

    Remove coordinate at coordIndex in contour 0. See fifth form.

  • pathname coords tagOrId add coordList
    $zinc->coords(tagOrId, 'add', coordList);

    Add coordinates at the end of contour 0. See sixth form.

5.2.14 currentpart

pathname currentpart

$num = $zinc->currentpart();

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 current tag) the command returns "". 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.

5.2.15 cursor

pathname cursor tagOrId index

$zinc->cursor(tagOrId, index);

Set the position of the insertion cursor for the items described by tagOrId to be just before the character at index. If some of the items described by tagOrId don’t support an insertion cursor, the command doesn’t change them. The possible values for index are described in the section Text indices . The command returns an empty string.

5.2.16 dchars

pathname dchars tagOrId first ?last?

$zinc->dchars(tagOrId, first);
$zinc->dchars(tagOrId, first, last);

Delete the character range defined by the parameters first and last inclusive in all the items described by tagOrId. Items that doesn’t support text indexing are skipped by the command. If last is not specified, the command deletes the character located at first. The command returns an empty string. first and last are indices as described in Text indices .

5.2.17 dtag

pathname dtag tagOrId ?tagToDelete?

$zinc->dtag(tagOrId);
$zinc->dtag(tagOrId, tagToDelete);

Delete the tag tagToDelete from the list of tags associated with each item named by tagOrId. If an item doesn’t have the tag then it is leaved unaffected. If tagToDelete is omitted, tagOrId is used instead. The command returns an empty string as result.

5.2.18 find

pathname find searchCommand ?arg arg ...?

@items = $zinc->find(searchCommand, ?arg?, ...);

This command returns the list of all items selected by searchCommand and the args. See the addtag command for an explanation of searchCommand and the various args. The items are sorted in drawing order, topmost first. For example:

  # to get the item under the mouse cursor:  
  $item = $zinc->find('withtag', 'current');  
 
  # to get the closest item of a point:  
  $closest = $zinc->find('closest', $x, $y);  
 
  # to get direct children of an atomic group with a pathTag:  
  @children = $zinc->find('withtag', ".atomicGroup.");  
 
# to get all groups recursively contained in a group  
@groups = $zinc->find('withtype', 'group', ".aGroup*");  
  

As detailled in addtag command the following searchCommands are possible:

  • pathname find above tagOrId
    $zinc->find('above', tagOrId);
  • pathname find atpriority priority ?tagOrId?
    $zinc->find('atpriority', priority, ?tagOrId?);
  • pathname find ancestors tagOrId ?tagOrId2?
    $zinc->find('ancestors', tagOrId, ?tagOrId2?);
  • pathname find below tagOrId
    $zinc->find('below', tagOrId);
  • pathname find closest x y ?halo? ?startItem?, ?recursive?
    $zinc->find('closest', x, y, ?halo?, ?startItem?, ?recursive?);
  • pathname find enclosed xo yo xc yc ?inGroup? ?recursive?
    $zinc->find('enclosed', xo, yo, xc, yc, ?inGroup?, ?recursive?);
  • pathname find overlapping xo yo xc yc ?inGroup? ?recursive?
    $zinc->find('overlapping', xo, yo, xc, yc, ?inGroup?, ?recursive?);
  • pathname find withtag tagOrId
    $zinc->find('withtag', tagOrId);
  • pathname find withtype type ?tagOrId?
    $zinc->find('withtype', type, ?tagOrId?);

5.2.19 fit

pathname fit coordList error

@controls = $zinc->fit(coordList, error);

This command fits a sequence of Bezier segments on the curve described by the vertices in coordList and returns a list of lists describing the points and control points for the generated segments. All the points on the fitted segments will be within error distance from the given curve. coordList should be either a flat list of an even number of coordinates in x, y order or a list of lists of point coordinates X, Y. The returned list can be directly used to create or change a curve item contour.

5.2.20 focus

pathname focus ?tagOrId? ?itemPart?

($item, $part) = $zinc->focus();
$zinc->focus(tagOrId, ?itemPart?);

Set the keyboard focus to the item described by tagOrId, and to its itemPart if the item has parts. If 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 tagOrId is an empty string the focus is reset and no item has the focus. If tagOrId is not specified, the command returns a list of two elements. The first is the id of the item with the focus or an empty string if no item has the focus. The second is the item part or an empty string if not appliable.

When the focus has been set to an item that support an insertion cursor, the item will display its cursor and the keyboard events will be directed to that item.

The widget receive keyboard events only if it has the window focus. It may be necessary to use the Tk focus command to force the focus to the widget window.

5.2.21 gdelete

pathname gdelete gradientName

$zinc->gdelete('fading');

This command breaks the binding between the given gradient name and the named gradient. When the gradient will be no longer used it will be deallocated.

5.2.22 gettags

pathname gettags tagOrId

@tags = $zinc->gettags(tagOrId);

This command returns the list of all the tags associated with the item specified by tagOrId. If more than one item is named by tagOrId, then the topmost in display list order is used to return the result. If no item is named by tagOrId, then the empty list is returned.

5.2.23 gname

pathname gname ?gradientDesc? gradientName

$zinc->gname('black:100|white:0/0', 'fading');
$exist = $zinc->gname('nameOrGradient');

This command sets a name binding between the given gradient description and the given name. The name can be used in the same way the gradient description would be. The gradient will not be deallocated until the gdelete command is invoqued on the name (and no item use the gradient). This feature can be a big performance gain when using many gradients in an animation, the name acts here as a caching mecanism.

When gname is called with only one argument, it returns iehter false or the name of a named gradient if the argument is either a named gradient or the name of a named gradient.

5.2.24 group

pathname group tagOrId

$group = $zinc->group(tagOrId);

Returns the group containing the item described by tagOrId. If more than one item is named by tagOrId, then the topmost in display list order is used to return the result.

5.2.25 hasanchors

pathname hasanchors tagOrId

$bool = $zinc->hasanchors(tagOrId);

This command returns a boolean telling if the item specified by tagOrId supports anchors. If more than one item is named by tagOrId, then the topmost in display list order is used to return the result. If no items are named by tagOrId, an error is raised.

5.2.26 hasfields

pathname hasfields tagOrId

$bool = $zinc->hasfields(tagOrId);

This command returns a boolean telling if the item specified by tagOrId supports fields. If more than one item is named by tagOrId, then the topmost in display list order is used to return the result. If no items are named by tagOrId, an error is raised.

5.2.27 hastag

pathname hastag tagOrId tag

$bool = $zinc->hastag(tagOrId, tag);

This command returns a boolean telling if the item specified by tagOrId has the specified tag. If more than one item is named by tagOrId, then the topmost in display list order is used to return the result. If no items are named by tagOrId, an error is raised.

5.2.28 index

pathname index tagOrId index

$num = $zinc->index(tagOrId, index);

This command returns a number which is the numerical index in the item described by tagOrId corresponding to index. The possible forms for index are described in Text indices . The command returns a value between 0 and the number of character in the item. If tagOrId describes more than one item, the index is processed in the first item supporting text indexing in display list order.

5.2.29 insert

pathname insert tagOrId before string

$zinc->insert(tagOrId, before, string);

This command inserts string in each item described by tagOrId just before the text position described by before. The possible values for before are described in Text indices . Items that doesn’t support text indexing are skipped by the command. The command returns an empty string.

5.2.30 itemcget

pathname itemcget tagOrId ?fieldId? attr

$val = $zinc->itemcget(tagOrId, attr);
$val = $zinc->itemcget(tagOrId, field, attr);

Returns the current value of the attribute given by attr for the item named by tagOrId. If tagOrId name more than one item, the topmost in display list order is used. If 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 attr as a field attribute (see field ), otherwise it will be interpreted as an item attribute (see the chapter Item types ). If the attribute is not available for the field or item type, an error is reported.

5.2.31 itemconfigure

pathname itemconfigure tagOrId ?fieldId? ?attr? ?value? ?attr value ...?

@attribs = $zinc->itemconfigure(tagOrId);
@attrib = $zinc->itemconfigure(tagOrId, attrib);
$zinc->itemconfigure(tagOrId, attrib=>value, ?attrib=>value?, ...);
@attrib = $zinc->itemconfigure(tagOrId, fieldId, attrib);
$zinc->itemconfigure(tagOrId, fieldId, attrib=>value, ?attrib=>value?, ...);

Query or modify the attributes of an item or field. If no attribute is given, returns a list of lists describing all the supported attributes in the same format as for a single attribute, as described next. If a single attribute is specified without a value, the command returns a list describing the named attribute. Each attribute is described by a list with the following content: the attribute name, the attribute type, a boolean telling if the attribute is read-only, an empty string, and the current value of the attribute. In the two querying forms of the command the topmost item described by tagOrId is used.

If at least one attribute - value pair is given, then the corresponding attributes are changed for all the items described by tagOrId and the command returns an empty string. If field is given, it must be a valid field index for the item or an error will be reported. If a field index is given, the command will interpret the given attributes as field attributes, otherwise they will be interpreted as item attributes. If an attribute does not belong to the item or field, an error is reported. When configuring a set of item defiend by a tag, all items must then accept these attributes.

5.2.32 lower

pathname lower tagOrId ?belowThis?

$zinc->lower(tagOrId);
$zinc->lower(tagOrId, belowThis);

Reorder all the items given by tagOrId so that they will be under the item given by belowThis. If tagOrId name more than one item, their relative order will be preserved. If tagOrId doesn’t name an item, an error is raised. If belowThis name more than one item, the bottom most them is used. If belowThis doesn’t name an item, an error is raised. If belowThis is omitted the items are put at the bottom most position of their respective groups. The command ignore all items named by tagOrId that are not in the same group than belowThis or, if not specified, in the same group than the first item named by tagOrId. The command returns an empty string. As a side affect of this command, the -priority attribute of all the reordered items is ajusted to match the priority of the belowThis item (or the priority of the bottom most item).

5.2.33 monitor

pathname monitor ?onOff?

$bool = $zinc->monitor();
$zinc->monitor(onOff);

This command controls the gathering of performance data. The data gathering is inited and turned on when the command is called with a boolean true parameter. The gathering is stopped if the command is called with a boolean false parameter. If the command is called with no parameters or with a boolean false parameter, it returns a string describing the currently collected data. The other form of the command returns the empty string.

5.2.34 numparts

pathname numparts tagOrId

$num = $zinc->numparts(tagOrId);

This command tells how many fieldId are available for event bindings or for field configuration commands in the item specified by tagOrId. If more than one item is named by tagOrId, the topmost in display list order is used to return the result. If no items are named by tagOrId, an error is raised. This command returns always 0 for items which do not support fields. The command hasfields may be used to decide whether an item has fields.

5.2.35 postscript

pathname postscript

$zinc->postscript();

Not yet implemented.

5.2.36 raise

pathname raise tagOrId ?aboveThis?

$zinc->raise(tagOrId);
$zinc->raise(tagOrId, aboveThis);

Reorder all the items given by tagOrId so that they will be above the item given by aboveThis. If tagOrId name more than one item, their relative order will be preserved. If tagOrId doesn’t name an item, an error is raised. If aboveThis name more than one item, the topmost in display list order is used. If aboveThis doesn’t name an item, an error is raised. If aboveThis is omitted the items are put at the top most position of their respective groups. The command ignore all items named by tagOrId that are not in the same group than aboveThis or, if not specified, in the same group than the first item named by tagOrId. The command returns an empty string. As a side affect of this command, the -priority attribute of all the reordered items is ajusted to match the priority of the aboveThis item (or the priority of the topmost item).

5.2.37 remove

pathname remove tagOrId ?tagOrId ...?

$zinc->remove(tagOrId, ?tagOrId?, ...);

Delete all the items named by each tagOrId. The command returns an empty string.

5.2.38 rotate

pathname rotate tagOrId angle ?degree? ?centerX centerY?

$zinc->rotate(tagOrId, angle);
$zinc->rotate(tagOrId, angle, centerX, centerY);

Add a rotation to the items or the transform described by tagOrId. If tagOrId describes a named transform then this transform is used to do the operation. If tagOrId describes more than one item then all the items are affected by the operation. If tagOrId describes neither a named transform nor an item, an error is raised. The angle is given in radian if degree is omitted or false, if it is specified as true, the angle is in degrees. The last two optional parameters describe the center of rotation, which defaults to the origin.

5.2.39 scale

pathname scale tagOrIdOrTName xFactor yFactor ?centerX centerY?

$zinc->scale(tagOrIdOrTName, xFactor, yFactor);
$zinc->scale(tagOrIdOrTName, xFactor, yFactor, centerX, centerY);

Add a scale factor to the items or the transform described by tagOrId. If tagOrId describes a named transform then this transform is used to do the operation. If tagOrId describes more than one item then all the items are affected by the operation. If tagOrId describes neither a named transform nor an item, an error is raised. A separate factor is specified for X and Y. The optional parameters describe the center of scaling, which defaults to the origin.

5.2.40 select

pathname select option ?tagOrId? ?arg?

$zinc->select(option, ?tagOrId?, ?arg?);

Manipulates the selection as requested by option. tagOrId describes the target item. This item must support text indexing and selection. If more than one item is referred to by tagOrId, the first in display list order that support both text indexing and selection will be used. Some forms of the command include an index parameter, this parameter describes a textual position within the item and should be a valid index as described in Text indices . The valid forms of the command are :

  • pathname select adjust tagOrId index
    $zinc->select('adjust', tagOrdId, index);

    Adjust the end of the selection in tagOrId that is nearest to the character given by index so that it is at index. The other end of the selection is made the anchor for future select to commands. If the selection is not currently in tagOrId, this command behaves as the select to command. The command returns an empty string.

  • pathname select clear
    $zinc->select('clear');

    Clear the selection if it is in the widget. If the selection is not in the widget, the command has no effect. Return an empty string.

  • pathname select from tagOrId index
    $zinc->select('from', tagOrdId, index);

    Set the selection anchor point for the widget to be just before the character given by index in the item described by 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.

  • pathname select item
    ($item, $part) = $zinc->select('item');

    Returns a list of two elements. The first is the id of the selected item if the selection is in an item on this widget; Otherwise the first element is an empty string. The second element is the part of the item (track, waypoint or tabular item only) or the empty string.

  • pathname select to tagOrId index
    $zinc->select('to', tagOrdId, index);

    Set the selection to be the characters that lies between the selection anchor and index in the item described by tagOrId. The selection includes the character given by index and includes the character given by the anchor point if index is greater or equal to the anchor point. The anchor point is set by the most recent select adjust or select from command issued for this widget. If the selection anchor point for the widget is not currently in tagOrId, it is set to the character given by index. The command returns an empty string.

5.2.41 skew

pathname skew tagOrIdOrTName xSkewAngle ySkewAngle

$zinc->skew(tagOrIdOrTName, xSkewAngle, ySkewAngle);

Add a skew (or shear) transform to the to the items or the transform described by tagOrIdOrTName. If tagOrId describes a named transform then this transform is used to do the operation. If tagOrId describes more than one item then all the items are affected by the operation. If tagOrId describes neither a named transform nor an item, an error is raised. The angles are given in radian.

5.2.42 smooth

pathname smooth coordList

@coords = $zinc->smooth(coordList);

This command computes a sequence of segments that will smooth the polygon described by the vertices in coordList and returns a list of lists describing points of the generated segments. These segments are approximating a Bezier curve. coordList should be either a flat list of an even number of coordinates in x, y order, or a list of lists of point coordinates X, Y. The returned list can be used to create or change the contour of a curve item.

5.2.43 tapply

pathname tapply

$zinc->tapply();

Not yet implemented.

5.2.44 tcompose

pathname tcompose tagOrIdOrTName tName ?invert?

$zinc->tcompose(tagOrIdOrTName, tName);
$zinc->tcompose(tagOrIdOrTName, tName, invert);

Modify either the named transform tagOrIdOrTName or the corresponding item by composing the tName transform. The invert boolean, if specified, causes the tName transform to be inverted prior composition.

If tagOrIdOrTName describes neither a named transform nor an item, an error is raised. If tName does not describe a named transform an error is raised.

5.2.45 tdelete

pathname tdelete tName

$zinc->tdelete(tName);

Destroy a named transform. If the given name is not found among the named transforms, an error is raised.

5.2.46 tget

pathname tget tagOrIdOrTName ?selector?

($m00, $m01, $m10, $m11, $m20, $m21) = $zinc->tget(tagOrIdOrTName);
($xtranslate, $ytranslate, $xscale, $yscale, $angle, $xskew) =
$zinc->tget(tagOrIdOrTName, 'all');
($xtranslate, $ytranslate) = $zinc->tget(tagOrIdOrTName, 'translate');
($xscale, $yscale) = $zinc->tget(tagOrIdOrTName, 'scale');
($angle) = $zinc->tget(tagOrIdOrTName, 'rotate');
($xskew) = $zinc->tget(tagOrIdOrTName, 'skew');

With only one argument, get the six elements of the 3x4 matrix used in affine transformation for tagOrIdOrTName. The result is compatible with the tset method. With optional second parameter ’all’ returns the transform decomposed in translation, scale, rotation, skew and return the list in this order, With ’translation’, ’scale’, ’rotation’, ’skew’ optional second parameter, returns the corresponding values.

5.2.47 transform

pathname transform ?tagOrIdFrom? tagOrIdTo coordList

@coords = $zinc->transform(tagOrIdTo, coordList);
@coords = $zinc->transform(tagOrIdFrom, tagOrIdTo, coordList);

This command returns a list of coordinates obtained by transforming the coordinates given in coordList from the coordinate space of the transform or item described by tagOrIdFrom to the coordinate space of the transform or item described by tagOrIdTo. If tagOrIdFrom is omitted it defaults to the window coordinate space. If either tagOrIdFrom or tagOrIdTo describes more than one item, the topmost in display list order is used. If either tagOrIdFrom or tagOrIdTo doesn’t describe either a transform or an item, an error is raised. The coordList should either be a flat list containing an even number of coordinates each point having two coordinates, or a list of lists each sublist of the form [ X Y ?pointtype? ]. The returned coordinates list will be isomorphic to the list given as argument.

It is possible to convert from window coordinate space to the coordinate space of any item. This is done by omitting ?tagOrIdFrom? and specifying in tagOrIdTo, the id of the item. It can also be done by using the predefined tag ’device’ as first argument.

It is also possible to convert from the coordinate space of an item to the window coordinate space by using the predefined tag ’device’ as second argument.

For example:

  • ($x, $y) = $zinc->transform('device', $mygroup, [$xdev, $ydev]);
    transforms the point described by $xdev,$ydev in window coordinates, to $mygroup coordinates in $x,$y;
  • ($xdev, $ydev) = $zinc->transform($mygroup, 'device', [$x, $y]);
    transforms the point described by $x,$y in $mygroup coordinates, to window coordinates in $xdev,$ydev
  • ($x2, $y2) = $zinc->transform($group1, $group2, [$x1, $y1]);
    transforms the point described by $x1,$y1 in $group1 coordinates, to $group2 coordinates in $x2,$y2;

5.2.48 translate

pathname translate tagOrIdOrTName xAmount yAmount ?absolute?

$zinc->translate(tagOrdIdOrTName, xAmount, yAmount, ?absolute?);

Add a translation to the items or the transform described by tagOrIdOrTName. If tagOrIdOrTName describes a named transform then this transform is used to do the operation. If tagOrIdOrTName describes more than one item then all the items are affected by the opration. If tagOrIdOrTName describes neither a named transform nor an item, an error is raised. A separate value is specified for X and Y. If the optionnal ?absolute? parameter is true, it will set an absolute translation to the tagOrIdOrTName

5.2.49 treset

pathname treset tagOrIdOrTName

$zinc->treset(tagOrdIdOrTName);

Set the named transform or the transform for the items described by tagOrIdOrTName to identity. If tagOrIdOrTName describes neither a named transform nor an item, an error is raised.

5.2.50 trestore

pathname trestore tagOrId tName

$zinc->trestore(tagOrdId, tName);

Set the transform for the items described by tagOrId to the transform named by tName. If tagOrId doesn’t describe any item or if the transform named tName doesn’t exist, an error is raised.

5.2.51 tsave

pathname tsave ?tagOrIdOrTName? tName ?invert?

$zinc->tsave(tName);
$zinc->tsave(tagOrdIdOrTName, tName);
$zinc->tsave(tagOrdIdOrTName, tName, invert);

Create (or reset) a transform associated with the name tName with initial value the transform associated with the item tagOrIdOrTName. If tagOrIdOrTName describes more than one item, the topmost in display list order is used. If tagOrIdOrTName doesn’t describe any item or named transformation, an error is raised. If tName already exists, the transform is set to the new value. This command is the only way to create a named transform. If tagOrIdOrTName is not specified, the command returns a boolean telling if the name is already in use. The invert boolean, if specified, cause the transform to be inverted prior to be saved.

It is possible to create a new named transformation from the identity by using the predefined tag ’identity’: $zinc->tsave('identity', 'myTransfo');

5.2.52 tset

pathname tset tagOrIdOrTName m00 m01 m10 m11 m20 m21

$zinc->tset(tagOrIdOrTName, m00, m01, m10, m11, m20, m21);

Set the six elements of the 3x4 matrix used in affine transformation for tagOrIdOrTName. BEWARE that depending on mij values, it is possible to define a not inversible matrix which will end up in core dump. This method must BE USED CAUTIOUSLY.

5.2.53 type

pathname type tagOrId

$name = $zinc->type(tagOrdId);

This command returns the type of the item specified by tagOrId. If more than one item is named by tagOrId, then the type of the topmost item in display list order is returned. If no items are named by tagOrId, an error is raised.

5.2.54 vertexat

pathname vertexat tagOrId x y

($contour, $vertex, $edgevertex) = $zinc->vertexat(tagOrdId, x, y);

Return a list of values describing the vertex and edge closest to the window coordinates x and y in the item described by tagOrId. If tagOrId describes more than one item, the first item in display list order that supports vertex picking is used. The list consists of the index of the contour containing the returned vertices, the index of the closest vertex and the index of a vertex next to the closest vertex that identify the closest edge (located between the two returned vertices).

[front]