Canvas(3pm)

🎀 Canvas(3pm): Tk::Canvas — Create and manipulate Canvas widgets 🎀

✨ NAME ✨

Tk::Canvas — create and manipulate Canvas widgets, and honestly? iconic.

🌸 SYNOPSIS 🌸

$canvas = $parent->Canvas(?options?);

👑 STANDARD OPTIONS 👑

Canvas rolls with all these standard Tk options, no cap:

• -background
• -highlightthickness
• -insertwidth
• -state
• -borderwidth
• -insertbackground
• -relief
• -tile
• -cursor
• -insertborderwidth
• -selectbackground
• -takefocus
• -highlightbackground
• -insertofftime
• -selectborderwidth
• -xscrollcommand
• -highlightcolor
• -insertontime
• -selectforeground
• -yscrollcommand

💅 WIDGET-SPECIFIC OPTIONS 💅

These are the options that make Canvas extra, bestie.

🎀 closeEnough 🎀

• Name: closeEnough
• Class: CloseEnough
• Switch: -closeenough

Specifies a floating-point value indicating how close the mouse cursor must be to an item before it is considered to be “inside” the item. Defaults to 1.0.

🎀 confine 🎀

• Name: confine
• Class: Confine
• Switch: -confine

Specifies a boolean value that indicates whether or not it should be allowable to set the canvas's view outside the region defined by the scrollRegion argument. Defaults to true, which means that the view will be constrained within the scroll region.

🎀 height 🎀

• Name: height
• Class: Height
• Switch: -height

Specifies a desired window height that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the COORDINATES section below.

🎀 scrollRegion 🎀

• Name: scrollRegion
• Class: ScrollRegion
• Switch: -scrollregion

Specifies a list with four coordinates describing the left, top, right, and bottom coordinates of a rectangular region. This region is used for scrolling purposes and is considered to be the boundary of the information in the canvas. Each of the coordinates may be specified in any of the forms given in the COORDINATES section below.

🎀 state 🎀

• Name: state
• Class: State
• Switch: -state

Modifies the default state of the canvas where state may be set to one of: normal, disabled, or hidden. Individual canvas objects all have their own state option, which overrides the default state. Many options can take separate specifications such that the appearance of the item can be different in different situations. The options that start with "active" control the appearance when the mouse pointer is over it, while the option starting with "disabled" controls the appearance when the state is disabled.

🎀 width 🎀

• Name: width
• Class: width
• Switch: -width

Specifies a desired window width that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the COORDINATES section below.

🎀 xScrollIncrement 🎀

• Name: xScrollIncrement
• Class: ScrollIncrement
• Switch: -xscrollincrement

Specifies an increment for horizontal scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the canvas x coordinate at the left edge of the window is always an even multiple of xScrollIncrement; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be xScrollIncrement. If the value of this option is less than or equal to zero, then horizontal scrolling is unconstrained.

🎀 yScrollIncrement 🎀

• Name: yScrollIncrement
• Class: ScrollIncrement
• Switch: -yscrollincrement

Specifies an increment for vertical scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the canvas y coordinate at the top edge of the window is always an even multiple of yScrollIncrement; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be yScrollIncrement. If the value of this option is less than or equal to zero, then vertical scrolling is unconstrained.

🌈 DESCRIPTION 🌈

okay so the Canvas method creates a new window (given by the $canvas argument) and makes it into a canvas widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the canvas such as its colors and 3-D relief. The canvas command returns its $canvas argument. At the time this command is invoked, there must not exist a window named $canvas, but $canvas's parent must exist.

Canvas widgets implement structured graphics. A canvas displays any number of items, which may be things like rectangles, circles, lines, and text. Items may be manipulated (e.g. moved or re-colored) and callbacks may be associated with items in much the same way that the bind method allows callbacks to be bound to widgets. For example, a particular callback may be associated with the <Button-1> event so that the callback is invoked whenever button 1 is pressed with the mouse cursor over an item. This means that items in a canvas can have behaviors defined by the Callbacks bound to them. periodt.

🦋 DISPLAY LIST 🦋

The items in a canvas are ordered for purposes of display, with the first item in the display list being displayed first, followed by the next item in the list, and so on. Items later in the display list obscure those that are earlier in the display list and are sometimes referred to as being “on top” of earlier items. When a new item is created it is placed at the end of the display list, on top of everything else. Widget methods may be used to re-arrange the order of the display list. it's giving layers.

Window items are an exception to the above rules. The underlying window systems require them always to be drawn on top of other items. In addition, the stacking order of window items is not affected by any of the canvas methods; you must use the raise and lower Tk widget methods instead. lowkey important.

🏷️ ITEM IDS AND TAGS 🏷️

Items in a canvas widget may be named in either of two ways: by id or by tag. Each item has a unique identifying number which is assigned to that item when it is created. The id of an item never changes and id numbers are never re-used within the lifetime of a canvas widget. iconic.

Each item may also have any number of tags associated with it. A tag is just a string of characters, and it may take any form except that of an integer. For example, “x123” is OK but “123” isn't. The same tag may be associated with many different items. This is commonly done to group items in various interesting ways; for example, all selected items might be given the tag “selected”. obsessed.

The tag all is implicitly associated with every item in the canvas; it may be used to invoke operations on all the items in the canvas.

The tag current is managed automatically by Tk; it applies to the current item, which is the topmost item whose drawn area covers the position of the mouse cursor. If the mouse is not in the canvas widget or is not over an item, then no item has the current tag. main character energy.

When specifying items in canvas methods, if the specifier is an integer then it is assumed to refer to the single item with that id. If the specifier is not an integer, then it is assumed to refer to all of the items in the canvas that have a tag matching the specifier. The symbol tagOrId is used below to indicate that an argument specifies either an id that selects a single item or a tag that selects zero or more items.

tagOrId may contain a logical expressions of tags by using operators: '&&', '||', '^' '!', and parenthezised 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.

Some 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 is for the methods is to use the first (lowest) of these items in the display list that is suitable for the method. Exceptions are noted in the method descriptions below.

📐 COORDINATES 📐

All coordinates related to canvases are stored as floating-point numbers. Coordinates and distances are specified in screen units, which are floating-point numbers optionally followed by one of several letters. If no letter is supplied then the distance is in pixels. If the letter is m then the distance is in millimeters on the screen; if it is c then the distance is in centimeters; i means inches, and p means printers points (1/72 inch). Larger y-coordinates refer to points lower on the screen; larger x-coordinates refer to points farther to the right. math is mathing.

🔄 TRANSFORMATIONS 🔄

Normally the origin of the canvas coordinate system is at the upper-left corner of the window containing the canvas. It is possible to adjust the origin of the canvas coordinate system relative to the origin of the window using the xview and yview methods; this is typically used for scrolling. Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system. no rotation, bestie.

Individual items may be moved or scaled using methods described below, but they may not be rotated.

✨ INDICES ✨

Okay bestie, so text items have this whole concept of an index — it's how you point at a specific spot inside an item. Think of it like a little cursor address. 💅

Indices are what you use for methods like inserting text, deleting a range of characters, and setting where the insertion cursor lives. You can specify an index in a bunch of different ways, and different item types might support different forms. No cap, they're not all the same.

And like, same energy for line and polygon items — they support indices too, for identifying, inserting and deleting subsets of their coordinates. Indices get used for commands like inserting or deleting a range of characters or coordinates, and setting the insertion cursor position. An index can be specified in any of a number of ways, and different types of items may support different forms for specifying indices. 🦋

Text items support the following forms for an index — and if you're out here defining new types of text-like items, it would be advisable to support as many of these forms as practical. Note that it's totally possible to refer to the character just after the last one in the text item; that's necessary for stuff like inserting new text at the end of the item. Lines and Polygons don't support the insertion cursor and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs. 👯‍♀️

• number — A decimal number giving the position of the desired character within the text item. 0 refers to the first character, 1 to the next character, and so on. If indexes are odd for lines and polygons, they will be automatically decremented by one. A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For polygons, numbers less than 0 or greater then the length of the coordinate list will be adjusted by adding or substracting the length until the result is between zero and the length, inclusive.
• end — Refers to the character or coordinate just after the last one in the item (same as the number of characters or coordinates in the item).
• insert — Refers to the character just before which the insertion cursor is drawn in this item. Not valid for lines and polygons. 🙈
• sel.first — Refers to the first selected character in the item. If the selection isn't in this item then this form is illegal. 🚫
• sel.last — Refers to the last selected character in the item. If the selection isn't in this item then this form is illegal. 🚫
• [x,y] — Refers to the character or coordinate at the point given by x and y, where x and y are specified in the coordinate system of the canvas. If x and y lie outside the coordinates covered by the text item, then they refer to the first or last character in the line that is closest to the given point. The Tcl string form "@x,y" is also allowed.

---

🎀 DASH PATTERNS 🎀

Many items support the notion of an dash pattern for outlines. Yes. Dashes. Iconic. ⭐

The first possible syntax is a list of integers. Each element represents the number of pixels of a line segment. Only the odd segments are drawn using the "outline" color. The other segments are drawn transparent. 🫥

The second possible syntax is a character list containing only 5 possible characters [.,-_ ], with the first 4 characters producing a segment of length 1 to 4, respectively, followed by a transparent segment of length 2. The space can be used repeatedly to enlarge the space between other line elements by 1, and can not occur as the first position in the string. The main difference of this syntax with the previous one is that it it shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This assures that "." will always be displayed as a dot and "-" always as a dash regardless of the line width. 💅

Some examples, for a line width of 2:

 -dash .     = -dash [2,4]
 -dash -     = -dash [6,4]
 -dash -.    = -dash [6,4,2,4]
 -dash -..   = -dash [6,4,2,4,2,4]
 -dash '.  ' = -dash [2,8]
 -dash ','   = -dash [4,4]

On systems where only a limited set of dash patterns is available, the dash pattern will be displayed as the closest available dash pattern. For example, on Windows only the first 4 of the above examples are available. The last 2 examples will be displayed identically as the first one. iykyk 😭

---

💖 WIDGET METHODS 💖

The Canvas method creates a widget object. This object supports the configure and cget methods described in Tk::options which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class. 🫶

The following additional methods are available for canvas widgets:

$canvas->addtag(tag, searchSpec, ?arg, arg, ...?)

For each item that meets the constraints specified by searchSpec and the args, add tag to the list of tags associated with the item if it isn't already present on that list. It is possible that no items will satisfy the constraints given by searchSpec and args, in which case the method has no effect. This command returns an empty string as result. SearchSpec and arg's may take any of the following forms:

• above tagOrId — Selects the item just after (above) the one given by tagOrId in the display list. If tagOrId denotes more than one item, then the last (topmost) of these items in the display list is used.
• all — Selects all the items in the canvas. 👑
• below tagOrId — Selects the item just before (below) the one given by tagOrId in the display list. If tagOrId denotes more than one item, then the first (lowest) of these items in the display list is used.
• closest x y ?halo? ?start? — Selects the item closest to the point given by x and y. If more than one item is at the same closest distance (e.g. two items overlap the point), then the top-most of these items (the last one in the display list) is used. If halo is specified, then it must be a non-negative value. Any item closer than halo to the point is considered to overlap it. The start argument may be used to step circularly through all the closest items. If start is specified, it names an item using a tag or id (if by tag, it selects the first item in the display list with the given tag). Instead of selecting the topmost closest item, this form will select the topmost closest item that is below start in the display list; if no such item exists, then the selection behaves as if the start argument had not been specified.
• enclosed x1 y1 x2 y2 — Selects all the items completely enclosed within the rectangular region given by x1, y1, x2, and y2. X1 must be no greater then x2 and y1 must be no greater than y2.
• overlapping x1 y1 x2 y2 — Selects all the items that overlap or are enclosed within the rectangular region given by x1, y1, x2, and y2. X1 must be no greater then x2 and y1 must be no greater than y2.
• withtag tagOrId — Selects all the items given by tagOrId.

$canvas->bbox(tagOrId, ?tagOrId, tagOrId, ...?)

Returns a list with four elements giving an approximate bounding box for all the items named by the tagOrId arguments. The list has the form ``x1 y1 x2 y2'' such that the drawn areas of all the named elements are within the region bounded by x1 on the left, x2 on the right, y1 on the top, and y2 on the bottom. The return value may overestimate the actual bounding box by a few pixels. If no items match any of the tagOrId arguments or if the matching items have empty bounding boxes (i.e. they have nothing to display) then an empty string is returned. 📦

$canvas->bind(tagOrId?, sequence? ?,callback?)

This method associates callback with all the items given by tagOrId such that whenever the event sequence given by sequence occurs for one of the items the callback will be invoked. This method is similar to the bind method except that it operates on items in a canvas rather than entire widgets. See Tk::bind for complete details on the syntax of sequence and the substitutions performed on callback before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagOrId (if the first character of command is ``+'' then command augments an existing binding rather than replacing it). In this case the return value is an empty string. If callback is omitted then the method returns the callback associated with tagOrId and sequence (an error occurs if there is no such binding). If both callback and sequence are omitted then the method returns a list of all the sequences for which bindings have been defined for tagOrId. 🔗

The only events for which bindings may be specified are those related to the mouse and keyboard (such as Enter, Leave, ButtonPress, Motion, and KeyPress) or virtual events. The handling of events in canvases uses the current item defined in "ITEM IDS AND TAGS" above. Enter and Leave events trigger for an item when it becomes the current item or ceases to be the current item; note that these events are different than Enter and Leave events for windows. Mouse-related events are directed to the current item, if any. Keyboard-related events are directed to the focus item, if any (see the focus method below for more on this). If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. 💀

Okay so multiple bindings can totally match the same event, and this is where it gets spicy 💅. It happens when, say, one binding is hanging out with the item's id and another one is chilling with one of the item's tags. When that goes down, all of the matching bindings get invoked. Here's the order, bestie, and it matters:

• the binding associated with the all tag fires first
• then one binding for each of the item's tags, in order
• then the binding associated with the item's id

If there are multiple matching bindings for a single tag, only the most specific binding gets invoked. A continue in a callback terminates that subroutine, and a break method terminates that subroutine and skips any remaining callbacks for the event — literally exactly like it works for the bind method.

And if bindings were made for a canvas window using CanvasBind, they get invoked in addition to the bindings created for the canvas's items using bind. The item bindings go first, before any of the window-as-a-whole bindings. No cap 🫶

---

$canvas->canvasx(screenx?, gridspacing?)

You hand it a window x-coordinate in screenx, and it hands you back the canvas x-coordinate that's being displayed at that spot. If gridspacing is specified, the canvas coordinate gets rounded to the nearest multiple of gridspacing units. Snapped ✨

$canvas->canvasy(screeny, ?gridspacing?)

Same vibe, but vertical 🌈 — you give it a window y-coordinate in screeny and it returns the canvas y-coordinate displayed there. And yep, if gridspacing is specified, the canvas coordinate gets rounded to the nearest multiple of gridspacing units.

$canvas->coords(tagOrId ?x0,y0 ...?)

Query or modify the coordinates that define an item 👑. If you pass no coordinates at all, it returns a list whose elements are the coordinates of the item named by tagOrId. If you do pass coordinates, they replace the current coordinates for the named item. And if tagOrId refers to multiple items? It uses the first one in the display list. Only the first, babe.

$canvas->create(type, x, y, ?x, y, ...?, ?option, value, ...?)

Make a brand new item in $canvas of type type 🎀. The exact format of the arguments after type depends on type, but usually they're the coordinates for one or more points, followed by specs for zero or more item options. Peep the subsections on individual item types below for the full syntax tea. This method returns the id for the new item — hold onto that, it's the item's whole identity 💖

$canvas->dchars(tagOrId, first, ?last?)

For each item given by tagOrId, delete the characters (or coordinates) in the range from first to last, inclusive. If some of the items given by tagOrId don't support this: text items interpret first and last as indices to a character, while line and polygon items interpret them as indices to a coordinate (an x,y pair), within the item(s), as described in "INDICES" above. If last is omitted, it defaults to first. This method returns an empty string.

$canvas->delete(?tagOrId, tagOrId, ...?)

Delete each of the items given by each tagOrId, and return an empty string. Poof 💀 Gone. Not coming back.

$canvas->dtag(tagOrId, ?tagToDelete?)

For each of the items given by tagOrId, delete the tag given by tagToDelete from the list of tags associated with that item. If an item doesn't have the tag tagToDelete, then it's just unaffected by the method — no drama, no error. If tagToDelete is omitted, it defaults to tagOrId. This method returns an empty string.

$canvas->find(searchCommand, ?arg, arg, ...?)

This one returns a list of all the items that meet the constraints you specify with searchCommand and the args 💅. searchCommand and args accept any of the forms that the addtag method takes. The items come back in stacking order, with the lowest item first.

---

focus

$canvas->focus(?tagOrId?)

Set the keyboard focus for the canvas widget to the item given by tagOrId 🎯. If tagOrId refers to several items, the focus goes to the first such item in the display list that supports the insertion cursor. If tagOrId doesn't refer to any items, or none of them support the insertion cursor, then the focus isn't changed — it just stays put. If tagOrId is an empty string, then the focus item is reset so that no item has the focus. And if tagOrId isn't specified at all? The method returns the id for the item that currently has the focus, or an empty string if no item has the focus.

Once the focus has been set to an item, that item will display the insertion cursor and all keyboard events get directed to it ⌨️✨. But listen — the focus item within a canvas and the focus window on the screen (set with the focus method) are totally independent. A given item doesn't actually have the input focus unless BOTH of these are true:

1. its canvas is the focus window, and
2. the item is the focus item within the canvas.

In most cases it's advisable to follow the focus widget method with the CanvasFocus method, to set the focus window to the canvas — if it wasn't already there. Do both, bestie, or nothing works 🙈

$canvas->gettags(tagOrId)

Return a list whose elements are the tags associated with the item given by tagOrId 🏷️. If tagOrId refers to more than one item, the tags come from the first such item in the display list. If tagOrId doesn't refer to any items, or the item has no tags, then you get an empty string. That's it, that's the tea.

$canvas->icursor(tagOrId, index)

Set the position of the insertion cursor for the item(s) given by tagOrId to just before the character whose position is given by index. If some or all of the items given by tagOrId don't support an insertion cursor, this method just has no effect on them. Check "INDICES" above for the legal forms for index.

Note: the insertion cursor is only displayed in an item if that item currently has the keyboard focus (see the widget method focus, below) — but the cursor position can still be set even when the item doesn't have the focus 👀

This method returns an empty string.

$canvas->index(tagOrId, index)

This returns a decimal string giving the numerical index within tagOrId corresponding to index. index is a textual description of the desired position, as described in "INDICES" above. Text items interpret index as an index to a character; line and polygon items interpret it as an index to a coordinate (an x,y pair). The return value is guaranteed to lie between 0 and the number of characters (or coordinates) within the item, inclusive 🫶. If tagOrId refers to multiple items, then the index is processed in the first of these items that supports indexing operations — in display list order.

$canvas->insert(tagOrId, beforeThis, string)

For each of the items given by tagOrId, if the item supports text or coordinate insertion, then string gets inserted into the item's text just before the character (or coordinate) whose index is beforeThis. Text items interpret beforethis as an index to a character; line and polygon items interpret it as an index to a coordinate (an x,y pair). For lines and polygons, string must be a valid coordinate sequence — no free-styling it ⚠️. See "INDICES" above for the forms allowed for beforeThis. This method returns an empty string.

$canvas->itemcget(tagOrId, option)

Returns the current value of the configuration option for the item given by tagOrId whose name is option ✨. It's like the cget method, except it applies to one particular item instead of the widget as a whole. option can have any of the values accepted by the create method when the item was created. And if tagOrId is a tag that refers to more than one item, the first (lowest) such item is the one used.

$canvas->itemconfigure(tagOrId, ?option?, ?value?, ?option, value, ...?)

Same energy as configure, except it modifies item-specific options for the items given by tagOrId instead of options for the whole canvas widget 💅. Here's the breakdown:

• If no option is specified, it returns a list describing all the available options for the first item given by tagOrId — see Tk::options for info on the format of that list.
• If option is specified with no value, the method returns a list describing that one named option (this list will be identical to the corresponding sublist of the value you'd get if no option was specified).
• If one or more option-value pairs are specified, then the method modifies the given widget option(s) to have the given value(s) in each of the items given by tagOrId — and in that case it returns an empty string.

The options and values are the same ones that are permissible in the create method when the item(s) were created; peep the sections describing individual item types below for the legal options 📋.

$canvas->lower(tagOrId, ?belowThis?)

Move all of the items given by tagOrId to a new position in the display list, just before the item given by belowThis 👑. If tagOrId refers to more than one item, then all of them get moved — but the relative order of the moved items will not change. belowThis is a tag or id; if it refers to more than one item, the first (lowest) of these items in the display list is used as the destination location for the moved items.

Note: this method has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the raise and lower methods of the widget, not the raise and lower methods for canvases. Wild, right? 😭

This method returns an empty string.

$canvas->move(tagOrId, xAmount, yAmount)

Move each of the items given by tagOrId in the canvas coordinate space, by adding xAmount to the x-coordinate of every point associated with the item and yAmount to the y-coordinate of every point associated with the item 🦋. This method returns an empty string.

$canvas->postscript(?option, value, option, value, ...?)

Okay bestie, this one is the whole vibe: it makes a Postscript representation of part of (or literally all of) your canvas. 💅

Here's how it decides where that Postscript goes:

• If you hand it the -file option, the Postscript gets written to a file and you get back an empty string. That's it, that's the deal.
• Otherwise the Postscript comes back to you as the result of the method. 🎀

Heads up: if the interpreter that owns the canvas is marked as safe, this whole operation will fail, because safe interpreters are not allowed to write files. Not a suggestion, it just won't work.

And if you pass -channel, the argument is the name of a channel that's already opened for writing. The Postscript goes to that channel, and the channel is left open so you can keep writing at the end of the operation. 🫶

The Postscript is created in Encapsulated Postscript form using version 3.0 of the Document Structuring Conventions.

⚠️ Note, and this trips people up every single time: by default Postscript is only generated for information that appears in the canvas's window on the screen. If the canvas is freshly created it may still have its initial size of 1x1 pixel, so literally nothing will show up in the Postscript. 😭 To get around this, either call the update method to wait for the canvas window to reach its final size, or use the -width and -height options to specify the area of the canvas to print.

The option-value argument pairs give extra info to control the Postscript generation. The following options are supported:

• -colormap => hashRef — hashRef must be a reference to a hash variable or an anonymous hash that specifies a color mapping to use in the Postscript. Every value of the hash has to be Postscript code that sets a particular color value (like 1.0 1.0 0.0 setrgbcolor). When Tk outputs color info in the Postscript, it checks whether there's a key in the hash with the same name as the color. If there is, Tk uses that element's value as the Postscript method to set the color. If this option wasn't specified, or if there's no key in hashRef for a given color, then Tk uses the red, green, and blue intensities from the X color. 🌈
• -colormode => mode — Says how to output color info. mode must be one of:
  • color — full color output, slay 💖
  • gray — convert all colors to their gray-scale equivalents
  • mono — convert all colors to black or white
• -file => fileName — The name of the file to write the Postscript into. If you don't specify this option, the Postscript is returned as the result of the method instead of being written to a file. 📄
• -fontmap => hashRef — hashRef must be a reference to a hash variable or an anonymous hash that specifies a font mapping to use in the Postscript. Each value of the hash must be an array reference with two elements: the name and point size of a Postscript font. When outputting Postscript commands for a particular font, Tk checks whether hashRef contains a value with the same name as the font. If there is such an element, the font info in that element is used in the Postscript. Otherwise Tk attempts to guess what Postscript font to use. Tk's guesses generally only work for well-known fonts like Times, Helvetica and Courier, and only if the X font name doesn't omit any dashes up through the point size. For example -*-Courier-Bold-R-Normal--*-120-* will work, but *Courier-Bold-R-Normal*120* will not — Tk needs the dashes to parse the font name. 😤
• -height => size — The height of the area of the canvas to print. Defaults to the height of the canvas window.
• -pageanchor => anchor — Which point of the printed area of the canvas should appear over the positioning point on the page (that point comes from the -pagex and -pagey options). For example, -pageanchor=>n means the top center of the area of the canvas being printed (as it appears in the canvas window) should sit over the positioning point. Defaults to center.
• -pageheight => size — Says the Postscript should be scaled in both x and y so the printed area is size high on the Postscript page. size is a floating-point number followed by c for centimeters, i for inches, m for millimeters, or p or nothing at all for printer's points (1/72 inch). Defaults to the height of the printed area on the screen. If both -pageheight and -pagewidth are specified, the scale factor from -pagewidth is used (non-uniform scaling is not implemented). 🙈
• -pagewidth => size — Says the Postscript should be scaled in both x and y so the printed area is size wide on the Postscript page. size has the same form as for -pageheight. Defaults to the width of the printed area on the screen. If both -pageheight and -pagewidth are specified, the scale factor from -pagewidth is used (non-uniform scaling is not implemented).
• -pagex => position — position gives the x-coordinate of the positioning point on the Postscript page, using any of the forms allowed for -pageheight. Used together with the -pagey and -pageanchor options to determine where the printed area shows up on the Postscript page. Defaults to the center of the page.
• -pagey => position — position gives the y-coordinate of the positioning point on the Postscript page, using any of the forms allowed for -pageheight. Used together with the -pagex and -pageanchor options to determine where the printed area shows up on the Postscript page. Defaults to the center of the page.
• -rotate => boolean — boolean says whether the printed area gets rotated 90 degrees. In non-rotated output the x-axis of the printed area runs along the short dimension of the page (that's portrait'' orientation); in rotated output the x-axis runs along the **long** dimension of the page (that's landscape'' orientation). Defaults to non-rotated.
• -width => size — The width of the area of the canvas to print. Defaults to the width of the canvas window.
• -x => position — The x-coordinate of the left edge of the area of the canvas to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the left edge of the window.
• -y => position — The y-coordinate of the top edge of the area of the canvas to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the top edge of the window.

---

$canvas->raise(tagOrId, ?aboveThis?)

Moves all the items given by tagOrId to a new position in the display list, right after the item given by aboveThis. 👑

If tagOrId refers to more than one item, then all of them get moved — but the relative order of the moved items doesn't change. aboveThis is a tag or id; if it refers to more than one item, the last (topmost) of those items in the display list is used as the destination for the moved items.

⚠️ Note: this method has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the raise and lower widget commands, not the raise and lower methods for canvases. Do not mix those up, I'm begging 😭

This method returns an empty string.

$canvas->scale(tagOrId, xOrigin, yOrigin, xScale, yScale)

Rescales all the items given by tagOrId in canvas coordinate space. ✨ xOrigin and yOrigin identify the origin for the scaling operation, and xScale and yScale identify the scale factors for x- and y-coordinates respectively (a scale factor of 1.0 implies no change to that coordinate).

For each of the points defining each item, the x-coordinate gets adjusted so its distance from xOrigin changes by a factor of xScale. Same energy for each y-coordinate: it gets adjusted so its distance from yOrigin changes by a factor of yScale.

This method returns an empty string.

$canvas->scan(option, args)

This method is how scanning on canvases gets implemented. It has two forms, depending on option:

• $canvas->scanMark(x, y) — Records x and y and the canvas's current view; used together with a later scanDragto method. Typically this method is associated with a mouse button press in the widget, and x and y are the coordinates of the mouse. It returns an empty string.
• $canvas->scanDragto(x, y, ?gain?.) — This method computes the difference between its x and y arguments (which are typically mouse coordinates) and the x and y arguments from the last scanMark method for the widget. It then adjusts the view by 10 times the difference in coordinates. This method is typically associated — and it then adjusts the view by gain times the difference in coordinates, where gain defaults to 10. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window. 🏃‍♀️💨 The return value is an empty string.

$canvas->select(option, ?tagOrId, arg?)

Manipulates the selection in one of several ways, depending on option. The method may take any of the forms described below. 💅

In all of the descriptions below, tagOrId must refer to an item that supports indexing and selection; if it refers to multiple items, then the first of these that supports indexing and the selection is used. Index gives a textual description of a position within tagOrId, as described in "INDICES" above.

• $canvas->selectAdjust(tagOrId, index) — bestie, this one goes and finds the end of the selection inside tagOrId that's nearest to the character given by index, and then it slides that end over to index (so it includes index but does not go past it, okay? boundaries 💅). Then the other end of the selection gets promoted to be the anchor point for all your future selectTo method calls. And if the selection isn't currently chilling in tagOrId at all? Then this method just does the exact same thing as the selectTo widget method, no drama. Returns an empty string. 🫶
• $canvas->selectClear — Clears the selection if it's in this widget. If the selection isn't in this widget, this method literally does nothing, no effect, zero, nada. Returns an empty string.
• $canvas->selectFrom(tagOrId, index) — Sets the selection anchor point for the widget to be just before the character given by index, in the item given by tagOrId. Important: this does not change the selection itself. It just locks in the fixed end of the selection for future selectTo method calls, like pinning your starting point. Returns an empty string. ✨
• $canvas->selectItem — Returns the id of the selected item, but only if the selection is inside an item in this canvas. If the selection is not in this canvas, you get an empty string back. Sorry queen, that's the rule. 😭
• $canvas->selectTo(tagOrId, index) — Sets the selection to be all those characters of tagOrId between the selection anchor point and index. The new selection will include the character given by index; it will include the character given by the anchor point only if index is greater than or equal to the anchor point. The anchor point is whatever was set by the most recent selectAdjust or selectFrom method calls for this widget. And if the widget's selection anchor point isn't currently in tagOrId? Then it just gets set to the same character given by index. Returns an empty string. slay, selection made. 🎀

---

🔍 $canvas->type(tagOrId)

Returns the type of the item given by tagOrId — like rectangle or text, you know, the vibes of the item. If tagOrId refers to more than one item, you get the type of the first item in the display list. And if tagOrId doesn't refer to any items at all, you get an empty string back. 💀

---

↔️ $canvas->xview(?args?)

This method queries and changes the horizontal position of the information displayed in the canvas's window. It can take any of these forms:

• $canvas->xview — Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that's visible in the window. For example, if the first element is .2 and the second element is .6, then 20% of the canvas's area (as defined by the -scrollregion option) is off-screen to the left, the middle 40% is visible in the window, and 40% of the canvas is off-screen to the right. These are the same values passed to scrollbars via the -xscrollcommand option. 🦋
• $canvas->xviewMoveto(fraction) — Adjusts the view in the window so that fraction of the total width of the canvas is off-screen to the left. fraction must be a fraction between 0 and 1.
• $canvas->xviewScroll(number, what) — Shifts the view in the window left or right according to number and what. number must be an integer. what must be either units or pages, or an abbreviation of one of these. If what is units, the view adjusts left or right in units of the xScrollIncrement option — if it's greater than zero — or in units of one-tenth the window's width otherwise. If what is pages, the view adjusts in units of nine-tenths the window's width. If number is negative then information farther to the left becomes visible; if it's positive then information farther to the right becomes visible. 👑

---

↕️ $canvas->yview(?args?)

This method queries and changes the vertical position of the information displayed in the canvas's window. It can take any of these forms:

• $canvas->yview — Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the vertical span that's visible in the window. For example, if the first element is .6 and the second element is 1.0, the lowest 40% of the canvas's area (as defined by the -scrollregion option) is visible in the window. These are the same values passed to scrollbars via the -yscrollcommand option. 🌸
• $canvas->yviewMoveto(fraction) — Adjusts the view in the window so that fraction of the canvas's area is off-screen to the top. fraction is a fraction between 0 and 1.
• $canvas->yviewScroll(number, what) — Adjusts the view in the window up or down according to number and what. number must be an integer. what must be either units or pages. If what is units, the view adjusts up or down in units of the yScrollIncrement option — if it's greater than zero — or in units of one-tenth the window's height otherwise. If what is pages, the view adjusts in units of nine-tenths the window's height. If number is negative then higher information becomes visible; if it's positive then lower information becomes visible. 🔥

---

🧚 OVERVIEW OF ITEM TYPES 🧚

The sections below describe the various types of items supported by canvas widgets. Each item type is characterized by two things: first, the form of the create method used to create instances of the type; and second, a set of configuration options for items of that type, which may be used in the create and itemconfigure methods.

Most items don't support indexing or selection, or the methods related to them — such as index and insert. Where items do support these facilities, it's noted explicitly in the descriptions below. At present, text, line and polygon items provide this support. For lines and polygons, the indexing facility is used to manipulate the coordinates of the item. periodt. 💜

---

🎀 ARC ITEMS 🎀

okay bestie, so items of type arc show up on the display as, you guessed it, arc-shaped regions. An arc is literally just a section of an oval, and it's delimited by two angles — those would be the -start and -extent options, no cap — and it gets displayed in one of several ways (that's the -style option doing the most). Arcs are created with methods shaped like this:

$canvas->createArc(x1, y1, x2, y2, ?option, value, option, value, ...?)

The arguments x1, y1, x2, and y2 give the coordinates of two diagonally opposite corners of a rectangular region that encloses the oval defining the arc. 🦋 After the coordinates there may be any number of option-value pairs, and each one sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for arcs:

• -dash => pattern
• -activedash => pattern
• -disableddash => pattern — This option specifies dash patterns for the normal state, the active state, and the disabled state of an arc item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline. ✨
• -dashoffset => offset — The starting offset into the pattern provided by the -dash option. Lowkey important: -dashoffset is ignored if there is no -dash pattern. 🙈
• -extent => degrees — Specifies the size of the angular range occupied by the arc. The arc's range extends for degrees degrees counter-clockwise from the starting angle given by the -start option. degrees may be negative. If it is greater than 360 or less than -360, then degrees modulo 360 is used as the extent. math girlies stay winning 💅
• -fill => color
• -activefill => color
• -disabledfill => color — Specifies the color to be used to fill the arc region in its normal, active, and disabled states. color may have any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then then the arc will not be filled. (yes bestie, that "then then" is in the original, iykyk 😭)
• -outline => color
• -activeoutline => color
• -disabledoutline => color — This option specifies the color that should be used to draw the outline of the arc in its normal, active and disabled states. color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is specified as undef then no outline is drawn for the arc. 🖤
• -outlinestipple => bitmap
• -activeoutlinestipple => bitmap
• -disabledoutlinestipple => bitmap — This option specifies stipple patterns that should be used to draw the outline of the arc in its normal, active and disabled states. It indicates that the outline for the arc should be drawn with a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.
• -start => degrees — Specifies the beginning of the angular range occupied by the arc. degrees is given in units of degrees measured counter-clockwise from the 3-o'clock position; it may be either positive or negative. ⏰
• -state => state — Modifies the state of the arc item, where state may be set to one of: normal, disabled, hidden or "". If set to empty, the state of the canvas itself is used. An arc item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state. main character energy fr fr 👑
• -stipple => bitmap
• -activestipple => bitmap
• -disabledstipple => bitmap — This option specifies stipple patterns that should be used to fill the the arc in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion. (another "the the" — iconic typo behaviour, not me fixing it 💀)
• -style => type — Specifies how to draw the arc. If type is pieslice (the default) then the arc's region is defined by a section of the oval's perimeter plus two line segments, one between the center of the oval and each end of the perimeter section. If type is chord then the arc's region is defined by a section of the oval's perimeter plus a single line segment connecting the two end points of the perimeter section. If type is arc then the arc's region consists of a section of the perimeter alone. In this last case the -fill option is ignored. 🍓
• -tags => tagList — Specifies a set of tags to apply to the item. tagList consists of a list of tag names, which replace any existing tags for the item. tagList may be an empty list.
• -updatecommand => command — Specifies a callback that is to be executed every time the arc item is updated on the screen. 🔥
• -width => outlineWidth
• -activewidth => outlineWidth
• -disabledwidth => outlineWidth — Specifies the width of the outline to be drawn around the arc's region, in its normal, active and disabled states. outlineWidth may be in any of the forms described in the "COORDINATES" section above. If the -outline option has been specified as undef then this option has no effect. Wide outlines will be drawn centered on the edges of the arc's region. This option defaults to 1.0. 💖

---

🦋 BITMAP ITEMS 🦋

Items of type bitmap appear on the display as images with two colors, foreground and background. Bitmaps are created with methods of the following form:

$canvas->createBitmap(x, y, ?option, value, option, value, ...?)

The arguments x and y specify the coordinates of a point used to position the bitmap on the display (peep the -anchor option below for more info on how bitmaps are displayed 👀). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for bitmaps:

• -anchor => anchorPos — anchorPos tells how to position the bitmap relative to the positioning point for the item; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the bitmap is centered on the point; if anchorPos is n then the bitmap will be drawn so that its top center point is at the positioning point. This option defaults to center. ⭐
• -background => color
• -activebackground => color
• -disabledbackground => color — Specifies the color to use for each of the bitmap's '0' valued pixels in its normal, active and disabled states. color may have any of the forms accepted by Tk_GetColor. If this option isn't specified, or if it is specified as undef, then nothing is displayed where the bitmap pixels are 0; this produces a transparent effect. 🫧
• -bitmap => bitmap
• -activebitmap => bitmap
• -disabledbitmap => bitmap — Specifies the bitmaps to display in the item in its normal, active and disabled states. All bitmaps must have the same width and height. bitmap may have any of the forms accepted by Tk_GetBitmap.
• -foreground => color
• -activeforeground => color
• -disabledforeground => color — Specifies the color to use for each of the bitmap's '1' valued pixels in its normal, active and disabled states. color may have any of the forms accepted by Tk_GetColor and defaults to black. 🖤
• -state => state — Modifies the state of the bitmap item, where state may be set to one of: normal, disabled, or hidden. A bitmap item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state. ✨
• -tags => tagList — Specifies a set of tags to apply to the item. tagList consists of a list of tag names, which replace any existing tags for the item. tagList may be an empty list.
• -updatecommand => command — Specifies a callback that is to be executed every time the bitmap item is updated on the screen. 🌈

✨ GRID ITEMS ✨

Okay bestie, grids are the little visual cheat-code of the canvas world. Items of type grid are intended for producing a visual reference for interpreting other items. They can be drawn as either lines (with dash style) or as rectangular "dots" at each grid point. 🎀

Grid items are lowkey the main character who refuses to be perceived — they're unlike other items because they always cover the whole of the canvas, but are never enclosed by nor overlap any area and are not near any point. That is, they are intended to be always visible but not "pickable", so as such they do support the "active" state. 💅

But they're like other items in that: multiple grids are permitted, they can be raised and lowered relative to other items, and they can be moved and scaled. And as yet, grids do not appear in PostScript output. 🙈

Grids have outline like configure options. Grids are created with methods of the following form:

$canvas->createGrid(x1, y1, x2, y2, ?option, value, option, value, ...?)

The arguments x1, y1 give the origin of the grid. x2, and y2 give the coordinates of the next grid point in their respective directions. After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. 🌸

The following options are supported for grids:

• -lines => boolean — if -lines is set to a true value then lines are drawn for both X and Y grids in the style determined by -dash. Otherwise retangular "dots" are drawn at each grid point.
• -dash => pattern, -disableddash => pattern — this option specifies dash patterns for the normal state, and the disabled state of a grid item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline.
• -dashoffset => offset — the starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern.
• -color => color, -disabledcolor => color — this option specifies the color that should be used to draw the outline of the grid in its normal and disabled states. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is undef then no grid will be drawn. 💀
• -stipple => bitmap, -disabledstipple => bitmap — this option specifies stipple patterns that should be used to draw the outline of the rectangle in its normal and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.
• -state => state — modifies the state of the rectangle item where state may be set to one of: normal, disabled, or hidden. Many options can take separate specifications in normal and disabled states such that the appearance of the item can be different in each state.
• -tags => tagList — specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.
• -updatecommand => command — specifies a callback that is to be executed every time the grid item is updated on the screen.
• -width => outlineWidth, -disabledwidth => outlineWidth — specifies the width of the lines drawn by the grid or the size (in both X and Y) of the dots, in its normal and disabled states. This option defaults to 1.0.

---

🦋 IMAGE ITEMS 🦋

Now THIS one is the moment, fr fr. Items of type image are used to display images on a canvas. Images are created with methods of the following form:

$canvas->createImage(x, y, ?option, value, option, value, ...?)

The arguments x and y specify the coordinates of a point used to position the image on the display (see the -anchor option below for more information). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for images: ✨

• -anchor => anchorPos — AnchorPos tells how to position the image relative to the positioning point for the item; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the image is centered on the point; if anchorPos is n then the image will be drawn so that its top center point is at the positioning point. This option defaults to center.
• -image => name, -activeimage => name, -disabledimage => name — specifies the name of the images to display in the item in is normal, active and disabled states. This image must have been created previously, see Tk::Image. 👑
• -state => state — modifies the state of the image item where state may be set to one of: normal, disabled, or hidden. An image item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.
• -tags => tagList — specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item; it may be an empty list.
• -updatecommand => command — specifies a callback that is to be executed every time the image item is updated on the screen.

Image items are literally the glow-up of your canvas, no cap. 💖

🧵 LINE ITEMS 🧵

Okay bestie, line items are exactly what they sound like: one or more connected line segments or curves chillin' on the display. ✨ And they support coordinate indexing via the canvas methods dchars, index, and insert — so you can poke at their coords like the icon you are.

Lines get created with methods shaped like this:

$canvas->createLine(x1, y1..., xn, yn, ?option, value, option, value, ...?)

The arguments x1 through yn are the coordinates for a whole series of two-or-more points that describe a bunch of connected line segments. 🫶 After the coords you can drop any number of option-value pairs, and each one sets a config option for the item. Those same pairs can also show up in itemconfigure methods to change the item's config later. Here's what lines support:

• -arrow => where — Says whether arrowheads get drawn at one or both ends of the line. where has to be one of none (no arrowheads), first (arrowhead at the first point of the line), last (arrowhead at the last point of the line), or both (arrowheads at both ends). Defaults to none.
• -arrowshape => shape — How to draw those arrowheads. The shape argument has to be a list of three elements, each one specifying a distance in any of the forms described in the COORDINATES section above. First element = distance along the line from the neck of the arrowhead to its tip. Second = distance along the line from the trailing points of the arrowhead to the tip. Third = distance from the outside edge of the line to the trailing points. If you don't specify this, Tk picks a "reasonable" shape for you. 💅
• -capstyle => style — How caps are drawn at the endpoints of the line. style can be any of the forms accepted by Tk_GetCapStyle (butt, projecting, or round). Defaults to butt if you don't say otherwise. And where arrowheads are drawn? The cap style is straight-up ignored. 💀
• -dash => pattern
• -activedash => pattern
• -disableddash => pattern — Sets dash patterns for the normal state, the active state, and the disabled state of a line item. pattern can take any of the forms accepted by Tk_GetDash. If you omit the dash options, the default is a solid outline.
• -dashoffset => offset — The starting offset into the pattern given by the -dash option. -dashoffset is ignored if there's no -dash pattern. 🙈
• -fill => color
• -activefill => color
• -disabledfill => color — The color used to fill the line in its normal, active, and disabled states. color can be any of the forms acceptable to Tk_GetColor. It can also be undef, in which case the line goes transparent. Defaults to black.
• -joinstyle => style — How joints are drawn at the vertices of the line. style can be any of the forms accepted by Tk_GetCapStyle (bevel, miter, or round). Defaults to miter if you don't specify. And if the line only has two points, this option is irrelevant — it's giving nothing, honestly.
• -smooth => boolean — boolean has to be one of the forms accepted by Tk_GetBoolean. It says whether the line should be drawn as a curve. If it is, the line gets rendered as a set of parabolic splines: one spline for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated inside a curve by duplicating the end-points of the line segment you want. 🌈
• -splinesteps => number — The degree of smoothness you want for curves: each spline gets approximated with number line segments. Ignored unless -smooth is true.
• -state => state — Modifies the state of the line item, where state can be normal, disabled, or hidden. A line item can also be in the "active" state if the mouse is currently over it. Lots of options can take separate specs for normal, active and disabled states, so the item can look different in each one. Main character energy, truly. 👑
• -stipple => bitmap
• -activestipple => bitmap
• -disabledstipple => bitmap — Stipple patterns used to fill the line in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), filling is done solid. 🎀
• -tags => tagList — A set of tags to apply to the item. tagList is a list of tag names, and it replaces any existing tags on the item. tagList can be an empty list.
• -updatecommand => command — A callback that gets executed every single time the line item is updated on the screen. Obsessed.
• -width => lineWidth
• -activewidth => lineWidth
• -disabledwidth => lineWidth — The width of the line in its normal, active and disabled states. lineWidth can be in any of the forms described in the COORDINATES section above.

Wide lines get drawn centered on the path specified by the points. If you don't specify this option it defaults to 1.0.

---

⭕ OVAL ITEMS ⭕

Items of type oval show up as circular or oval regions on the display. Every oval can have an outline, a fill, or both — your choice, bestie. 💖 Ovals are created with methods shaped like this:

$canvas->createOval(x1, y1, x2, y2, ?option, value, option, value, ...?)

The arguments x1, y1, x2, and y2 give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval. The oval will include the top and left edges of the rectangle, not the lower or right edges. 🦋 If the region is square, the resulting oval is circular; otherwise it's elongated in shape. After the coords there can be any number of option-value pairs, each setting one of the item's config options, and those same pairs work in itemconfigure methods too. Here's what ovals support:

• -dash => pattern
• -activedash => pattern
• -disableddash => pattern — Dash patterns for the normal state, the active state, and the disabled state of an oval item. pattern can take any of the forms accepted by Tk_GetDash. If the dash options are omitted, the default is a solid outline.
• -dashoffset => offset — The starting offset into the pattern given by the -dash option. -dashoffset is ignored if there's no -dash pattern.
• -fill => color
• -activefill => color
• -disabledfill => color — The color used to fill the oval in its normal, active, and disabled states. color can be any of the forms accepted by Tk_GetColor. If color is undef (the default), then the oval won't be filled at all. ✨
• -outline => color
• -activeoutline => color
• -disabledoutline => color — The color used to draw the outline of the oval in its normal, active and disabled states. color can be any of the forms accepted by Tk_GetColor. Defaults to black. If color is undef, no outline gets drawn for the oval.
• -outlinestipple => bitmap
• -activeoutlinestipple => bitmap
• -disabledoutlinestipple => bitmap — Stipple patterns used to draw the outline of the oval in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't been specified, this option has no effect. If bitmap is an empty string (the default), the outline is drawn solid. 🌸
• -state => state — Modifies the state of the oval item, where state can be normal, disabled, or hidden. An oval item can also be in the "active" state if the mouse is currently over it. Many options take separate specs in normal, active and disabled states so the item can look different in each. 💅
• -stipple => bitmap
• -activestipple => bitmap
• -disabledstipple => bitmap — Stipple patterns used to fill the oval in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified, this option has no effect. If bitmap is an empty string (the default), filling is done solid. 🍓
• -tags => tagList — A set of tags to apply to the item. tagList is a list of tag names, and it replaces any existing tags for the item. tagList can be an empty list.
• -updatecommand => command — A callback that gets executed every time the oval item is updated on the screen. Periodt.
• -width => outlineWidth
• -activewidth => outlineWidth
• -disabledwidth => outlineWidth — The width of the outline drawn around the oval, in its normal, active and disabled states. outlineWidth specifies the width of the outline drawn around the oval, in any of the forms described in the COORDINATES section above.

If the -outline option hasn't been specified, this option has no effect. Wide outlines get drawn centered on the oval path defined by x1, y1, x2, and y2. Defaults to 1.0. 🫶

✨ POLYGON ITEMS ✨

Okay bestie, polygons!! 🦋 These ones show up as polygonal or curved filled regions on your display. Iconic, versatile, a little bit extra. Polygon items support coordinate indexing with these canvas methods: dchars, index, insert. And you make them like this:

$canvas->createPolygon(x1, y1, ..., xn, yn, ?option, value, option, value, ...?)

The args x1 through yn give you the coords for three or more points that define a closed polygon. The first and last points may be the same — and whether they are or not, Tk will draw the polygon as a closed polygon. No cap. 💅

After the coords you can drop any number of option-value pairs, each one setting a configuration option for the item. Those same option-value pairs work in itemconfigure methods too, so you can change the item's config later. Here's what polygons support:

• -dash => pattern, -activedash => *pattern*, -disableddash => pattern — this one sets the dash patterns for the normal state, the active state, and the disabled state of a polygon item. pattern can take any of the forms accepted by Tk_GetDash. If the dash options are omitted, the default is a solid outline.
• -dashoffset => offset — the starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there's no -dash pattern. 🫶
• -fill => color, -activefill => *color*, -disabledfill => color — specifies the color used to fill the polygon in its normal, active, and disabled states. Color can take any of the forms acceptable to Tk_GetColor. If color is undef then the polygon will be transparent. This option defaults to black.
• -joinstyle => style — specifies the ways joints get drawn at the vertices of the outline. Style can take any of the forms accepted by Tk_GetCapStyle (bevel, miter, or round). If this option isn't specified, it defaults to miter.
• -outline => color, -activeoutline => *color*, -disabledoutline => color — specifies the color used to draw the outline of the polygon in its normal, active and disabled states. Color can take any of the forms accepted by Tk_GetColor. If color is undef then no outline will be drawn for the polygon. This option defaults to undef (no outline).
• -outlinestipple => bitmap, -activeoutlinestipple => *bitmap*, -disabledoutlinestipple => bitmap — specifies stipple patterns used to draw the outline of the polygon in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.
• -smooth => boolean — Boolean must have one of the forms accepted by Tk_GetBoolean. It indicates whether or not the polygon should be drawn with a curved perimeter. If so, the outline of the polygon becomes a set of parabolic splines — one spline for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated in a smoothed polygon by duplicating the end-points of the desired line segment. 🎀
• -splinesteps => number — specifies the degree of smoothness desired for curves: each spline will be approximated with number line segments. This option is ignored unless the -smooth option is true.
• -state => state — modifies the state of the polygon item, where state may be set to one of: normal, disabled, or hidden. A polygon item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states, so the appearance of the item can be different in each state. ✨
• -stipple => bitmap, -activestipple => *bitmap*, -disabledstipple => bitmap — specifies stipple patterns used to fill the polygon in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then filling is done in a solid fashion.
• -tags => tagList — specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.
• -updatecommand => command — specifies a callback that gets executed every time the polygon item is updated on the screen.
• -width => outlineWidth, -activewidth => *outlineWidth*, -disabledwidth => outlineWidth — specifies the width of the outline to be drawn around the polygon, in its normal, active and disabled states. outlineWidth may be in any of the forms described in the COORDINATES section above. OutlineWidth specifies the width of the outline to be drawn around the polygon, in any of the forms described in the "COORDINATES" section above. If the -outline option hasn't been specified then this option has no effect. This option defaults to 1.0.

Okay so this next bit is the polygon's whole personality: polygon items are different from other items like rectangles, ovals and arcs in that interior points are considered to be ``inside'' a polygon (e.g. for purposes of the find closest and find overlapping methods) even if it is not filled. For most other item types, an interior point is considered to be inside the item only if the item is filled or if it has neither a fill nor an outline. So if you would like an unfilled polygon whose interior points are not considered to be inside the polygon, use a line item instead. 🧚

---

🌈 RECTANGLE ITEMS 🌈

Rectangles!! The moment you've all been waiting for, the humble little box that ate. 💜 Items of type rectangle appear as rectangular regions on the display. Each rectangle may have an outline, a fill, or both. They're created with methods of the following form:

$canvas->createRectangle(x1, y1, x2, y2, ?option, value, option, value, ...?)

The arguments x1, y1, x2, and y2 give the coordinates of two diagonally opposite corners of the rectangle (the rectangle will include its upper and left edges but not its lower or right edges — lowkey important, bestie). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. Here's the option lineup for rectangles:

• -dash => pattern, -activedash => *pattern*, -disableddash => pattern — specifies dash patterns for the normal state, the active state, and the disabled state of a rectangle item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline.
• -dashoffset => offset — the starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern.
• -fill => color, -activefill => *color*, -disabledfill => color — specifies the color used to fill the rectangle in its normal, active, and disabled states. Color may be specified in any of the forms accepted by Tk_GetColor. If color is undef (the default), then the rectangle will not be filled. 🙈
• -outline => color, -activeoutline => *color*, -disabledoutline => color — specifies the color that should be used to draw the outline of the rectangle in its normal, active and disabled states. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is undef then no outline will be drawn for the rectangle.
• -outlinestipple => bitmap, -activeoutlinestipple => *bitmap*, -disabledoutlinestipple => bitmap — specifies stipple patterns that should be used to draw the outline of the rectangle in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.
• -state => state — modifies the state of the rectangle item, where state may be set to one of: normal, disabled, or hidden. A rectangle item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states, so the appearance of the item can be different in each state. ✨
• -stipple => bitmap, -activestipple => *bitmap*, -disabledstipple => bitmap — specifies stipple patterns that should be used to fill the rectangle in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion.
• -tags => tagList — specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.
• -updatecommand => command — specifies a callback that is to be executed every time the rectangle item is updated on the screen.
• -width => outlineWidth, -activewidth => *outlineWidth*, -disabledwidth => outlineWidth — specifies the width of the outline to be drawn around the rectangle, in its normal, active and disabled states. OutlineWidth specifies the width of the outline to be drawn around the rectangle, in any of the forms described in the "COORDINATES" section above.

If the -outline option hasn't been specified then this option has no effect. Wide outlines are drawn centered on the rectangular path defined by x1, y1, x2, and y2. This option defaults to 1.0. 💅

not me putting the width paragraph on its own so you actually read it — it matters, bestie, the default is literally 1.0 and if there's no -outline it does nothing at all. periodt.

✨ TEXT ITEMS ✨

Okay bestie, a text item is literally just a string of characters chillin' on the screen in one or more lines. That's it, that's the vibe. 💅

Text items are indexable and selectable, and they come with a whole lil' squad of text-related canvas methods: dchars, focus, icursor, index, insert, select. You create them like this:

$canvas->createText(x, y, ?option, value, option, value, ...?)

The x and y args are the coordinates of the point that positions the text on the display (peep the options below for how the text actually gets shown, iykyk). After the coords you can drop any number of option-value pairs, each one setting a configuration option for the item. Those same option-value pairs work in itemconfigure methods too, so you can change the item's config later. Periodt. 💖

Here's everything text items support:

• -anchor => anchorPos — anchorPos tells the widget how to position the text relative to its positioning point. It can take any of the forms that Tk_GetAnchor accepts. Say anchorPos is center — then the text is centered on the point. Say it's n — then the text gets drawn so the top center point of the rectangular region the text occupies lands right on the positioning point. This defaults to center.
• -fill => color
• -activefill => color
• -disabledfill => color — These set the color used to fill the text in its normal, active, and disabled states respectively. color can be any of the forms Tk_GetColor accepts. If color is undef then the text goes transparent, no cap. And if you never specify this option at all, it defaults to black.
• -font => fontName — Sets the font for the text item. fontName can be any string Tk_GetFontStruct is happy with. If you don't specify it, you get a system-dependent font — surprise! 🙈
• -justify => how — Tells the widget how to justify the text inside its bounding region. how has to be one of left, right, or center. Heads up: this only matters if the text is displayed across multiple lines. Leave it out and it defaults to left.
• -state => state — Changes the state of the text item, where state can be normal, disabled, or hidden. A text item can also be in the "active" state if the mouse is currently hovering over it. Lots of options take separate specs for the normal, active and disabled states, so the item can look different in each one. Main character energy fr fr. 👑
• -stipple => bitmap
• -activestipple => bitmap
• -disabledstipple => bitmap — Sets the stipple patterns used to fill the text in its normal, active and disabled states. bitmap specifies the stipple pattern, in any form Tk_GetBitmap accepts. If bitmap is an empty string (which is the default), the text is drawn solid, no stippling at all.
• -tags => tagList — Sets the tags applied to the item. tagList is a list of tag names that replaces any tags the item already had. It can also be an empty list, and that's fine.
• -text => string — string is the actual characters displayed in the text item. Newline characters cause line breaks. You can also change the item's characters with the insert and delete methods. This option defaults to an empty string.
• -updatecommand => command — Sets a callback that runs every single time the text item gets updated on the screen.
• -width => lineLength — Sets a maximum line length for the text, in any of the forms described up in the "COORDINATES" section. If this is zero (the default) the text only breaks into new lines at newline characters. But if it's non-zero, then any line that would be longer than lineLength gets broken just before a space character, to make the line shorter than lineLength. That space character gets treated as if it were a newline. 🎀

---

✨ WINDOW ITEMS ✨

Items of type window cause a particular window to be displayed at a given position on the canvas. The way that works is iconic, ngl.

Window items get created like this:

$canvas->createWindow(x, y?, -option=>value, -option=>value, ...?)

The x and y args are the coordinates of the point that positions the window on the display (check the -anchor option below for how bitmaps get displayed). After the coords you can pass any number of option-value pairs, each setting a config option for the item. Those same pairs work in itemconfigure methods too. Here's what window items support:

• -anchor => anchorPos — anchorPos tells the widget how to position the window relative to the item's positioning point. Any form Tk_GetAnchor accepts works. Example: if anchorPos is center the window is centered on the point; if it's n the window is drawn so its top center point sits at the positioning point. Defaults to center.
• -height => pixels — Sets the height to assign to the item's window. pixels can take any of the forms described in the "COORDINATES" section above. If you don't specify this option, or if you specify it as an empty string, the window gets whatever height it asks for internally. Let it cook. 🍓
• -state => state — Modifies the state of the window item, where state can be set to normal, disabled, or hidden.
• -tags => tagList — Sets the tags applied to the item. tagList is a list of tag names that replaces any existing tags on the item. It can be an empty list too.
• -updatecommand => command — Sets a callback that runs every time the window item is updated on the screen.
• -width => pixels — Sets the width to assign to the item's window. pixels can take any of the forms described in the "COORDINATES" section above. If you don't specify this option, or if you specify it as an empty string, the window gets whatever width it requests internally.
• -window => $widget — Specifies the window to associate with this item. The window named by $widget has to be either a child of the canvas widget or a child of some ancestor of the canvas widget. PathName may not refer to a top-level window.

⚠️ Note: because of restrictions in how windows are managed, you can't draw other graphical items (like lines and images) on top of window items. A window item always obscures any graphics that overlap it, no matter what order they're in on the display list. It said what it said. 💀

---

✨ APPLICATION-DEFINED ITEM TYPES ✨

It's totally possible for individual applications to define brand new item types for canvas widgets using C code. Slay, honestly. 🦋

See the docs for Tk_CreateItemType for the details.

---

✨ BINDINGS ✨

Canvas has default bindings so scrolling works when you need it: <Up>, <Down>, <Left> and <Right> (plus their <Control-*> counterparts). And also <Proir>, <Next>, <Home> and <End>. These bindings let you navigate the exact same way you do in other widgets that can scroll. Vibe check: passed. ✨

---

✨ Perl/Tk Methods ✨

These methods get added as perl code:

• $canvas->get_corners — Returns the bounding box, in Canvas coordinates, of the visible portion of the Canvas. (Written by Slaven Rezic.) 🫶

---

✨ CREDITS ✨

Tk's canvas widget is a total blatant ripoff of ideas from Joel Bartlett's ezd program. ezd provides structured graphics in a Scheme environment and came along a year or two before canvases did. Its simple mechanisms for placing and animating graphical objects are literally what inspired the functions of canvases. Respect where respect is due. 💜

---

✨ KEYWORDS ✨

canvas, widget

---

And that's a wrap on Canvas(3pm), bestie!! 🎀✨ This whole thing came from perl v5.40.1, dated 2025-04-13, and you just read the very last page of it. Go build something gorgeous with it, you absolute icon. 💅👑🌈