Provided by: tk8.5-doc_8.5.11-1_all bug

NAME

       canvas - Create and manipulate canvas widgets

SYNOPSIS

       canvas pathName ?options?

STANDARD OPTIONS

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

       See the options manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS

       Command-Line Name:-closeenough
       Database Name:  closeEnough
       Database Class: 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.

       Command-Line Name:-confine
       Database Name:  confine
       Database Class: 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.

       Command-Line Name:-height
       Database Name:  height
       Database Class: 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.

       Command-Line Name:-scrollregion
       Database Name:  scrollRegion
       Database Class: 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.

       Command-Line Name:-state
       Database Name:  state
       Database Class: 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   may   override   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.  Canvas items which are disabled will not
              react to canvas bindings.

       Command-Line Name:-width
       Database Name:  width
       Database Class: 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.

       Command-Line Name:-xscrollincrement
       Database Name:  xScrollIncrement
       Database Class: ScrollIncrement

              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.

       Command-Line Name:-yscrollincrement
       Database Name:  yScrollIncrement
       Database Class: ScrollIncrement

              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.
_________________________________________________________________

INTRODUCTION

       The canvas command creates a new window (given by the pathName 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 pathName argument.  At the time this command
       is invoked, there must not exist a window  named  pathName,  but  pathName'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 commands may be associated with items in much the same way
       that the bind command allows commands to be bound to widgets.  For example,  a  particular
       command  may  be  associated  with  the  <Button-1>  event  so that the command 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 Tcl scripts bound to them.

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 commands may
       be used to re-arrange the order of the display list.

       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 widget commands; you must  use  the  raise  and
       lower Tk commands instead.

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.

       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” is not.  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”.

       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 (different  item
       types  interpret  this  in  varying  ways;  see the individual item type documentation for
       details).  If the mouse is not in the canvas widget or is not over an item, then  no  item
       has the current tag.

       When specifying items in canvas widget commands, 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 parenthesized 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 widget commands 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 command to use the
       first (lowest) of these items in the display  list  that  is  suitable  for  the  command.
       Exceptions are noted in the widget command 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.  Coordinates can be specified either as an even
       number of parameters, or as a single list parameter containing an even number of x  and  y
       coordinate values.

   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 widget
       commands;  this is typically used for scrolling.   Canvases  do  not  support  scaling  or
       rotation of the canvas coordinate system relative to the window coordinate system.

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

       Note that the default origin of the canvas's visible area is coincident  with  the  origin
       for  the whole window as that makes bindings using the mouse position easier to work with;
       you only need to use the canvasx and canvasy widget commands if you adjust the  origin  of
       the  visible  area.   However,  this  also means that any focus ring (as controlled by the
       -highlightthickness option) and window border (as controlled by the  -borderwidth  option)
       must be taken into account before you get to the visible area of the canvas.

INDICES

       Text  items support the notion of an index for identifying particular positions within the
       item.  In a similar fashion,  line  and  polygon  items  support  index  for  identifying,
       inserting  and  deleting subsets of their coordinates.  Indices are used for commands such
       as inserting or deleting a range of characters or coordinates, and setting  the  insertion
       cursor position. An index may 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;  if you define new types of text-like items, it would be
       advisable to support as many of these forms as practical.  Note that  it  is  possible  to
       refer  to  the  character just after the last one in the text item;  this is necessary for
       such tasks as inserting new text at the end of  the  item.   Lines  and  Polygons  do  not
       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  subtracting  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 is not in
                 this item then this form is illegal.

       sel.last  Refers to the last selected character in the item.  If the selection is  not  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.

DASH PATTERNS

       Many items support the notion of a dash pattern for outlines.

       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 “.,-_
       ”.   The  space  can  be used to enlarge the space between other line elements, and cannot
       occur as the first position in the string. Some examples:
              -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}

       The main difference of this syntax with the previous is that it is 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.

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

WIDGET COMMAND

       The canvas command creates a new Tcl command whose name is pathName.  This command may  be
       used to invoke various operations on the widget.  It has the following general form:
              pathName option ?arg arg ...?
       Option  and  the  args  determine the exact behavior of the command.  The following widget
       commands are possible for canvas widgets:

       pathName 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 is not already present on
              that list.  It is possible that no items will  satisfy  the  constraints  given  by
              searchSpec and args, in which case the command 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.

       pathName 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.

       pathName bind tagOrId ?sequence? ?command?
              This  command  associates  command  with  all  the items given by tagOrId such that
              whenever the event sequence given by sequence occurs  for  one  of  the  items  the
              command will be invoked.  This widget command is similar to the bind command except
              that it operates on items in a canvas rather than entire  widgets.   See  the  bind
              manual  entry  for complete details on the syntax of sequence and the substitutions
              performed on command 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 command is omitted then the command returns the command associated with
              tagOrId  and  sequence  (an  error  occurs  if  there is no such binding).  If both
              command and sequence are omitted then  the  command  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 widget command 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.

              It is possible for multiple bindings to  match  a  particular  event.   This  could
              occur,  for example, if one binding is associated with the item's id and another is
              associated with one of the item's tags.  When this  occurs,  all  of  the  matching
              bindings  are  invoked.   A  binding  associated with the all tag is invoked first,
              followed by one binding for each of the item's  tags  (in  order),  followed  by  a
              binding associated with the item's id.  If there are multiple matching bindings for
              a single tag, then only the most specific binding is invoked.  A  continue  command
              in  a  binding  script  terminates that script, and a break command terminates that
              script and skips any remaining scripts for the event, just as for the bind command.

              If bindings have been created for a canvas window using the bind command, then they
              are  invoked  in addition to bindings created for the canvas's items using the bind
              widget command.  The bindings for items will be invoked before any of the  bindings
              for the window as a whole.

       pathName canvasx screenx ?gridspacing?
              Given  a window x-coordinate in the canvas screenx, this command returns the canvas
              x-coordinate that is displayed at that location.  If gridspacing is specified, then
              the canvas coordinate is rounded to the nearest multiple of gridspacing units.

       pathName canvasy screeny ?gridspacing?
              Given  a  window y-coordinate in the canvas screeny this command returns the canvas
              y-coordinate that is displayed at that location.  If gridspacing is specified, then
              the canvas coordinate is rounded to the nearest multiple of gridspacing units.

       pathName cget option
              Returns  the current value of the configuration option given by option.  Option may
              have any of the values accepted by the canvas command.

       pathName configure ?option? ?value? ?option value ...?
              Query or modify  the  configuration  options  of  the  widget.   If  no  option  is
              specified, returns a list describing all of the available options for pathName (see
              Tk_ConfigureInfo for information on  the  format  of  this  list).   If  option  is
              specified  with  no value, then the command returns a list describing the one named
              option (this list will be identical to  the  corresponding  sublist  of  the  value
              returned  if  no  option  is  specified).   If  one  or more option-value pairs are
              specified, then the command modifies the given widget option(s) to have  the  given
              value(s);   in  this case the command returns an empty string.  Option may have any
              of the values accepted by the canvas command.

       pathName coords tagOrId ?x0 y0 ...?

       pathName coords tagOrId ?coordList?
              Query or modify the coordinates  that  define  an  item.   If  no  coordinates  are
              specified,  this  command  returns a list whose elements are the coordinates of the
              item named by tagOrId.  If coordinates are specified, then they replace the current
              coordinates  for  the  named  item.   If tagOrId refers to multiple items, then the
              first one in the display list is used.

       pathName create type x y ?x y ...? ?option value ...?

       pathName create type coordList ?option value ...?
              Create a new item in pathName of type type.  The  exact  format  of  the  arguments
              after  type depends on type, but usually they consist of the coordinates for one or
              more points, followed by specifications for zero or more  item  options.   See  the
              subsections  on individual item types below for more on the syntax of this command.
              This command returns the id for the new item.

       pathName dchars tagOrId first ?last?
              For each item given by tagOrId, delete the characters, or coordinates, in the range
              given  by  first and last, inclusive.  If some of the items given by tagOrId do not
              support indexing operations then they ignore dchars.  Text  items  interpret  first
              and  last  as indices to a character, line and polygon items interpret them indices
              to a coordinate (an x,y pair).  Indices are described in INDICES above.  If last is
              omitted, it defaults to first.  This command returns an empty string.

       pathName delete ?tagOrId tagOrId ...?
              Delete each of the items given by each tagOrId, and return an empty string.

       pathName dtag tagOrId ?tagToDelete?
              For  each  of  the items given by tagOrId, delete the tag given by tagToDelete from
              the list of those associated with the item.  If an  item  does  not  have  the  tag
              tagToDelete  then the item is unaffected by the command.  If tagToDelete is omitted
              then it defaults to tagOrId.  This command returns an empty string.

       pathName find searchCommand ?arg arg ...?
              This command returns a list consisting of all the items that meet  the  constraints
              specified by searchCommand and arg's.  SearchCommand and args have any of the forms
              accepted by the addtag command.  The items are returned in stacking order, with the
              lowest item first.

       pathName focus ?tagOrId?
              Set  the  keyboard  focus  for  the canvas widget to the item given by tagOrId.  If
              tagOrId refers to several items, then the focus is set to the first  such  item  in
              the  display list that supports the insertion cursor.  If tagOrId does not refer to
              any items, or if none of them support the insertion cursor, then the focus  is  not
              changed.   If  tagOrId  is an empty string, then the focus item is reset so that no
              item has the focus.  If tagOrId is not specified then the command  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, the item will display the insertion  cursor
              and  all  keyboard  events  will be directed to that item.  The focus item within a
              canvas and the focus window on the screen (set with the focus command) are  totally
              independent:  a  given  item  does not actually have the input focus unless (a) its
              canvas is the focus window and (b) the item is the focus item  within  the  canvas.
              In  most  cases  it  is advisable to follow the focus widget command with the focus
              command to set the focus window to the canvas (if it was not there already).

       pathName 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, then the tags are returned from
              the first such item in the display list.  If tagOrId does not refer to  any  items,
              or if the item contains no tags, then an empty string is returned.

       pathName 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 do not support an insertion cursor then this command has no effect
              on them.  See INDICES above for a description of 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 command focus, below), but the cursor  position  may
              be  set  even when the item does not have the focus.  This command returns an empty
              string.

       pathName index tagOrId index
              This command returns a decimal string giving the  numerical  index  within  tagOrId
              corresponding  to index.  Index gives 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).

       pathName insert tagOrId beforeThis string
              For  each  of  the items given by tagOrId, if the item supports text or coordinate,
              insertion then string is 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 the string must be a valid
              coordinate sequence.  See INDICES above for information about the forms allowed for
              beforeThis.  This command returns an empty string.

       pathName itemcget tagOrId option
              Returns the current value of the configuration option for the item given by tagOrId
              whose name is option.  This command is similar to the cget  widget  command  except
              that it applies to a particular item rather than the widget as a whole.  Option may
              have any of the values accepted by the create widget  command  when  the  item  was
              created.  If tagOrId is a tag that refers to more than one item, the first (lowest)
              such item is used.

       pathName itemconfigure tagOrId ?option? ?value? ?option value ...?
              This command is similar to the configure widget command  except  that  it  modifies
              item-specific  options  for the items given by tagOrId instead of modifying options
              for the overall  canvas  widget.   If  no  option  is  specified,  returns  a  list
              describing  all  of  the available options for the first item given by tagOrId (see
              Tk_ConfigureInfo for information on  the  format  of  this  list).   If  option  is
              specified  with  no value, then the command returns a list describing the one named
              option (this list will be identical to  the  corresponding  sublist  of  the  value
              returned  if  no  option  is  specified).   If  one  or more option-value pairs are
              specified, then the command modifies the given widget option(s) to have  the  given
              value(s)  in  each of the items given by tagOrId;  in this case the command returns
              an empty string.  The options and values are the same as those permissible  in  the
              create  widget  command  when the item(s) were created; see the sections describing
              individual item types below for details on the legal options.

       pathName 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 are moved but the relative order of  the  moved  items  will  not  be  changed.
              BelowThis  is  a  tag  or  id;   if  it refers to more than one item then the first
              (lowest) of these items in the display list is used as the destination location for
              the  moved  items.  Note: this command 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 commands, not the raise and lower widget commands
              for canvases.  This command returns an empty string.

       pathName 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 each point associated with the item and yAmount to
              the y-coordinate of each point associated with the item.  This command  returns  an
              empty string.

       pathName postscript ?option value option value ...?
              Generate  a  Postscript representation for part or all of the canvas.  If the -file
              option is specified then the Postscript is written to a file and an empty string is
              returned;   otherwise  the Postscript is returned as the result of the command.  If
              the interpreter that owns the canvas is marked as safe,  the  operation  will  fail
              because  safe  interpreters are not allowed to write files.  If the -channel option
              is specified, the argument denotes  the  name  of  a  channel  already  opened  for
              writing.  The  Postscript  is written to that channel, and the channel is left open
              for further 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: 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  nothing  will  appear  in  the
              Postscript.   To  get  around this problem either invoke the update command to wait
              for the canvas window to reach its final size, or else use the -width  and  -height
              options  to  specify  the  area  of the canvas to print.  The option-value argument
              pairs provide additional information to control the generation of Postscript.   The
              following options are supported:

              -colormap varName
                     VarName must be the name of an array variable that specifies a color mapping
                     to use  in  the  Postscript.   Each  element  of  varName  must  consist  of
                     Postscript  code  to  set  a  particular  color  value  (e.g.   “1.0 1.0 0.0
                     setrgbcolor”).  When outputting color  information  in  the  Postscript,  Tk
                     checks  to  see  if there is an element of varName with the same name as the
                     color.  If so, Tk uses the value of the element as the Postscript command to
                     set  the  color.   If  this option has not been specified, or if there is no
                     entry in varName for a given color, then Tk uses the red,  green,  and  blue
                     intensities from the X color.

              -colormode mode
                     Specifies  how  to output color information.  Mode must be either color (for
                     full  color  output),  gray  (convert  all  colors   to   their   gray-scale
                     equivalents) or mono (convert all colors to black or white).

              -file fileName
                     Specifies  the  name  of the file in which to write the Postscript.  If this
                     option is not specified then the Postscript is returned as the result of the
                     command instead of being written to a file.

              -fontmap varName
                     VarName  must be the name of an array variable that specifies a font mapping
                     to use in the Postscript.  Each element of varName must  consist  of  a  Tcl
                     list  with  two  elements, which are the name and point size of a Postscript
                     font.  When outputting Postscript commands for a particular font, Tk  checks
                     to  see  if  varName contains an element with the same name as the font.  If
                     there is such an element,  then  the  font  information  contained  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  such  as Times and Helvetica and Courier, and only if the X font name
                     does  not  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
                     Specifies the height of the area of the canvas to print.   Defaults  to  the
                     height of the canvas window.

              -pageanchor anchor
                     Specifies  which  point of the printed area of the canvas should appear over
                     the positioning point on the page (which is given by the -pagex  and  -pagey
                     options).   For example, -pageanchor n means that the top center of the area
                     of the canvas being printed (as it appears in the canvas window)  should  be
                     over the positioning point. Defaults to center.

              -pageheight size
                     Specifies  that  the Postscript should be scaled in both x and y so that the
                     printed area is size high on  the  Postscript  page.   Size  consists  of  a
                     floating-point  number  followed  by  c for centimeters, i for inches, m for
                     millimeters, or p or nothing 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 then the scale factor from -pagewidth is used (non-
                     uniform scaling is not implemented).

              -pagewidth size
                     Specifies  that  the Postscript should be scaled in both x and y so that 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 then 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  in  conjunction
                     with  the -pagey and -pageanchor options to determine where the printed area
                     appears 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 in conjunction
                     with the -pagex and -pageanchor options to determine where the printed  area
                     appears on the Postscript page.  Defaults to the center of the page.

              -rotate boolean
                     Boolean  specifies whether the printed area is to be rotated 90 degrees.  In
                     non-rotated output the x-axis of the  printed  area  runs  along  the  short
                     dimension  of the page (“portrait”orientation); in rotated output the x-axis
                     runs  along  the  long  dimension  of  the  page   (“landscape”orientation).
                     Defaults to non-rotated.

              -width size
                     Specifies  the  width  of  the area of the canvas to print.  Defaults to the
                     width of the canvas window.

              -x position
                     Specifies the x-coordinate of the left edge of the area of the  canvas  that
                     is  to  be printed, in canvas coordinates, not window coordinates.  Defaults
                     to the coordinate of the left edge of the window.

              -y position
                     Specifies the y-coordinate of the top edge of the area of the canvas that is
                     to  be  printed, in canvas coordinates, not window coordinates.  Defaults to
                     the coordinate of the top edge of the window.

       pathName raise tagOrId ?aboveThis?
              Move all of the items given by tagOrId to a new position in the display  list  just
              after  the  item  given by aboveThis.  If tagOrId refers to more than one item then
              all are moved but the relative order of  the  moved  items  will  not  be  changed.
              AboveThis  is  a  tag  or  id;   if  it  refers to more than one item then the last
              (topmost) of these items in the display list is used as  the  destination  location
              for  the  moved  items.   Note: this command 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 commands, not the raise and lower widget commands
              for canvases.  This command returns an empty string.

       pathName scale tagOrId xOrigin yOrigin xScale yScale
              Rescale all of 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 is adjusted to change the distance from xOrigin by a  factor
              of  xScale.   Similarly,  each y-coordinate is adjusted to change the distance from
              yOrigin by a factor of yScale.  This command returns an empty string.

       pathName scan option args
              This command is used  to  implement  scanning  on  canvases.   It  has  two  forms,
              depending on option:

              pathName scan mark x y
                     Records  x  and  y  and the canvas's current view;  used in conjunction with
                     later scan dragto commands.  Typically this command  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.

              pathName scan dragto x y ?gain?.
                     This command computes the difference between its x and  y  arguments  (which
                     are  typically mouse coordinates) and the x and y arguments to the last scan
                     mark command for the widget.  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.

       pathName select option ?tagOrId arg?
              Manipulates the selection in one of several ways, depending on option.  The command
              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.

              pathName select adjust tagOrId index
                     Locate the end of the selection in tagOrId nearest to the character given by
                     index, and adjust that end of the selection to be at index  (i.e.  including
                     but  not  going  beyond  index).  The other end of the selection is made the
                     anchor point for future  select  to  commands.   If  the  selection  is  not
                     currently  in  tagOrId  then  this command behaves the same as the select to
                     widget command.  Returns an empty string.

              pathName select clear
                     Clear the selection if it is in this widget.  If the  selection  is  not  in
                     this widget then the command has no effect.  Returns an empty string.

              pathName select from tagOrId index
                     Set  the  selection  anchor  point  for  the  widget  to  be just before the
                     character given by index in the item given by tagOrId.   This  command  does
                     not  change  the selection;  it just sets the fixed end of the selection for
                     future select to commands.  Returns an empty string.

              pathName select item
                     Returns the id of the selected item, if the selection is in an item in  this
                     canvas.   If  the  selection  is  not in this canvas then an empty string is
                     returned.

              pathName select to tagOrId index
                     Set the selection to consist of 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 determined by the most recent select adjust or  select  from
                     command  for  this  widget.  If the selection anchor point for the widget is
                     not currently in tagOrId, then it is set to  the  same  character  given  by
                     index.  Returns an empty string.

       pathName type tagOrId
              Returns  the  type  of  the  item  given by tagOrId, such as rectangle or text.  If
              tagOrId refers to more than one item, then the  type  of  the  first  item  in  the
              display  list  is  returned.  If tagOrId does not refer to any items at all then an
              empty string is returned.

       pathName xview  ?args?
              This command is used to query and change the horizontal position of the information
              displayed in the canvas's window.  It can take any of the following forms:

              pathName xview
                     Returns  a  list  containing  two elements.  Each element is a real fraction
                     between 0 and 1;  together they describe the horizontal span that is visible
                     in  the  window.   For  example,  if  the first element is .2 and the second
                     element is .6, 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.

              pathName xview moveto 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.

              pathName xview scroll number what
                     This command 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 is greater  than  zero,
                     or  in  units  of  one-tenth the window's width otherwise.  If what is pages
                     then 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 is
                     positive then information farther to the right becomes visible.

       pathName yview ?args?
              This command is used to query and change the vertical position of  the  information
              displayed in the canvas's window.  It can take any of the following forms:

              pathName yview
                     Returns  a  list  containing  two elements.  Each element is a real fraction
                     between 0 and 1;  together they describe the vertical span that  is  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.

              pathName yview moveto 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.

              pathName yview scroll number what
                     This  command  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 is greater than zero, or  in  units  of  one-
                     tenth the window's height otherwise.  If what is pages then the view adjusts
                     in units of nine-tenths the window's height.  If  number  is  negative  then
                     higher   information   becomes  visible;   if  it  is  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 command 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 widget commands.  Most items
       do not support indexing or selection or the commands related to them, such  as  index  and
       insert.   Where  items  do  support  these  facilities,  it  is  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.

   COMMON ITEM OPTIONS
       Many items share a common set of options.  These options  are  explained  here,  and  then
       referred to be each widget type for brevity.

       -dash pattern

       -activedash pattern

       -disableddash pattern
              This  option  specifies  dash  patterns  for the normal, active state, and disabled
              state of an 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.  See DASH
              PATTERNS for more information.

       -dashoffset offset
              The starting offset in pixels into  the  pattern  provided  by  the  -dash  option.
              -dashoffset  is  ignored  if there is no -dash pattern.  The offset may have any of
              the forms described in the COORDINATES section above.

       -fill color

       -activefill color

       -disabledfill color
              Specifies the color to be used to fill item's area.  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 the item will not be filled.  For  the  line
              item,  it  specifies  the color of the line drawn.  For the text item, it specifies
              the foreground color of the text.

       -outline color

       -activeoutline color

       -disabledoutline color
              This option specifies the color that should be used to draw the outline of the item
              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
              an empty string then no outline is drawn for the item.

       -offset offset
              Specifies the offset of stipples.  The offset value can be of the form x,y or side,
              where side can be n, ne, e, se, s, sw, w, nw, or center.  In  the  first  case  the
              origin  is the origin of the toplevel of the current window.  For the canvas itself
              and canvas objects the origin is the canvas origin, but putting # in front  of  the
              coordinate  pair  indicates  using the toplevel origin instead. For canvas objects,
              the -offset option is used for stippling as well.  For the line and polygon  canvas
              items  you can also specify an index as argument, which connects the stipple origin
              to one of the coordinate points of the line/polygon.

       -outlinestipple bitmap

       -activeoutlinestipple bitmap

       -disabledoutlinestipple bitmap
              This option specifies stipple patterns that should be used to draw the  outline  of
              the item in its normal, active and disabled states.  Indicates that the outline for
              the item 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 has not 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.  Note
              that stipples are not well supported on platforms that do  not  use  X11  as  their
              drawing API.

       -outlineoffset offset
              Specifies the offset of the stipple pattern used for outlines. The offset value can
              be of the form “x,y” or the description of a side (one of n, ne, e, se, s,  sw,  w,
              nw,  or  center).  This  option  only  has an effect when the outline is drawn as a
              stipple pattern, and is only supported under X11.

       -stipple bitmap

       -activestipple bitmap

       -disabledstipple bitmap
              This option specifies stipple patterns that should be used to fill the item 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  has  not  been
              specified  then  this  option  has  no  effect.   If bitmap is an empty string (the
              default), then filling is done in a solid fashion.  For the text item,  it  affects
              the  actual  text.   Note that stipples are not well supported on platforms that do
              not use X11 as their drawing API.

       -state state
              This allows an item to override the canvas widget's global state option.  It  takes
              the same values: normal, disabled or hidden.

       -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.

       -width outlineWidth

       -activewidth outlineWidth

       -disabledwidth outlineWidth
              Specifies the width of the outline to be drawn around the  item'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 an empty string then this option has no effect.  This option defaults
              to 1.0.  For arcs, wide outlines will be drawn centered on the edges of  the  arc's
              region.

ARC ITEMS

       Items  of type arc appear on the display as arc-shaped regions.  An arc is a section of an
       oval delimited by two angles (specified by the -start and -extent options)  and  displayed
       in  one  of  several  ways (specified by the -style option).  Arcs are created with widget
       commands of the following form:
              pathName create arc x1 y1 x2 y2 ?option value option value ...?
              pathName create arc coordList ?option value option value ...?
       The arguments x1, y1, x2, and y2 or coordList  give  the  coordinates  of  two  diagonally
       opposite  corners  of a rectangular region enclosing the oval that defines the arc.  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 widget commands to change the item's configuration. An arc item becomes  the
       current  item  when  the  mouse  pointer  is  over any part that is painted or (when fully
       transparent) that would be painted if both the -fill and -outline options were non-empty.

       The following standard options are supported by arcs:
              -dash
              -activedash
              -disableddash
              -dashoffset
              -fill
              -activefill
              -disabledfill
              -offset
              -outline
              -activeoutline
              -disabledoutline
              -outlineoffset
              -outlinestipple
              -activeoutlinestipple
              -disabledoutlinestipple
              -stipple
              -activestipple
              -disabledstipple
              -state
              -tags
              -width
              -activewidth
              -disabledwidth
       The following extra options are supported for arcs:

       -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.

       -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.

       -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.

BITMAP ITEMS

       Items  of  type  bitmap  appear  on  the display as images with two colors, foreground and
       background.  Bitmaps are created with widget commands of the following form:
              pathName create bitmap x y ?option value option value ...?
              pathName create bitmap coordList ?option value option value ...?
       The arguments x and y or coordList (which must have two elements) specify the  coordinates
       of  a  point  used to position the bitmap on the display (see the -anchor option below for
       more information 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  widget  commands  to
       change  the  item's  configuration.  A bitmap item becomes the current item when the mouse
       pointer is over any part of its bounding box.

       The following standard options are supported by bitmaps:
              -state
              -tags
       The following extra 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 bitmap

       -disabledbackground bitmap
              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 is not specified, or if it is specified  as  an  empty
              string,  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.  Bitmap may have any of the forms accepted by Tk_GetBitmap.

       -foreground color

       -activeforeground bitmap

       -disabledforeground bitmap
              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.

IMAGE ITEMS

       Items  of  type  image  are  used  to display images on a canvas.  Images are created with
       widget commands of the following form:
              pathName create image x y ?option value option value ...?
              pathName create image coordList ?option value option value ...?
       The arguments x and y or coordList 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 widget commands to change the item's configuration. An  image  item  becomes
       the current item when the mouse pointer is over any part of its bounding box.

       The following standard options are supported by images:
              -state
              -tags
       The following extra 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  with  the  image
              create command.

LINE ITEMS

       Items of type line appear on the display as one or more connected line segments or curves.
       Line items support coordinate  indexing  operations  using  the  canvas  widget  commands:
       dchars, index, insert.  Lines are created with widget commands of the following form:
              pathName create line x1 y1... xn yn ?option value option value ...?
              pathName create line coordList ?option value option value ...?
       The  arguments x1 through yn or coordList give the coordinates for a series of two or more
       points that describe a series of connected line segments.  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 widget  commands
       to  change  the  item's  configuration. A line item is the current item whenever the mouse
       pointer is over any segment of the line, whether drawn or not and whether or not the  line
       is smoothed.

       The following standard options are supported by lines:
              -dash
              -activedash
              -disableddash
              -dashoffset
              -fill
              -activefill
              -disabledfill
              -stipple
              -activestipple
              -disabledstipple
              -state
              -tags
              -width
              -activewidth
              -disabledwidth
       The following extra options are supported for lines:

       -arrow where
              Indicates  whether  or  not  arrowheads  are to be drawn at one or both ends of the
              line.  Where must have one of the values none (for no arrowheads),  first  (for  an
              arrowhead at the first point of the line), last (for an arrowhead at the last point
              of the line), or both (for arrowheads at both ends).  This option defaults to none.

       -arrowshape shape
              This option indicates how to draw arrowheads.  The shape argument must  be  a  list
              with  three  elements,  each specifying a distance in any of the forms described in
              the COORDINATES section above.  The first element of the list  gives  the  distance
              along the line from the neck of the arrowhead to its tip.  The second element gives
              the distance along the line from the trailing points of the arrowhead to  the  tip,
              and  the  third element gives the distance from the outside edge of the line to the
              trailing points.  If this option is not specified  then  Tk  picks  a  “reasonable”
              shape.

       -capstyle style
              Specifies  the  ways  in  which  caps are to be drawn at the endpoints of the line.
              Style may have any of the forms accepted by Tk_GetCapStyle  (butt,  projecting,  or
              round).   If  this  option  is  not  specified  then  it  defaults  to butt.  Where
              arrowheads are drawn the cap style is ignored.

       -joinstyle style
              Specifies the ways in which joints are to be drawn at the  vertices  of  the  line.
              Style  may  have  any  of  the  forms  accepted by Tk_GetCapStyle (bevel, miter, or
              round).  If this option is not specified then it defaults to round.   If  the  line
              only contains two points then this option is irrelevant.

       -smooth smoothMethod
              smoothMethod  must  have  one  of  the  forms  accepted by Tcl_GetBoolean or a line
              smoothing method.  Only true and raw are supported in the core (with  bezier  being │
              an  alias for true), but more can be added at runtime.  If a boolean false value or │
              empty string is given, no smoothing is applied.  A boolean truth value assumes true │
              smoothing.  If the smoothing method is true, this indicates that the line should be │
              drawn as a curve, rendered as a set of quadratic splines: one spline is  drawn  for │
              the  first  and  second  line  segments,  one  for the second and third, and so on. │
              Straight-line segments can be generated within a  curve  by  duplicating  the  end- │
              points of the desired line segment.  If the smoothing method is raw, this indicates │
              that the line should also be drawn as a curve but where the list of coordinates  is │
              such that the first coordinate pair (and every third coordinate pair thereafter) is │
              a knot point on a cubic Bezier curve, and the other coordinates are control  points │
              on  the cubic Bezier curve.  Straight line segments can be generated within a curve │
              by making control points equal to their neighbouring  knot  points.   If  the  last │
              point  is  a  control point and not a knot point, the point is repeated (one or two │
              times) so that it also becomes a knot point.

       -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 or raw.

OVAL ITEMS

       Items of type oval appear as circular or oval regions on the display.  Each oval may  have
       an  outline,  a  fill,  or  both.  Ovals are created with widget commands of the following
       form:
              pathName create oval x1 y1 x2 y2 ?option value option value ...?
              pathName create oval coordList ?option value option value ...?
       The arguments x1, y1, x2, and y2 or coordList  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
       then  the  resulting  oval  is  circular;  otherwise  it is elongated in shape.  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 widget commands to change the item's configuration. An oval item becomes the
       current  item  when  the  mouse  pointer  is  over any part that is painted or (when fully
       transparent) that would be painted if both the -fill and -outline options were non-empty.

       The following standard options are supported by ovals:
              -dash
              -activedash
              -disableddash
              -dashoffset
              -fill
              -activefill
              -disabledfill
              -offset
              -outline
              -activeoutline
              -disabledoutline
              -outlineoffset
              -outlinestipple
              -activeoutlinestipple
              -disabledoutlinestipple
              -stipple
              -activestipple
              -disabledstipple
              -state
              -tags
              -width
              -activewidth
              -disabledwidth

POLYGON ITEMS

       Items of type polygon appear as  polygonal  or  curved  filled  regions  on  the  display.
       Polygon  items  support  coordinate  indexing operations using the canvas widget commands:
       dchars, index, insert.  Polygons are created with widget commands of the following form:
              pathName create polygon x1 y1 ... xn yn ?option value option value ...?
              pathName create polygon coordList ?option value option value ...?
       The arguments x1 through yn or coordList specify the coordinates for three or more  points
       that  define  a  polygon.  The first point should not be repeated as the last to close the
       shape; Tk will automatically close the periphery between the first and last points.  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  widget  commands  to change the item's configuration. A polygon item is the
       current item whenever the mouse pointer is over any part of the polygon, whether drawn  or
       not and whether or not the outline is smoothed.

       The following standard options are supported by polygons:
              -dash
              -activedash
              -disableddash
              -dashoffset
              -fill
              -activefill
              -disabledfill
              -offset
              -outline
              -activeoutline
              -disabledoutline
              -outlinestipple
              -activeoutlinestipple
              -disabledoutlinestipple
              -stipple
              -activestipple
              -disabledstipple
              -state
              -tags
              -width
              -activewidth
              -disabledwidth
       The following extra options are supported for polygons:

       -joinstyle style
              Specifies  the ways in which joints are to be drawn at the vertices of the outline.
              Style may have any of the  forms  accepted  by  Tk_GetCapStyle  (bevel,  miter,  or
              round).  If this option is not specified then it defaults to round.

       -smooth boolean
              Boolean  must  have one of the forms accepted by Tcl_GetBoolean or a line smoothing │
              method. Only true and raw are supported in the core (with bezier being an alias for │
              true),  but more can be added at runtime.  If a boolean false value or empty string │
              is given, no smoothing is applied.  A boolean truth value assumes  true  smoothing. │
              If the smoothing method is true, this indicates that the polygon should be drawn as │
              a curve, rendered as a set of quadratic splines: one spline is drawn for the  first │
              and  second  line segments, one for the second and third, and so on.  Straight-line │
              segments can be generated within a curve  by  duplicating  the  end-points  of  the │
              desired  line  segment.   If  the  smoothing method is raw, this indicates that the │
              polygon should also be drawn as a curve but where the list of coordinates  is  such │
              that  the  first  coordinate pair (and every third coordinate pair thereafter) is a │
              knot point on a cubic Bezier curve, and the other coordinates are control points on │
              the  cubic Bezier curve.  Straight line segments can be venerated within a curve by │
              making control points equal to their neighbouring knot points.  If the  last  point │
              is  not the second point of a pair of control points, the point is repeated (one or │
              two times) so that it also becomes the second point of a  pair  of  control  points │
              (the associated knot point will be the first control point).

       -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 or raw.

       Polygon  items  are  different from other items such as 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 widget commands) 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.  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

       Items  of type rectangle appear as rectangular regions on the display.  Each rectangle may
       have an outline, a fill, or both.  Rectangles are created  with  widget  commands  of  the
       following form:
              pathName create rectangle x1 y1 x2 y2 ?option value option value ...?
              pathName create rectangle coordList ?option value option value ...?
       The  arguments  x1,  y1,  x2, and y2 or coordList (which must have four elements) 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).  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 widget
       commands to change the item's configuration. A rectangle item  becomes  the  current  item
       when  the  mouse pointer is over any part that is painted or (when fully transparent) that
       would be painted if both the -fill and -outline options were non-empty.

       The following standard options are supported by rectangles:
              -dash
              -activedash
              -disableddash
              -dashoffset
              -fill
              -activefill
              -disabledfill
              -offset
              -outline
              -activeoutline
              -disabledoutline
              -outlineoffset
              -outlinestipple
              -activeoutlinestipple
              -disabledoutlinestipple
              -stipple
              -activestipple
              -disabledstipple
              -state
              -tags
              -width
              -activewidth
              -disabledwidth

TEXT ITEMS

       A text item displays a string of characters on the screen in  one  or  more  lines.   Text
       items  support indexing and selection, along with the following text-related canvas widget
       commands:  dchars, focus, icursor, index, insert, select.  Text  items  are  created  with
       widget commands of the following form:
              pathName create text x y ?option value option value ...?
              pathName create text coordList ?option value option value ...?
       The  arguments x and y or coordList (which must have two elements) specify the coordinates
       of a point used to position the text on the  display  (see  the  options  below  for  more
       information  on  how text is 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 widget commands to change the
       item's configuration. A text item becomes the current item when the mouse pointer is  over
       any part of its bounding box.

       The following standard options are supported by text items:
              -fill
              -activefill
              -disabledfill
              -stipple
              -activestipple
              -disabledstipple
              -state
              -tags
       The following extra options are supported for text items:

       -anchor anchorPos
              AnchorPos  tells how to position the text relative to the positioning point for the
              text;  it may have any of the forms accepted  by  Tk_GetAnchor.   For  example,  if
              anchorPos is center then the text is centered on the point;  if anchorPos is n then
              the text will be drawn such that the top center point  of  the  rectangular  region
              occupied  by  the  text  will be at the positioning point.  This option defaults to
              center.

       -font fontName
              Specifies the font to use for the text item.  FontName may be any string acceptable
              to  Tk_GetFont.  If this option is not specified, it defaults to a system-dependent
              font.

       -justify how
              Specifies how to justify the text within its bounding region.  How must be  one  of
              the  values  left,  right,  or center.  This option will only matter if the text is
              displayed as multiple lines.  If the option is omitted, it defaults to left.

       -text string
              String specifies the  characters  to  be  displayed  in  the  text  item.   Newline
              characters  cause line breaks.  The characters in the item may also be changed with
              the insert and delete widget commands.  This option defaults to an empty string.    │

       -underline                                                                                 │
              Specifies the integer index of a character within the  text  to  be  underlined.  0 │
              corresponds  to the first character of the text displayed, 1 to the next character, │
              and so on. -1 means that no underline should be drawn (if the whole text item is to │
              be underlined, the appropriate font should be used instead).

       -width lineLength
              Specifies  a maximum line length for the text, in any of the forms described in the
              COORDINATES section above.  If this option is zero (the default) the text is broken
              into  lines  only  at newline characters.  However, if this option is non-zero then
              any line that would be longer  than  lineLength  is  broken  just  before  a  space
              character to make the line shorter than lineLength;  the space character is treated
              as if it were a newline character.

WINDOW ITEMS

       Items of type window cause a particular window to be displayed at a given position on  the
       canvas.  Window items are created with widget commands of the following form:
              pathName create window x y ?option value option value ...?
              pathName create window coordList ?option value option value ...?
       The  arguments x and y or coordList (which must have two elements) specify the coordinates
       of a point used to position the window on the display (see the -anchor  option  below  for
       more  information  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 widget commands to
       change the item's configuration. Theoretically, a window item  becomes  the  current  item
       when  the  mouse  pointer  is  over  any  part  of  its bounding box, but in practice this
       typically does not happen because the mouse pointer ceases to be over the canvas  at  that
       point.

       The following standard options are supported by window items:
              -state
              -tags
       The following extra options are supported for window items:

       -anchor anchorPos
              AnchorPos  tells  how  to position the window 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 window is centered on the point;  if anchorPos is n
              then the window will be drawn so that its top center point is  at  the  positioning
              point.  This option defaults to center.

       -height pixels
              Specifies  the  height  to assign to the item's window.  Pixels may have any of the
              forms described in the COORDINATES section above.  If this option is not specified,
              or if it is specified as zero, then the window is given whatever height it requests
              internally.

       -width pixels
              Specifies the width to assign to the item's window.  Pixels may  have  any  of  the
              forms described in the COORDINATES section above.  If this option is not specified,
              or if it is specified as zero, then the window is given whatever width it  requests
              internally.

       -window pathName
              Specifies the window to associate with this item.  The window specified by pathName
              must either be 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:   due  to  restrictions  in the ways that windows are managed, it is not possible to
       draw other graphical items (such as lines and images) on top of window  items.   A  window
       item  always  obscures  any  graphics  that  overlap  it, regardless of their order in the
       display list. Also note that window items, unlike other canvas items, are not clipped  for
       display  by their containing canvas's border, and are instead clipped by the parent widget
       of the window specified by the -window option; when the parent widget is the canvas,  this
       means that the window item can overlap the canvas's border.

APPLICATION-DEFINED ITEM TYPES

       It  is  possible  for  individual applications to define new item types for canvas widgets
       using C code.  See the documentation for Tk_CreateItemType.

BINDINGS

       In the current implementation, new canvases are not given any default behavior:  you  will
       have to execute explicit Tcl commands to give the canvas its behavior.

CREDITS

       Tk's  canvas  widget  is  a blatant ripoff of ideas from Joel Bartlett's ezd program.  Ezd
       provides structured graphics in a Scheme environment and preceded canvases by  a  year  or
       two.   Its  simple  mechanisms  for  placing  and animating graphical objects inspired the
       functions of canvases.

SEE ALSO

       bind(3tk), font(3tk), image(3tk), scrollbar(3tk)

KEYWORDS

       canvas, widget