Chapter 4
Item ids, tags and indices

4.1 Item ids

Each item is associated with a unique numerical id which is returned by the add or clone commands. All commands on items accept those ids as (often first) parameter in order to uniquely identify on which item they should operate. When an id has been allocated to an item, it is never collected even after the item has been destroyed, in a TkZinc session two items cannot have the same id. This property can be quite useful when used in conjonction with tags, which are described below.

4.2 Tags

Apart from an id, an item can be associated with as many symbolic names as it may be needed by an application. Those names are called tags and can be any string which does not form a valid id (an integer). However the following characters may not be used to form a tag: . * ! ( ) & | :. Tags exists, and may be used in commands, even if no item are associated with them. In contrast an item id doesn’t exist if its item is no longer around and thus it is illegal to use it. Tags can be used to group items to do some action, or to mark an item that has a special function. Many other tasks can be solved with tags once one gets used to them.

Two special tags are implicitly managed by TkZinc. The tag all is associated with all items in TkZinc. The tag current is always associated with the topmost item that lies under the mouse pointer. If no such item exists, no item has this tag.

In commands, tags can be used almost anywhere an item id would be legal. In the command descriptions, the expression tagOrId means that it is legal to provide either a tag or an item id. This means that virtually all actions can be either performed on a specific item by using its id or on a whole set of items by using a tag. In order for this collective behavior to be useful, if a command or an attribute does not apply to an item named by the tag, it is simply ignored, no error will be reported (This may yet not be the case with all commands, please report infringements).

Everywhere a tagOrId can be specified as a target for some action, it is possible to give a logical expression of tags and ids. The available boolean operators include logical and &&, logical or ||, logical xor ^, logical not ! and subexpression grouping (). Here is an example of a bbox command called on a set of items defined by a logical expression. Note that tags and ids can be mixed. For example:

 ($xo, $yo, $xc, $yc) = $zinc->bbox("(red && black)||(pink && !$thisitem)");

Many methods only operate on a single item at a time; if tagOrId is specified in a way that names multiple items, then the normal behavior for these methods is to use the first of these items in the display list (most visible) that is suitable for the method. Exceptions are noted in the method descriptions below.

Tags can be associated with items by giving a tag list to the -tags attribute or by using the more powerful addtag command. A tag can be removed by the dtag command, by setting the -tags attribute to the empty list, all tags are remove from an item at once (except the implicit ones). Tags can be read with the gettags or by querying the -tags attribute. The items named by a tag are returned in a list by the find command which as exactly the same capabilities as addtag .

4.3 PathTags

A special form of tag called a pathTag can be used as a tagOrId argument in all commands except bind . This special tag describes an item or a group of items in the absolute item hierarchy. The pathTag consists in a path down the group hierarchy followed by an (optionnal) effective tag, in the usual sense.

The path is an ordered list of tags set up on groups that drives the search from the root group down the group hierarchy. The path starts with either a dot or a star, and the tags in the path are separated by dots or stars. The dot means that the next tag selects a group item that is a direct child of the current group, starting with the root group. The star selects a group item that is a possibly indirect child of the current group, the candidate is found in display list order. The first tag in the path, the one just after the first dot or star, can be a group id; This is useful in order to limit the search in a specific sub-hierarchy.

The last tag of a pathTag, the one not followed by a dot or a star, is the effective tag searched for. It can be omitted, in this case the search proceed with the tag all. The dot or star just before the effective tag, even if the tag is implied, controls how the tag is searched. If a dot is present, the search is limited to the current group level. If a star is present, the search proceed from the current group level down the whole group subtree.

A demo called “Using pathTags” in zinc-demos may help you better understand pathTags. Here are some commonly used pathTags idioms:

4.4 Tags and bindings

Tags are also very useful to associate scripts with events. The bind command is used to specify a script to be invoqued when an event sequence is associated with a tag.

The event dispatch mecanism in TkZinc collects which tags are related to a given event and then use the bindings established by bind to activate the related scripts. Event dispatching operates on three event sources: mouse events, keyboard events and internally generated enter/leave events. Mouse events are dispatched to the item under the mouse pointer, if any; keyboard events are dispatched to the focus item, if any; leave events are dispatched to the item previously under the pointer, enter events to the item newly under the pointer. Tags are collected from the item found.

Special tags are managed for items with fields or parts (e.g. a track has both, a tabular has only fields and a rectangle has none). They are built from a tag or an id followed by a : followed by a (zero based) field index or by the name of a part. Those tags can only be used in event bindings.

Here is the complete list of tags, either real or implicit, that are tried to find bindings. They are listed in the order they are processed.

  1. the implicit tag all (associated with all items),
  2. the other tags (in some not reliable order),
  3. the item id,
  4. the implicit tags build from the tags and the current part name or field index, if any,,
  5. the implicit tag build from the item id and the current part name or field index, if any.

An exception is made for the Leave event when dispatched to an item with parts or fields. This is needed to process the exit of a field/part before the exit of the corresponding item. In this case the order is shown by the following list.

  1. the implicit tags build from the tags and the current part name or field index,
  2. the implicit tag build from the item id and the current part name or field index,
  3. the implicit tag all,
  4. the other tags,
  5. the item id.

Here are examples of possible bindings.

  1. $zinc->bind($id, '<1>', \&acallback);
    will call acallback if mouse button 1 is clicked anywhere over item $id;
  2. $zinc->bind('selected', '<1>', \&acallback);
    the click must be anywhere over any item associated with the selected tag;
  3. $zinc->bind('foo:0', '<1>', \&acallback);
    the click must occurs over field 0 of an item with tag foo;
  4. $zinc->bind("$id:3", '<1>', \&acallback);
    the click must be over field 3 of item $id, and the field must exists in the item;
  5. $zinc->bind("$id:speedvector", '<1>', \&acallback);
    the click must be over a part named speedvector (item track) in item $id, the part must exists in the item.

4.5 Text indices

Indices are used to specify a character position in textual items such as the text item. Indices are accepted as parameters by commands managing text: cursor , index , insert , dchars and select .