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.
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:
create type ?x0 y0 ... ? ?option value ...?
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 ...?
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 ...?
createchild* parenttags tags type ?x0 y0 ... ? ?option value ...?
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 ...?
createrootchild* parenttags tags type ?x0 y0 ... ? ?option value ...?
createrootchild
,
again, intended only for use within the construct
procedure of the complex item classes.
delete ?tagOrID ...?
root id
must
be an item ID, not a tag.
bbox ?tagOrID? ....
coords tagOrID ?x0 y0 ... ?
find searchSpec
searchSpec
.
searchSpec
can have the following forms:
above tagOrID
: Return the root item immediately
above the item matching tagOrID
.
all
: Return every root item.
below tagOrID
: Return the root item immediately
below the item matching tagOrID
.
closest x y ?halo? ?start?
: Return the root item
closest to the point (x,y)
.
enclosed x0 x1 y0 y1
: Return every root item
enclosed by the given region. Invisible items will not be
# returned.
overlapping x0 x1 y0 y1
: Return every root item
that overlaps the given region. Invisible items will not be
# returned.
withtag tagOrID
: If
tagOrID
is an ID, just return it. If it is a tag,
return every complex item that has been tagged with
tagOrID
, and every unparented simple item with
that tag. If tagOrID
is "current," return the
root item that the mouse is currently operating on.
lower tagOrID ?belowThis?
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?
raise tagOrID ?aboveThis?
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?
xOrigin
and
yOrigin
specify the point about which scaling
occurs; xScale
and yScale
are
the proportions to scale by.
itemcget tagOrID option
itemconfigure tagOrID ?option value ...?
addtag tag searchSpec
tag
to all items indicated by
searchSpec
. searchSpec
has
all the same formats as the find
method.
bind tagOrID ?sequence? ?command?
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?
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
dchars tagOrID first ?last?
focus ???
focusin
icursor tagOrID index
index tagOrID index
insert tagOrID beforeThis string
select mode ?tagOrID? ?index?
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
.
canvasx screenx ?gridspacing?
canvasy screeny ?gridspacing?
postscript ???
scan option ?val? ...
type tagOrID
xview ???
yview ???