canvas man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

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

______________________________________________________________________________

NAME
       canvas - Create and manipulate canvas widgets

SYNOPSIS
       canvas pathName ?options?

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

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

WIDGET-SPECIFIC OPTIONS
       [-closeenough closeEnough]  Specifies a floating-point value indicating
       how close the mouse cursor must be to an item before it	is  considered
       to be ``inside'' the item.  Defaults to 1.0.  [-confine confine] Speci‐
       fies a boolean value that indicates whether or not it should be	allow‐
       able to set the canvas's view outside the region defined by the scroll‐
       Region argument.	 Defaults to true, which means that the view  will  be
       constrained  within  the	 scroll	 region.  [-height height] Specifies a
       desired window height that the canvas widget should  request  from  its
       geometry	 manager.   The	 value	may  be	 specified in any of the forms
       described in the COORDINATES section  below.   [-scrollregion scrollRe‐
       gion]  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.
       [-width width] Specifies a desired window width that the canvas	widget
       should  request	from its geometry manager.  The value may be specified
       in any of the forms described in the COORDINATES section below.
       [-xscrollincrement xScrollIncrement] Specifies an increment  for	 hori‐
       zontal  scrolling,  in any of the usual forms permitted for screen dis‐
       tances.	If the value of this option is greater than zero, the horizon‐
       tal view in the window will be constrained so that the canvas x coordi‐
       nate 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	uncon‐
       strained.   [-yscrollincrement yScrollIncrement] Specifies an increment
       for vertical scrolling, in any of the usual forms permitted for	screen
       distances.   If the value of this option is greater than zero, the ver‐
       tical view in the window will be constrained so that the canvas y coor‐
       dinate  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 uncon‐
       strained.
_________________________________________________________________

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

       Canvas widgets implement structured graphics.  A	 canvas	 displays  any
       number  of  items, which may be things like rectangles, circles, lines,
       and text.  Items may be manipulated (e.g. moved or re-colored) and com‐
       mands  may  be associated with items in much the same way that the bind
       command allows commands to be bound to widgets.	For example, a partic‐
       ular  command  may  be associated with the <Button-1> event so that the
       command is invoked whenever button 1 is pressed with the	 mouse	cursor
       over  an	 item.	 This  means that items in 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 every‐
       thing else.  Widget commands may be used to re-arrange the order of the
       display list.

       Window  items are an exception to the above rules.  The underlying win‐
       dow systems require them always to be drawn on top of other items.   In
       addition,  the stacking order of window items is not affected by any of
       the canvas widget commands; you must use the raise 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 commands, if the specifier is an
       integer then it is assumed to refer to the single item  with  that  id.
       If  the specifier is not an integer, then it is assumed to refer to all
       of the items in the canvas that have a tag matching the specifier.  The
       symbol  tagOrId	is  used  below to indicate that an argument specifies
       either an id that selects a single item or a tag that selects  zero  or
       more  items.   Some  widget commands only operate on a single item at a
       time;  if tagOrId is specified in a way that names multiple items, then
       the  normal  behavior  is  for the command to use the first (lowest) of
       these items in the display list	that  is  suitable  for	 the  command.
       Exceptions are noted in the widget command descriptions below.

COORDINATES
       All  coordinates	 related to canvases are stored as floating-point 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 commands;   this  is
       typically used for scrolling.  Canvases do not support scaling or rota‐
       tion of the canvas coordinate system relative to the window  coordinate
       system.

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

INDICES
       Text items support the notion of an index  for  identifying  particular
       positions  within  the  item.   Indices	are  used for commands 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
		 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 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.  This command
	      returns  an  empty  string  as result.  SearchSpec and arg's may
	      take any of the following forms:

	      above tagOrId
		     Selects the item just after  (above)  the	one  given  by
		     tagOrId  in  the  display	list.  If tagOrId denotes more
		     than one item, then the last (topmost) of these items  in
		     the display list is used.

	      all    Selects all the items in the canvas.

	      below tagOrId
		     Selects  the  item	 just  before (below) the one given by
		     tagOrId in the display list.   If	tagOrId	 denotes  more
		     than  one item, then the first (lowest) of these items in
		     the display list is used.

	      closest x y ?halo? ?start?
		     Selects the item closest to the point given by x  and  y.
		     If	 more  than  one  item is at the same closest distance
		     (e.g. two items overlap the point), then the top-most  of
		     these  items  (the last one in the display list) is used.
		     If halo is specified, then	 it  must  be  a  non-negative
		     value.  Any item closer than halo to the point is 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 rec‐
		     tangular  region given by x1, y1, x2, and y2.  X1 must be
		     no greater then x2 and y1 must be no greater than y2.

	      overlapping x1 y1 x2 y2
		     Selects all the items that overlap or are enclosed within
		     the  rectangular  region given by x1, y1, x2, and y2.  X1
		     must be no greater then x2 and y1 must be no greater than
		     y2.

	      withtag tagOrId
		     Selects all the items given by tagOrId.

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

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

	      The  only	 events	 for which bindings may be specified are those │
	      related to the mouse and keyboard (such as Enter, Leave, Button‐ │
	      Press, Motion, and KeyPress) or virtual 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.  A continue command in a
	      binding script terminates that script, and a break command  ter‐
	      minates  that  script  and  skips	 any remaining scripts for the
	      event, just as for the bind 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 bind‐
	      ings  for	 items	will be invoked before any of the bindings for
	      the window as a whole.

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

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

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

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

       pathName coords tagOrId ?x0 y0 ...?
	      Query or modify the coordinates that  define  an	item.	If  no
	      coordinates  are	specified,  this  command returns a list whose
	      elements are the coordinates of the item named by	 tagOrId.   If
	      coordinates are specified, then they replace the current coordi‐
	      nates 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  con‐
	      sist  of	the  coordinates  for  one or more points, followed by
	      specifications for zero or more item options.  See  the  subsec‐
	      tions  on	 individual item types below for more on the syntax of
	      this command.  This command returns the id for the new item.

       pathName dchars tagOrId first ?last?
	      For each item given by tagOrId, delete  the  characters  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 command returns an empty string.

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

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

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

       pathName focus ?tagOrId?
	      Set the keyboard focus for the canvas widget to the  item	 given
	      by  tagOrId.  If tagOrId refers to several items, then the focus
	      is set to the first such item in the display list that  supports
	      the insertion cursor.  If tagOrId 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 cur‐
	      rently 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  indepen‐
	      dent:  a given item doesn't actually have the input focus unless
	      (a) its canvas is the focus window and (b) the item is the focus
	      item within the canvas.  In most cases it is advisable to follow
	      the focus widget command with the focus command to set the focus
	      window to the canvas (if it wasn't there already).

       pathName gettags tagOrId
	      Return  a	 list  whose elements are the tags associated with the
	      item given by tagOrId.  If tagOrId refers to more than one item,
	      then  the tags are returned from the first such item in the dis‐
	      play 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 character whose position is	 given
	      by  index.   If  some or all of the items given by tagOrId don't
	      support an insertion cursor then this command has no  effect  on
	      them.   See  INDICES  above for a description of the legal forms
	      for index.  Note:	 the insertion cursor is only displayed in  an
	      item if that item currently has the keyboard focus (see the wid‐
	      get 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 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).

       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 wid‐
	      get.  If no option is specified, returns a list  describing  all
	      of  the  available  options  for the first item given by tagOrId
	      (see Tk_ConfigureInfo for information  on	 the  format  of  this
	      list).   If  option is specified with no value, then the command
	      returns a list describing the one named option (this  list  will
	      be  identical to the corresponding sublist of the value returned
	      if no option is specified).  If one or more  option-value	 pairs
	      are  specified,  then  the  command  modifies  the  given widget
	      option(s) to have the given value(s) in each of the items	 given
	      by  tagOrId;   in this case the command returns an empty string.
	      The options and values are the same as those permissible in  the
	      create  widget  command  when  the item(s) were created; see the
	      sections describing individual item types below for  details  on
	      the legal options.

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

       pathName move tagOrId xAmount yAmount
	      Move each of the items given by tagOrId in the canvas coordinate
	      space  by adding xAmount to the x-coordinate of each point asso‐
	      ciated with the item and yAmount to  the	y-coordinate  of  each
	      point  associated	 with the item.	 This command returns an empty
	      string.

       pathName postscript ?option value option value ...?
	      Generate a Postscript representation for part or all of the can‐
	      vas.   If	 the  -file option is specified then the Postscript is
	      written to a file and an empty string  is	 returned;   otherwise
	      the Postscript is returned as the result of the command.	If the │
	      interpreter that owns the canvas is marked as safe,  the	opera‐ │
	      tion  will  fail	because	 safe  interpreters are not allowed to │
	      write files.  If the -channel option is specified, the  argument │
	      denotes  the  name  of a channel already opened for writing. The │
	      Postscript is written to that channel, and the channel  is  left │
	      open for further writing at the end of the operation.  The Post‐
	      script is created in Encapsulated Postscript form using  version
	      3.0  of  the Document Structuring Conventions.  Note: by default
	      Postscript is only generated for information that appears in the
	      canvas's window on the screen.  If the canvas is freshly created
	      it may still have its initial size of 1x1 pixel so nothing  will
	      appear  in  the  Postscript.   To get around this problem either
	      invoke the "update" command to wait for  the  canvas  window  to
	      reach its final size, or else use the -width and -height options
	      to specify the area of the canvas to  print.   The  option-value
	      argument	pairs  provide	additional  information to control the
	      generation of Postscript.	 The following options are supported:

	      -colormap varName
		     VarName must be the name of an array variable that speci‐
		     fies a color mapping to use in the Postscript.  Each ele‐
		     ment of varName must consist of Postscript code to set  a
		     particular	 color	value  (e.g.  ``1.0  1.0  0.0  setrgb‐
		     color'').	When outputting color information in the Post‐
		     script,  Tk  checks to see if there is an element of var‐
		     Name with the same name as the color.  If so, Tk uses the
		     value of the element as the Postscript command to set 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 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 variable that speci‐
		     fies  a font mapping to use in the Postscript.  Each ele‐
		     ment of varName must consist of a Tcl list with two  ele‐
		     ments,  which are the name and point size of a Postscript
		     font.  When outputting Postscript commands for a particu‐
		     lar font, Tk checks to see if varName contains an element
		     with the same name as the font.  If there is such an ele‐
		     ment, 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 gener‐
		     ally 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 exam‐
		     ple,   -*-Courier-Bold-R-Normal--*-120-*  will  work  but
		     *Courier-Bold-R-Normal*120*  will	not;   Tk  needs   the
		     dashes to parse the font name).

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

	      -pageanchor anchor
		     Specifies which point of the printed area of  the	canvas
		     should  appear  over  the	positioning  point on the page
		     (which is given by the -pagex and -pagey  options).   For
		     example,  -pageanchor  n means that the top center of the
		     area of the canvas being printed (as it  appears  in  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 Post‐
		     script page.  Size consists of  a	floating-point	number
		     followed  by  c for centimeters, i for inches, m for mil‐
		     limeters, or p or	nothing	 for  printer's	 points	 (1/72
		     inch).  Defaults to the height of the printed area on the
		     screen.  If both -pageheight and -pagewidth are specified
		     then  the	scale factor 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 Post‐
		     script page.  Size has the same form as for  -pageheight.
		     Defaults  to the width of the printed area on the screen.
		     If both -pageheight and -pagewidth are specified then the
		     scale  factor from -pagewidth  is used (non-uniform scal‐
		     ing is not implemented).

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

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

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

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

       pathName scale tagOrId xOrigin yOrigin xScale yScale
	      Rescale all of the items given by tagOrId in  canvas  coordinate
	      space.   XOrigin and yOrigin identify the origin for the scaling
	      operation and xScale and yScale identify the scale  factors  for
	      x-  and  y-coordinates,  respectively  (a	 scale	factor	of 1.0
	      implies no change to that coordinate).  For each of  the	points
	      defining	each  item, the x-coordinate is adjusted to change the
	      distance from xOrigin by a factor of xScale.  Similarly, each y-
	      coordinate  is adjusted to change the distance from yOrigin by a
	      factor of yScale.	 This command returns an empty string.

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

	      pathName scan mark x y
		     Records  x	 and y and the canvas's current view;  used in
		     conjunction with later scan dragto	 commands.   Typically
		     this  command  is associated with a mouse button press in
		     the widget and x and y are the coordinates of the	mouse.
		     It returns an empty string.

	      pathName scan dragto x y.
		     This  command computes the difference between its x and y
		     arguments (which are typically mouse coordinates) and the
		     x	and  y arguments to the last scan mark command for the
		     widget.  It then adjusts the view by 10 times the differ‐
		     ence  in  coordinates.  This command is typically associ‐
		     ated with mouse motion events in the widget,  to  produce
		     the  effect  of dragging the canvas at high speed through
		     its window.  The return value is an empty string.

       pathName select option ?tagOrId arg?
	      Manipulates the selection in one of several ways,	 depending  on
	      option.	The command may take any of the forms described below.
	      In all of the descriptions below, tagOrId must refer to an  item
	      that  supports indexing and selection;  if it refers to multiple
	      items then the first of these that  supports  indexing  and  the
	      selection is used.  Index gives a textual description of a posi‐
	      tion 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 widget 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 characters of
		     tagOrId between the selection  anchor  point  and	index.
		     The  new  selection  will	include the character given by
		     index; it will include the character given by the	anchor
		     point  only  if  index  is	 greater  than or equal to the
		     anchor point.  The anchor point is determined by the most
		     recent select adjust or select from command for this wid‐
		     get.  If the selection anchor point for the widget	 isn't
		     currently	in tagOrId, then it is set to the same charac‐
		     ter given by index.  Returns an empty string.

       pathName type tagOrId
	      Returns the type of the item given by tagOrId, such as rectangle
	      or text.	If tagOrId refers to more than one item, then the type
	      of the first item in 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 horizontal position
	      of  the  information  displayed  in the canvas's window.	It can
	      take any of the following forms:

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

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

	      pathName xview scroll number what
		     This command shifts the view in the window left or	 right
		     according to number and what.  Number must be an integer.
		     What must be either units or pages or an abbreviation  of
		     one of these.  If what is units, the view adjusts left or
		     right in units of the xScrollIncrement option, if	it  is
		     greater  than zero, or in units of one-tenth the window's
		     width otherwise.  If what is pages then the view  adjusts
		     in units of nine-tenths the window's width.  If number is
		     negative then information farther	to  the	 left  becomes
		     visible;	if  it is positive then information farther to
		     the right becomes visible.

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

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

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

	      pathName yview scroll number what
		     This  command  adjusts  the view in the window up or down
		     according to number and what.  Number must be an integer.
		     What  must	 be  either units or pages.  If what is units,
		     the view adjusts up or down in units of the 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 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 commands related
       to them, such as index and insert.  Where items do support these facil‐
       ities,  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 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 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 commands to change the item's configuration.	 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.

       -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 commands of
       the following form:
	      pathName create bitmap x y ?option value option value ...?
       The arguments x and y specify the coordinates of a point used to	 posi‐
       tion  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 configu‐
       ration.	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
	      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 commands of the following form:
	      pathName create image x y ?option value option value ...?
       The  arguments x and y specify the coordinates of a point used to posi‐
       tion 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 itemconfig‐
       ure 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 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
	      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 fol‐
       lowing 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 following options are supported
       for lines:

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

       -arrowshape shape
	      This  option  indicates how to draw arrowheads.  The shape argu‐
	      ment must be a list with three elements, each specifying a  dis‐
	      tance  in	 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
	      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 following 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 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  configu‐
       ration.	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.

       -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
	      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  follow‐
       ing 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 configuration options
       for the item.  These same option-value pairs may be used in itemconfig‐
       ure  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 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.

       -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 commands of 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  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 commands to change the item's
       configuration.  The following options are supported for rectangles:

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

       -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 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 posi‐
       tion the text on the display (see the options below for	more  informa‐
       tion on how text is displayed).	After the coordinates there may be any
       number of option-value pairs, each of which sets one of the  configura‐
       tion  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 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	 color
	      is  an  empty string then the text will be transparent.  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
	      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  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
       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 posi‐
       tion 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  configu‐
       ration.	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
	      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 wid‐
	      get or a child of some ancestor of the canvas widget.   PathName
	      may not refer to a top-level window.

       Note:   due to restrictions in 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 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 can‐
       vases.

KEYWORDS
       canvas, widget

Tk				      4.0			     canvas(n)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net