Seth Woolley's Man Viewer

canvas(n) - canvas, canvas - Create and manipulate canvas widgets - man n canvas

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

canvas(n)                    Tk Built-In Commands                    canvas(n)



NAME
       canvas - Create and manipulate canvas widgets

SYNOPSIS
       canvas  pathName ?options?  -background    -insertborderwidth  -select-
       borderwidth    -borderwidth   -insertofftime -selectforeground    -cur-
       sor   -insertontime  -takefocus        -highlightbackground     -inser-
       twidth   -xscrollcommand  -highlightcolor     -relief   -yscrollcommand
       -highlightthickness -state -insertbackground   -selectbackground

WIDGET-SPECIFIC OPTIONS
       Specifies  a floating-point value indicating how close(2,7,n) the mouse cursor
       must be to an item before it is considered to be ``inside''  the  item.
       Defaults  to  1.0.  Specifies a boolean value that indicates whether or
       not it should be allowable to set(7,n,1 builtins) 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.   Specifies
       a  desired window height that the canvas widget should request from its
       geometry manager.  The value may be  specified  in(1,8)  any  of  the  forms
       described in(1,8) the COORDINATES section below.  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(1,8)  the  canvas.
       Each  of  the coordinates may be specified in(1,8) any of the forms given in(1,8)
       the COORDINATES section below.  Modifies the default state of the  can-
       vas  where  state  may  be  set(7,n,1 builtins) 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 specifica-
       tions such that the appearance of the item can be different in(1,8)  differ-
       ent  situations.  The  options  that  start  with  active  control  the
       appearence when the mouse pointer is over it, while the option starting
       with disabled controls the appearence when the state is disabled.  Can-
       vas items which are disabled will not react to canvas bindings.  Speci-
       fies  a desired window width that the canvas widget should request from
       its geometry manager.  The value may be specified in(1,8) any of  the  forms
       described in(1,8) the COORDINATES section below.  Specifies an increment for
       horizontal scrolling, in(1,8) any of the usual forms  permitted  for  screen
       distances.  If the value of this option is greater than zero, the hori-
       zontal view in(1,8) 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(1,7)  for  scrolling  (e.g.,  the
       change  in(1,8)  view  when  the  left  and  right arrows of a scrollbar are
       selected) will also be xScrollIncrement.  If the value of  this  option
       is  less(1,3)  than  or  equal  to zero, then horizontal scrolling is uncon-
       strained.  Specifies an increment for vertical scrolling, in(1,8) any of the
       usual  forms  permitted  for  screen  distances.   If the value of this
       option is greater than zero, the vertical view in(1,8) the  window  will  be
       constrained so that the canvas y coordinate at the top edge of the win-
       dow is always an even multiple of yScrollIncrement;   furthermore,  the
       units(1,7)  for  scrolling (e.g., the change in(1,8) view when the top and bottom
       arrows of a scrollbar are selected) will also be yScrollIncrement.   If
       the  value  of this option is less(1,3) than or equal to zero, then vertical
       scrolling is unconstrained.


INTRODUCTION
       The canvas command creates a new window (given by  the  pathName  argu-
       ment) and makes it into a canvas widget.  Additional options, described
       above, may be specified on the command line or in(1,8) 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(1,2,n)  this
       command  is  invoked, there must not exist a window named(5,8) 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 com-
       mands  may  be associated with items in(1,8) much the same way that the bind(2,n,1 builtins)
       command allows commands to be bound to widgets.  For example, a partic-
       ular  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(1,8) a canvas can have behaviors
       defined by the Tcl scripts bound to them.


DISPLAY LIST
       The items in(1,8) a canvas are ordered for purposes  of  display,  with  the
       first  item  in(1,8) the display list being displayed first, followed by the
       next item in(1,8) the list, and so on.  Items  later  in(1,8)  the  display  list
       obscure  those  that  are earlier in(1,8) 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 every-
       thing 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 win-
       dow 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(3,n) and  lower  Tk  com-
       mands instead.


ITEM IDS AND TAGS
       Items  in(1,8)  a canvas widget may be named(5,8) in(1,8) 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(3,n) 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(1,8) various interesting ways;  for example, all  selected
       items might be given the tag ``selected''.

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

       The tag current is managed automatically by Tk; it applies to the  cur-
       rent  item, which is the topmost item whose drawn area covers the posi-
       tion of the mouse cursor.  If the mouse is not in(1,8) the canvas widget  or
       is not over an item, then no item has the current tag.

       When specifying items in(1,8) canvas widget commands, if(3,n) 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(1,8) 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  widget  commands  only  operate  on  a single item at a time(1,2,n);  if(3,n)
       tagOrId is specified in(1,8) a way that names multiple items, then the  nor-
       mal  behavior  is  for  the  command to use the first (lowest) of these
       items in(1,8) the display list that is suitable for the command.  Exceptions
       are noted in(1,8) the widget command descriptions below.


COORDINATES
       All  coordinates  related to canvases are stored as floating-point num-
       bers.  Coordinates and distances are specified in(1,8) screen  units(1,7),  which
       are  floating-point  numbers optionally followed by one of several let-
       ters.  If no letter is supplied then the distance is in(1,8) pixels.  If the
       letter  is  m then the distance is in(1,8) millimeters on the screen;  if(3,n) it
       is c then the distance is in(1,8) 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 ori-
       gin of the window using the xview and yview widget commands;   this  is
       typically used for scrolling.  Canvases do not support scaling or rota-
       tion 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.


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  inser-
       tion  cursor  position. An index may be specified in(1,8) 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(3,n) you define new types of text-like items, it would be  advis-
       able  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(1,8) the  text
       item;   this  is  necessary for such tasks as inserting new text at the
       end of the item.  Lines and Polygons don't support the insertion cursor
       and  the  selection.  Their  indixes  are  supposed  to be even always,
       because coordinates always appear in(1,8) 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(1,3) than 0 is treated as if(3,n) it  were  zero,  and  a
                 number greater than the length of the text item is treated as
                 if(3,n) it were equal to the length of the text  item.  For  poly-
                 gons,  numbers  less(1,3) 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(1,8)  the item (same as the number of characters or coordinates
                 in(1,8) the item).

       insert    Refers to the character just before which the insertion  cur-
                 sor  is drawn in(1,8) this item. Not valid for lines and polygons.

       sel.first Refers to the first selected character in(1,8) the item.   If  the
                 selection isn't in(1,8) this item then this form is illegal.

       sel.last  Refers  to  the  last selected character in(1,8) the item.  If the
                 selection isn't in(1,8) 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(1,8) the coordinate system
                 of the canvas.  If x and y lie outside the  coordinates  cov-
                 ered  by  the text item, then they refer to the first or last
                 character in(1,8) the line that is closest to the given point.


DASH PATTERNS
       Many items support the notion of an dash pattern for outlines.

       The first possible syntax is a list of integers.  Each  element  repre-
       sents the number of pixels of a line segment. Only the odd segments are
       drawn  using  the  "outline"  color.  The  other  segments  are   drawn
       transparant.

       The second possible syntax is a character list containing only 5 possi-
       ble characters [.,-_ ]. The space can be  used  to  enlarge  the  space
       between other line elements, and can not occur as the first position in(1,8)
       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  it
       shape-conserving.  This  means that all values in(1,8) 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(7,n,1 builtins) of dash patterns, the  dash
       pattern  will  be  displayed as the closest dash pattern that is avail-
       able.  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(3,n) it isn't already present on that list.  It  is  possible
              that  no  items will satisfy the constraints given by searchSpec
              and args, in(1,8) which case the command has no effect.  This command
              returns  an  empty  string(3,n)  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(1,8)  the  display  list.  If tagOrId denotes more
                     than one item, then the last (topmost) of these items  in(1,8)
                     the display list is used.

              all    Selects all the items in(1,8) the canvas.

              below tagOrId
                     Selects  the  item  just  before (below) the one given by
                     tagOrId in(1,8) the display list.   If  tagOrId  denotes  more
                     than  one item, then the first (lowest) of these items in(1,8)
                     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(1,8) 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 consid-
                     ered 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(3,n)  by
                     tag,  it  selects the first item in(1,8) the display list with
                     the given tag).  Instead of selecting the topmost closest
                     item, this form will select(2,7,2 select_tut) the topmost closest item that
                     is below start in(1,8) the display  list;   if(3,n)  no  such  item
                     exists,  then the selection behaves as if(3,n) the start argu-
                     ment 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(5,8) by the tagOrId arguments.  The list
              has the form ``x1 y1 x2 y2'' such that the drawn  areas  of  all
              the  named(5,8)  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(3,n)
              the  matching  items  have  empty bounding boxes (i.e. they have
              nothing to display) then an empty string(3,n) is returned.

       pathName bind(2,n,1 builtins) 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(2,n,1 builtins) command except that it
              operates on items in(1,8) a canvas rather than entire  widgets.   See
              the  bind(2,n,1 builtins)  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(3,n)  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(8,n) occurs if(3,n) there is no such bind-
              ing).  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, Button-
              Press, Motion, and KeyPress) or virtual(5,8) events.  The handling of
              events in(1,8) canvases uses the current item defined in(1,8) 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(3,n) any.  Keyboard-related events are directed to the focus item,
              if(3,n)  any  (see  the focus widget command below for more on this).
              If a virtual(5,8) event is used in(1,8) a binding, that binding can  trig-
              ger only if(3,n) the virtual(5,8) 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(3,n) one binding is associ-
              ated 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(1,8)
              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(1,8)  a
              binding  script terminates that script, and a break command ter-
              minates that script and skips  any  remaining  scripts  for  the
              event, just as for the bind(2,n,1 builtins) command.

              If bindings have been created for a canvas window using the bind(2,n,1 builtins)
              command, then they are invoked in(1,8) addition to  bindings  created
              for the canvas's items using the bind(2,n,1 builtins) widget command.  The bind-
              ings 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(1,8) the canvas screenx, this command
              returns the canvas x-coordinate that is displayed at that  loca-
              tion.   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(1,8) the canvas screeny  this  command
              returns  the canvas y-coordinate that is displayed at that loca-
              tion.  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  can-
              vas 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 avail-
              able  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(5,8)
              option (this list will be identical to the corresponding sublist
              of  the  value  returned  if(3,n) 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(1,8) 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(5,8) by tagOrId.  If
              coordinates are specified, then they replace the current coordi-
              nates  for the named(5,8) item.  If tagOrId refers to multiple items,
              then the first one in(1,8) 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(1,8) pathName of type type.  The exact format of
              the  arguments after type depends on type, but usually they con-
              sist of the coordinates for one  or  more  points,  followed  by
              specifications  for  zero or more item options.  See the subsec-
              tions 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 coor-
              dinates, in(1,8) the range given by first and  last,  inclusive.   If
              some of the items given by tagOrId don't support indexing opera-
              tions 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(1,8) 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 doesn't have the tag tagToDelete then the item is unaf-
              fected 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(1,8) 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(7,n,1 builtins) to the first such item in(1,8) the display list that supports
              the insertion cursor.  If tagOrId doesn't refer to any items, or
              if(3,n)  none  of  them  support the insertion cursor, then the focus
              isn't changed.  If tagOrId is an empty string(3,n),  then  the  focus
              item  is reset(1,7,1 tput) so that no item has the focus.  If tagOrId is not
              specified then the command returns the id for the item that cur-
              rently  has  the  focus,  or  an empty string(3,n) if(3,n) no item has the
              focus.

              Once the focus has been set(7,n,1 builtins) 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(7,n,1 builtins) with the focus command) are totally indepen-
              dent: a given item doesn't 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(7,n,1 builtins) the focus
              window to the canvas (if(3,n) it wasn't 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(1,8) the  dis-
              play  list.   If  tagOrId  doesn't refer to any items, or if(3,n) the
              item contains no tags, then an empty string(3,n) 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  don't
              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(1,8) an
              item if(3,n) that item currently has the keyboard focus (see the wid-
              get  command  focus,  below), but the cursor position may be set(7,n,1 builtins)
              even when the item doesn't have the focus.  This command returns
              an empty string.

       pathName index tagOrId index
              This command returns a decimal string(3,n) giving the numerical index
              within tagOrId corresponding to index.  Index  gives  a  textual
              description  of  the  desired  position  as described in(1,8) 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(1,8) the first of these items that supports indexing
              operations (in(1,8) display list order).

       pathName insert tagOrId beforeThis string(3,n)
              For each of the items given by tagOrId,  if(3,n)  the  item  supports
              text  or  coordinate, insertion then string(3,n) 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(3,n) 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 wid-
              get.   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(5,8) option (this list will
              be identical to the corresponding sublist of the value  returned
              if(3,n)  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(1,8) each of the items given
              by tagOrId;  in(1,8) this case the command returns an  empty  string.
              The  options and values are the same as those permissible in(1,8) 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(1,8)  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(3,n) it refers to more  than  one  item
              then  the  first  (lowest) of these items in(1,8) 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(3,n) and lower commands, not the raise(3,n) and
              lower widget commands for canvases.   This  command  returns  an
              empty string.

       pathName move(3x,7,3x curs_move) tagOrId xAmount yAmount
              Move each of the items given by tagOrId in(1,8) the canvas coordinate
              space by adding xAmount to the x-coordinate of each point  asso-
              ciated  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 can-
              vas.  If the -file option is specified then  the  Postscript  is
              written  to  a  file(1,n) and an empty string(3,n) 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 opera-
              tion will fail because safe  interpreters  are  not  allowed  to
              write(1,2)  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(2,3,n) for further writing at the end of the operation.  The Post-
              script  is created in(1,8) Encapsulated Postscript form using version(1,3,5)
              3.0 of the Document Structuring Conventions.  Note:  by  default
              Postscript is only generated for information that appears in(1,8) 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(1,8) the Postscript.  To get  around  this  problem  either
              invoke  the  "update(7,n)"  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 speci-
                     fies a color mapping to use in(1,8) the Postscript.  Each ele-
                     ment  of varName must consist of Postscript code to set(7,n,1 builtins) a
                     particular  color  value  (e.g.  ``1.0  1.0  0.0  setrgb-
                     color'').  When outputting color information in(1,8) the Post-
                     script, Tk checks to see if(3,n) there is an element  of  var-
                     Name with the same name as the color.  If so, Tk uses the
                     value of the element as the Postscript command to set(7,n,1 builtins) the
                     color.  If this option hasn't been specified, or if(3,n) there
                     isn't an entry in(1,8) 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(1,n)  in(1,8)  which  to  write(1,2)  the
                     Postscript.   If  this  option  isn't  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 speci-
                     fies a font mapping to use in(1,8) the Postscript.  Each  ele-
                     ment  of varName must consist of a Tcl list with two ele-
                     ments, which are the name and point size of a  Postscript
                     font.  When outputting Postscript commands for a particu-
                     lar font, Tk checks to see if(3,n) varName contains an element
                     with the same name as the font.  If there is such an ele-
                     ment, then the font information contained in(1,8) that element
                     is  used  in(1,8)  the  Postscript.   Otherwise Tk attempts to
                     guess what Postscript font to use.  Tk's  guesses  gener-
                     ally  only  work  for  well-known fonts such as Times and
                     Helvetica and Courier, and only if(3,n) the X font  name  does
                     not omit any dashes up through the point size.  For exam-
                     ple,  -*-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(1,8) the
                     canvas window) should  be  over  the  positioning  point.
                     Defaults to center.

              -pageheight size
                     Specifies  that the Postscript should be scaled in(1,8) both x
                     and y so that the printed area is size high on the  Post-
                     script  page.   Size  consists of a floating-point number
                     followed by c for centimeters, i for inches, m  for  mil-
                     limeters,  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(1,6) from -pagewidth is  used  (non-uni-
                     form scaling is not implemented).

              -pagewidth size
                     Specifies  that the Postscript should be scaled in(1,8) both x
                     and y so that the printed area is size wide on the  Post-
                     script  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(1,6) from -pagewidth  is used (non-uniform  scal-
                     ing 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(1,8) 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(1,8) 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(1,8) rotated output the x-
                     axis  runs  along the long dimension of the page (``land-
                     scape'' 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(1,8)  canvas  coordi-
                     nates,  not  window coordinates.  Defaults to the coordi-
                     nate 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(1,8) canvas coordinates,
                     not window coordinates.  Defaults to  the  coordinate  of
                     the top edge of the window.

       pathName raise(3,n) tagOrId ?aboveThis?
              Move  all of the items given by tagOrId to a new position in(1,8) 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(3,n)  it refers to more than one item then the last
              (topmost) of these items in(1,8) the display list is used as the des-
              tination  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(3,n) and lower commands, not the raise(3,n) 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(1,8) 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(1,6)  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(1,6) of xScale.  Similarly, each y-
              coordinate is adjusted to change the distance from yOrigin by  a
              factor(1,6) 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(1,8)
                     conjunction  with  later scan dragto commands.  Typically
                     this command is associated with a mouse button  press  in(1,8)
                     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 dif-
                     ference in(1,8) coordinates, where gain defaults to 10.   This
                     command  is typically associated with mouse motion events
                     in(1,8) the widget, to produce the effect of dragging the can-
                     vas  at  high speed through its window.  The return value
                     is an empty string.

       pathName select(2,7,2 select_tut) option ?tagOrId arg?
              Manipulates the selection in(1,8) 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(3,n) 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 posi-
              tion within tagOrId, as described in(1,8) INDICES above.

              pathName select(2,7,2 select_tut) adjust tagOrId index
                     Locate the end of the selection in(1,8) 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(2,7,2 select_tut) to commands.   If  the
                     selection  isn't  currently  in(1,8) tagOrId then this command
                     behaves  the  same  as  the  select(2,7,2 select_tut)  to  widget  command.
                     Returns an empty string.

              pathName select(2,7,2 select_tut) clear(1,3x,3x clrtobot)
                     Clear  the  selection  if(3,n)  it  is in(1,8) this widget.  If the
                     selection isn't in(1,8) this widget then the  command  has  no
                     effect.  Returns an empty string.

              pathName select(2,7,2 select_tut) from tagOrId index
                     Set  the selection anchor point for the widget to be just
                     before the character given by index in(1,8) the item given  by
                     tagOrId.   This command doesn't change the selection;  it
                     just sets the fixed  end  of  the  selection  for  future
                     select(2,7,2 select_tut) to commands.  Returns an empty string.

              pathName select(2,7,2 select_tut) item
                     Returns  the id of the selected item, if(3,n) the selection is
                     in(1,8) an item in(1,8) this canvas.  If the selection  is  not  in(1,8)
                     this canvas then an empty string(3,n) is returned.

              pathName select(2,7,2 select_tut) 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(3,n)  index  is  greater  than or equal to the
                     anchor point.  The anchor point is determined by the most
                     recent select(2,7,2 select_tut) adjust or select(2,7,2 select_tut) from command for this wid-
                     get.  If the selection anchor point for the widget  isn't
                     currently  in(1,8) tagOrId, then it is set(7,n,1 builtins) to the same charac-
                     ter 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(1,8) the display list is returned.   If  tagOrId
              doesn't  refer  to  any  items  at  all  then an empty string(3,n) is
              returned.

       pathName xview  ?args?
              This command is used to query and change the horizontal position
              of  the  information  displayed  in(1,8) 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(1,8) the  window.   For
                     example,  if(3,n)  the first element is .2 and the second ele-
                     ment is .6, 20% of the canvas's area (as defined  by  the
                     -scrollregion option) is off-screen to the left, the mid-
                     dle 40% is visible in(1,8) 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(1,8) 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(1,8) the window left or  right
                     according to number and what.  Number must be an integer.
                     What must be either units(1,7) or pages or an abbreviation  of
                     one of these.  If what is units(1,7), the view adjusts left or
                     right in(1,8) units(1,7) of the xScrollIncrement option, if(3,n)  it  is
                     greater  than zero, or in(1,8) units(1,7) of one-tenth the window's
                     width otherwise.  If what is pages then the view  adjusts
                     in(1,8) units(1,7) of nine-tenths the window's width.  If number is
                     negative then information farther  to  the  left  becomes
                     visible;   if(3,n)  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(1,8) 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(1,8)  the  window.   For
                     example,  if(3,n)  the first element is .6 and the second ele-
                     ment is 1.0, the lowest 40%  of  the  canvas's  area  (as
                     defined  by  the  -scrollregion option) is visible in(1,8) the
                     window.  These are the same values passed  to  scrollbars
                     via the -yscrollcommand option.

              pathName yview moveto fraction
                     Adjusts  the  view  in(1,8) 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(1,8) the window up or down
                     according to number and what.  Number must be an integer.
                     What  must  be  either units(1,7) or pages.  If what is units(1,7),
                     the view adjusts up or down in(1,8) units(1,7) of the yScrollIncre-
                     ment  option,  if(3,n) it is greater than zero, or in(1,8) units(1,7) of
                     one-tenth the window's  height  otherwise.   If  what  is
                     pages  then  the view adjusts in(1,8) units(1,7) of nine-tenths the
                     window's height.   If  number  is  negative  then  higher
                     information  becomes  visible;   if(3,n)  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(7,n,1 builtins)  of  configuration options for items of that type,
       which may be used in(1,8) the  create  and  itemconfigure  widget  commands.
       Most  items don't support indexing or selection or the commands related
       to them, such as index and insert.  Where items do support these facil-
       ities,  it  is noted explicitly in(1,8) the descriptions below.  At present,
       text, line and polygon items provide this support.  For lines and poly-
       gons the indexing facility is used to manipulate the coordinates of the
       item.


COMMON ITEM OPTIONS
       Many items share a common set(7,n,1 builtins) 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 omit-
              ted then the default is a solid outline.   See  "DASH  PATTERNS"
              for more information.

       -dashoffset offset
              The  starting  offset in(1,8) pixels into the pattern provided by the
              -dash option.  -dashoffset is ignored if(3,n) there is no -dash  pat-
              tern.   The  offset  may  have any of the forms described in(1,8) the
              COORDINATES section above.

       -fill color

       -activefill color

       -disabledfill color
              Specifies the color to be used to fill item's area.  in(1,8) its nor-
              mal,  active,  and  disabled  states,  Color may have any of the
              forms accepted by Tk_GetColor.  If color is an empty string(3,n) (the
              default),  then  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(1,8) 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(3,n) 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  can-
              vas  objects  the  origin is the canvas origin, but putting # in(1,8)
              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 stip-
              ple 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(1,8) 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(1,8) any of the forms accepted by Tk_GetBitmap.  If the -out-
              line option hasn't  been  specified  then  this  option  has  no
              effect.   If  bitmap  is an empty string(3,n) (the default), then the
              outline is drawn in(1,8) a solid fashion.

       -stipple bitmap

       -activestipple bitmap

       -disabledstipple bitmap
              This option specifies stipple patterns that should  be  used  to
              fill  the  the  item  in(1,8) its normal, active and disabled states.
              bitmap specifies the stipple pattern to use, in(1,8) any of the forms
              accepted by Tk_GetBitmap.  If the -fill option hasn't been spec-
              ified then this option has no effect.  If  bitmap  is  an  empty
              string(3,n)  (the  default), then filling is done in(1,8) a solid fashion.
              For the text item, it affects the actual text.

       -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(7,n,1 builtins) 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(1,8) its normal, active and disabled states.  outlineWidth
              may  be in(1,8) any of the forms described in(1,8) the COORDINATES section
              above.  If the -outline option has been specified  as  an  empty
              string(3,n)  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(1,8) one of several ways (spec-
       ified 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(1,8) itemconfigure widget commands to change the item's  configu-
       ration.
       The following standard options are supported by arcs: -dash -activedash
       -disableddash -dashoffset -fill -activefill -disabledfill -offset -out-
       line   -activeoutline   -disabledoutline   -outlinestipple  -activeout-
       linestipple -disabledoutlinestipple -stipple -activestipple  -disabled-
       stipple  -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(1,3) 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(1,8) units(1,7) of degrees measured counter-
              clockwise from the 3-o'clock(3,n) position;  it may be  either  posi-
              tive 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 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(1,8)  itemconfigure  widget  commands  to
       change the item's configuration.
       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 posi-
              tioning  point  for  the  item;   it  may  have any of the forms
              accepted by Tk_GetAnchor.  For example, if(3,n) anchorPos  is  center
              then  the  bitmap  is  centered on the point;  if(3,n) 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(1,8) 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(3,n) it is specified as an empty string(3,n),  then
              nothing  is  displayed where the bitmap pixels are 0;  this pro-
              duces a transparent effect.

       -bitmap bitmap

       -activebitmap bitmap

       -disabledbitmap bitmap
              Specifies the bitmaps to display in(1,8)  the  item  in(1,8)  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(1,8)  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(1,8) itemconfigure widget com-
       mands to change the item's configuration.
       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 posi-
              tioning point for the item;   it  may  have  any  of  the  forms
              accepted  by  Tk_GetAnchor.  For example, if(3,n) anchorPos is center
              then the image is centered on the point;  if(3,n) 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(1,8) the  item  in(1,8)  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(1,8)  itemconfigure  widget  commands  to
       change the item's configuration.
       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  argu-
              ment  must be a list with three elements, each specifying a dis-
              tance in(1,8) any of the forms described in(1,8) 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 isn't specified then Tk picks  a  ``rea-
              sonable'' shape.

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

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

       -smooth smoothMethod
              smoothMethod  must  have  one  of  the forms accepted by Tk_Get-
              Boolean or a line smoothing method.  Only bezier is supported in(1,8)
              the  core, but more can be added at runtime.  If a boolean false
              value or empty string(3,n) is given,  no  smoothing  is  applied.   A
              boolean  truth  value  assume  bezier  smoothing.   It indicates
              whether or not the line should be drawn as a curve.  If so,  the
              line  is  rendered  as a set(7,n,1 builtins) of parabolic 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.

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


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  rectangu-
       lar  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(1,8)  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(1,8) itemconfig-
       ure widget commands to change the item's configuration.
       The   following   standard   options  are  supported  by  ovals:  -dash
       -activedash -disableddash -dashoffset -fill  -activefill  -disabledfill
       -offset   -outline   -activeoutline   -disabledoutline  -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 cre-
       ate 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(2,7,n) the shape; Tk will automatically close(2,7,n) the periph-
       ery 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 con-
       figuration options for the item.  These same option-value pairs may  be
       used  in(1,8)  itemconfigure widget commands to change the item's configura-
       tion.
       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(1,8) which joints are to be drawn at the ver-
              tices of the outline.  Style may have any of the forms  accepted
              by  Tk_GetCapStyle  (bevel,  miter,  or  round).  If this option
              isn't specified then it defaults to miter.

       -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(7,n,1 builtins)  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(1,8) 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.

       Polygon items are different from other items such as rectangles,  ovals
       and  arcs  in(1,8)  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(3,n) it is not filled.  For most other item types,
       an interior point is considered to be inside the item only if(3,n) the  item
       is  filled  or  if(3,n)  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 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  coordi-
       nates 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(1,8) itemconfigure widget commands to change the item's
       configuration.
       The following standard  options  are  supported  by  rectangles:  -dash
       -activedash  -disableddash  -dashoffset -fill -activefill -disabledfill
       -offset  -outline   -activeoutline   -disabledoutline   -outlinestipple
       -activeoutlinestipple  -disabledoutlinestipple  -stipple -activestipple
       -disabledstipple -state -tags -width -activewidth -disabledwidth


TEXT ITEMS
       A text item displays a string(3,n) of characters on the  screen  in(1,8)  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(2,7,2 select_tut).  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 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(1,8) itemconfigure widget commands to change the item's
       configuration.
       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  posi-
              tioning  point  for  the  text;   it  may  have any of the forms
              accepted by Tk_GetAnchor.  For example, if(3,n) anchorPos  is  center
              then  the text is centered on the point;  if(3,n) 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 position-
              ing point.  This option defaults to center.

       -font fontName
              Specifies the font to use for the text item.   FontName  may  be
              any string(3,n) acceptable to Tk_GetFont.  If this option isn't spec-
              ified, 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(3,n) the text  is  displayed  as  multiple
              lines.  If the option is omitted, it defaults to left.

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

       -width lineLength
              Specifies a maximum line length for the  text,  in(1,8)  any  of  the
              forms  described  in(1,8)  the  COORDINATES  section  above.  If this
              option is zero (the default) the text is broken into lines  only
              at newline characters.  However, if(3,n) 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 line-
              Length;  the space character is treated as if(3,n) 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 specify the coor-
       dinates of a point used to position the window on the display (see  the
       -anchor  option  below  for  more  information  on how bitmaps are dis-
       played).  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(1,8) itemconfigure  wid-
       get commands to change the item's configuration.
       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 posi-
              tioning  point  for  the  item;   it  may  have any of the forms
              accepted by Tk_GetAnchor.  For example, if(3,n) anchorPos  is  center
              then  the  window  is  centered on the point;  if(3,n) 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(1,8)  the  COORDINATES  section
              above.  If this option isn't specified, or if(3,n) it is specified as
              an empty string(3,n), 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(1,8)  the  COORDINATES  section
              above.  If this option isn't specified, or if(3,n) it is specified as
              an empty string(3,n), 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  wid-
              get  or a child of some ancestor of the canvas widget.  PathName
              may not refer to a top-level window.

       Note:  due to restrictions in(1,8) 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(1,8) the display list.


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


BINDINGS
       In  the  current implementation, new canvases are not given any default
       behavior:  you'll 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(1,8) a Scheme  environment
       and  preceded  canvases  by  a  year or two.  Its simple mechanisms for
       placing and animating graphical objects inspired the functions of  can-
       vases.


KEYWORDS
       canvas, widget



Tk                                    8.3                            canvas(n)

References for this manual (incoming links)