IncrCanvas methods

We have tried to make the IncrCanvas a strict superset of the Tk canvas so that it can be dropped into existing applications. This page gives an overview of the methods of IncrCanvas, grouped according to function. For more detailed description of each method, see the IncrCanvas code documentation. Note also that the Slate class adds further functionality -- see the Slate code documentation and the overview of Slate methods.

An overview of IncrCanvas

Tycho's IncrCanvas extends the Tk canvas with hierarchical items. There are two types of item: simple items are Tk canvas items, while complex items are composed of a collection of simple and complex items. Both types of item have a unique (and opaque) ID that is passed to IncrCanvas methods to query and manipulate methods.

The Tk canvas has a powerful mechanism for manipulating items: each item can be given zero or more tags, which are used to identify a set of items. IncrCanvas extends the tagging mechanism to operate with complex items. In addition, it has the notion of an "invisible" item: any item tagged with "#" is treated differently by many methods -- this is for use in implementing background items, grids, and so on, which do not respond to the mouse. Because of the way that IncrCanvas uses tags internally, tags must not start with the characters "_" or "!".

The Tk canvas also gives each item a number of options which control its appearance. Options always start with a dash, and, if setting options, are followed by a value. For example, when creating an item, the argument list might include -fill red, which will fill the item red. The tags of an item are in fact an option, although manipulating tags should usually be done with the methods addtag, dtag, and gettags.

All canvas methods fall into one of three classes:

Creating and deleting items

create type ?x0 y0 ... ? ?option value ...?
Create a new item and return its ID. If type starts with a lower-case letter, create a simple item; if not, create a complex item. The number of coordinates depends on the item type; following arguments are option-value pairs.

create* tags type ?x0 y0 ... ? ?option value ...?
This is a version of create that is slightly faster if initializing an item with tags: instead of providing the tags in the options list, they are provided as the first argument.

createchild parent type ?x0 y0 ... ? ?option value ...?
Create a new item that is a child of some other item, and return its ID. The child item becomes a "part" of the parent item, and will be moved and scaled when the parent is moved and scaled.

createchild* parenttags tags type ?x0 y0 ... ? ?option value ...?
This is a faster version of createchild: instead of providing the name of the parent and the tags in the options list, provide the tags of the parent as the first argument, and the new tags of the item as the second. This method should only be used within the construct procedure of the complex item classes.

createrootchild parent type ?x0 y0 ... ? ?option value ...?
Create a new "logical root" that is a child of some other item, and return its ID. A "root" item is one that will respond to events, but otherwise behaves like a regular child item.

createrootchild* parenttags tags type ?x0 y0 ... ? ?option value ...?
This is a faster version of createrootchild, again, intended only for use within the construct procedure of the complex item classes.

delete ?tagOrID ...?
Delete all matching items. Each argument can be an item ID or a tag.

root id
Return the root of an item -- that is, the item containing this one (or this one if it is a root) that will respond to events. Note that the argument must be an item ID, not a tag.

Moving and scaling items

bbox ?tagOrID? ....
Return the bounding box of the matching items in a four-element list. Each argument can either be an item ID or a tag. If there are no matching items, return null.

coords tagOrID ?x0 y0 ... ?
If just the first argument is given, return the coordinates of the item (or the first matching item if the argument is a tag). If coordinates are also given, set the item's coordinates to those coordinates.

find searchSpec
Return all items matching searchSpec. searchSpec can have the following forms:

lower tagOrID ?belowThis?
Lower all items matching the first argument to the bottom of the display list, or to just below belowThis if it is given. belowThis can also be a tag or an ID -- if a tag, lower below the first matching item.

move tagOrID ?x y?
Move all matching items by the given amount. The first argument can either be a tag or an id.

raise tagOrID ?aboveThis?
Raise all items matching the first argument to the top of the display list, or to just above aboveThis if it is given. aboveThis can also be a tag or an ID -- if a tag, raise above the first matching item.

scale tagOrID ?xOrigin yOrigin xScale yScale?
Scale all matching items. xOrigin and yOrigin specify the point about which scaling occurs; xScale and yScale are the proportions to scale by.

Configuring items

itemcget tagOrID option
Read the specified configuration option of the given item, or of the first matching item if the first argument is a tag.

itemconfigure tagOrID ?option value ...?
If only the first argument is given, return a list of all configuration options of the given item, or the first matching item if the first argument is a tag. If the second argument is given, return a list representing the given option; if three or more arguments are given, set each option to the given value.

Tagging and binding

addtag tag searchSpec
Add tag to all items indicated by searchSpec. searchSpec has all the same formats as the find method.

bind tagOrID ?sequence? ?command?
Bind a command to an item or tag. If just the first argument is given, return the event sequences for which there is a binding to tagOrID. If sequence is given, return the command, if any, bound to the given tag or ID and event sequence. If command is given, bind it to the given tag or ID and event sequence.

dtag tagOrID ?delete?
If delete is not given, delete tag tagOrID from all items matching by tagOrID; if delete is given, delete the tag delete from all items matching tagOrID.

gettags tagOrID
Return the tags of the given item, or the first matching item if the argument is a tag.

Focus and selection on the canvas

These methods may not be fully implemented yet.

dchars tagOrID first ?last?
Delete characters in a text item. Not properly implemented for complex items.

focus ???
Focus on an item. Not properly implemented for complex items.

focusin
Apply the focus to the canvas inside the slate.

icursor tagOrID index
Set the insertion cursor. Not properly implemented for complex items.

index tagOrID index
Return the numerical value of a symbolic index. Not properly implemented for complex items.

insert tagOrID beforeThis string
Insert text at the insertion cursor. Not properly implemented for complex items.

select mode ?tagOrID? ?index?
Manipulate the selection in a text item. The mode argument can have the following values, which control the position of the selection in the current text item: adjust, clear, from, item, and to.

Miscellaneous canvas methods

These methods simply defer their actions to the canvas contained in the IncrCanvas.

canvasx screenx ?gridspacing?
Convert a screen x coordinate into a canvas x coordinate

canvasy screeny ?gridspacing?
Convert a screen y coordinate into a canvas y coordinate

postscript ???
Generate a postscript representation of the canvas.

scan option ?val? ...
Scanning on an item???.

type tagOrID
Return the type of the given item.

xview ???
Set the horizontal view for scrolling.

yview ???
Set the vertical view for scrolling.

Back up
Tycho Home Page


Copyright © 1996-1998, The Regents of the University of California. All rights reserved.
Last updated: 05/20/98, comments to: johnr@eecs.berkeley.edu