


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


NAME
       canvas - Create and manipulate canvas widgets

SYNOPSIS
       canvas pathName ?options?

STANDARD OPTIONS
       background      highlightThickness             insertWidthtakeFocus
       borderWidth     insertBackground               reliefxScrollCommand
       cursor          insertBorderWidth              selectBackgroundyScrollCommand
       highlightColor  insertOffTime  selectBorderWidth
       highlightBackground            insertOnTime    selectForeground

       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       Name:           closeEnough
       Class:          CloseEnough
       Command-Line Switch:-closeenough

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

       Name:           confine
       Class:          Confine
       Command-Line Switch:-confine

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

       Name:           height
       Class:          Height
       Command-Line Switch:-height

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

       Name:           scrollRegion
       Class:          ScrollRegion
       Command-Line Switch:-scrollregion

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



Tk                             4.0                              1





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


              the coordinates may be  specified  in  any  of  the
              forms given in the COORDINATES section below.

       Name:           width
       Class:          width
       Command-Line Switch:-width

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

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

              Specifies an increment for horizontal scrolling, in
              any  of  the  usual forms permitted for screen dis-
              tances.  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 mul-
              tiple 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.

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

              Specifies  an  increment for vertical scrolling, in
              any of the usual forms permitted  for  screen  dis-
              tances.   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



Tk                             4.0                              2





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


       time this command is invoked, there must not exist a  win-
       dow 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 manip-
       ulated (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 exam-
       ple, a particular command may be associated with the <But-
       ton-1> event so that the command is invoked whenever  but-
       ton 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.


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'' isn't.  The same tag may  be  associated
       with many different items.  This is commonly done to group
       items in  various  interesting  ways;   for  example,  all
       selected items might be given the tag ``selected''.

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

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

       When  specifying  items  in canvas widget commands, if the



Tk                             4.0                              3





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


       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.   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 (low-
       est) of these items in the display list that  is  suitable
       for  the command.  Exceptions are noted in the widget com-
       mand descriptions below.


COORDINATES
       All coordinates related to canvases are stored  as  float-
       ing-point  numbers.   Coordinates and distances are speci-
       fied in screen units,  which  are  floating-point  numbers
       optionally followed by one of several letters.  If no let-
       ter 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.


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  coordi-
       nate 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 rota-
       tion of the canvas coordinate system relative to the  win-
       dow coordinate system.

       Indidividual  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.  Indices are used
       for commands such as inserting text, deleting a  range  of
       characters, 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;



Tk                             4.0                              4





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


       this  is necessary for such tasks as inserting new text at
       the end of the item.

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

       end       Refers  to the character just after the last one
                 in the item (same as the number of characters in
                 the item).

       insert    Refers  to  the  character just before which the
                 insertion cursor is drawn in this item.

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

       sel.last  Refers to the last  selected  character  in  the
                 item.   If the selection isn't in this item then
                 this form is illegal.

       @x,y      Refers to the character at the point given by  x
                 and  y, where x and y are specified in the coor-
                 dinate 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 char-
                 acter  in  the line that is closest to the given
                 point.


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



Tk                             4.0                              5





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


              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 over-
                     lap 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  top-
                     most 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.




Tk                             4.0                              6





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


              withtag tagOrId
                     Selects all the items given by tagOrId.

       pathName bbox tagOrId ?tagOrId tagOrId ...?
              Returns a list with four elements giving an approx-
              imate  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  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 substitu-
              tions  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 exist-
              ing binding rather than  replacing  it).   In  this
              case  the return value is an empty string.  If com-
              mand is omitted then the command returns  the  com-
              mand associated with tagOrId and sequence (an error
              occurs if there is no such binding).  If both  com-
              mand  and  sequence  are  omitted  then the command
              returns a list of all the sequences for which bind-
              ings 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.
              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).

              It  is  possible  for  multiple bindings to match a
              particular event.  This could occur,  for  example,



Tk                             4.0                              7





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


              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 multi-
              ple 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 screen x-coordinate  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 near-
              est multiple of gridspacing units.

       pathName canvasy screeny ?gridspacing?
              Given a screen y-coordinate  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 near-
              est 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  path-
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ-
              ing the one named option (this list will be identi-
              cal  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



Tk                             4.0                              8





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


              the values accepted by the canvas command.

       pathName coords tagOrId ?x0 y0 ...?
              Query  or  modify  the  coordinates  that define an
              item.  If no coordinates are specified,  this  com-
              mand  returns a list whose elements are the coordi-
              nates of the item named by tagOrId.  If coordinates
              are  specified, then they replace the current coor-
              dinates 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 ...?
              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 syn-
              tax 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 charac-
              ters in the range given by first and  last,  inclu-
              sive.   If some of the items given by tagOrId don't
              support text operations,  then  they  are  ignored.
              First and last are indices of characters within the
              item(s) as 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 doesn't 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  com-
              mand.

       pathName focus ?tagOrId?
              Set the keyboard focus for the canvas widget to the



Tk                             4.0                              9





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


              item given by tagOrId.  If tagOrId refers  to  sev-
              eral items, then the focus is set to the first such
              item in the display list that supports  the  inser-
              tion  cursor.   If  tagOrId  doesn't  refer  to any
              items, or if none of  them  support  the  insertion
              cursor,  then  the focus isn't 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 doesn't actually have the
              input focus unless (a) its canvas is the focus win-
              dow  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  wasn't
              there already).

       pathName gettags tagOrId
              Return  a  list whose elements are the tags associ-
              ated 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 doesn't 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 charac-
              ter  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 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 doesn't 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.
              The return value is guaranteed to lie between 0 and



Tk                             4.0                             10





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


              the  number  of  characters within the item, inclu-
              sive.  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 insertion  then  string  is  inserted
              into  the  item's  text  just  before the character
              whose index is beforeThis.  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  describ-
              ing all of the available options for the first item
              given by tagOrId (see Tk_ConfigureInfo for informa-
              tion  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



Tk                             4.0                             11





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


              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  dis-
              play  list  is used as the destination location for
              the moved items.  This  command  returns  an  empty
              string.

       pathName move tagOrId xAmount yAmount
              Move each of the items given by tagOrId in the can-
              vas 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 asso-
              ciated  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 speci-
              fied then the Postscript is written to a  file  and
              an   empty   string  is  returned;   otherwise  the
              Postscript is returned as the result  of  the  com-
              mand.   The  Postscript  is created in Encapsulated
              Postscript form using version 3.0 of  the  Document
              Structuring Conventions.  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  vari-
                     able  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
                     hasn't  been specified, or if there isn't an
                     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



Tk                             4.0                             12





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


                     write  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  vari-
                     able that specifies a font mapping to use in
                     the Postscript.   Each  element  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  particular  font,
                     Tk checks to see if varName contains an ele-
                     ment 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 can-
                     vas to print.  Defaults to the height of the
                     canvas window.

              -pageanchor anchor
                     Specifies  which  point  of the printed area
                     should be appear over the positioning  point
                     on  the  page  (which is given by the -pagex
                     and -pagey options).  For example,  -pagean-
                     chor  n  means  that  the  top center of the
                     printed area 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 the
                     later option is used (non-uniform scaling is



Tk                             4.0                             13





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


                     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 fac-
                     tor  from  the  later  option  is used (non-
                     uniform scaling is not implemented).

              -pagex position
                     Position gives the x-coordinate of the posi-
                     tioning  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 posi-
                     tioning  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  out-
                     put 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 can-
                     vas 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.





Tk                             4.0                             14





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


              -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 dis-
              play list is used as the destination  location  for
              the  moved  items.   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 can-
              vases.  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.
                     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  wid-
                     get.   It  then adjusts the view by 10 times
                     the difference in coordinates.  This command
                     is  typically  associated  with mouse motion
                     events in the widget, to produce the  effect



Tk                             4.0                             15





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


                     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 descrip-
              tions below, tagOrId must refer  to  an  item  that
              supports  indexing  and selection;  if it refers to
              multiple items then the first of  these  that  sup-
              ports  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 isn't 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 isn't 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 wid-
                     get to be just before the character given by
                     index  in  the  item given by tagOrId.  This
                     command doesn't 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  char-
                     acters  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



Tk                             4.0                             16





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


                     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 isn't 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 doesn't
              refer to any items at all then an empty  string  is
              returned.

       pathName xview  ?args?
              This  command is used to query and change the hori-
              zontal 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  horizon-
                     tal 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 mid-
                     dle 40% is visible in the window, and 40% of
                     the  canvas  is  off-screen  to  the  right.
                     These are the same values passed to  scroll-
                     bars via the -xscrollcommand option.

              pathName xview moveto fraction
                     Adjusts the view in the window so that frac-
                     tion 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 win-
                     dow's width otherwise.   If  what  is  pages
                     then  the  view  adjusts  in  units of nine-



Tk                             4.0                             17





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


                     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 verti-
              cal  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 -scrollre-
                     gion  option)  is  visible  in  the  window.
                     These  are the same values passed to scroll-
                     bars via the -yscrollcommand option.

              pathName yview moveto fraction
                     Adjusts the view in the window so that frac-
                     tion  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 win-
                     dow'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 character-
       ized  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  don't  support  indexing  or selection or the



Tk                             4.0                             18





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


       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,  only  text  items
       provide this support).


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

       The arguments x1, y1, x2, and y2 give the  coordinates  of
       two  diagonally  opposite  corners of a rectangular region
       enclosing the oval that defines the arc.  After the  coor-
       dinates  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 config-
       uration.  The following 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  nega-
              tive.  If it is greater than 360 or less than -360,
              then degrees modulo 360 is used as the extent.

       -fill color
              Fill the region of the arc with color.   Color  may
              have  any of the forms accepted by Tk_GetColor.  If
              color is an empty string (the default),  then  then
              the arc will not be filled.

       -outline color
              Color  specifies  a  color  to  use for drawing the
              arc's outline;   it  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 arc.

       -outlinestipple bitmap
              Indicates  that  the  outline for the arc should be
              drawn with a stipple pattern; bitmap specifies  the
              stipple  pattern  to  use,  in  any  of  the  forms
              accepted by Tk_GetBitmap.  If the  -outline  option
              hasn't  been  specified  then  this  option  has no
              effect.   If  bitmap  is  an  empty   string   (the
              default),  then  the  outline  is  drawn in a solid



Tk                             4.0                             19





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


              fashion.

       -start degrees
              Specifies the beginning of the angular range  occu-
              pied  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.

       -stipple bitmap
              Indicates that the arc should be filled in a  stip-
              ple  pattern;  bitmap specifies the stipple pattern
              to  use,  in  any  of   the   forms   accepted   by
              Tk_GetBitmap.   If  the  -fill  option  hasn't been
              specified then  this  option  has  no  effect.   If
              bitmap is an empty string (the default), then fill-
              ing is done in a solid fashion.

       -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  seg-
              ments,  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 sec-
              tion.  If type is arc then the  arc's  region  con-
              sists of a section of the perimeter alone.  In this
              last case the -fill option is ignored.

       -tags tagList
              Specifies a set of  tags  to  apply  to  the  item.
              TagList  consists  of  a  list  of tag names, which
              replace any existing tags for  the  item.   TagList
              may be an empty list.

       -width outlineWidth
              Specifies  the  width  of  the  outline to be drawn
              around the  arc's  region,  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.  Wide out-
              lines will be drawn centered on the  edges  of  the
              arc's region.  This option defaults to 1.0.


BITMAP ITEMS
       Items  of type bitmap appear on the display as images with
       two colors, foreground and background.  Bitmaps  are  cre-
       ated with widget commands of the following form:

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




Tk                             4.0                             20





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


       The  arguments  x and y 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.  The  follow-
       ing 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
              Specifies a color to use for  each  of  the  bitmap
              pixels whose value is 0.  Color may have any of the
              forms accepted  by  Tk_GetColor.   If  this  option
              isn't  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
              Specifies  the  bitmap  to  display  in  the  item.
              Bitmap  may  have  any  of  the  forms  accepted by
              Tk_GetBitmap.

       -foreground color
              Specifies a color to use for  each  of  the  bitmap
              pixels whose value is 1.  Color may have any of the
              forms  accepted  by  Tk_GetColor  and  defaults  to
              black.

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


IMAGE ITEMS
       Items of type image are used to display images on  a  can-
       vas.   Images are created with widget commands of the fol-
       lowing form:

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

       The arguments x and y specify the coordinates of  a  point



Tk                             4.0                             21





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


       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.   The
       following options are supported for images:

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

       -image name
              Specifies the name of the image to display  in  the
              item.  This image must have been created previously
              with the image create command.

       -tags tagList
              Specifies a set of  tags  to  apply  to  the  item.
              TagList  consists  of  a  list  of tag names, which
              replace any existing tags for the item;  it may  be
              an empty list.


LINE ITEMS
       Items  of  type  line appear on the display as one or more
       connected line segments or curves.  Lines are created with
       widget commands of the following form:

              pathName create line x1 y1... xn yn ?option value option value ...?

       The  arguments  x1  through  yn 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.  The follow-
       ing 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.



Tk                             4.0                             22





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


       -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  isn't  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, pro-
              jecting, or round).  If this option isn't specified
              then  it  defaults  to  butt.  Where arrowheads are
              drawn the cap style is ignored.

       -fill color
              Color specifies a color  to  use  for  drawing  the
              line;  it  may  have any of the forms acceptable to
              Tk_GetColor.  It may also be an  empty  string,  in
              which  case  the  line  will  be transparent.  This
              option defaults to black.

       -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 isn't specified then it
              defaults to miter.  If the line only  contains  two
              points then this option is irrelevant.

       -smooth boolean
              Boolean  must  have  one  of  the forms accepted by
              Tk_GetBoolean.  It indicates  whether  or  not  the
              line  should  be drawn as a curve.  If so, the line
              is rendered as a set of Bezier 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 seg-
              ment.

       -splinesteps number
              Specifies  the  degree  of  smoothness  desired for
              curves:  each spline will be approximated with num-
              ber  line  segments.  This option is ignored unless
              the -smooth option is true.




Tk                             4.0                             23





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


       -stipple bitmap
              Indicates that the line should be filled in a stip-
              ple  pattern;  bitmap specifies the stipple pattern
              to  use,  in  any  of   the   forms   accepted   by
              Tk_GetBitmap.   If  bitmap  is an empty string (the
              default), then filling is done in a solid  fashion.

       -tags tagList
              Specifies  a  set  of  tags  to  apply to the item.
              TagList consists of a  list  of  tag  names,  which
              replace  any  existing  tags for the item.  TagList
              may be an empty list.

       -width lineWidth
              LineWidth specifies the width of the line,  in  any
              of  the  forms described in the COORDINATES section
              above.  Wide lines will be drawn  centered  on  the
              path specified by the points.  If this option isn't
              specified then it defaults to 1.0.


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  fol-
       lowing form:

              pathName create oval x1 y1 x2 y2 ?option value option value ...?

       The  arguments  x1, y1, x2, and y2 give the coordinates of
       two diagonally opposite corners of  a  rectangular  region
       enclosing  the  oval.   The  oval will include the top and
       left edges of the rectangle not the lower or right  edges.
       If  the region is square then the resulting oval is circu-
       lar; otherwise it is elongated in shape.  After the  coor-
       dinates  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 config-
       uration.  The following options are supported for ovals:

       -fill color
              Fill  the  area  of the oval with color.  Color may
              have any of the forms accepted by Tk_GetColor.   If
              color  is  an empty string (the default), then then
              the oval will not be filled.

       -outline color
              Color specifies a color  to  use  for  drawing  the
              oval's  outline;   it  may  have  any  of the forms
              accepted by Tk_GetColor.  This option  defaults  to
              black.  If color is an empty string then no outline
              will be drawn for the oval.




Tk                             4.0                             24





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


       -stipple bitmap
              Indicates that the oval should be filled in a stip-
              ple  pattern;  bitmap specifies the stipple pattern
              to  use,  in  any  of   the   forms   accepted   by
              Tk_GetBitmap.   If  the  -fill  option  hasn't been
              specified then  this  option  has  no  effect.   If
              bitmap is an empty string (the default), then fill-
              ing is done in a solid fashion.

       -tags tagList
              Specifies a set of  tags  to  apply  to  the  item.
              TagList  consists  of  a  list  of tag names, which
              replace any existing tags for  the  item.   TagList
              may be an empty list.

       -width outlineWidth
              outlineWidth  specifies the width of the outline to
              be drawn around the  oval,  in  any  of  the  forms
              described in the COORDINATES section above.  If the
              -outline option hasn't  been  specified  then  this
              option has no effect.  Wide outlines are drawn cen-
              tered on the oval path defined by x1, y1,  x2,  and
              y2.  This option defaults to 1.0.


POLYGON ITEMS
       Items of type polygon appear as polygonal or curved filled
       regions on the display.  Polygons are created with  widget
       commands of the following form:

              pathName create polygon x1 y1 ... xn yn ?option value option value ...?

       The  arguments  x1  through yn specify the coordinates for
       three or more points that define a  closed  polygon.   The
       first  and  last points may be the same;  whether they are
       or not, Tk will draw the  polygon  as  a  closed  polygon.
       After   the   coordinates  there  may  be  any  number  of
       option-value pairs, each of which sets one of the configu-
       ration  options  for  the  item.   These same option-value
       pairs may be used  in  itemconfigure  widget  commands  to
       change  the  item's  configuration.  The following options
       are supported for polygons:

       -fill color
              Color specifies a color to use for filling the area
              of  the  polygon;  it  may  have  any  of the forms
              acceptable to Tk_GetColor.  If color  is  an  empty
              string  then the polygon will be transparent.  This
              option defaults to black.

       -outline color
              Color specifies a color  to  use  for  drawing  the
              polygon's  outline;   it  may have any of the forms
              accepted by Tk_GetColor.   If  color  is  an  empty



Tk                             4.0                             25





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


              string  then no outline will be drawn for the poly-
              gon.  This option defaults to empty (no outline).

       -smooth boolean
              Boolean must have one  of  the  forms  accepted  by
              Tk_GetBoolean It indicates whether or not the poly-
              gon should be drawn with a  curved  perimeter.   If
              so,  the  outline  of  the polygon becomes a set of
              Bezier splines, one spline for the first and second
              line segments, one for the second and third, and so
              on.  Straight-line segments can be generated  in  a
              smoothed  polygon  by duplicating the end-points of
              the desired line segment.

       -splinesteps number
              Specifies the  degree  of  smoothness  desired  for
              curves:  each spline will be approximated with num-
              ber line segments.  This option is  ignored  unless
              the -smooth option is true.

       -stipple bitmap
              Indicates  that  the  polygon should be filled in a
              stipple pattern; bitmap specifies the stipple  pat-
              tern  to  use,  in  any  of  the  forms accepted by
              Tk_GetBitmap.  If bitmap is an  empty  string  (the
              default),  then filling is done in a solid fashion.

       -tags tagList
              Specifies a set of  tags  to  apply  to  the  item.
              TagList  consists  of  a  list  of tag names, which
              replace any existing tags for  the  item.   TagList
              may be an empty list.

       -width outlineWidth
              OutlineWidth  specifies the width of the outline to
              be drawn around the polygon, in any  of  the  forms
              described in the COORDINATES section above.  If the
              -outline option hasn't  been  specified  then  this
              option has no effect.  This option defaults to 1.0.

       Polygon items are different from other items such as rect-
       angles, ovals and arcs in that interior points are consid-
       ered to be ``inside'' a polygon 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



Tk                             4.0                             26





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


       the following form:

              pathName create rectangle x1 y1 x2 y2 ?option value option value ...?

       The arguments x1, y1, x2, and y2 give the  coordinates  of
       two  diagonally  opposite  corners  of  the rectangle (the
       rectangle will include its upper and left  edges  but  not
       its  lower  or  right edges).  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  wid-
       get commands to change the item's configuration.  The fol-
       lowing options are supported for rectangles:

       -fill color
              Fill the area of the rectangle  with  color,  which
              may  be  specified  in any of the forms accepted by
              Tk_GetColor.  If color  is  an  empty  string  (the
              default), then the rectangle will not be filled.

       -outline color
              Draw an outline around the edge of the rectangle in
              color.  Color may have any of the forms accepted by
              Tk_GetColor.   This  option  defaults to black.  If
              color is an empty string then no  outline  will  be
              drawn for the rectangle.

       -stipple bitmap
              Indicates  that the rectangle should be filled in a
              stipple pattern; bitmap specifies the stipple  pat-
              tern  to  use,  in  any  of  the  forms accepted by
              Tk_GetBitmap.  If  the  -fill  option  hasn't  been
              specified  then  this  option  has  no  effect.  If
              bitmap is an empty string (the default), then fill-
              ing is done in a solid fashion.

       -tags tagList
              Specifies  a  set  of  tags  to  apply to the item.
              TagList consists of a  list  of  tag  names,  which
              replace  any  existing  tags for the item.  TagList
              may be an empty list.

       -width outlineWidth
              OutlineWidth specifies the width of the outline  to
              be  drawn around the rectangle, in any of the forms
              described in the COORDINATES section above.  If the
              -outline  option  hasn't  been  specified then this
              option has no effect.  Wide outlines are drawn cen-
              tered  on  the  rectangular path defined by x1, y1,
              x2, and y2.  This option defaults to 1.0.


TEXT ITEMS
       A text item displays a string of characters on the  screen



Tk                             4.0                             27





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


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

       The  arguments  x and y 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 configu-
       ration options for  the  item.   These  same  option-value
       pairs  may  be  used  in  itemconfigure widget commands to
       change the item's configuration.   The  following  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.

       -fill color
              Color specifies a color to use for filling the text
              characters; it may have any of the  forms  accepted
              by  Tk_GetColor.   If  this  option isn't specified
              then it defaults to black.

       -font fontName
              Specifies the font to use for the text item.  Font-
              Name    may    be    any   string   acceptable   to
              Tk_GetFontStruct.  If this option isn't  specified,
              it defaults to a system-dependent font.

       -justify how
              Specifies how to justify the text within its bound-
              ing 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.

       -stipple bitmap
              Indicates  that the text should be drawn in a stip-
              pled pattern rather than  solid;  bitmap  specifies
              the  stipple  pattern  to  use, in any of the forms
              accepted by Tk_GetBitmap.  If bitmap  is  an  empty
              string  (the  default)  then the text is drawn in a



Tk                             4.0                             28





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


              solid fashion.

       -tags tagList
              Specifies a set of  tags  to  apply  to  the  item.
              TagList  consists  of  a  list  of tag names, which
              replace any existing tags for  the  item.   TagList
              may be an empty list.

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

       -width lineLength
              Specifies  a  maximum  line length for the text, in
              any of the forms described in the COORDINATES  sec-
              tion  above.   If this option is zero (the default)
              the text is broken into lines only at newline char-
              acters.   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 dis-
       played 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 ...?

       The  arguments  x and y 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.  The  follow-
       ing 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.




Tk                             4.0                             29





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


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

       -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 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  isn't
              specified,  or  if  it  is  specified  as  an empty
              string, 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.


APPLICATION-DEFINED ITEM TYPES
       It  is  possible for individual applications to define new
       item types for canvas widgets using C code.  See the docu-
       mentation for Tk_CreateItemType.


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


KEYWORDS
       canvas, widget
