


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


NAME
       canvas - Create and manipulate canvas widgets

SYNOPSIS
       (canvas                      widget-name                     ?options?)
       :background    :highlightthickness :insertwidth   :takefocus
       :borderwidth   :insertbackground   :relief   :xscrollcommand
       :cursor   :insertborderwidth  :selectbackground   :yscrollcommand
       :highlightbackground     :insertofftime :selectborderwidth
       :highlightcolor     :insertontime  :selectforeground

WIDGET-SPECIFIC OPTIONS
       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.  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.  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.  Specifies a list with four
       coordinates  describing the left, top, right, and bottom coordinates of
       a rectangular region.  This region is used for scrolling  purposes  and
       is  considered  to  be  the  boundary of the information in the canvas.
       Each of the coordinates may be specified in any of the forms  given  in
       the  COORDINATES  section below.  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 sec-
       tion below.
       Specifies an increment for horizontal scrolling, in any  of  the  usual
       forms  permitted  for screen distances.  If the value of this option is
       greater than zero, the horizontal view  in  the  window  will  be  con-
       strained so that the canvas x coordinate at the left edge of the window
       is always an even multiple of xScrollIncrement;  furthermore, the units
       for  scrolling (e.g., the change in view when the left and right arrows
       of a scrollbar are selected) will also  be  xScrollIncrement.   If  the
       value  of  this  option  is less than or equal to zero, then horizontal
       scrolling  is  unconstrained.   Specifies  an  increment  for  vertical
       scrolling,  in  any  of the usual forms permitted for screen distances.
       If the value of this option is greater than zero, the vertical view  in
       the  window  will be constrained so that the canvas y coordinate at the
       top edge of the window is always an even multiple of  yScrollIncrement;
       furthermore, the units for scrolling (e.g., the change in view when the
       top and bottom arrows  of  a  scrollbar  are  selected)  will  also  be
       yScrollIncrement.  If the value of this option is less than or equal to
       zero, then vertical scrolling is unconstrained.


INTRODUCTION
       The canvas procedure creates a new window  (given  by  the  widget-name
       argument)  and  makes  it  into  a  canvas widget.  Additional options,
       described above, may be specified on  the  procedure  line  or  in  the
       option  database  to configure aspects of the canvas such as its colors
       and 3-D relief.  The canvas procedure returns its widget-name argument.



STk                            4.0                              1





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


       At  the  time  this procedure is invoked, there must not exist a window
       named widget-name, but widget-name'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 pro-
       cedures may be associated with items in much the same way that the bind
       procedure allows procedures to be bound to  widgets.   For  example,  a
       particular  procedure  may  be  associated with the <Button-1> event so
       that the procedure is invoked whenever button 1  is  pressed  with  the
       mouse  cursor over an item.  This means that items in a canvas can have
       behaviors defined by the STk 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 every-
       thing else.  Widget procedures 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 and  lower  Tk  com-
       mands instead.


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

       Each item may also have any number of tags associated with it.   A  tag
       is just a string of characters, and it may take any form except that of
       an integer.  For example, ``x123'' is OK but ``123'' 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  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 the canvas widget  or
       is not over an item, then no item has the current tag.

       When  specifying items in canvas widget procedures, if the specifier is
       an integer then it is assumed to refer to the single item with that id.



STk                            4.0                              2





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


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


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


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 procedures;  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 procedures
       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 procedures such as
       inserting text, deleting a range of characters, and setting the  inser-
       tion  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  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 the  text
       item;   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



STk                            4.0                              3





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


                 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  cur-
                 sor 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 coordinate system of the canvas.
                 If  x  and  y lie outside the coordinates covered by the text
                 item, then they refer to the first or last character  in  the
                 line that is closest to the given point.


WIDGET PROCEDURE
       The  canvas  procedure  creates  a new STk procedure whose name is wid-
       get-name.  This procedure may be used to invoke various  operations  on
       the  widget.   It  has  the following general form: (widget-name option
       ?arg arg ...?)  Option and the args determine the exact behavior of the
       procedure.   The  following  widget  procedures are possible for canvas
       widgets:

       (widget-name '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 procedure has no effect.  This  pro-
              cedure  returns  an  empty list 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.



STk                            4.0                              4





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


                     If  more  than  one  item is at the same closest distance
                     (e.g. two items overlap the point), then the top-most  of
                     these  items  (the last one in the display list) is used.
                     If halo is specified, then  it  must  be  a  non-negative
                     value.  Any item closer than halo to the point is 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  by
                     tag,  it  selects the first item in the display list with
                     the given tag).  Instead of selecting the topmost closest
                     item, this form will select the topmost closest item that
                     is below start in the display  list;   if  no  such  item
                     exists,  then the selection behaves as if the start 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.

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

       (widget-name 'bind tagOrId ?sequence? ?procedure?)
              This procedure associates procedure with all the items given  by
              tagOrId  such that whenever the event sequence given by sequence
              occurs for one of the items the procedure will be invoked.  This
              widget procedure is similar to the bind procedure except that it
              operates on items in a canvas rather than entire  widgets.   See
              the  bind  manual  entry  for  complete details on the syntax of
              sequence and the substitutions  performed  on  procedure  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 procedure is ``+'' then
              procedure augments an existing  binding  rather  than  replacing
              it).  In this case the return value is an empty list.  If proce-
              dure  is  omitted  then  the  procedure  returns  the  procedure



STk                            4.0                              5





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


              associated  with  tagOrId and sequence (an error occurs if there
              is no such binding).  If both procedure and sequence are omitted
              then the procedure returns a list of all the sequences for which
              bindings have been defined for tagOrId.

              Example: (pack (canvas '.c))
                          (define item (.c 'create 'rectangle 0 0 10 10))
                          (.c 'bind item  "<Enter>"  (lambda()  (display  "You
              enter0)))


              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 events.  The handling of
              events in canvases uses the current item defined in ITEM IDS AND
              TAGS  above.  Enter and Leave events trigger for an item when it
              becomes the current item or ceases to be the current item;  note
              that  these events are different than Enter and Leave events for
              windows.  Mouse-related events are directed to the current item,
              if any.  Keyboard-related events are directed to the focus item,
              if any (see the focus widget command below for  more  on  this).
              If  a virtual event is used in a binding, that binding can trig-
              ger only if the virtual event is defined by an underlying mouse-
              related or keyboard-related event.

              It  is  possible  for  multiple  bindings  to match a particular
              event.  This could occur, for example, if one binding is 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
              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.   If a binding script
              returns the symbol break, remaining scripts for  the  event  are
              skipped, just as for the bind procedure.


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


       (widget-name 'canvasx screenx)

       (widget-name 'canvasx screenx gridspacing)
              Given  a window x-coordinate in 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.





STk                            4.0                              6





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


       (widget-name 'canvasy screeny)

       (widget-name 'canvasy screeny gridspacing)
              Given a window y-coordinate in 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.

       (widget-name '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 procedure.

       (widget-name '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 widget-name (see Tk_ConfigureInfo for informa-
              tion on the format of this list).  If option is  specified  with
              no  value,  then the procedure 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 procedure
              modifies  the given widget option(s) to have the given value(s);
              in this case the procedure returns an empty  list.   Option  may
              have any of the values accepted by the canvas procedure.

       (widget-name 'coords tagOrId ?x0 y0 ...?)
              Query  or  modify  the  coordinates  that define an item.  If no
              coordinates are specified, this procedure returns a  list  whose
              elements  are  the coordinates of the item named by tagOrId.  If
              coordinates are specified, then they replace the current coordi-
              nates  for the named item.  If tagOrId refers to multiple items,
              then the first one in the display list is used.

       (widget-name 'create type x y ?x y ...? ?option value ...?)
              Create a new item in widget-name 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 subsec-
              tions on individual item types below for more on the  syntax  of
              this procedure.  This procedure returns the id for the new item.

       (widget-name 'dchars tagOrId first )

       (widget-name 'dchars tagOrId first last)
              For each item given by tagOrId, delete  the  characters  in  the
              range  given by first and last, inclusive.  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 procedure returns an empty list.

       (widget-name 'delete ?tagOrId tagOrId ...?)
              Delete  each  of  the items given by each tagOrId, and return an



STk                            4.0                              7





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


              empty list.

       (widget-name 'dtag tagOrId )

       (widget-name '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  procedure.   If  tagToDelete is omitted then it
              defaults to tagOrId.  This procedure returns an empty list.

       (widget-name 'find searchProcedure ?arg arg ...?)
              This procedure returns a list consisting of all the  items  that
              meet  the  constraints  specified  by searchProcedure and arg's.
              SearchProcedure and args have any of the forms accepted  by  the
              addtag  procedure.   The  items  are returned in stacking order,
              with the lowest item first.

       (widget-name 'focus )

       (widget-name 'focus tagOrId)
              Set the keyboard focus for the canvas widget to the  item  given
              by  tagOrId.  If tagOrId refers to several items, then the focus
              is set to the first such item in the display list that  supports
              the insertion cursor.  If tagOrId 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  procedure returns the id for the item that
              currently has the focus, or an empty list 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 procedure) are  totally  inde-
              pendent:  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 procedure with the  focus  option  to
              set the focus window to the canvas (if it wasn't there already).


       (widget-name 'gettags tagOrId)
              Return a list whose elements are the tags  associated  with  the
              item given by tagOrId.  If tagOrId refers to more than one item,
              then the tags are returned from the first such item in the  dis-
              play  list.   If  tagOrId  doesn't refer to any items, or if the
              item contains no tags, then an empty list is returned.

       (widget-name '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



STk                            4.0                              8





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


              support an insertion cursor then this procedure 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 wid-
              get  procedure focus, below), but the cursor position may be set
              even when the item  doesn't  have  the  focus.   This  procedure
              returns an empty list.

       (widget-name 'index tagOrId index)
              This  procedure  returns  a  decimal string giving the numerical
              index within tagOrId corresponding to index.  Index gives a tex-
              tual description of the desired position as described in INDICES
              above.  The return value is guaranteed to lie between 0 and  the
              number  of  characters  within  the item, inclusive.  If tagOrId
              refers to multiple items, then the index  is  processed  in  the
              first  of these items that supports indexing operations (in dis-
              play list order).

       (widget-name '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 procedure returns an empty list.

       (widget-name 'itemcget tagOrId option)
              Returns the current value of the configuration  option  for  the
              item  given  by tagOrId whose name is option.  This procedure is
              similar to the cget widget procedure 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  procedure
              when  the  item was created.  If tagOrId is a tag that refers to
              more than one item, the first (lowest) such item is used.

       (widget-name 'itemconfigure tagOrId ?option? ?value? ?option value
       ...?)
              This  procedure  is  similar  to  the configure widget procedure
              except that it modifies  item-specific  options  for  the  items
              given  by  tagOrId  instead of modifying options for the overall
              canvas widget.  If  no  option  is  specified,  returns  a  list
              describing all of the available options for the first item given
              by tagOrId (see Tk_ConfigureInfo for information on  the  format
              of  this  list).  If option is specified with no value, then the
              procedure 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 procedure modifies
              the given widget option(s) to have the given value(s) in each of
              the  items given by tagOrId;  in this case the procedure returns
              an empty list.  The options and values are  the  same  as  those
              permissible in the create widget procedure when the item(s) were
              created; see the sections describing individual item types below
              for details on the legal options.




STk                            4.0                              9





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


       (widget-name 'lower tagOrId )

       (widget-name 'lower tagOrId belowThis)
              Move  all of the items given by tagOrId to a new position in the
              display list just  before  the  item  given  by  belowThis.   If
              tagOrId  refers to more than one item then all are moved but the
              relative  order  of  the  moved  items  will  not  be   changed.
              BelowThis  is  a  tag or id;  if it refers to more than one item
              then the first (lowest) of these items in the  display  list  is
              used  as  the  destination  location for the moved items.  Note:
              this procedure has no effect  on  window  items.   Window  items
              always  obscure other item types, and the stacking order of win-
              dow items is determined by the raise and lower commands, not the
              raise  and  lower  widget commands for canvases.  This procedure
              returns an empty list.

       (widget-name 'move tagOrId xAmount yAmount)
              Move each of the items given by tagOrId in the canvas coordinate
              space  by adding xAmount to the x-coordinate of each point asso-
              ciated with the item and yAmount to  the  y-coordinate  of  each
              point associated with the item.  This procedure returns an empty
              list.

       (widget-name '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 and an empty list is returned;  otherwise  the
              Postscript  is  returned  as  the  result of the procedure.  The
              Postscript is created in Encapsulated Postscript form using ver-
              sion  3.0  of  the  Document  Structuring Conventions.  Note: by
              default  Postscript  is  only  generated  for  information  that
              appears  in the canvas's window on the screen.  If the canvas is
              freshly created it may still have its initial size of 1x1  pixel
              so  nothing  will  appear in the Postscript.  To get around this
              problem either invoke the "update" procedure  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
                     NOT IMPLEMENTED IN STk

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

              :file fileName
                     Specifies the name of the file  in  which  to  write  the
                     Postscript.   If  this  option  isn't  specified then the
                     Postscript is returned as the  result  of  the  procedure



STk                            4.0                             10





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


                     instead of being written to a file.

              :fontmap varName
                     NOT IMPLEMENTED IN STk

              :height size
                     Specifies  the height of the area of the canvas to print.
                     Defaults to the height of the canvas window.

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

              :pageheight size
                     Specifies that the Postscript should be scaled in both  x
                     and  y  so  that  the  printed  area  is size high on the
                     Postscript page.  Size consists of a floating-point  num-
                     ber  followed  by  c for centimeters, i for inches, m for
                     millimeters, or p or nothing for printer's  points  (1/72
                     inch).  Defaults to the height of the printed area on the
                     screen.  If both :pageheight and :pagewidth are specified
                     then  the scale factor from :pagewidth  is used (non-uni-
                     form scaling is not implemented).

              :pagewidth size
                     Specifies that the Postscript should be scaled in both  x
                     and  y  so  that  the  printed  area  is size wide on the
                     Postscript page.  Size has the same form  as  for  :page-
                     height.  Defaults to the width of the printed area on the
                     screen.  If both :pageheight and :pagewidth are specified
                     then  the scale factor from  :pagewidth is used (non-uni-
                     form scaling is not implemented).

              :pagex position
                     Position gives the x-coordinate of the positioning  point
                     on  the  Postscript  page, using any of the forms allowed
                     for :pageheight.  Used in conjunction with the :pagey and
                     :pageanchor  options  to determine where the printed area
                     appears on the Postscript page.  Defaults to  the  center
                     of the page.

              :pagey position
                     Position  gives the y-coordinate of the positioning point
                     on the Postscript page, using any of  the  forms  allowed
                     for :pageheight.  Used in conjunction with the :pagex and
                     :pageanchor options to determine where the  printed  area
                     appears  on  the Postscript page.  Defaults to the center
                     of the page.




STk                            4.0                             11





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


              :rotate boolean
                     Boolean specifies whether  the  printed  area  is  to  be
                     rotated  90 degrees.  In non-rotated output the x-axis of
                     the printed area runs along the short  dimension  of  the
                     page (``portrait'' orientation); in rotated output the x-
                     axis runs along the long dimension of the  page  (``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 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 canvas  coordinates,
                     not  window  coordinates.   Defaults to the coordinate of
                     the top edge of the window.

       (widget-name 'raise tagOrId )

       (widget-name 'raise tagOrId aboveThis)
              Move all of the items given by tagOrId to a new position in  the
              display list just after the item given by aboveThis.  If tagOrId
              refers to more than one item then all are moved but the relative
              order  of  the  moved items will not be changed.  AboveThis is a
              tag or id;  if it refers to more than one  item  then  the  last
              (topmost) of these items in the display list is used as the des-
              tination location for the moved items.  Note: this procedure has
              no  effect  on  window items.  Window items always obscure other
              item types, and the stacking order of window items is determined
              by  the raise and lower commands, not the raise and lower widget
              commands for canvases.  This procedure returns an empty list.

       (widget-name '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 procedure returns an empty list.

       (widget-name 'scan option args)
              This procedure is used to implement scanning  on  canvases.   It
              has two forms, depending on option:




STk                            4.0                             12





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


              (widget-name 'scan 'mark x y)
                     Records  x  and y and the canvas's current view;  used in
                     conjunction with later scan dragto procedures.  Typically
                     this procedure is associated with a mouse button press in
                     the widget and x and y are the coordinates of the  mouse.
                     It returns an empty list.

              (widget-name 'scan 'dragto x y)
                     This  procedure 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 procedure for
                     the widget.  It then adjusts the view  by  10  times  the
                     difference  in  coordinates.  This procedure is typically
                     associated with mouse motion events  in  the  widget,  to
                     produce  the  effect of dragging the canvas at high speed
                     through its window.  The return value is an empty list.

       (widget-name 'select option ?tagOrId arg?)
              Manipulates the selection in one of several ways,  depending  on
              option.   The  procedure  may  take  any  of the forms described
              below.  In all of the descriptions below, tagOrId must refer  to
              an  item  that supports indexing and selection;  if it refers to
              multiple items then the first of these  that  supports  indexing
              and the selection is used.  Index gives a textual description of
              a position within tagOrId, as described in INDICES above.

              (widget-name '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 procedures.  If the
                     selection  isn't currently in tagOrId then this procedure
                     behaves the same  as  the  select  to  widget  procedure.
                     Returns an empty list.

              (widget-name 'select 'clear)
                     Clear  the  selection  if  it  is in this widget.  If the
                     selection isn't in this widget then the procedure has  no
                     effect.  Returns an empty list.

              (widget-name 'select 'from tagOrId index)
                     Set  the selection anchor point for the widget to be just
                     before the character given by index in the item given  by
                     tagOrId.   This  procedure  doesn't change the selection;
                     it just sets the fixed end of the  selection  for  future
                     select to procedures.  Returns an empty list.

              (widget-name '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 list is returned.





STk                            4.0                             13





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


              (widget-name 'select 'to tagOrId index)
                     Set  the  selection  to  consist  of  those characters of
                     tagOrId between the selection  anchor  point  and  index.
                     The  new  selection  will  include the character given by
                     index; it will include the character given by the  anchor
                     point  only  if  index  is  greater  than or equal to the
                     anchor point.  The anchor point is determined by the most
                     recent  select  adjust  or select from procedure 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 list.

       (widget-name '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 list is
              returned.

       (widget-name 'xview  ?args?)
              This procedure is used to query and change the horizontal  posi-
              tion  of  the  information displayed in the canvas's window.  It
              can take any of the following forms:

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

              (widget-name 'xview 'moveto fraction)
                     Adjusts the view in the window so that  fraction  of  the
                     total  width  of  the  canvas  is off-screen to the left.
                     Fraction must be a fraction between 0 and 1.

              (widget-name 'xview 'scroll number what)
                     This procedure 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 abbre-
                     viation  of  one  of  these.   If what is units, the view
                     adjusts left or right in units  of  the  xScrollIncrement
                     option,  if  it is greater than zero, or in units of one-
                     tenth the window's width otherwise.   If  what  is  pages
                     then  the  view  adjusts in units of nine-tenths the win-
                     dow's width.  If number is negative then information far-
                     ther to the left becomes visible;  if it is positive then
                     information farther to the right becomes visible.





STk                            4.0                             14





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


       (widget-name 'yview ?args?)
              This procedure is used to query and change the vertical position
              of  the  information  displayed  in the canvas's window.  It can
              take any of the following forms:

              (widget-name '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 ele-
                     ment is 1.0, the lowest 40%  of  the  canvas's  area  (as
                     defined  by  the  :scrollregion option) is visible in the
                     window.  These are the same values passed  to  scrollbars
                     via the :yscrollcommand option.

              (widget-name 'yview 'moveto fraction)
                     Adjusts  the  view  in the window so that fraction of the
                     canvas's area is off-screen to the top.   Fraction  is  a
                     fraction between 0 and 1.

              (widget-name 'yview 'scroll number what)
                     This  procedure 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 yScrollIncre-
                     ment  option,  if it is greater than zero, or in units of
                     one-tenth the window's  height  otherwise.   If  what  is
                     pages  then  the view adjusts in units of nine-tenths the
                     window's height.   If  number  is  negative  then  higher
                     information  becomes  visible;   if  it  is positive then
                     lower information becomes visible.


OVERVIEW OF ITEM TYPES
       The sections below describe the various types  of  items  supported  by
       canvas  widgets.  Each item type is characterized by two things: first,
       the form of the create procedure 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  procedures.
       Most  items  don't  support  indexing  or  selection  or the procedures
       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 (spec-
       ified  by  the :style option).  Arcs are created with widget procedures
       of the following form: (widget-name '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 coordinates there



STk                            4.0                             15





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


       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 procedures 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 negative.  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 fashion.

       :start degrees
              Specifies  the  beginning  of  the angular range occupied by the
              arc.  Degrees is given in units  of  degrees  measured  counter-
              clockwise  from  the 3-o'clock position;  it may be either posi-
              tive or negative.

       :stipple bitmap
              Indicates that the arc should be filled in  a  stipple  pattern;
              bitmap specifies the stipple pattern to use, in 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 (the default), then filling 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 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.



STk                            4.0                             16





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


       :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 outlines will be
              drawn centered on the edges of the arc's  region.   This  option
              defaults to 1.0.


BITMAP ITEMS
       Items  of  type bitmap appear on the display as images with two colors,
       foreground and background.  Bitmaps are created with widget  procedures
       of  the  following form: (widget-name 'create 'bitmap x y ?option value
       option value ...?)  The arguments x and y specify the coordinates of  a
       point  used  to  position  the  bitmap  on the display (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 procedures to
       change the item's configuration.  The following options  are  supported
       for bitmaps:

       :anchor anchorPos
              AnchorPos tells how to position the bitmap relative to the posi-
              tioning 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_Get-
              Color.  If this option isn't specified, or if it is specified as
              an empty string, then nothing is displayed where the bitmap pix-
              els 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_Get-
              Color 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



STk                            4.0                             17





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


              item.  TagList may be an empty list.


IMAGE ITEMS
       Items of type image are used to display images on a canvas.  Images are
       created with widget procedures  of  the  following  form:  (widget-name
       'create  'image  x  y ?option value option value ...?)  The arguments x
       and y specify the coordinates of a point used to position the image  on
       the display (see the :anchor option below for more information).  After
       the coordinates there may be any number of option-value pairs, each  of
       which  sets  one of the configuration options for the item.  These same
       option-value pairs may be used in itemconfigure  widget  procedures  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  posi-
              tioning  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
              procedure.

       :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  procedures  of  the
       following form: (widget-name '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 itemconfig-
       ure  widget procedures 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.




STk                            4.0                             18





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


       :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  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 ``rea-
              sonable'' shape.

       :capstyle style
              Specifies the ways in 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.

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

       :stipple bitmap
              Indicates  that  the line should be filled in a stipple 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



STk                            4.0                             19





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


              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  procedures of the following form: (widget-name '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 circular; otherwise  it  is
       elongated  in  shape.  After the coordinates there may be any number of
       option-value pairs, each of which sets one of the configuration options
       for the item.  These same option-value pairs may be used in itemconfig-
       ure widget procedures to change the item's configuration.  The  follow-
       ing 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.

       :stipple bitmap
              Indicates that the oval should be filled in a  stipple  pattern;
              bitmap specifies the stipple pattern to use, in 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 (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  oval,  in any of the forms described in the COORDI-
              NATES section above.  If the :outline option hasn't been  speci-
              fied  then  this  option has no effect.  Wide outlines are drawn
              centered on the oval path defined by x1, y1, x2, and  y2.   This



STk                            4.0                             20





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


              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 procedures of  the  fol-
       lowing  form:  (widget-name  'create  'polygon  x1 y1 ... xn yn ?option
       value option value ...?)  The arguments x1 through yn specify the coor-
       dinates  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
       configuration  options for the item.  These same option-value pairs may
       be used in itemconfigure widget procedures to change the item's config-
       uration.  The following options are supported for polygons:

       :fill color
              Color specifies a color to use for filling the area of the poly-
              gon; 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  out-
              line;  it may have any of the forms accepted by Tk_GetColor.  If
              color is an empty string then no outline will be drawn  for  the
              polygon.  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 polygon  should  be  drawn  with  a
              curved  perimeter.   If so, the outline of the polygon becomes a
              set of parabolic splines, one spline for the  first  and  second
              line  segments,  one  for  the  second  and  third,  and  so on.
              Straight-line segments can be generated in a smoothed polygon by
              duplicating the end-points of the desired line segment.

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

       :stipple bitmap
              Indicates  that  the  polygon should be filled in a stipple pat-
              tern; 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.





STk                            4.0                             21





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


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

       Polygon items are different from other items such as rectangles,  ovals
       and  arcs  in  that  interior  points are considered to be ``inside'' a
       polygon (e.g. for purposes of the find  closest  and  find  overlapping
       widget  commands) even if it is not filled.  For most other item types,
       an interior point is considered to be inside the item only if the  item
       is  filled  or  if  it has neither a fill nor an outline.  If you would
       like an unfilled polygon whose interior points are not considered to be
       inside the polygon, use a line item instead.


RECTANGLE ITEMS
       Items  of  type rectangle appear as rectangular regions on the display.
       Each rectangle may have an outline, a fill, or  both.   Rectangles  are
       created  with  widget  procedures  of  the following form: (widget-name
       '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 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 itemconfigure  widget  procedures  to  change  the
       item's  configuration.  The following options are supported for rectan-
       gles:

       :fill color
              Fill the area of the rectangle with color, which may  be  speci-
              fied  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  pat-
              tern; bitmap specifies the stipple pattern to use, in any of the
              forms accepted by Tk_GetBitmap.  If the :fill option hasn't been
              specified then this option has no effect.  If bitmap is an empty
              string (the default), then filling is done in a solid fashion.

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



STk                            4.0                             22





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


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


TEXT ITEMS
       A  text  item  displays  a string of characters on the screen in one or
       more lines.  Text items support indexing and selection, along with  the
       following  text-related canvas widget procedures:  dchars, focus, icur-
       sor, index, insert, select.  Text items are created with widget  proce-
       dures  of  the  following  form: (widget-name '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  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 procedures 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 posi-
              tioning 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 position-
              ing 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.  FontName 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 bounding region.
              How must be one of the values  left,  right,  or  center.   This
              option  will  only  matter  if the text is displayed as multiple
              lines.  If the option is omitted, it defaults to left.

       :stipple bitmap
              Indicates that the text should be drawn in  a  stippled  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 solid



STk                            4.0                             23





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


              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
              procedures.  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  section  above.   If  this
              option  is zero (the default) the text is broken into lines only
              at newline characters.  However, if this option is non-zero then
              any  line  that  would  be longer than lineLength is broken just
              before a space character to make the  line  shorter  than  line-
              Length;   the space character is treated as if it were a newline
              character.


WINDOW ITEMS
       Items of type window cause a particular window to  be  displayed  at  a
       given  position  on  the  canvas.  Window items are created with widget
       procedures of the following form:  (widget-name  '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 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 itemconfigure  wid-
       get  procedures  to  change  the  item's  configuration.  The following
       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 anchorPos  is  center
              then  the  window  is  centered on the point;  if anchorPos is n
              then the window will be drawn so that its top center point is at
              the positioning point.  This option defaults to center.

       :height pixels
              Specifies the height to assign to the item's window.  Pixels may
              have any of the  forms  described  in  the  COORDINATES  section
              above.  If this option 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



STk                            4.0                             24





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


              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 widget-name
              Specifies  the  window  to associate with this item.  The window
              specified by widget-name must either be a child  of  the  canvas
              widget  or a child of some ancestor of the canvas widget.  Path-
              Name may not refer to a top-level window.

       Note:  due to restrictions in the ways that windows are managed, it  is
       not  possible  to draw other graphical items (such as lines and images)
       on top of window items.  A window item  always  obscures  any  graphics
       that overlap it, regardless of their order in the display list.



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 STk procedures 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  can-
       vases.















STk                            4.0                             25


