NAME

       eps -  Encapsulated PostScript canvas item.


SYNOPSIS

       canvas create eps x y ?option value?...
_________________________________________________________________


DESCRIPTION

       The  eps canvas item lets you place encapulated PostScript
       (EPS) on a canvas, controlling  its  size  and  placement.
       The EPS item is displayed either as a solid rectangle or a
       preview image.  The preview image is designated in one  of
       two  ways:  1)  the EPS file contains an ASCII hexidecimal
       preview, or 2) a Tk photo image.  When the  canvas  gener­
       ates  PostScript output, the EPS will be inserted with the
       proper translation and scaling to match that  of  the  EPS
       item.  So can use the canvas widget as a page layout tool.


EXAMPLE

       Let's say you have for PostScript  files  of  four  graphs
       which you want to tile two-by-two on a single page.  Maybe
       you'd like to annotate the graphs by putting a caption  at
       the bottom of each graph.

       Normally,  you would have to resort to an external tool or
       write your own PostScript program.  The  eps  canvas  item
       lets  you do this through Tk's canvas widget.  An eps item
       displays an image (or rectangle) representing the encapsu­
       lated  PostScript file.  It also scales and translates the
       EPS file when the canvas is printed.


SYNTAX

              canvas create eps x y ?option value?...

       The eps item creates a new canvas item. Canvas is the name
       of a canvas widget.  You must supply the X-Y coordinate of
       the new eps item.  How the coordinate  is  exactly  inter­
       pretered  is controlled by the -anchor option (see below).

       Additional options may be specified on the command line to
       configure aspects of the eps item such as its color, stip­
       ple, and font.  The following option and value  pairs  are
       valid.

       -anchor anchor
              Tells  how to position the EPS item relative to its
              X-Y coordinate.  The default is center.

       -background color
              Sets the background color of the EPS rectangle.

              Sets the width of the 3-D border around the outside
              edge of the item.  The -relief option determines if
              the border is to be drawn.  The default is 0.

       -file fileName
              Specifies the name of the EPS file.  The first line
              of an EPS file must start with "%!PS" and contain a
              "EPS" version specification.  The other requirement
              is  that  there  be  a "%%BoundingBox:" entry which
              contains four integers representing the  lower-left
              and  upper-right  coordinates  of the area bounding
              the EPS.  The default is "".

       -font fontName
              Specifies the font of the  title.  The  default  is
              *-Helvetica-Bold-R-Normal-*-18-180-*.

       -foreground color
              Specifies  the  foreground color of the EPS rectan­
              gle.  The option matters  only  when  the  -stipple
              option is set.  The default is white.

       -height pixels
              Specifies  the  height  EPS  item.  If pixels is 0,
              then the height is determined from  the  PostScript
              "BoundingBox:"  entry in the EPS file.  The default
              is 0.

       -image photo
              Specifies the name of a Tk photo image to  be  dis­
              played  as  in  the  item as a preview image.  This
              option overrides any preview specification found in
              the EPS file.  The default is "".

       -justify justify
              Specifies  how the title should be justified.  This
              matters only when the title contains more than  one
              line  of text. Justify must be left, right, or cen­
              ter.  The default is center.

       -relief relief
              Specifies the 3-D effect for the EPS item.   Relief
              specifies  how  the  item should appear relative to
              canvas; for example, raised means the  item  should
              appear to protrude.  The default is flat.

       -shadowcolor color
              Specifies the color of the drop shadow used for the
              title.  The option with  the  -shadowoffset  option
              control  how  the title's drop shadow appears.  The
              default is grey.

              Specifies the offset of the drop  shadow  from  the
              title's  text.   If  pixels is 0, no shadow will be
              seen.  The default is 0.

       -showimage boolean
              Indicates whether to display the image preview  (if
              one exists), or a simple rectangle.  The default is
              yes.

       -stipple bitmap
              Specifies a bitmap to used to stipple the rectangle
              representing the EPS item.  The default is "".

       -title string
              Sets  the  title of the EPS item.  If string is "",
              then the title specified by the PostScript "Title:"
              entry  is  used.   You  can set the string a single
              space to display no title.  The default is "".

       -titleanchor anchor
              Tells how to position the title  within  EPS  item.
              The default is n.

       -titlecolor color
              Specifies  the  color of the title.  The default is
              white.

       -titlerotate degrees
              Sets the rotation of the title.  Degrees is a  real
              number  representing  the  angle  of rotation.  The
              title is first rotated in  space  and  then  placed
              according   to   the  -titleanchor  position.   The
              default rotation is 0.0.

       -width pixels
              Specifies the width EPS item.  If pixels is 0, then
              the width is determined from the PostScript "Bound­
              ingBox:" entry in the EPS file.  The default is  0.
              5i.


EXAMPLE

       The graph command creates a new graph.

              # Create a new graph.  Plotting area is black.
              graph .g -plotbackground black

       A new Tcl command .g is also created.  This command can be
       used to query and  modify  the  graph.   For  example,  to
       change  the  title  of the graph to "My Plot", you use the
       new command and the graph's configure operation.

              # Change the title.
              .g configure -title "My Plot"

       component  you  use  the component's name. For example, to
       add data elements, you use the new command and the element
       component.

              # Create a new element named "line1"
              .g element create line1 \
                   -xdata { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 } \
                   -ydata { 26.18 50.46 72.85 93.31 111.86 128.47 143.14
                        155.85 166.60 175.38 }

       The  element's  X  and  Y  coordinates are specified using
       lists of numbers.  Alternately, BLT vectors could be  used
       to hold the X-Y coordinates.

              # Create two vectors and add them to the graph.
              vector xVec yVec
              xVec set { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 }
              yVec set { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85
                   166.60 175.38 }
              .g element create line1 -xdata xVec -ydata yVec

       The  advantage  of  using  vectors is that when you modify
       one, the graph is automatically redrawn to display the new
       values.

              # Change the X-Y coordinates of the first point.
              set xVec(0) 0.18
              set yVec(0) 25.18

       An  element named line1 is now created in .g.  By default,
       the element's label in the legend will be also line1.  You
       can  change  the  label, or specify no legend entry, again
       using the element's configure operation.

              # Don't display "line1" in the legend.
              .g element configure line1 -label ""

       You can configure more than just the element's label.   An
       element  has many attributes such as symbol type and size,
       dashed or solid lines, colors, line width, etc.

              .g element configure line1 -symbol square -color red \
                   -dashes { 2 4 2 } -linewidth 2 -pixels 2c

       Four coordinate axes are automatically created: x, x2,  y,
       and y2.  And by default, elements are mapped onto the axes
       x and y.  This can be changed with  the  -mapx  and  -mapy
       options.

              # Map "line1" on the alternate Y-axis "y2".
              .g element configure line1 -mapy y2

       Axes can be configured in many ways too.  For example, you

       the axis component.

              # Y-axis is log scale.
              .g axis configure y -logscale yes

       One important way axes are used is to zoom in on a partic­
       ular data region.  Zooming is done  by  simply  specifying
       new  axis  limits  using  the  -min and -max configuration
       options.

              .g axis configure x -min 1.0 -max 1.5
              .g axis configure y -min 12.0 -max 55.15

       To zoom interactively, you link the axis configure  opera­
       tions  with  some  user  interaction (such as pressing the
       mouse button), using the bind command.  To convert between
       screen  and graph coordinates, use the invtransform opera­
       tion.

              # Click the button to set a new minimum
              bind .g <ButtonPress-1> {
                  %W axis configure x -min [%W axis invtransform x %x]
                  %W axis configure x -min [%W axis invtransform x %y]
              }

       By default, the limits of the  axis  are  determined  from
       data values.  To reset back to the default limits, set the
       -min and -max options to the empty value.

              # Reset the axes to autoscale again.
              .g axis configure x -min {} -max {}
              .g axis configure y -min {} -max {}

       By default, the legend is drawn in the right margin.   You
       can  change this or any legend configuration options using
       the legend component.

              # Configure the legend font, color, and relief
              .g legend configure -position left -relief raised \
                   -font fixed -fg blue

       To prevent the legend from being displayed,  turn  on  the
       -hide option.

              # Don't display the legend.
              .g legend configure -hide yes

       The  graph  widget  has  simple  drawing procedures called
       markers.  They can be used to highlight or  annotate  data
       in  the graph. The types of markers available are bitmaps,
       images, polygons, lines, or windows.  Markers can be used,
       for example, to mark or brush points.  In this example, is
       a text marker that labels the data first  point.   Markers


              # Create a label for the first data point of "line1".
              .g marker create text -name first_marker -coords { 0.2 26.18 } \
                   -text "start" -anchor se -xoffset -10 -yoffset -10

       This  creates  a  text marker named first_marker.  It will
       display the text "start" near the coordinates of the first
       data  point.   The -anchor, -xoffset, and -yoffset options
       are used to display the marker above and to  the  left  of
       the  data  point,  so that the data point isn't covered by
       the marker.  By default, markers are drawn last, on top of
       data.  You can change this with the -under option.

              # Draw the label before elements are drawn.
              .g marker configure first_marker -under yes

       You can add cross hairs or grid lines using the crosshairs
       and grid components.

              # Display both cross hairs and grid lines.
              .g crosshairs configure -hide no -color red
              .g grid configure -hide no -dashes { 2 2 }

       Finally, to get hardcopy of the graph, use the  postscript
       component.

              # Print the graph into file "file.ps"
              .g postscript output file.ps -maxpect yes -decorations no

       This  generates a file file.ps containing the encapsulated
       PostScript of the graph.   The  option  -maxpect  says  to
       scale  the  plot to the size of the page.  Turning off the
       -decorations option denotes that no borders or color back­
       grounds  should  be drawn (i.e. the background of the mar­
       gins, legend, and plotting area will be white).


GRAPH OPERATIONS

       pathName axis operation ?arg?...
              See the AXIS COMPONENTS section.

       pathName bar elemName ?option value?...
              Creates a new barchart element elemName.   It's  an
              error  if  an element elemName already exists.  See
              the manual for  barchart  for  details  about  what
              option and value pairs are valid.

       pathName cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may be  any  option
              described below for the configure operation.

       pathName configure ?option value?...
              Queries  or  modifies  the configuration options of

              describing  the  current  options  for  pathName is
              returned.  If option is specified, but  not  value,
              then  a list describing option is returned.  If one
              or more option and value pairs are specified,  then
              for  each  pair, the option option is set to value.
              The following options are valid.

              -background color
                     Sets the background color. This includes the
                     margins  and  legend,  but  not the plotting
                     area.

              -borderwidth pixels
                     Sets the width of the 3-D border around  the
                     outside  edge  of  the  widget.  The -relief
                     option determines if the  border  is  to  be
                     drawn.  The default is 2.

              -bottommargin pixels
                     Specifies  the  size of the margin below the
                     X-coordinate axis.  If pixels is 0, the size
                     of  the  margin  is  selected automatically.
                     The default is 0.

              -bufferelements boolean
                     Indicates  whether  an  internal  pixmap  to
                     buffer  the  display of data elements should
                     be used.  If boolean is true, data  elements
                     are  drawn  to  an  internal  pixmap.   This
                     option is especially useful when  the  graph
                     is redrawn frequently while the remains data
                     unchanged  (for  example,  moving  a  marker
                     across  the  plot).  See the SPEED TIPS sec­
                     tion.  The default is 1.

              -cursor cursor
                     Specifies the widget's cursor.  The  default
                     cursor is crosshair.

              -font fontName
                     Specifies  the  font of the graph title. The
                     default      is      *-Helvetica-Bold-R-Nor­
                     mal-*-18-180-*.

              -halo pixels
                     Specifies  a  maximum  distance  to consider
                     when searching for the  closest  data  point
                     (see the element's closest operation below).
                     Data points further  than  pixels  away  are
                     ignored.  The default is 0.5i.

              -height pixels
                     Specifies  the  requested  height of widget.


              -invertxy boolean
                     Indicates whether the placement  X-axis  and
                     Y-axis  should  be  inverted.  If boolean is
                     true, the X and Y  axes  are  swapped.   The
                     default is 0.

              -justify justify
                     Specifies how the title should be justified.
                     This matters only when  the  title  contains
                     more  than one line of text. Justify must be
                     left, right, or center.  The default is cen­
                     ter.

              -leftmargin pixels
                     Sets  the  size  of the margin from the left
                     edge of the window to the Y-coordinate axis.
                     If pixels is 0, the size is calculated auto­
                     matically.  The default is 0.

              -plotbackground color
                     Specifies the background color of the  plot­
                     ting area.  The default is white.

              -plotborderwidth pixels
                     Sets  the width of the 3-D border around the
                     plotting  area.   The   -plotrelief   option
                     determines   if  a  border  is  drawn.   The
                     default is 2.

              -plotpadx pad
                     Sets the amount of padding to  be  added  to
                     the  left  and  right  sides of the plotting
                     area.  Pad can be  a  list  of  one  or  two
                     screen  distances.  If pad has two elements,
                     the left side of the plotting area entry  is
                     padded  by  the first distance and the right
                     side by the second.  If pad is just one dis­
                     tance,  both  the  left  and right sides are
                     padded evenly.  The default is 8.

              -plotpady pad
                     Sets the amount of padding to  be  added  to
                     the  top  and  bottom  of the plotting area.
                     Pad can be a list of one or two screen  dis­
                     tances.  If pad has two elements, the top of
                     the plotting area is  padded  by  the  first
                     distance  and  the bottom by the second.  If
                     pad is just one distance, both the  top  and
                     bottom are padded evenly.  The default is 8.

              -plotrelief relief
                     Specifies the 3-D effect  for  the  plotting

                     the plotting area should appear relative  to
                     rest of the graph; for example, raised means
                     the plot should appear to protrude from  the
                     graph, relative to the surface of the graph.
                     The default is sunken.

              -relief relief
                     Specifies the 3-D effect for the graph  wid­
                     get.   Relief specifies how the graph should
                     appear relative to widget it is packed into;
                     for  example,  raised means the graph should
                     appear to protrude.  The default is flat.

              -rightmargin pixels
                     Sets the size of margin  from  the  plotting
                     area  to  the  right edge of the window.  By
                     default, the legend is drawn in this margin.
                     If  pixels  is  than  1,  the margin size is
                     selected automatically.

              -takefocus focus
                     Provides information used  when  moving  the
                     focus  from  window  to  window via keyboard
                     traversal (e.g.,  Tab  and  Shift-Tab).   If
                     focus  is  0,  this  means  that this window
                     should be skipped entirely  during  keyboard
                     traversal.   1  means  that  the this window
                     should always receive the input  focus.   An
                     empty value means that the traversal scripts
                     make the decision whether to  focus  on  the
                     window.  The default is "".

              -tile image
                     Specifies a tiled background for the widget.
                     If image isn't "", the background  is  tiled
                     using  image.   Otherwise,  the normal back­
                     ground color is drawn (see  the  -background
                     option).   Image  must  be  an image created
                     using the Tk image command.  The default  is
                     "".

              -title text
                     Sets  the  title  to text. If text is "", no
                     title will be displayed.

              -topmargin pixels
                     Specifies the size of the margin  above  the
                     x2 axis.  If pixels is 0, the margin size is
                     calculated automatically.

              -width pixels
                     Specifies the requested width of the widget.
                     The default is 5i.

              See the CROSSHAIRS COMPONENT section.

       pathName element operation ?arg?...
              See the ELEMENT COMPONENTS section.

       pathName extents item
              Reports  the  size  of  a  particular  items in the
              graph.  Item must be either  leftmargin,  rightmar­
              gin,   topmargin,   bottommargin,   plotwidth,   or
              plotheight.

       pathName grid operation ?arg?...
              See the GRID COMPONENT section.

       pathName invtransform winX winY
              Performs an inverse coordinate transformation, map­
              ping  window coordinates back to graph coordinates,
              using the standard X-axis and  Y-axis.   Returns  a
              list of containing the X-Y y graph coordinates.

       pathName inside x y
              Returns  1  is  the designated screen coordinate (x
              and y) is inside the plotting area and 0 otherwise.

       pathName legend operation ?arg?...
              See the LEGEND COMPONENT section.

       pathName line operation arg...
              The operation is the same as element.

       pathName marker operation ?arg?...
              See the MARKER COMPONENTS section.

       pathName postscript operation ?arg?...
              See the POSTSCRIPT COMPONENT section.

       pathName snap photoName
              Takes  a  snapshot of the graph and stores the con­
              tents in the photo image photoName.   PhotoName  is
              the  name  of  a  Tk  photo image that must already
              exist.

       pathName transform x y
              Performs a coordinate transformation, mapping graph
              coordinates  to window coordinates, using the stan­
              dard X-axis and Y-axis.  Returns a list  containing
              the X-Y screen coordinates.

       pathName xaxis operation ?arg?...

       pathName x2axis operation ?arg?...


       pathName y2axis operation ?arg?...
              See the AXIS COMPONENTS section.


GRAPH COMPONENTS

       A  graph  is  composed  of  several components: coordinate
       axes,  data   elements,   legend,   grid,   cross   hairs,
       postscript, and annotation markers. Instead of one big set
       of configuration options and operations, the graph is par­
       titioned,  where  each component has its own configuration
       options and  operations  that  specifically  control  that
       aspect or part of the graph.

   AXIS COMPONENTS
       Four   coordinate  axes  are  automatically  created:  two
       X-coordinate axes (x and x2) and two Y-coordinate axes (y,
       and  y2).  By default, the axis x is located in the bottom
       margin, y in the left margin, x2 in the top margin, and y2
       in the right margin.

       An  axis consists of the axis line, title, major and minor
       ticks, and tick labels.  Major ticks are drawn at  uniform
       intervals  along  the axis.  Each tick is labeled with its
       coordinate value.  Minor ticks are drawn at uniform inter­
       vals within major ticks.

       The  range  of  the  axis  controls what region of data is
       plotted.  Data points outside the minimum and maximum lim­
       its  of the axis are not plotted.  By default, the minimum
       and maximum limits are determined from the data,  but  you
       can reset either limit.

       You  can  create  and use several axes. To create an axis,
       invoke the axis component and its create operation.

              # Create a new axis called "tempAxis"
              .g axis create tempAxis

       You map data elements to an axis using the element's -mapy
       and  -mapx configuration options. They specify the coordi­
       nate axes an element is mapped onto.

              # Now map the tempAxis data to this axis.
              .g element create "e1" -xdata $x -ydata $y -mapy tempAxis

       While you can create many axes, only four can be displayed
       simultaneously. They are drawn in each of the margins sur­
       rounding the plotting area.  The axes x and y are drawn in
       the  bottom and left margins. The axes x2 and y2 are drawn
       in top and right margins.  Only  x  and  y  are  shown  by
       default. Note that the axes can have different scales.

       To  display  a  different  axis,  you  invoke  one  of the

       The  use  operation designates the axis to be drawn in the
       corresponding margin: xaxis in the bottom,  yaxis  in  the
       left, x2axis in the top, and y2axis in the right.

              # Display the axis tempAxis in the left margin.
              .g yaxis use tempAxis

       You can configure axes in many ways. The axis scale can be
       linear or logarithmic.  The  values  along  the  axis  can
       either  monotonically  increase  or decrease.  If you need
       custom tick labels, you can specify  a  Tcl  procedure  to
       format  the  label  any way you wish.  You can control how
       ticks are drawn, by changing the major  tick  interval  or
       the  number  of  minor  ticks.  You can define non-uniform
       tick intervals, such as for time-series plots.

       pathName axis cget axisName option
              Returns the current value of the  option  given  by
              option  for  axisName.   Option  may  be any option
              described below for the axis configure operation.

       pathName axis configure axisName ?axisName?... ?option
              value?...
              Queries or modifies the  configuration  options  of
              axisName.   Several axes can be changed.  If option
              isn't specified, a list describing all the  current
              options  for  axisName  is  returned.  If option is
              specified, but not value, then  a  list  describing
              option  is  returned.   If  one  or more option and
              value pairs are specified, then for each pair,  the
              axis  option option is set to value.  The following
              options are valid for axes.

              -color color
                     Sets the color of the axis and tick  labels.
                     The default is black.

              -command prefix
                     Specifies  a  Tcl command to be invoked when
                     formatting the axis tick labels. Prefix is a
                     string containing the name of a Tcl proc and
                     any extra arguments for the procedure.  This
                     command  is  invoked  for each major tick on
                     the  axis.   Two  additional  arguments  are
                     passed to the procedure: the pathname of the
                     widget and the current the numeric value  of
                     the tick.  The procedure returns the format­
                     ted tick label.  If "" is returned, no label
                     will  appear  next to the tick.  You can get
                     the standard tick labels  again  by  setting
                     prefix to "".  The default is "".

                     while the graph is redrawn.  You  may  query
                     configuration  options.   But  do  not them,
                     because this can have unexpected results.

              -descending boolean
                     Indicates whether the values along the  axis
                     are  monotonically increasing or decreasing.
                     If boolean is true, the axis values will  be
                     decreasing.  The default is 0.

              -hide boolean
                     Indicates whether the axis is displayed.

              -justify justify
                     Specifies  how the axis title should be jus­
                     tified.  This matters  only  when  the  axis
                     title  contains  more than one line of text.
                     Justify must be left, right, or center.  The
                     default is center.

              -limits formatStr
                     Specifies  a printf-like description to for­
                     mat the minimum and maximum  limits  of  the
                     axis.   The  limits  are  displayed  at  the
                     top/bottom or left/right sides of the  plot­
                     ting  area.   FormatStr  is a list of one or
                     two format descriptions.  If one description
                     is  supplied,  both  the minimum and maximum
                     limits are formatted in the  same  way.   If
                     two, the first designates the format for the
                     minimum limit, the second for  the  maximum.
                     If  ""  is given as either description, then
                     the that limit will not be  displayed.   The
                     default is "".

              -linewidth pixels
                     Sets  the  width of the axis and tick lines.
                     The default is 1 pixel.

              -logscale boolean
                     Indicates whether the scale of the  axis  is
                     logarithmic  or linear.  If boolean is true,
                     the axis is logarithmic.  The default  scale
                     is linear.

              -loose boolean
                     Indicates  whether  the  limits  of the axis
                     should fit the data points tightly,  at  the
                     outermost  data  points,  or loosely, at the
                     outer tick intervals.  This is relevant only
                     when  the axis limit is automatically calcu­
                     lated.  If boolean is true, the  axis  range
                     is "loose".  The default is 0.

                     Specifies where to display major axis ticks.
                     You can use this option to display ticks  at
                     non-uniform  intervals.  MajorList is a list
                     of axis coordinates designating the location
                     of  major  ticks.  No minor ticks are drawn.
                     If majorList is  "",  major  ticks  will  be
                     automatically computed. The default is "".

              -max value
                     Sets  the  maximum  limit  of axisName.  Any
                     data point greater than value  is  not  dis­
                     played.   If  value is "", the maximum limit
                     is calculated using the largest data  value.
                     The default is "".

              -min value
                     Sets the minimum limit of axisName. Any data
                     point less than value is not displayed.   If
                     value is "", the minimum limit is calculated
                     using the smallest data value.  The  default
                     is "".

              -minorticks minorList
                     Specifies where to display minor axis ticks.
                     You can use this  option  to  display  minor
                     ticks at non-uniform intervals. MinorList is
                     a list of real values, ranging from  0.0  to
                     1.0,  designating  the  placement of a minor
                     tick.  No  minor  ticks  are  drawn  if  the
                     -majortick option is also set.  If minorList
                     is "", minor  ticks  will  be  automatically
                     computed. The default is "".

              -rotate theta
                     Specifies the how many degrees to rotate the
                     axis tick labels.  Theta  is  a  real  value
                     representing the number of degrees to rotate
                     the  tick  labels.   The  default   is   0.0
                     degrees.

              -showticks boolean
                     Indicates   whether  axis  ticks  should  be
                     drawn. If boolean is true, ticks are  drawn.
                     If  false,  only the axis line is drawn. The
                     default is 1.

              -stepsize value
                     Specifies the interval  between  major  axis
                     ticks.   If  value  isn't  a  valid interval
                     (must be less  than  the  axis  range),  the
                     request  is  ignored  and  the  step size is
                     automatically calculated.

                     Indicates how many minor axis ticks  are  to
                     be  drawn.   For  example, if number is two,
                     only one minor tick is drawn.  If number  is
                     one,  no  minor  ticks  are  displayed.  The
                     default is 2.

              -tickfont fontName
                     Specifies the font for axis tick labels. The
                     default  is *-Courier-Bold-R-Normal-*-100-*.

              -ticklength pixels
                     Sets the length of  major  and  minor  ticks
                     (minor  ticks  are  half the length of major
                     ticks). If pixels is  less  than  zero,  the
                     axis  will  be  inverted  with  ticks  drawn
                     pointing towards the plot.  The  default  is
                     0.1i.

              -title text
                     Sets  the  title of the axis. If text is "",
                     no axis title will be displayed.

              -titlecolor color
                     Sets  the  color  of  the  axis  title.  The
                     default is black.

              -titlefont fontName
                     Specifies  the  font  for  axis  title.  The
                     default      is      *-Helvetica-Bold-R-Nor­
                     mal-*-14-140-*.

              Axis  configuration  options  may be also be set by
              the option command.  The resource  class  is  Axis.
              The  resource names are the names of the axes (such
              as x or x2).

                     option add *Graph.Axis.Color  blue
                     option add *Graph.x.LogScale  true
                     option add *Graph.x2.LogScale false

       pathName axis create axisName ?option value?...
              Creates a new axis by the name axisName.   No  axis
              by  the  same  name  can  already exist. Option and
              value are described in above in the axis  configure
              operation.

       pathName axis delete ?axisName?...
              Deletes  the  named  axes.  An  axis  is not really
              deleted until it is not longer in use, so it's safe
              to delete axes mapped to elements.

              Performs  the  inverse transformation, changing the
              screen coordinate value to a graph coordinate, map­
              ping  the  value  mapped  to axisName.  Returns the
              graph coordinate.

       pathName axis limits axisName
              Returns a list of the minimum  and  maximum  limits
              for axisName.  The order of the list is min max.

       pathName axis names ?pattern?...
              Returns  a  list of axes matching zero or more pat­
              terns.  If no pattern argument is give,  the  names
              of all axes are returned.

       pathName axis transform axisName value
              Transforms the coordinate value to a screen coordi­
              nate by mapping the it to  axisName.   Returns  the
              transformed screen coordinate.

       Only  four  axes  can  be  displayed  simultaneously.   By
       default, they are x, y, x2, and y2.  You  can  swap  in  a
       different axis with use operation of the special axis com­
       ponents: xaxis, x2axis, yaxis, and y2axis.

              .g create axis temp
              .g create axis time
              ...
              .g xaxis use temp
              .g yaxis use time

       Only the axes specified  for  use  are  displayed  on  the
       screen.

       The xaxis, x2axis, yaxis, and y2axis components operate on
       an axis location rather than a specific axis like the more
       general  axis component does.  The xaxis component manages
       the X-axis located in the  bottom  margin  (whatever  axis
       that  happens  to be).  Likewise, yaxis uses the Y-axis in
       the left margin, x2axis the top  X-axis,  and  y2axis  the
       right Y-axis.

       They  implicitly  control the axis that is currently using
       to that location.  By default,  xaxis  uses  the  x  axis,
       yaxis  uses  y, x2axis uses x2, and y2axis uses y2.  These
       components can be  more  convenient  to  use  than  always
       determining  what  axes are current being displayed by the
       graph.

       The following operations are available for axes. They mir­
       ror  exactly  the  operations  of the axis component.  The
       axis argument must be xaxis, x2axis, yaxis, or y2axis.


       pathName axis configure ?option value?...

       pathName axis invtransform value

       pathName axis limits

       pathName axis transform value

       pathName axis use ?axisName?
              Designates the axis axisName is to be displayed  at
              this  location.  AxisName can not be already in use
              at another location.  This command returns the name
              of the axis currently using this location.

   CROSSHAIRS COMPONENT
       Cross  hairs consist of two intersecting lines (one verti­
       cal and one horizontal) drawn completely across the  plot­
       ting  area.   They are used to position the mouse in rela­
       tion to the coordinate axes.  Cross hairs differ from line
       markers  in  that  they  are implemented using XOR drawing
       primitives.  This means that they can be quickly drawn and
       erased without redrawing the entire graph.

       The following operations are available for cross hairs:

       pathName crosshairs cget option
              Returns  the  current value of the cross hairs con­
              figuration option given by option.  Option  may  be
              any option described below for the cross hairs con­
              figure operation.

       pathName crosshairs configure ?option value?...
              Queries or modifies the  configuration  options  of
              the cross hairs.  If option isn't specified, a list
              describing all the current options  for  the  cross
              hairs is returned.  If option is specified, but not
              value, then a list describing option  is  returned.
              If  one  or  more option and value pairs are speci­
              fied, then for each pair, the  cross  hairs  option
              option  is set to value.  The following options are
              available for cross hairs.

              -color color
                     Sets the color  of  the  cross  hairs.   The
                     default is black.

              -dashes dashList
                     Sets  the  dash  style  of  the cross hairs.
                     DashList is a list of up to 11 numbers  that
                     alternately  represent  the  lengths  of the
                     dashes and gaps on  the  cross  hair  lines.
                     Each  number  must be between 1 and 255.  If

                     solid lines.

              -hide boolean
                     Indicates  whether cross hairs are drawn. If
                     boolean is true, cross hairs are not  drawn.
                     The default is yes.

              -linewidth pixels
                     Set  the width of the cross hair lines.  The
                     default is 1.

              -position pos
                     Specifies  the  screen  position  where  the
                     cross  hairs  intersect.  Pos must be in the
                     form "@x,y", where x and y  are  the  window
                     coordinates of the intersection.

              Cross  hairs  configuration  options may be also be
              set by the option command.  The resource  name  and
              class are crosshairs and Crosshairs respectively.

                     option add *Graph.Crosshairs.LineWidth 2
                     option add *Graph.Crosshairs.Color     red

       pathName crosshairs off
              Turns off the cross hairs.

       pathName crosshairs on
              Turns on the display of the cross hairs.

       pathName crosshairs toggle
              Toggles  the  current  state  of  the  cross hairs,
              alternately mapping and unmapping the cross  hairs.

   ELEMENT COMPONENTS
       A  data  element  represents a set of data.  It contains x
       and y vectors  containing  the  coordinates  of  the  data
       points.   Elements  can be displayed with a symbol at each
       data point and lines connecting the points.  Elements also
       control  the  appearance  of  the data, such as the symbol
       type, line width, color etc.

       When new data elements are created, they are automatically
       added  to a list of displayed elements.   The display list
       controls what elements are drawn and in what order.

       The following operations are available for elements.

       pathName element activate elemName ?index?...
              Specifies the data points of element elemName to be
              drawn  using  active foreground and background col­
              ors.  ElemName is the name of the element and index

              point. If no indices  are  present  then  all  data
              points become active.

       pathName element cget elemName option
              Returns the current value of the element configura­
              tion option given by option.  Option may be any  of
              the options described below for the element config­
              ure operation.

       pathName element closest x y  varName  ?option  value?...
              ?elem­ Name?...
              Finds the data point closest to the window  coordi­
              nates x and y in the element elemName.  ElemName is
              the name of an element, that must  not  be  hidden.
              If no elements are specified, then all visible ele­
              ments are searched.  It returns via the array vari­
              able  varName  the name of the closest element, the
              index of its closest point, and the  graph  coordi­
              nates  of  the  point.  Returns 0, if no data point
              within the threshold distance can be found,  other­
              wise  1  is  returned.   The following option-value
              pairs are available.

              -halo pixels
                     Specifies   a   threshold   distance   where
                     selected data points are ignored.  Pixels is
                     a valid screen distance, such as 2 or  1.2i.
                     If  this  option  isn't  specified,  then it
                     defaults to the value of the  graph's  -halo
                     option.

              -interpolate boolean
                     Indicates  that  both  the  data  points and
                     interpolated points along the  line  segment
                     formed  should be considered.  If boolean is
                     true,  the  closest  line  segment  will  be
                     selected  instead  of  the closest point. If
                     this   option   isn't   specified,   boolean
                     defaults to 0.

       pathName   element   configure   elemName   ?elemName...
              ?option value?...
              Queries  or  modifies the configuration options for
              elements.  Several elements can be modified at  the
              same  time.  If  option  isn't  specified,  a  list
              describing all the current options for elemName  is
              returned.   If  option is specified, but not value,
              then  a  list  describing  the  option  option   is
              returned.   If  one  or more option and value pairs
              are specified, then  for  each  pair,  the  element
              option  option  is  set  to  value.   The following
              options are valid for elements.

                     Specifies pen to use to draw active element.
                     If penName is "", no active elements will be
                     drawn.  The default is activeLine.

              -color color
                     Sets the color of the traces connecting  the
                     data points.

              -dashes dashList
                     Sets  the  dash style of element line. Dash­
                     List is a list of  up  to  11  numbers  that
                     alternately  represent  the  lengths  of the
                     dashes and gaps on the element  line.   Each
                     number  must be between 1 and 255.  If dash­
                     List is "", the lines will be solid.

              -data coordList
                     Specifies the X-Y coordinates of  the  data.
                     CoordList  is  a list of numeric expressions
                     representing the  X-Y  coordinate  pairs  of
                     each data point.

              -fill color
                     Sets  the  interior  color  of  symbols.  If
                     color is "", then the interior of the symbol
                     is  transparent.  If color is defcolor, then
                     the color will be the  same  as  the  -color
                     option.  The default is defcolor.

              -hide boolean
                     Indicates  whether the element is displayed.
                     The default is no.

              -label text
                     Sets the element's label in the legend.   If
                     text  is  "", the element will have no entry
                     in the legend.  The  default  label  is  the
                     element's name.

              -linewidth pixels
                     Sets  the  width  of  the  connecting  lines
                     between data points.  If  pixels  is  0,  no
                     connecting  lines will be drawn between sym­
                     bols.  The default is 0.

              -mapx xAxis
                     Selects the  X-axis  to  map  the  element's
                     X-coordinates  onto.  XAxis must be the name
                     of an axis.  The default is x.

              -mapy yAxis
                     Selects the  Y-axis  to  map  the  element's
                     Y-coordinates  onto.  YAxis must be the name


              -offdash color
                     Sets the color of the  stripes  when  traces
                     are  dashed  (see  the  -dashes option).  If
                     color is "", then the "off" pixels will rep­
                     resent gaps instead of stripes.  If color is
                     defcolor, then the color will be the same as
                     the -color option.  The default is defcolor.

              -outline color
                     Sets the color or the  outline  around  each
                     symbol.   If color is "", then no outline is
                     drawn. If color is defcolor, then the  color
                     will  be the same as the -color option.  The
                     default is defcolor.

              -outlinewidth pixels
                     Sets the width of the outline bordering each
                     symbol.   If pixels is 0, no outline will be
                     drawn. The default is 1.

              -pixels pixels
                     Sets the size of symbols.  If pixels  is  0,
                     no  symbols  will  be drawn.  The default is
                     0.125i.

              -scalesymbols boolean
                     If boolean is true, the size of the  symbols
                     drawn for elemName will change with scale of
                     the X-axis and Y-axis.   At  the  time  this
                     option  is  set,  the  current ranges of the
                     axes are saved as the normalized scales (i.e
                     scale  factor  is  1.0)  and  the element is
                     drawn at its designated size (see the  -pix­
                     els  option).   As  the  scale  of  the axes
                     change, the symbol will be scaled  according
                     to  the  smaller  of  the  X-axis and Y-axis
                     scales.  If boolean is false, the  element's
                     symbols  are  drawn  at the designated size,
                     regardless of axis scales.  The  default  is
                     0.

              -smooth smooth
                     Specifies  how  connecting line segments are
                     drawn between data points.   Smooth  can  be
                     either  linear, step, natural, or quadratic.
                     If smooth is linear, a single  line  segment
                     is  drawn, connecting both data points. When
                     smooth is step, two line segments are drawn.
                     The  first is a horizontal line segment that
                     steps the next X-coordinate.  The second  is
                     a  vertical line, moving to the next Y-coor­
                     dinate.  Both natural and quadratic generate

                     natural, the segments are generated using  a
                     cubic  spline.   If  quadratic,  a quadratic
                     spline is used.  The default is linear.

              -styles styleList
                     Specifies what pen to use based on the range
                     of  weights  given.   StyleList is a list of
                     style specifications. Each style  specifica­
                     tion, in turn, is a list consisting of a pen
                     name, and optionally a minimum  and  maximum
                     range.   Data  points  whose weight (see the
                     -weight option) falls  in  this  range,  are
                     drawn  with this pen.  If no range is speci­
                     fied it defaults to the index of the pen  in
                     the  list.  Note that this affects only sym­
                     bol attributes.  Line  attributes,  such  as
                     line width, dashes, etc. are ignored.

              -symbol symbol
                     Specifies  the symbol for data points.  Sym­
                     bol can be either square,  circle,  diamond,
                     plus,  cross,  splus,  scross,  triangle, ""
                     (where no symbol is  drawn),  or  a  bitmap.
                     Bitmaps  are  specified  as "source ?mask?",
                     where source is the name of the bitmap,  and
                     mask  is  the  bitmap's  optional mask.  The
                     default is circle.

              -trace direction
                     Indicates whether connecting  lines  between
                     data  points  (whose X-coordinate values are
                     either increasing or decreasing) are  drawn.
                     Direction must be increasing, decreasing, or
                     both.  For example, if direction is increas­
                     ing,  connecting  lines  will  be drawn only
                     between those data points where X-coordinate
                     values  are  monotonically  increasing.   If
                     direction is both, connecting lines will  be
                     draw  between  all data points.  The default
                     is both.

              -weights wVec
                     Specifies the weights of the individual data
                     points.  This, with the list pen styles (see
                     the  -styles  option),  controls  how   data
                     points are drawn.  WVec is the name of a BLT
                     vector or a list of numeric expressions rep­
                     resenting the weights for each data point.

              -xdata xVec
                     Specifies  the  X-coordinates  of  the data.
                     XVec is the name of a BLT vector or  a  list
                     of numeric expressions.

                     Specifies  the  Y-coordinates  of  the data.
                     YVec is the name of a BLT vector or  a  list
                     of numeric expressions.

              Element  configuration  options  may also be set by
              the option command.  The resource class is Element.
              The resource name is the name of the element.

                     option add *Graph.Element.symbol line
                     option add *Graph.e1.symbol line

       pathName element create elemName ?option value?...
              Creates  a  new element elemName.  It's an error is
              an element elemName already exists.  If  additional
              arguments  are  present, they specify options valid
              for the element configure operation.

       pathName element deactivate elemName ?elemName?...
              Deactivates  all  the  elements  matching  pattern.
              Elements  whose  names  match  any  of the patterns
              given are redrawn using their normal colors.

       pathName element delete ?elemName?...
              Deletes all the named elements.  The graph is auto­
              matically redrawn.

       pathName element exists elemName
              Returns  1  if an element elemName currently exists
              and 0 otherwise.

       pathName element names ?pattern?...
              Returns the elements matching one or more  pattern.
              If  no  pattern is given, the names of all elements
              is returned.

       pathName element show ?nameList?
              Queries or modifies the element display list.   The
              element  display list designates the elements drawn
              and in what order. NameList is a list  of  elements
              to  be  displayed  in the order they are named.  If
              there is no nameList argument, the current  display
              list is returned.

       pathName element type elemName
              Returns  the type of elemName.  If the element is a
              bar element, the commands returns the string "bar",
              otherwise it returns "line".

   GRID COMPONENT
       Grid  lines  extend from the major and minor ticks of each
       axis horizontally or vertically across the plotting  area.


       pathName grid cget option
              Returns the current value of the grid line configu­
              ration option given by option.  Option may  be  any
              option described below for the grid configure oper­
              ation.

       pathName grid configure ?option value?...
              Queries or modifies the configuration  options  for
              grid  lines.   If  option  isn't  specified, a list
              describing all the current grid options  for  path­
              Name  is returned.  If option is specified, but not
              value, then a list describing option  is  returned.
              If  one  or  more option and value pairs are speci­
              fied, then for each  pair,  the  grid  line  option
              option  is set to value.  The following options are
              valid for grid lines.

              -color color
                     Sets the  color  of  the  grid  lines.   The
                     default is black.

              -dashes dashList
                     Sets the dash style of the grid lines. Dash­
                     List is a list of  up  to  11  numbers  that
                     alternately  represent  the  lengths  of the
                     dashes and gaps on  the  grid  lines.   Each
                     number  must be between 1 and 255.  If dash­
                     List is "", the grid will be solid lines.

              -hide boolean
                     Indicates whether the grid should be  drawn.
                     If  boolean  is  true,  grid  lines  are not
                     shown. The default is yes.

              -linewidth pixels
                     Sets the width of grid lines.   The  default
                     width is 1.

              -mapx xAxis
                     Specifies  the X-axis to display grid lines.
                     XAxis must be the  name  of  an  axis.   The
                     default is x.

              -mapy yAxis
                     Specifies  the Y-axis to display grid lines.
                     YAxis must be  the  name  of  an  axis.  The
                     default is y.

              -minor boolean
                     Indicates  whether  the grid lines should be
                     drawn for minor ticks.  If boolean is  true,
                     the   lines   will   appear  at  minor  tick



SPEED TIPS

       There may be cases where the graph needs to be  drawn  and
       updated  as quickly as possible.  If drawing speed becomes
       a big problem, here are a few tips to speed up displays.

       · Try to minimize the number of  data  points.   The  more
         data  points the looked at, the more work the graph must
         do.

       · If your data is generated as floating point values,  the
         time  required  to  convert  the data values to and from
         ASCII strings can be significant, especially when  there
         any  many  data  points.   You  can  avoid the redundant
         string-to-decimal conversions using the  C  API  to  BLT
         vectors.

       · Data elements without symbols are drawn faster than with
         symbols.  Set the data element's -symbol option to none.
         If  you  need to draw symbols, try using the simple sym­
         bols such as splus and scross.

       · Don't stipple or dash the element.  Solid lines are much
         faster.

       · If  you update data elements frequently, try turning off
         the widget's -bufferelements option.  When the graph  is
         first displayed, it draws data elements into an internal
         pixmap.  The pixmap acts as a cache, so  that  when  the
         graph  needs  to be redrawn again, and the data elements
         or coordinate axes haven't changed, the pixmap is simply
         copied  to  the  screen.  This is especially useful when
         you are using markers to highlight points and regions on
         the  graph.   But  if  the  graph is updated frequently,
         changing either the element data or coordinate axes, the
         buffering becomes redundant.


LIMITATIONS

       Auto-scale routines do not use requested min/max limits as
       boundaries when the axis is logarithmically scaled.

       The PostScript output generated  for  polygons  with  more
       than  1500  points  may exceed the limits of some printers
       (See PostScript Language Reference Manual, page 568).  The
       work-around  is to break the polygon into separate pieces.


FUTURE INCOMPATIBILITY

       The -mapped options are obsoleted  and  will  be  removed.
       You  can  achieve  the same results using the -hide option
       instead.

              # Works for now.


              # Instead use this.
              .g legend configure -hide yes


KEYWORDS

       graph, widget


Man(1) output converted with man2html