start page | rating of books | rating of authors | reviews | copyrights
Book HomeMastering Perl/TkSearch this book
PreviousNext

9.9. Tags

Each item can also have a tag (or more than one tag) associated with it. We have seen tags used before in the Text widget, where sections of text could be assigned a tag. A tag can be assigned when the item is created, or you can use the addtag method to assign a tag after the item has been created.

There are two special tags that are assigned and maintained automatically: "current" and "all". The "all" tag refers to all the items in the Canvas. The "current" tag refers to the topmost item that the mouse cursor is over. If the mouse cursor is outside the Canvas widget or not over an item, the "current" tag does not exist.

You can use tags to make changes to many different items at once. For instance, if you want all circles to have the same color, but you want to be able to change it from time to time, give all circles a "circle" tag when you create them, using the itemconfigure method to change the configuration options of the items with the "circle" tag.

Tags can also be logical expressions by using the operators: &&, ||, ^, !, and parenthetical subexpressions. For example: 

$c->find('withtag',  '(a&&!b)|(!a&&b)');

or equivalently:

$c->find('withtag', 'a^b');

will find only those items with either a or b tags, but not both.

The following are some sample syntax lines for creating tags:

$canvas->addtag("newtag", "above", tag/id);
The "newtag" tag is added to the item that is above the tag/id item. If there is more than one match for tag/id, the last item found will be used so the "newtag" is directly above the tag/id item in the display list. The display list is created as you add items to the Canvas and can be manipulated with the raise and lower methods.

$canvas->addtag("newtag", "all");
The keyword "all" is a special tag that includes every item currently in the Canvas. Items added to the Canvas after the call to add tag will not contain "newtag" in their tag lists.

$canvas->addtag("newtag", "below", tag/id);
The "newtag" tag is added to the item that is directly below the tag/id item. If more than one item matches the below tag/id search, the lowest item in the list will be used.

$canvas->addtag("newtag", "closest", x, y);
Use the "closest" tag to select the item closest to the (x, y) coordinates (in Canvas coordinates). If more than one item matches, the last one found is used.

There are two more possible arguments for this form of addtag. You can specify a number that indicates how far out from the (x, y) coordinates items are to be considered. For instance, if you want an item that is within 10 pixels to be considered "closest", make the call as follows: 

$canvas->addtag("newtag", "closest", 50, 100, 10);

You can also specify a starting tag or ID to start a search. The call would then look like this: 

$canvas->addtag("newtag", "closest", x, y, 10, $tag_or_id);

Using this form, you can loop through all the closest items.

$canvas->addtag("newtag", "enclosed", x1, y1, x2, y2);
You can use the "enclosed" form of addtag to assign the same tag to several items within the area bounded by (x1, y1) to (x2, y2). Items will be given "newtag" only if they are completely within the area. The coordinates must make sense when you specify them: x1 < x2 and y1 < y2.

$canvas->addtag("newtag", "overlapping", x1, y1, x2, y2);
To assign tags to any item that has any part inside a bounded region, use "overlapping" instead of "enclosed". Even if the item has only one pixel inside this area, it will still count. All other rules for the bounding area are the same as for "enclosed".

$canvas->addtag("newtag", "withtag", tag/id);
Assigns "newtag" to all the items with the tag or ID specified.

9.9.1. Binding Items Using Tags

Each item in a Canvas can have an event sequence bound to it so that a callback will be invoked when that event sequence happens. This is similar to adding an event sequence binding for widgets, except item tags or item IDs are used. (Remember, if you want to add a normal binding to the Canvas widget itself, you must use CanvasBind instead of just bind.)

The general form of bind is as follows:

$canvas->bind(tag/id [ , sequence, command ] );

The sequence would be similar to "<Button-1>" or "<Double-1>". A complete definition and explanation of event sequences is available in Chapter 15, "Anatomy of the MainLoop".

When you create item bindings, keep in mind that only mouse and keyboard bindings are valid for items. You can't do any of the weird, esoteric bindings that are available for all widgets.

Here is an example that changes the color of any items tagged with "blue" when the mouse is over them: 

# When the mouse is over the item, color it blue
$c->bind("blue", "<Enter>", 
         sub { $c->itemconfigure("blue", -fill => "blue"); });
# When the mouse is not over, color it black.
$c->bind("blue", "<Leave>",
         sub { $c->itemconfigure("blue", -fill => "black"); });

9.9.2. Finding Tags

You can use the find command to determine which items have a certain tag. The possible ways to call find are the same as those of addtag (except for the newtag argument). Here are the basic formats (see "Tags" earlier in this chapter for more details on what they mean and how they work): 

$canvas->find("above", tag/id);
$canvas->find("all");
$canvas->find("below", tag/id);
$canvas->find("closest", x, y [ , additional_area ] [ , tag/id ]);
$canvas->find("enclosed", x1, y1, x2, y2);
$canvas->find("overlapping", x1, y1, x2, y2);
$canvas->find("withtag", tag/id);

9.9.3. Getting Tags from a Specific Item

To get a list of all the tags associated with an item, use: 

@list = $canvas->gettags(tag/id);

If the tag/id matches more than one item, the first item found is used. If the tag/id doesn't match anything, an empty string is returned.

PreviousHomeNext
9.8. Configuring Items in the Canvas WidgetBook Index9.10. Retrieving Bounding Box Coordinates
Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.