canvas man page on Slackware

Man page or keyword search:  
man Server   14563 pages
apropos Keyword Search (all sections)
Output format
Slackware 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	     -borderwidth	  -cursor
       -highlightbackground  -highlightcolor	  -highlightthickness
       -insertbackground     -insertborderwidth	  -insertofftime
       -insertontime	     -insertwidth	  -relief
       -selectbackground     -selectborderwidth	  -selectforeground
       -takefocus	     -xscrollcommand	  -yscrollcommand

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

WIDGET-SPECIFIC OPTIONS
       [-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] 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  con‐
       strained	 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.
       [-state state] Modifies the default state of the canvas where state may
       be  set	to  one	 of:  normal,  disabled,  or hidden. Individual canvas
       objects all have their own state option which may override the  default
       state.  Many  options  can  take	 separate specifications such that the
       appearance of the item can be different in  different  situations.  The
       options	that  start  with active control the appearance when the mouse
       pointer is over it, while the option starting  with  disabled  controls
       the  appearance when the state is disabled. Canvas items which are dis‐
       abled will not react to canvas bindings.	  [-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.   [-xscrollincre‐
       ment xScrollIncrement] Specifies an increment for horizontal scrolling,
       in  any of the usual forms permitted for screen distances. If the value
       of this option is greater than zero, the horizontal view in the	window
       will be constrained so that the canvas x coordinate at the left edge of
       the window is always an even multiple of xScrollIncrement; furthermore,
       the  units  for	scrolling  (e.g., the change in view when the left and
       right arrows of a scrollbar are selected) will  also  be	 xScrollIncre‐
       ment.  If  the value of this option is less than or equal to zero, then
       horizontal     scrolling	    is	   unconstrained.      [-yscrollincre‐
       ment 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 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 bot‐
       tom  arrows of a scrollbar are selected) will also be yScrollIncrement.
       If the value of this option is less than or equal to zero, then	verti‐
       cal scrolling is unconstrained.
_________________________________________________________________

INTRODUCTION
       The  canvas  command  creates a new window (given by the pathName argu‐
       ment) and makes it into a canvas widget.	 Additional options, described
       above,  may  be specified on the command line or in 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 com‐
       mand 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 particu‐
       lar 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 window
       systems	require	 them  always  to  be drawn on top of other items.  In
       addition, the stacking order of window items is not affected by any  of
       the canvas widget commands; you must use the Tk raise command and lower
       command instead.

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

       Each item may also have any number of tags associated with it. A tag is
       just a string of characters, and it may take any form except that of an
       integer.	 For example, “x123” is OK but “123” is not.  The same tag may
       be associated with many different items.	  This	is  commonly  done  to
       group  items  in	 various  interesting  ways; for example, all selected
       items might be given the tag “selected”.

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

       The  tag current is managed automatically by Tk; it applies to the cur‐
       rent item, which is the topmost item whose drawn area covers the	 posi‐
       tion  of the mouse cursor (different item types interpret this in vary‐
       ing ways; see the individual item type documentation for details).   If
       the  mouse  is not in the canvas widget or is not over an item, then no
       item has the current tag.

       When specifying items in canvas widget commands, if the specifier is an
       integer	then  it  is assumed to refer to the single item with that id.
       If the specifier is not an integer, then it is assumed to refer to  all
       of the items in the canvas that have a tag matching the specifier.  The
       symbol tagOrId is used below to indicate	 that  an  argument  specifies
       either  an  id that selects a single item or a tag that selects zero or
       more items.

       tagOrId may contain a logical expressions of tags by  using  operators:
       “&&”, “||”, “^”, “!”, and parenthesized subexpressions. For example:
		    .c find withtag {(a&&!b)||(!a&&b)}
       or equivalently:
		    .c find withtag {a^b}
       will find only those items with either “a” or “b” tags, but not both.

       Some  widget  commands  only  operate  on  a  single item at a time; if
       tagOrId is specified in a way that names multiple items, then the  nor‐
       mal  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.   Coordinates  can be specified either as an even number of
       parameters, or as a single list parameter containing an even number  of
       x and y coordinate values.

   TRANSFORMATIONS
       Normally	 the  origin  of the canvas coordinate system is at the upper-
       left corner of the window containing the canvas.	  It  is  possible  to
       adjust  the origin of the canvas coordinate system relative to the ori‐
       gin of the window using the xview and yview widget  commands;  this  is
       typically used for scrolling.  Canvases do not support scaling or rota‐
       tion of the canvas coordinate system relative to the window  coordinate
       system.

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

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

INDICES
       Text  items  support  the notion of an index for identifying particular
       positions within the item.  In a	 similar  fashion,  line  and  polygon
       items  support index for identifying, inserting and deleting subsets of
       their coordinates.  Indices are used for commands such as inserting  or
       deleting	 a  range of characters or coordinates, and setting the 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.	Lines and Polygons do not support the insertion cursor
       and the selection. Their	 indices  are  supposed	 to  be	 even  always,
       because coordinates always appear in pairs.

       number	 A decimal number giving the position of the desired character
		 within the text item.	0 refers to the first character, 1  to
		 the  next  character, and so on. If indexes are odd for lines
		 and polygons, they will be automatically decremented by  one.
		 A  number  less  than	0 is treated as if it were zero, and a
		 number greater than the length of the text item is treated as
		 if  it	 were  equal to the length of the text item. For poly‐
		 gons, numbers less than 0 or greater then the length  of  the
		 coordinate list will be adjusted by adding or subtracting the
		 length until the result  is  between  zero  and  the  length,
		 inclusive.

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

       insert	 Refers	 to the character just before which the insertion cur‐
		 sor is drawn in this item. Not valid for lines and polygons.

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

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

       @x,y	 Refers to the character or coordinate at the point given by x
		 and  y,  where x and y are specified in the coordinate system
		 of the canvas.	 If x and y lie outside the  coordinates  cov‐
		 ered  by  the text item, then they refer to the first or last
		 character in the line that is closest to the given point.

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

       The first possible syntax is a list of integers.	 Each  element	repre‐
       sents the number of pixels of a line segment. Only the odd segments are
       drawn using the “outline” color. The other segments are drawn transpar‐
       ent.

       The second possible syntax is a character list containing only 5 possi‐
       ble characters “.,-_ ”.	The space can be used  to  enlarge  the	 space
       between	other line elements, and cannot occur as the first position in
       the string. Some examples:
	      -dash .	  → -dash {2 4}
	      -dash -	  → -dash {6 4}
	      -dash -.	  → -dash {6 4 2 4}
	      -dash -..	  → -dash {6 4 2 4 2 4}
	      -dash {. }  → -dash {2 8}
	      -dash ,	  → -dash {4 4}

       The main difference of this syntax with the  previous  is  that	it  is
       shape-conserving.  This	means that all values in the dash list will be
       multiplied by the line width before  display.  This  assures  that  “.”
       will  always  be displayed as a dot and “-” always as a dash regardless
       of the line width.

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

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

       pathName addtag tag searchSpec ?arg arg ...?
	      For each item that meets the constraints specified by searchSpec
	      and the args, add tag to the list of tags	 associated  with  the
	      item  if it is not already present on that list.	It is possible
	      that no items will satisfy the constraints given	by  searchSpec
	      and args, in which case the command has no effect.  This command
	      returns an empty string as result.   SearchSpec  and  arg's  may
	      take any of the following forms:

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

	      all    Selects all the items in the canvas.

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

	      closest x y ?halo? ?start?
		     Selects  the  item closest to the point given by x and y.
		     If more than one item is at  the  same  closest  distance
		     (e.g.  two items overlap the point), then the top-most of
		     these items (the last one in the display list)  is	 used.
		     If	 halo  is  specified,  then  it must be a non-negative
		     value.  Any item closer than halo to the point is 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 com‐
	      mand 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  trigger
	      only  if	the  virtual  event is defined by an underlying mouse-
	      related or keyboard-related event.

	      It is possible for  multiple  bindings  to  match	 a  particular
	      event.  This could occur, for example, if one binding is 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 ...?

       pathName coords tagOrId ?coordList?
	      Query  or	 modify	 the  coordinates  that define an item.	 If no
	      coordinates are specified, this command  returns	a  list	 whose
	      elements	are  the coordinates of the item named by tagOrId.  If
	      coordinates are specified, then they replace the current 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 ...?

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

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

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

       pathName dtag tagOrId ?tagToDelete?
	      For  each of the items given by tagOrId, delete the tag given by
	      tagToDelete from the list of those associated with the item.  If
	      an item does not have the tag tagToDelete then the item is 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 does not refer to  any	items,
	      or  if none of them support the insertion cursor, then the focus
	      is not changed.  If tagOrId is an empty string, then  the	 focus
	      item  is reset so that no item has the focus.  If tagOrId is not
	      specified then the command returns the id for the item that 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 does not actually have the input focus unless
	      (a) its canvas is the focus window and (b) the item is the focus
	      item within the canvas.  In most cases it is advisable to follow
	      the focus widget command with the focus command to set the focus
	      window to the canvas (if it was not there already).

       pathName gettags tagOrId
	      Return a list whose elements are the tags	 associated  with  the
	      item given by tagOrId.  If tagOrId refers to more than one item,
	      then the tags are returned from the first such item in the  dis‐
	      play  list.   If	tagOrId does not refer to any items, or if the
	      item contains no tags, then an empty string is returned.

       pathName icursor tagOrId index
	      Set the position of the insertion cursor for the	item(s)	 given
	      by  tagOrId to just before the character whose position is given
	      by index.	 If some or all of the items given by tagOrId  do  not
	      support  an  insertion cursor then this command has no effect on
	      them.  See INDICES above for a description of  the  legal	 forms
	      for  index.   Note: the insertion cursor is only displayed in an
	      item if that item currently has  the  keyboard  focus  (see  the
	      focus widget command, above), but the cursor position may be set
	      even when the item  does	not  have  the	focus.	 This  command
	      returns an empty string.

       pathName imove tagOrId index x y
	      This command causes the index'th coordinate of each of the items │
	      indicated by tagOrId to be  relocated  to	 the  location	(x,y). │
	      Each  item interprets index independently according to the rules │
	      described in INDICES above. Out of the standard  set  of	items, │
	      only line and polygon items may have their coordinates relocated │
	      this way.

       pathName index tagOrId index
	      This command returns a decimal string giving the numerical index
	      within  tagOrId  corresponding  to index.	 Index gives a textual
	      description of the desired  position  as	described  in  INDICES
	      above.   Text  items interpret index as an index to a character,
	      line and polygon items interpret it as an index to a  coordinate
	      (an  x,y pair).  The return value is guaranteed to lie between 0
	      and the number of characters, or coordinates, within  the	 item,
	      inclusive.   If tagOrId refers to multiple items, then the index
	      is processed in the first of these items that supports  indexing
	      operations (in display list order).

       pathName insert tagOrId beforeThis string
	      For  each	 of  the  items given by tagOrId, if the item supports
	      text or coordinate, insertion then string is inserted  into  the
	      item's  text  just  before  the  character, or coordinate, whose
	      index is beforeThis.  Text  items	 interpret  beforeThis	as  an
	      index  to a character, line and polygon items interpret it as an
	      index to a coordinate (an x,y pair).  For lines and polygons the
	      string  must  be a valid coordinate sequence.  See INDICES above
	      for information about the forms allowed  for  beforeThis.	  This
	      command returns an empty string.

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

       pathName itemconfigure tagOrId ?option? ?value? ?option value ...?
	      This  command  is similar to the configure widget command except
	      that it modifies item-specific options for the  items  given  by
	      tagOrId instead of modifying options for the overall canvas 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 command and lower  command,  not  the
	      raise  widget  command  and  lower  widget command 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 moveto tagOrId xPos yPos
	      Move the items given by tagOrId in the canvas  coordinate	 space │
	      so  that	the  first coordinate pair of the bottommost item with │
	      tag tagOrId is located at position (xPos,yPos).  xPos  and  yPos │
	      may be the empty string, in which case the corresponding coordi‐ │
	      nate will be unchanged. All items matching tagOrId remain in the │
	      same  positions relative to each other.  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 argu‐
	      ment pairs provide additional information to control the genera‐
	      tion of Postscript. The following options are supported:

	      -channel channelName
		     Specifies the name of the channel to which to  write  the
		     Postscript.   If this option and the -file option are not
		     specified then the Postscript is returned as  the	result
		     of the command.

	      -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 setrgbcolor”).
		     When  outputting  color information in the Postscript, Tk
		     checks to see if there is an element of varName with  the
		     same  name as the color.  If so, Tk uses the value of the
		     element as the Postscript command to set the  color.   If
		     this  option  has	not  been specified, or if there is no
		     entry in varName for a given color, then Tk uses the red,
		     green, and blue intensities from the X color.

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

	      -file fileName
		     Specifies the name of the file  in	 which	to  write  the
		     Postscript.   If  this option and the -channel option are
		     not specified then the  Postscript	 is  returned  as  the
		     result of the command.

	      -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 scaling
		     is not implemented).

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

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

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

	      Note: this command 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 command and lower  command,
	      not  the	raise widget command and lower widget command for can‐
	      vases.

       pathName rchars tagOrId first last string
	      This command causes the text or coordinates  between  first  and │
	      last  for	 each of the items indicated by tagOrId to be replaced │
	      by string. Each item interprets  first  and  last	 independently │
	      according	 to  the  rules described in INDICES above. Out of the │
	      standard set of items, text  items  support  this	 operation  by │
	      altering their text as directed, and line and polygon items sup‐ │
	      port this operation by altering their coordinate list (in	 which │
	      case string should be a list of coordinates to use as a replace‐ │
	      ment). The other items ignore this operation.

       pathName scale tagOrId xOrigin yOrigin xScale yScale
	      Rescale the coordinates of all of the items given by tagOrId  in
	      canvas  coordinate space.	 XOrigin and yOrigin identify the ori‐
	      gin 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.  Sim‐
	      ilarly,  each  y-coordinate  is  adjusted to change the distance
	      from yOrigin by a factor of yScale.   This  command  returns  an
	      empty string.

	      Note  that  some	items  have  only a single pair of coordinates
	      (e.g., text, images and windows) and so scaling of them by  this
	      command can only move them around.

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

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

	      pathName scan dragto x y ?gain?
		     This command computes the difference between its x and  y
		     arguments (which are typically mouse coordinates) and the
		     x and y arguments to the last scan mark command  for  the
		     widget.   It then adjusts the view by gain times the dif‐
		     ference in coordinates, where gain defaults to 10.	  This
		     command  is typically associated with mouse motion events
		     in the widget, to produce the effect of dragging the can‐
		     vas 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	is  not currently in tagOrId then this command
		     behaves  the  same	 as  the  select  to  widget  command.
		     Returns an empty string.

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

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

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

	      pathName select to tagOrId index
		     Set  the  selection  to  consist  of  those characters of
		     tagOrId between the selection  anchor  point  and	index.
		     The  new  selection  will	include the character given by
		     index; it will include the character given by the	anchor
		     point  only  if  index  is	 greater  than or equal to the
		     anchor point.  The anchor point is determined by the most
		     recent select adjust or select from command for this wid‐
		     get.  If the selection anchor point for the widget is not
		     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
	      does  not	 refer	to  any	 items	at all then an empty string is
	      returned.

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

	      pathName xview
		     Returns a list containing two elements.  Each element  is
		     a	real  fraction between 0 and 1; together they describe
		     the horizontal span that is visible in the	 window.   For
		     example,  if  the first element is .2 and the second 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 do not 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,
       text, line and polygon items provide this support.  For lines and poly‐
       gons the indexing facility is used to manipulate the coordinates of the
       item.

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

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

       -dash pattern

       -activedash pattern

       -disableddash pattern
	      This option specifies  dash  patterns  for  the  normal,	active
	      state,  and  disabled state of an item.  pattern may have any of
	      the forms accepted by Tk_GetDash.	 If the dash options are omit‐
	      ted  then the default is a solid outline.	 See DASH PATTERNS for
	      more information.

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

       -fill color

       -activefill color

       -disabledfill color
	      Specifies the color to be used to fill item's area.  in its nor‐
	      mal, active, and disabled states, Color  may  have  any  of  the
	      forms accepted by Tk_GetColor.  If color is an empty string (the
	      default), then the item will not be filled.  For the line	 item,
	      it specifies the color of the line drawn.	 For the text item, it
	      specifies the foreground color of the text.

       -outline color

       -activeoutline color

       -disabledoutline color
	      This option specifies the color that should be used to draw  the
	      outline  of  the item in its normal, active and disabled states.
	      Color may have any of the forms accepted by  Tk_GetColor.	  This
	      option  defaults	to  black.  If	color is specified as an empty
	      string then no outline is drawn for the item.

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

       -outlinestipple bitmap

       -activeoutlinestipple bitmap

       -disabledoutlinestipple bitmap
	      This  option  specifies  stipple patterns that should be used to
	      draw the outline of the item in its normal, active and  disabled
	      states.  Indicates that the outline for the item should be drawn
	      with a stipple pattern; bitmap specifies the stipple pattern  to
	      use, in any of the forms accepted by Tk_GetBitmap.  If the -out‐
	      line option has not been	specified  then	 this  option  has  no
	      effect.	If  bitmap  is an empty string (the default), then the
	      outline is drawn in a solid fashion.  Note that stipples are not
	      well supported on platforms that do not use X11 as their drawing
	      API.

       -outlineoffset offset
	      Specifies the offset of the stipple pattern used	for  outlines,
	      in the same way that the -outline option controls fill stipples.
	      (See the -outline option for a description of the syntax of off‐
	      set.)

       -stipple bitmap

       -activestipple bitmap

       -disabledstipple bitmap
	      This  option  specifies  stipple patterns that should be used to
	      fill the item in its normal, active and disabled states.	bitmap
	      specifies	 the  stipple  pattern	to  use,  in  any of the forms
	      accepted by Tk_GetBitmap.	 If the	 -fill	option	has  not  been
	      specified then this option has no effect.	 If bitmap is an empty
	      string (the default), then filling is done in a  solid  fashion.
	      For  the text item, it affects the actual text.  Note that stip‐
	      ples are not well supported on platforms that do not use X11  as
	      their drawing API.

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

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

       -width outlineWidth

       -activewidth outlineWidth

       -disabledwidth outlineWidth
	      Specifies the width of the outline to be drawn around the item's
	      region, in its normal, active and disabled states.  outlineWidth
	      may be in any of the forms described in the COORDINATES  section
	      above.   If  the	-outline option has been specified as an empty
	      string then this option has no effect. This option  defaults  to
	      1.0.   For  arcs,	 wide  outlines	 will be drawn centered on the
	      edges of the arc's region.

STANDARD ITEM TYPES
   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 ...?
	      pathName create arc coordList ?option value ...?
       The arguments x1, y1, x2, and y2 or coordList give the  coordinates  of
       two  diagonally	opposite corners of a rectangular region enclosing the
       oval that defines the arc.  After the coordinates there may be any num‐
       ber  of option-value pairs, each of which sets one of the configuration
       options for the item. These same option-value  pairs  may  be  used  in
       itemconfigure  widget  commands	to change the item's configuration. An
       arc item becomes the current item when the mouse pointer	 is  over  any
       part  that is painted or (when fully transparent) that would be painted
       if both the -fill and -outline options were non-empty.

       The   following	 standard   options    are    supported	   by	 arcs:
       -dash			     -activedash		    -disabled‐
       dash		    -dashoffset -fill			      -active‐
       fill		-disabledfill		      -offset		 -out‐
       line			 -activeoutline			 -disabledout‐
       line		 -outlineoffset -outlinestipple		      -active‐
       outlinestipple	-disabledoutlinestipple	      -stipple	  -activestip‐
       ple		  -disabledstipple -state			 -tags
       -width			     -activewidth -disabledwidth The following
       extra options are supported for arcs:

       -extent degrees
	      Specifies	 the  size  of	the angular range occupied by the arc.
	      The arc's range extends for  degrees  degrees  counter-clockwise
	      from the starting angle given by the -start option.  Degrees may
	      be negative.  If it is greater than 360 or less than -360,  then
	      degrees modulo 360 is used as the extent.

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

       -style type
	      Specifies how to draw the arc. If type is pieslice (the default)
	      then  the	 arc's	region	is  defined by a section of the oval's
	      perimeter plus two line segments, one between the center of  the
	      oval  and	 each  end of the perimeter section.  If type is chord
	      then the arc's region is defined by  a  section  of  the	oval's
	      perimeter	 plus  a  single  line	segment connecting the two end
	      points of the perimeter section.	If type is arc then the	 arc's
	      region  consists	of  a section of the perimeter alone.  In this
	      last case the -fill option is ignored.

   BITMAP ITEMS
       Items of type bitmap appear on the display as images with  two  colors,
       foreground and background.  Bitmaps are created with widget commands of
       the following form:
	      pathName create bitmap x y ?option value ...?
	      pathName create bitmap coordList ?option value ...?
       The arguments x and y or coordList (which must have two elements) spec‐
       ify  the coordinates of a point used to position the bitmap on the dis‐
       play, as controlled by the -anchor option.  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. A bitmap item becomes the current item when the	mouse  pointer
       is over any part of its bounding box.

       The    following	  standard   options   are   supported	 by   bitmaps:
       -anchor			     -state -tags The following extra  options
       are supported for bitmaps:

       -background color

       -activebackground color

       -disabledbackground color
	      Specifies	 the  color to use for each of the bitmap's “0” valued
	      pixels in its normal, active and	disabled  states.   Color  may
	      have  any	 of the forms accepted by Tk_GetColor.	If this option
	      is not specified, or if it is specified as an empty string, then
	      nothing  is  displayed  where the bitmap pixels are 0; this pro‐
	      duces a transparent effect.

       -bitmap bitmap

       -activebitmap bitmap

       -disabledbitmap bitmap
	      Specifies the bitmaps to display in  the	item  in  its  normal,
	      active  and  disabled  states.  Bitmap may have any of the forms
	      accepted by Tk_GetBitmap.

       -foreground color

       -activeforeground color

       -disabledforeground color
	      Specifies the color to use for each of the bitmap's  “1”	valued
	      pixels  in  its  normal,	active and disabled states.  Color may
	      have any of the forms accepted by Tk_GetColor  and  defaults  to
	      black.

   IMAGE ITEMS
       Items of type image are used to display images on a canvas.  Images are
       created with widget commands of the following form:
	      pathName create image x y ?option value ...?
	      pathName create image coordList ?option value ...?
       The arguments x and y or coordList specify the coordinates of  a	 point
       used to position the image on the display, as controlled by the -anchor
       option.	After the coordinates there may be any number of  option-value
       pairs,  each  of	 which	sets  one of the configuration options for the
       item. These same option-value pairs may be used in itemconfigure widget
       commands	 to change the item's configuration. An image item becomes the
       current item when the mouse pointer is over any part  of	 its  bounding
       box.

       The    following	   standard   options	are   supported	  by   images:
       -anchor			     -state -tags The following extra  options
       are supported for images:

       -image name

       -activeimage name

       -disabledimage name
	      Specifies	 the  name  of the images to display in the item in is
	      normal, active and disabled states.  This image must  have  been
	      created previously with the image create command.

   LINE ITEMS
       Items  of type line appear on the display as one or more connected line
       segments or curves.  Line items support coordinate indexing  operations
       using  the dchars, index and insert widget commands.  Lines are created
       with widget commands of the following form:
	      pathName create line x1 y1... xn yn ?option value ...?
	      pathName create line coordList ?option value ...?
       The arguments x1 through yn or coordList give  the  coordinates	for  a
       series  of  two or more points that describe a series of connected line
       segments.   After  the  coordinates  there  may	be   any   number   of
       option-value pairs, each of which sets one of the configuration options
       for the item. These same option-value pairs may be used in  itemconfig‐
       ure  widget commands to change the item's configuration. A line item is
       the current item whenever the mouse pointer is over any segment of  the
       line, whether drawn or not and whether or not the line is smoothed.

       The    following	   standard    options	 are   supported   by	lines:
       -dash			     -activedash		    -disabled‐
       dash		    -dashoffset -fill			      -active‐
       fill	   -disabledfill		 -stipple	  -activestip‐
       ple		  -disabledstipple -state			 -tags
       -width			     -activewidth -disabledwidth The following
       extra options are supported for lines:

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

       -arrowshape shape
	      This option indicates how to draw arrowheads.  The  shape	 argu‐
	      ment  must be a list with three elements, each specifying a dis‐
	      tance in any of the forms described in the  COORDINATES  section
	      above.   The  first element of the list gives the distance along
	      the line from the neck of the arrowhead to its tip.  The	second
	      element  gives  the  distance  along  the line from the trailing
	      points of the arrowhead to the tip, and the third element	 gives
	      the  distance  from the outside edge of the line to the trailing
	      points.  If this option is not specified then Tk picks  a	 “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 is
	      not specified then it defaults to butt.	Where  arrowheads  are
	      drawn the cap style is ignored.

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

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

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

   OVAL ITEMS
       Items  of  type oval appear as circular or oval regions on the display.
       Each oval may have an outline, a fill, or both. Ovals are created  with
       widget commands of the following form:
	      pathName create oval x1 y1 x2 y2 ?option value ...?
	      pathName create oval coordList ?option value ...?
       The  arguments  x1, y1, x2, and y2 or coordList give the coordinates of
       two diagonally opposite corners of a rectangular region	enclosing  the
       oval.   The  oval  will include the top and left edges of the rectangle
       not the lower or right edges.  If the region is square then the result‐
       ing  oval  is  circular; otherwise it is elongated in shape.  After the
       coordinates there may be any number  of	option-value  pairs,  each  of
       which  sets  one	 of the configuration options for the item. These same
       option-value pairs may be used  in  itemconfigure  widget  commands  to
       change  the item's configuration. An oval item becomes the current item
       when the mouse pointer is over any part that is painted or (when	 fully
       transparent)  that  would  be  painted  if  both the -fill and -outline
       options were non-empty.

       The   following	 standard   options   are    supported	  by	ovals:
       -dash			     -activedash		    -disabled‐
       dash		    -dashoffset -fill			      -active‐
       fill		-disabledfill		      -offset		 -out‐
       line			 -activeoutline			 -disabledout‐
       line		 -outlineoffset -outlinestipple		      -active‐
       outlinestipple	-disabledoutlinestipple	      -stipple	  -activestip‐
       ple		  -disabledstipple -state			 -tags
       -width			     -activewidth -disabledwidth There are  no
       oval-specific options.

   POLYGON ITEMS
       Items  of  type polygon appear as polygonal or curved filled regions on
       the display.  Polygon  items  support  coordinate  indexing  operations
       using  the dchars, index and insert widget commands.  Polygons are cre‐
       ated with widget commands of the following form:
	      pathName create polygon x1 y1 ... xn yn ?option value ...?
	      pathName create polygon coordList ?option value ...?
       The arguments x1 through yn or coordList specify	 the  coordinates  for
       three or more points that define a polygon.  The first point should not
       be repeated as the last to close the shape; Tk will automatically close
       the periphery between the first and last points.	 After the coordinates
       there may be any number of option-value pairs, each of which  sets  one
       of  the	configuration  options	for  the item. These same option-value
       pairs may be used in itemconfigure widget commands to change the item's
       configuration.  A  polygon  item is the current item whenever the mouse
       pointer is over any part of the	polygon,  whether  drawn  or  not  and
       whether or not the outline is smoothed.

       The   following	 standard   options   are   supported	by   polygons:
       -dash			     -activedash		    -disabled‐
       dash		    -dashoffset -fill			      -active‐
       fill	       -disabledfill		     -offset		 -out‐
       line			 -activeoutline			 -disabledout‐
       line		 -outlineoffset -outlinestipple		      -active‐
       outlinestipple	 -disabledoutlinestipple       -stipple	  -activestip‐
       ple		  -disabledstipple -state			 -tags
       -width			     -activewidth -disabledwidth The following
       extra options are supported for polygons:

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

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

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

       Polygon items are different from other items such as rectangles,	 ovals
       and  arcs in that interior points are considered to be “inside” a poly‐
       gon (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 ...?
	      pathName create rectangle coordList ?option value ...?
       The  arguments  x1,  y1,	 x2, and y2 or coordList (which must have four
       elements) give the coordinates of two diagonally	 opposite  corners  of
       the  rectangle (the rectangle will include its upper and left edges but
       not its lower or right edges).  After the coordinates there may be  any
       number  of option-value pairs, each of which sets one of the configura‐
       tion options for the item. These same option-value pairs may be used in
       itemconfigure  widget  commands	to  change the item's configuration. A
       rectangle item becomes the current item when the mouse pointer is  over
       any  part  that	is  painted  or (when fully transparent) that would be
       painted if both the -fill and -outline options were non-empty.

       The  following  standard	  options   are	  supported   by   rectangles:
       -dash			     -activedash		    -disabled‐
       dash		    -dashoffset -fill			      -active‐
       fill		-disabledfill		      -offset		 -out‐
       line			 -activeoutline			 -disabledout‐
       line		 -outlineoffset -outlinestipple		      -active‐
       outlinestipple	-disabledoutlinestipple	      -stipple	  -activestip‐
       ple		  -disabledstipple -state			 -tags
       -width			     -activewidth -disabledwidth There are  no
       rectangle-specific options.

   TEXT ITEMS
       A  text	item  displays	a string of characters on the screen in one or
       more lines.  Text items support indexing, editing and selection through
       the dchars widget command, the focus widget command, the icursor widget
       command, the index widget command, the insert widget command,  and  the
       select  widget command.	Text items are created with widget commands of
       the following form:
	      pathName create text x y ?option value ...?
	      pathName create text coordList ?option value ...?
       The arguments x and y or coordList (which must have two elements) spec‐
       ify the coordinates of a point used to position the text on the display
       (see the options below for more information on how text is  displayed).
       After  the  coordinates	there may be any number of option-value pairs,
       each of which sets one of the configuration options for the item. These
       same option-value pairs may be used in itemconfigure widget commands to
       change the item's configuration. A text item becomes the	 current  item
       when the mouse pointer is over any part of its bounding box.

       The   following	 standard   options   are  supported  by  text	items:
       -anchor			     -fill -activefill			 -dis‐
       abledfill  -stipple			-activestipple	-disabledstip‐
       ple		-state -tags The following extra options are supported
       for text items:

       -angle rotationDegrees
	      RotationDegrees  tells how many degrees to rotate the text anti‐ │
	      clockwise about the positioning point for the text; it may  have │
	      any  floating-point  value  from	0.0  to 360.0. For example, if │
	      rotationDegrees is 90, then the text will	 be  drawn  vertically │
	      from bottom to top.  This option defaults to 0.0.

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

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

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

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

       -width lineLength
	      Specifies	 a  maximum  line  length  for the text, in any of the
	      forms described in  the  COORDINATES  section  above.   If  this
	      option  is zero (the default) the text is broken into lines only
	      at newline characters.  However, if this option is non-zero then
	      any  line	 that  would  be longer than lineLength is broken just
	      before a space character to make the  line  shorter  than	 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 ...?
	      pathName create window coordList ?option value ...?
       The arguments x and y or coordList (which must have two elements) spec‐
       ify  the coordinates of a point used to position the window on the dis‐
       play, as controlled by the -anchor option.  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. Theoretically, a window item becomes the current item when  the
       mouse  pointer  is  over	 any part of its bounding box, but in practice
       this typically does not happen because the mouse pointer ceases	to  be
       over the canvas at that point.

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

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

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

       -window pathName
	      Specifies	 the  window  to associate with this item.  The window
	      specified by pathName must either be a child of the canvas  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. Also note
       that window items, unlike other canvas items, are not clipped for  dis‐
       play  by	 their	containing canvas's border, and are instead clipped by
       the parent widget of the window specified by the -window	 option;  when
       the  parent  widget  is the canvas, this means that the window item can
       overlap the canvas's border.

APPLICATION-DEFINED ITEM TYPES
       It is possible for individual applications to define new item types for
       canvas  widgets using C code.  See the documentation for Tk_CreateItem‐
       Type.

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

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

SEE ALSO
       bind(n), font(n), image(n), scrollbar(n)

KEYWORDS
       canvas, widget

Tk				      8.3			     canvas(n)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Slackware

List of man pages available for Slackware

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