Canvas Operations

	Practical Programming in Tcl & Tk, Third Edition By Brent B. Welch
	Table of Contents

	Chapter 34. The Canvas Widget

Canvas Operations

Table 34-11 summarizes the operations on canvas widgets. In the table, $c is a canvas and $t represents a canvas tag or numerical object ID. In some cases, an operation only applies to a single object. In these cases, if a tag identifies several objects, the first object in the display list is operated on.

The canvas display list refers to the global order among canvas objects. New objects are put at the end of the display list. Objects later in the display list obscure objects earlier in the list. The term above refers to objects later in the display list.

Table 34-9 describes several of the canvas operations that only apply to text objects. They are dchars , focus , index , icursor , insert , and select. Table 34-11 does not repeat those operations.

Table 34-11. Operations on a `canvas` widget.

`$c addtag` `tag` `above $t`	Adds `tag` to the item just above `$t` in the display list.
`$c addtag` `tag` `all`	Adds `tag` to all objects in the canvas.
`$c addtag` `tag` `below $t`	Adds `tag` to the item just below `$t` in the display list.
`$c addtag` `tag` `closest` `x y ?halo? ?start?`	Adds `tag` to the item closest to the `x y` position. If more than one object is the same distance away, or if more than one object is within `halo` pixels, then the last one in the display list (uppermost) is returned. If `start` is specified, the closest object after `start` in the display list is returned.
`$c addtag` `tag` `enclosed` `x1 y1 x2 y2`	Adds `tag` to the items completely enclosed in the specified region. `x1` <= `x2` , `y1` <= `y2` .
`$c addtag` `tag` `withtag $t`	Adds `tag` to the items identified by `$t` .
`$c bbox $t ?` `tag tag` `...?`	Returns the bounding box of the items identified by the tag(s) in the form `x1 y1 x2 y2`
`$c bind $t` `?sequence? ?command?`	Sets or queries the bindings of canvas items.
`$c canvasx` `screenx ?grid?`	Maps from the X screen coordinate `screenx` to the X coordinate in canvas space, rounded to multiples of `grid` if specified.
`$c canvasy` `screeny ?grid?`	Maps from screen Y to canvas Y.
`$c cget` `option`	Returns the value of `option` for the canvas.
`$c configure ...`	Queries or updates the attributes of the canvas.
`$c coords $t ?` `x1 y1` `...?`	Queries or modifies the coordinates of the item.
`$c create` `type x y` `?` `x2 y2` `...? ?` `opt value` `...?`	Creates a canvas object of the specified `type` at the specified coordinates.
`$c delete $t ?` `tag` `...?`	Deletes the item(s) specified by the tag(s) or ID(s).
`$c dtag $t ?` `deltag` `?`	Removes the specified tags from the items identified by `$t` . If `deltag` is omitted, it defaults to `$t.`
`$c find` `addtagSearch` `...`	Returns the IDs of the tags that match the search specification: `above` , `all` , `below` , `closest` , `enclosed` , and `withtag` , as for `addtag` .
`$c gettags $t`	Returns the tags associated with the first item identified by `$t` .
`$c itemcget $t` `option`	Returns the value of `option` for item `$t` .
`$c itemconfigure $t ...`	Queries or reconfigures item `$t` .
`$c lower $t` `?belowThis?`	Moves the items identified by `$t` to the beginning of the display list, or just before `belowThis` .
`$c move $t` `dx dy`	Moves `$t` by the specified amount.
`$c postscript ...`	Generates postscript. Table 34-12 lists options.
`$c raise $t ?` `aboveThis` `?`	Moves the items identified by `$t` to the end of the display list, or just after `aboveThis` .
`$c scale $t` `x0 y0 xS yS`	Scales the coordinates of the items identified by `$t` . The distance between `x0` and a given X coordinate changes by a factor of `xS` . Similarly for Y.
`$c scan mark` `x y`	Sets a mark for a scrolling operation.
`$c scan dragto` `x y`	Scrolls the canvas from the previous mark.
`$c type $t`	Returns the type of the first item identified by `$t` .
`$t xview`	Returns two fractions between zero and one that describes the amount of the canvas off-screen to the left and the amount of the canvas displayed.
`$t xview moveto` `fraction`	Positions the canvas so that `fraction` of the scroll region is off screen to the left.
`$t xview scroll` `num what`	Scrolls `num` of `what` , which is `units` or `pages` .
`$t yview`	Returns two fractions between zero and one that describes the amount of the canvas off screen to the top and the amount of the canvas displayed.
`$t yview moveto` `fraction`	Positions the text so that `fraction` of the canvas scroll region is off screen toward the top.
`$t yview scroll` `num what`	Scrolls `num` of `what` , which is `units` or `pages` .