From 0c854c2841345e631ccb1b14c1f2703ba6274f7f Mon Sep 17 00:00:00 2001 From: William Joye Date: Thu, 16 Jun 2016 15:48:21 -0400 Subject: add html --- doc/barchart.html | 1640 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/graph.html | 1751 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/vector.html | 704 +++++++++++++++++++++ 3 files changed, 4095 insertions(+) create mode 100644 doc/barchart.html create mode 100644 doc/graph.html create mode 100644 doc/vector.html diff --git a/doc/barchart.html b/doc/barchart.html new file mode 100644 index 0000000..0f314c2 --- /dev/null +++ b/doc/barchart.html @@ -0,0 +1,1640 @@ + + +
+
+
+
+

SYNOPSIS

+       barchart pathName ?option value?...
+
+
+
+

DESCRIPTION

+       The  barchart  command creates a bar chart for plotting two-dimensional
+       data (X-Y coordinates). A bar chart is a  graphic  means  of  comparing
+       numbers by displaying bars of lengths proportional to the y-coordinates
+       of the points they represented.  The bar chart  has  many  configurable
+       components: coordinate axes, elements, legend, grid lines, cross hairs,
+       etc.  They allow you to customize the look and feel of the graph.
+
+
+
+

INTRODUCTION

+       The barchart command creates a new window for plotting  two-dimensional
+       data  (X-Y coordinates), using bars of various lengths to represent the
+       data points.  The bars are drawn in a rectangular area displayed in the
+       center  of  the new window.  This is the plotting area.  The coordinate
+       axes are drawn in  the  margins  surrounding  the  plotting  area.   By
+       default,  the  legend  is drawn in the right margin.  The title is dis-
+       played in top margin.
+
+       A barchart widget has several configurable components: coordinate axes,
+       data elements, legend, grid, cross hairs, pens, postscript, and annota-
+       tion markers.  Each component can be queried or modified.
+
+       axis       Up to four coordinate axes (two X-coordinate and two Y-coor-
+                 dinate axes) can be displayed, but you can create and use any
+                 number of axes. Axes control what region of data is displayed
+                 and  how  the  data is scaled. Each axis consists of the axis
+                 line, title, major and minor ticks,  and  tick  labels.  Tick
+                 labels display the value at each major tick.
+
+       crosshairs
+                 Cross  hairs  are used to position the mouse pointer relative
+                 to the X and Y  coordinate  axes.  Two  perpendicular  lines,
+                 intersecting  at  the  current  location of the mouse, extend
+                 across the plotting area to the coordinate axes.
+
+       element   An element represents a set of data to be plotted.   It  con-
+                 tains  an  x  and  y  vector  of values representing the data
+                 points.  Each data point is displayed  as  a  bar  where  the
+                 length  of the bar is proportional to the ordinate (Y-coordi-
+                 nate) of the data point.  The appearance of the bar, such  as
+                 its color, stipple, or relief is configurable.
+
+                 A  special  case exists when two or more data points have the
+                 same abscissa (X-coordinate).  By default, the bars are over-
+                 layed,  one  on  top of the other.  The bars are drawn in the
+                 order of the element display list.  But you can also  config-
+                 ure  the bars to be displayed in two other ways.  They may be
+                 displayed as a stack, where each bar (with the same abscissa)
+                 is  stacked  on  the previous.  Or they can be drawn side-by-
+                 side as thin bars.  The width of each bar is  a  function  of
+
+       pen       Pens define attributes for elements.  Data elements use  pens
+                 to  specify how they should be drawn.  A data element may use
+                 many pens at once.  Here the particular pen used for  a  data
+                 point  is  determined  from each element's weight vector (see
+                 the element's -weight and -style options).
+
+       postscript
+                 The widget can generate encapsulated PostScript output.  This
+                 component has several options to configure how the PostScript
+                 is generated.
+
+
+
+

SYNTAX

+       barchart pathName ?option value?...  The barchart command creates a new
+       window  pathName and makes it into a barchart widget.  At the time this
+       command is invoked, there must not exist a window named  pathName,  but
+       pathName's  parent  must exist.  Additional options may be specified on
+       the command line or in the option database to configure aspects of  the
+       graph  such  as its colors and font.  See the configure operation below
+       for the exact details about what option and value pairs are valid.
+
+       If successful, barchart returns the path name of the widget.   It  also
+       creates  a  new Tcl command by the same name.  You can use this command
+       to invoke various operations that query or modify the graph.  The  gen-
+       eral form is: pathName operation ?arg?...  Both operation and its argu-
+       ments determine the exact behavior  of  the  command.   The  operations
+       available  for  the graph are described in the BARCHART OPERATIONS sec-
+       tion.
+
+       The command can also be used to access components of the graph.   path-
+       Name component operation ?arg?...  The operation, now located after the
+       name of the component, is the function to be performed on  that  compo-
+       nent. Each component has its own set of operations that manipulate that
+       component.  They will be described below in their own sections.
+
+
+
+

EXAMPLE

+       The barchart command creates a new bar  chart.   #  Create  a  new  bar
+       chart.   Plotting  area  is black.  barchart .b -plotbackground black A
+       new Tcl command .b is created.  This command can be used to  query  and
+       modify the bar chart.  For example, to change the title of the graph to
+       "My Plot", you use the new command  and  the  configure  operation.   #
+       Change  the title.  .b configure -title "My Plot" To add data elements,
+       you use the command and the element component.  # Create a new  element
+       named  "e1" .b element create e1 \      -xdata { 1 2 3 4 5 6 7 8 9 10 }
+       \       -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-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 barchart.  vector xVector yVector xVector set { 1 2 3 4 5 6 7  8  9
+       10  } yVector set { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85
+            166.60 175.38 } n.b element create e1 -xdata xVector -ydata  yVec-
+       tor  The  advantage  of  using vectors is that when you modify one, the
+       sure we change the bar width  too.   .b  configure  -barwidth  0.2  The
+       height  of  each  bar is proportional to the ordinate (Y-coordinate) of
+       the data point.
+
+       If two or more data points have the same abscissa (X-coordinate value),
+       the  bars  representing those data points may be drawn in various ways.
+       The default is to overlay the bars, one  on  top  of  the  other.   The
+       ordering  is  determined  from  the  of  element  display list.  If the
+       stacked mode is selected (using the -barmode configuration option), the
+       bars  are stacked, each bar above the previous.  # Display the elements
+       as stacked.  .b configure -barmode  stacked  If  the  aligned  mode  is
+       selected,  the bars having the same x-coordinates are displayed side by
+       side.  The width of each bar is a fraction of its normal  width,  based
+       upon the number of bars with the same x-coordinate.  # Display the ele-
+       ments side-by-side.  .b configure -barmode aligned By default, the ele-
+       ment's  label in the legend will be also e1.  You can change the label,
+       or specify no legend entry, again using the element's configure  opera-
+       tion.   #  Don't  display  "e1" in the legend.  .b element configure e1
+       -label "" You can configure more than just  the  element's  label.   An
+       element  has many attributes such as stipple, foreground and background
+       colors, relief, etc.  .b element  configure  e1  -fg  red  -bg  pink  \
+            -stipple gray50 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 "e1"
+       on the alternate y axis "y2".  .b element configure e1  -mapy  y2  Axes
+       can  be configured in many ways too.  For example, you change the scale
+       of the Y-axis from linear to log using the axis component.  # Y-axis is
+       log  scale.   .b  axis configure y -logscale yes One important way axes
+       are used is to zoom in on a particular data region.  Zooming is done by
+       simply specifying new axis limits using the -min and -max configuration
+       options.  .b axis configure x -min 1.0 -max 1.5  .b  axis  configure  y
+       -min  12.0 -max 55.15 To zoom interactively, you link theaxis configure
+       operations with some user interaction (such as pressing the mouse  but-
+       ton),  using  the  bind  command.   To convert between screen and graph
+       coordinates, use the invtransform operation.  # Click the button to set
+       a new minimum bind .b <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.  .b axis configure x  -min
+       {}  -max  {} .b axis configure y -min {} -max {} By default, the legend
+       is drawn in the right margin.  You can change this or any  legend  con-
+       figuration  options using the legend component.  # Configure the legend
+       font, color, and relief .b  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.   .b
+       legend  configure  -hide yes The barchart 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, polygons, lines, or
+       windows.  Markers can be used, for example, to mark  or  brush  points.
+       For  example  there may be a line marker which indicates some low-water
+       chart into file "file.ps" .b postscript  output  file.ps  -maxpect  yes
+       -decorations  no  This generates a file file.ps containing the encapsu-
+       lated 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 backgrounds should be drawn (i.e.  the
+       background of the margins, legend, and plotting area will be white).
+
+
+
+

SYNTAX

+       barchart pathName ?option value?...  The barchart command creates a new
+       window pathName and makes it into a barchart widget.  At the time  this
+       command  is  invoked, there must not exist a window named pathName, but
+       pathName's parent must exist.  Additional options may may be  specified
+       on  the  command line or in the option database to configure aspects of
+       the bar chart such as its colors and font.  See the configure operation
+       below  for  the  exact  details  as  to what option and value pairs are
+       valid.
+
+       If successful, barchart returns pathName. It also  creates  a  new  Tcl
+       command  pathName.   This  command may be used to invoke various opera-
+       tions to query or modify the bar chart.  It has the general form: path-
+       Name operation ?arg?...  Both operation and its arguments determine the
+       exact behavior of the command.  The operations available  for  the  bar
+       chart are described in the following section.
+
+
+
+

BARCHART OPERATIONS

+       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  con-
+              figure operation.
+
+       pathName configure ?option value?...
+              Queries  or modifies the configuration options of the graph.  If
+              option isn't specified, a list 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.
+
+              -barmode mode
+                     Indicates  how  related  bar  elements  will  be   drawn.
+                     Related elements have data points with the same abscissas
+                     (X-coordinates). Mode indicates how those segments should
+
+              -barwidth value
+                     Specifies the width of the bars.  This value can be over-
+                     rided  by  the  individual elements using their -barwidth
+                     configuration option.  Value is the  width  in  terms  of
+                     graph-coordinates.  The default width is 1.0.
+
+              -borderwidth pixels
+                     Sets  the width of the 3-D border around the outside edge
+                     of the widget.  The -relief option determines if the bor-
+                     der 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 dis-
+                     play 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 section.  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-Normal-*-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.  The default is
+                     4i.
+
+              -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 mat-
+                     ters only when the title contains more than one  line  of
+                     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 distance, 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  distances.  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 area.  Relief
+                     specifies how the interior of 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 barchart widget.  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 win-
+                     dow  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
+              -width pixels
+                     Specifies the requested width of the widget.  The default
+                     is 5i.
+
+       pathName crosshairs operation ?arg?
+              See the CROSSHAIRS COMPONENT section.
+
+       pathName element operation ?arg?...
+              See the ELEMENT COMPONENTS section.
+
+       pathName extents item
+              Returns  the  size of a particular item in the graph.  Item must
+              be  either  leftmargin,  rightmargin,  topmargin,  bottommargin,
+              plotwidth, or plotheight.
+
+       pathName grid operation ?arg?...
+              See the GRID COMPONENT section.
+
+       pathName invtransform winX winY
+              Performs  an  inverse  coordinate transformation, mapping window
+              coordinates back to graph-coordinates, using the standard X-axis
+              and  Y-axis.  Returns a list of containing the X-Y graph-coordi-
+              nates.
+
+       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 metafile ?fileName?
+              This  operation is for Window platforms only.  Creates a Windows
+              enhanced metafile of the barchart.  If present, fileName is  the
+              file name of the new metafile.  Otherwise, the metafile is auto-
+              matically added to the clipboard.
+
+       pathName postscript operation ?arg?...
+              See the POSTSCRIPT COMPONENT section.
+
+       pathName snap photoName
+              Takes a snapshot of the graph and stores  the  contents  in  the
+              photo  image  photoName.   PhotoName  is  the name of a Tk photo
+              image that must already exist.
+
+       pathName transform x y
+       A graph is composed of several components: coordinate axes,  data  ele-
+       ments,  legend,  grid, cross hairs, postscript, and annotation markers.
+       Instead of one big set of configuration  options  and  operations,  the
+       graph  is  partitioned,  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 intervals within major ticks.
+
+       The  range  of  the axis controls what region of data is plotted.  Data
+       points outside the minimum and maximum limits of the axis are not plot-
+       ted.   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 "tem-
+       perature" .b axis create temperature You map data elements to  an  axis
+       using the element's -mapy and -mapx configuration options. They specify
+       the coordinate axes an element is mapped onto.  # Now map the  tempera-
+       ture  data  to  this  axis.   .b element create "temp" -xdata $x -ydata
+       $tempData \
+           -mapy temperature While you can have many axes, only four axes  can
+       be  displayed  simultaneously.   They  are drawn in each of the margins
+       surrounding the plotting area.  The axes x and y are drawn in the  bot-
+       tom  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 following compo-
+       nents: xaxis, yaxis, x2axis, and y2axis.  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.  #  Dis-
+       play the axis temperature in the left margin.  .b yaxis use temperature
+
+       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.
+
+
+              -autorange range
+                     Sets the range of values for the axis to range.  The axis
+                     limits are automatically reset to display the most recent
+                     data points in this range.  If range is 0.0, the range is
+                     determined  from the limits of the data.  If -min or -max
+                     are specified, they override this option.  The default is
+                     0.0.
+
+              -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  formatted  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 "".
+
+                     Please  note that this procedure is invoked while the bar
+                     chart is redrawn.  You may query the widget's  configura-
+                     tion options.  But do not reset options, because this can
+                     have unexpected results.
+
+              -descending boolean
+                     Indicates whether the values along the axis are monotoni-
+                     cally  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  justified.   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 format the minimum
+                     and maximum limits of the axis.  The limits are displayed
+                     at  the  top/bottom  or  left/right sides of the plotting
+                     area.  FormatStr is a list of one or two format  descrip-
+                     tions.   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
+                     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 calculated.  If
+                     boolean  is true, the axis range is "loose".  The default
+                     is 0.
+
+              -majorticks majorList
+                     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  com-
+                     puted. The default is "".
+
+              -max value
+                     Sets  the  maximum  limit  of  axisName.   Any data point
+                     greater than value is not displayed.  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  inter-
+                     vals.  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  automati-
+                     cally 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.
+
+              -shiftby value
+                     Specifies how much to automatically shift  the  range  of
+                     the  axis.   When  the  new data exceeds the current axis
+                     maximum, the maximum is increased in increments of value.
+                     You  can  use this option to prevent the axis limits from
+                     being recomputed at each new time point. If value is 0.0,
+                     then no automatic shifting is down. The default is 0.0.
+
+              -showticks boolean
+                     Indicates  whether axis ticks should be drawn. If boolean
+                     is true, ticks are drawn.  If false, only the  axis  line
+
+              -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  *-Hel-
+                     vetica-Bold-R-Normal-*-14-140-*.
+
+              Axis configuration options may be also be set by the option com-
+              mand.  The resource class is Axis.  The resource names  are  the
+              names  of  the  axes  (such  as  x  or  x2).   option  add *Bar-
+              chart.Axis.Color  blue  option  add  *Barchart.x.LogScale   true
+              option add *Barchart.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 ele-
+              ments.
+
+       pathName axis invtransform axisName value
+              Performs the inverse transformation, changing the screen-coordi-
+              nate value to a graph-coordinate, mapping 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  patterns.   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-coordinate by map-
+
+       right Y-axis.
+
+       They implicitly control the axis that is currently using to that  loca-
+       tion.  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  mirror  exactly
+       the operations of the axis component.  The axis argument must be xaxis,
+       x2axis, yaxis, or y2axis.
+
+       pathName axis cget option
+
+       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  loca-
+              tion.   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 vertical and one
+       horizontal) drawn completely across the plotting area.  They  are  used
+       to  position the mouse in relation 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 with-
+       out redrawing the entire widget.
+
+       The following operations are available for cross hairs:
+
+       pathName crosshairs cget option
+              Returns the current  value  of  the  cross  hairs  configuration
+              option  given  by  option.   Option  may be any option described
+              below for the cross hairs configure 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  specified,
+              then  for  each  pair,  the  cross hairs option option is set to
+              value.  The following options are available for cross hairs.
+
+              -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      *Bar-
+              chart.Crosshairs.LineWidth     2      option      add      *Bar-
+              chart.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 map-
+              ping and unmapping the cross hairs.
+
+
+
+

ELEMENTS

+       A data element represents a set of data.  It contains x and  y  vectors
+       which  are  the coordinates of the data points.  Elements are displayed
+       as bars where the length of the bar is proportional to the ordinate  of
+       the data point.  Elements also control the appearance of the data, such
+       as the color, stipple, relief, 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 colors.  ElemName is the name
+              of the element and index is a number representing the  index  of
+              the  data  point. If no indices are present then all data points
+              become active.
+
+       pathName element bind tagName ?sequence?  ?command?
+              Associates command with tagName such  that  whenever  the  event
+              sequence  given by sequence occurs for an element with this tag,
+              command will be invoked.  The syntax is similar to the bind com-
+              mand except that it operates on graph elements, rather than wid-
+              gets. See the bind manual entry for complete details on sequence
+              and the substitutions performed on command before invoking it.
+
+
+       pathName element closest x y ?option value?... ?elemName?...
+              Finds  the data point representing the bar closest to the window
+              coordinates x and y in the element elemName.   ElemName  is  the
+              name  of  an  element, which must be currently displayed.  If no
+              elements  are  specified,  then  all  displayed   elements   are
+              searched.   It  returns  a key-value list containing the name of
+              the closest element, the index of its  closest  point,  and  the
+              graph-coordinates  of  the  point.  If  no data point within the
+              threshold distance can be found, "" 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 barchart's -halo option.
+
+       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.
+
+              -activepen penName
+                     Specifies  pen to use to draw active element.  If penName
+                     is "", no active elements will be drawn.  The default  is
+                     activeLine.
+
+              -bindtags tagList
+                     Specifies the binding tags for the element.  TagList is a
+                     list of binding tag names.  The tags and their order will
+                     determine  how events for elements.  Each tag in the list
+                     matching the current event sequence  will  have  its  Tcl
+                     command  executed.  Implicitly the name of the element is
+                     always the first tag in the list.  The default  value  is
+                     all.
+
+              -background color
+                     Sets  the  the  color of the border around each bar.  The
+                     default is white.
+
+              -barwidth value
+                     Specifies the width  the  bars  drawn  for  the  element.
+                     Value  is  the  width  in  X-coordinates.  If this option
+                     isn't specified, the width of each bar is  the  value  of
+                     the widget's -barwidth option.
+
+                     a list of numeric expressions representing the X-Y  coor-
+                     dinate pairs of each data point.
+
+              -foreground color
+                     Sets the color of the interior of the bars.
+
+              -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.
+
+              -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 of an axis. The default is
+                     y.
+
+              -relief string
+                     Specifies the 3-D effect desired for bars.  Relief  indi-
+                     cates  how the interior of the bar should appear relative
+                     to the surface of the chart; for  example,  raised  means
+                     the bar should appear to protrude from the surface of the
+                     plotting area.  The default is raised.
+
+              -stipple bitmap
+                     Specifies a stipple pattern with which to draw the  bars.
+                     If  bitmap  is "", then the bar is drawn in a solid fash-
+                     ion.
+
+              -xdata xVector
+                     Specifies the x-coordinate vector of the  data.   XVector
+                     is  the name of a BLT vector or a list of numeric expres-
+                     sions.
+
+              -ydata yVector
+                     Specifies the y-coordinate vector of the  data.   YVector
+                     is  the name of a BLT vector or a list of numeric expres-
+                     sions.
+
+              Element configuration options may also be set by the option com-
+              mand.   The  resource names  in the option database are prefixed
+              by elem.  option add *Barchart.Element.background blue
+
+       pathName element create elemName ?option value?...
+
+       pathName element exists elemName
+              Returns  1  if an element elemName currently exists and 0 other-
+              wise.
+
+       pathName element names ?pattern?...
+              Returns the elements matching one or more pattern.  If  no  pat-
+              tern is given, the names of all elements is returned.
+
+       pathName element show ?nameList?
+              Queries  or modifies the element display list.  The element dis-
+              play 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  dis-
+              play 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 horizon-
+       tally or vertically across the plotting area.  The following operations
+       are available for grid lines.
+
+       pathName grid cget option
+              Returns  the current value of the grid line configuration option
+              given by option.  Option may be any option described  below  for
+              the grid configure operation.
+
+       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 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 grid line option option is set to value.  The  follow-
+              ing 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. DashList 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 dashList is "", the
+                     grid will be solid lines.
+
+              -hide boolean
+                     Indicates whether the grid should be drawn. If boolean is
+
+              -minor boolean
+                     Indicates  whether  the  grid  lines  should be drawn for
+                     minor ticks.  If boolean is true, the lines  will  appear
+                     at minor tick intervals.  The default is 1.
+
+              Grid  configuration  options  may also be set by the option com-
+              mand.  The resource name and class are  grid  and  Grid  respec-
+              tively.   option add *Barchart.grid.LineWidth 2 option add *Bar-
+              chart.Grid.Color     black
+
+       pathName grid off
+              Turns off the display the grid lines.
+
+       pathName grid on
+              Turns on the display the grid lines.
+
+       pathName grid toggle
+              Toggles the display of the grid.
+
+   LEGEND COMPONENT
+       The legend displays a list of the data elements.  Each  entry  consists
+       of the element's symbol and label.  The legend can appear in any margin
+       (the default location is in the right margin).  It can  also  be  posi-
+       tioned anywhere within the plotting area.
+
+       The following operations are valid for the legend.
+
+       pathName legend activate pattern...
+              Selects  legend entries to be drawn using the active legend col-
+              ors and relief.  All entries whose element names  match  pattern
+              are  selected.  To be selected, the element name must match only
+              one pattern.
+
+       pathName legend bind tagName ?sequence?  ?command?
+              Associates command with tagName such  that  whenever  the  event
+              sequence  given  by sequence occurs for a legend entry with this
+              tag, command will be invoked.  Implicitly the element  names  in
+              the  entry  are tags.  The syntax is similar to the bind command
+              except that it operates on legend entries, rather than  widgets.
+              See  the  bind manual entry for complete details on 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 tag-
+              Name.  If the first character of command is + then command  aug-
+              ments  an existing binding rather than replacing it.  If no com-
+              mand argument is provided then the command currently  associated
+              with  tagName  and  sequence (it's an error occurs if there's no
+              such binding) is returned.  If both  command  and  sequence  are
+              missing  then  a list of all the event sequences for which bind-
+              ings have been defined for tagName.
+
+              -activebackground color
+                     Sets the background color for active legend entries.  All
+                     legend  entries  marked  active  (see the legend activate
+                     operation) are drawn using this background color.
+
+              -activeborderwidth pixels
+                     Sets the width of the 3-D border around the outside  edge
+                     of the active legend entries.  The default is 2.
+
+              -activeforeground color
+                     Sets the foreground color for active legend entries.  All
+                     legend entries marked as active (see the legend  activate
+                     operation) are drawn using this foreground color.
+
+              -activerelief relief
+                     Specifies  the  3-D  effect  desired  for  active  legend
+                     entries.  Relief denotes how the interior  of  the  entry
+                     should appear relative to the legend; for example, raised
+                     means the entry should appear to protrude from  the  leg-
+                     end,  relative to the surface of the legend.  The default
+                     is flat.
+
+              -anchor anchor
+                     Tells how to position the legend relative  to  the  posi-
+                     tioning  point  for the legend.  This is dependent on the
+                     value of the -position option.  The default is center.
+
+                     left or right
+                                 The anchor describes how to position the leg-
+                                 end vertically.
+
+                     top or bottom
+                                 The anchor describes how to position the leg-
+                                 end horizontally.
+
+                     @x,y        The anchor specifies how to position the leg-
+                                 end  relative  to  the positioning point. For
+                                 example, if anchor is center then the  legend
+                                 is centered on the point; if anchor is n then
+                                 the legend will be drawn such  that  the  top
+                                 center  point of the rectangular region occu-
+                                 pied by the legend will be at the positioning
+                                 point.
+
+                     plotarea    The anchor specifies how to position the leg-
+                                 end relative to the plotting area. For  exam-
+                                 ple,  if  anchor is center then the legend is
+                                 centered in the plotting area; if  anchor  is
+                                 ne  then  the  legend will be drawn such that
+                                 occupies the upper right corner of the  plot-
+                                 ting area.
+
+                     of  the legend (if such border is being drawn; the relief
+                     option determines this).  The default is 2 pixels.
+
+              -font fontName
+                     FontName specifies a font to use when drawing the  labels
+                     of  each  element into the legend.  The default is *-Hel-
+                     vetica-Bold-R-Normal-*-12-120-*.
+
+              -foreground color
+                     Sets the foreground color of the text drawn for the  ele-
+                     ment's label.  The default is black.
+
+              -hide boolean
+                     Indicates  whether  the  legend  should  be displayed. If
+                     boolean is true,  the  legend  will  not  be  draw.   The
+                     default is no.
+
+              -ipadx pad
+                     Sets  the  amount  of internal padding to be added to the
+                     width of each legend entry.  Pad can be a list of one  or
+                     two  screen distances.  If pad has two elements, the left
+                     side of the legend entry is padded by the first  distance
+                     and  the  right  side  by the second.  If pad is just one
+                     distance, both  the  left  and  right  sides  are  padded
+                     evenly.  The default is 2.
+
+              -ipady pad
+                     Sets  an  amount  of  internal padding to be added to the
+                     height of each legend entry.  Pad can be a list of one or
+                     two  screen  distances.  If pad has two elements, the top
+                     of the entry is padded by the first distance and the bot-
+                     tom by the second.  If pad is just one distance, both the
+                     top and bottom of  the  entry  are  padded  evenly.   The
+                     default is 2.
+
+              -padx pad
+                     Sets  the  padding to the left and right exteriors of the
+                     legend.  Pad can be a list of  one  or  two  screen  dis-
+                     tances.   If  pad  has two elements, the left side of the
+                     legend is padded by the first distance and the right side
+                     by  the  second.   If pad has just one distance, both the
+                     left and right sides are padded evenly.  The  default  is
+                     4.
+
+              -pady pad
+                     Sets  the padding above and below the legend.  Pad can be
+                     a list of one or two screen distances.  If  pad  has  two
+                     elements,  the  area  above  the  legend is padded by the
+                     first distance and the area below by the second.  If  pad
+                     is  just  one distance, both the top and bottom areas are
+                     padded evenly.  The default is 0.
+
+                     drawn on top of any elements that  may  overlap  it.  The
+                     default is no.
+
+              -relief relief
+                     Specifies  the  3-D effect for the border around the leg-
+                     end.  Relief specifies how the  interior  of  the  legend
+                     should  appear  relative  to  the bar chart; for example,
+                     raised means the legend should appear  to  protrude  from
+                     the  bar chart, relative to the surface of the bar chart.
+                     The default is sunken.
+
+              Legend configuration options may also be set by the option  com-
+              mand.  The resource name and class are legend and Legend respec-
+              tively.  option add *Barchart.legend.Foreground blue option  add
+              *Barchart.Legend.Relief     raised
+
+       pathName legend deactivate pattern...
+              Selects  legend entries to be drawn using the normal legend col-
+              ors and relief.  All entries whose element names  match  pattern
+              are  selected.  To be selected, the element name must match only
+              one pattern.
+
+       pathName legend get pos
+              Returns the name of the element whose entry  is  at  the  screen
+              position  pos  in  the  legend.  Pos must be in the form "@x,y",
+              where x and y are window coordinates.  If the given  coordinates
+              do not lie over a legend entry, "" is returned.
+
+   PEN COMPONENTS
+       Pens  define  attributes  for  elements.  Pens mirror the configuration
+       options of data elements that pertain to  how  symbols  and  lines  are
+       drawn.  Data elements use pens to determine how they are drawn.  A data
+       element may use several pens at once.  In this case, the pen used for a
+       particular  data  point is determined from each element's weight vector
+       (see the element's -weight and -style options).
+
+       One pen, called activeBar, is automatically created.  It's used as  the
+       default  active  pen  for  elements.  So  you  can  change  the  active
+       attributes for all elements by simply reconfiguring this pen.   .g  pen
+       configure  "activeBar" -fg green -bg green4 You can create and use sev-
+       eral pens. To create a pen, invoke the pen  component  and  its  create
+       operation.   .g  pen  create myPen You map pens to a data element using
+       either the element's -pen or -activepen  options.   .g  element  create
+       "e1" -xdata $x -ydata $tempData \
+           -pen myPen An element can use several pens at once. This is done by
+       specifying the name of the pen in the element's  style  list  (see  the
+       -styles  option).   .g element configure "e1" -styles { myPen 2.0 3.0 }
+       This says that any data point with a weight between 2.0 and 3.0  is  to
+       be drawn using the pen myPen.  All other points are drawn with the ele-
+       ment's default attributes.
+
+       The following operations are available for pen components.
+              value.  The following options are valid for pens.
+
+              -background color
+                     Sets the the color of the border around  each  bar.   The
+                     default is white.
+
+              -borderwidth pixels
+                     Sets  the border width of the 3-D border drawn around the
+                     outside of each bar.  The -relief  option  determines  if
+                     such  a  border  is drawn.  Pixels must be a valid screen
+                     distance like 2 or 0.25i. The default is 2.
+
+              -foreground color
+                     Sets the color of the interior of the bars.
+
+              -relief string
+                     Specifies the 3-D effect desired for bars.  Relief  indi-
+                     cates  how the interior of the bar should appear relative
+                     to the surface of the chart; for  example,  raised  means
+                     the  bar  should  appear  to protrude from the bar chart,
+                     relative to  the  surface  of  the  plotting  area.   The
+                     default is raised.
+
+              -stipple bitmap
+                     Specifies  a stipple pattern with which to draw the bars.
+                     If bitmap is "", then the bar is drawn in a  solid  fash-
+                     ion.
+
+              -type elemType
+                     Specifies the type of element the pen is to be used with.
+                     This option should only be  employed  when  creating  the
+                     pen.   This is for those that wish to mix different types
+                     of elements (bars and lines)  on  the  same  graph.   The
+                     default type is "bar".
+
+              Pen  configuration options may be also be set by the option com-
+              mand.  The resource class is Pen.  The resource  names  are  the
+              names  of  the  pens.   option add *Barchart.Pen.Foreground
+              blue option add *Barchart.activeBar.foreground  green
+
+       pathName pen create penName ?option value?...
+              Creates a new pen by the name penName.  No pen by the same  name
+              can  already  exist.  Option and value are described in above in
+              the pen configure operation.
+
+       pathName pen delete ?penName?...
+              Deletes the named pens. A pen is not really deleted until it  is
+              not  longer  in  use, so it's safe to delete pens mapped to ele-
+              ments.
+
+       pathName pen names ?pattern?...
+              Returns a list of pens matching zero or more  patterns.   If  no
+              option.   Option may be any option described below for the post-
+              script configure operation.
+
+       pathName postscript configure ?option value?...
+              Queries or modifies the  configuration  options  for  PostScript
+              generation.   If  option  isn't specified, a list describing the
+              current postscript 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  postscript  option option is set to
+              value.  The following postscript options are available.
+
+              -center boolean
+                     Indicates whether the plot  should  be  centered  on  the
+                     PostScript  page.   If boolean is false, the plot will be
+                     placed in the upper left corner of the page.  The default
+                     is 1.
+
+              -colormap varName
+                     VarName  must be the name of a global array variable that
+                     specifies a color mapping from the X color name to  Post-
+                     Script.   Each  element  of varName must consist of Post-
+                     Script code to set a particular color value  (e.g.  ``1.0
+                     1.0  0.0  setrgbcolor'').  When generating color informa-
+                     tion in PostScript, the array variable varName is checked
+                     if  an element of the name as the color exists. If so, it
+                     uses its value as  the  PostScript  command  to  set  the
+                     color.  If this option hasn't been specified, or if there
+                     isn't an entry in varName for a given color, then it 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
+                     foreground colors  to  black  and  background  colors  to
+                     white).  The default mode is color.
+
+              -fontmap varName
+                     VarName  must be the name of a global array variable that
+                     specifies a font mapping from the X font  name  to  Post-
+                     Script.   Each  element  of varName must consist of a Tcl
+                     list with one or two elements; the name and point size of
+                     a  PostScript  font.  When outputting PostScript commands
+                     for a particular font,  the  array  variable  varName  is
+                     checked  to  see  if  an  element  by  the specified font
+                     exists.  If there is  such  an  element,  then  the  font
+                     information  contained  in  that  element  is used in the
+                     PostScript output.  (If the point size  is  omitted  from
+                     the  list, the point size of the X font is used).  Other-
+                     wise the X font is examined in an attempt to  guess  what
+                     PostScript  font to use.  This works only for fonts whose
+                     widget's height.  The default is 0.
+
+              -landscape boolean
+                     If boolean is true, this specifies 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 0.
+
+              -maxpect boolean
+                     Indicates  to  scale  the plot so that it fills the Post-
+                     Script page.  The aspect ratio of the barchart  is  still
+                     retained.  The default is 0.
+
+              -padx pad
+                     Sets  the  horizontal padding for the left and right page
+                     borders.  The borders are exterior to the plot.  Pad  can
+                     be a list of one or two screen distances.  If pad has two
+                     elements, the left border is padded by the first distance
+                     and  the right border by the second.  If pad has just one
+                     distance, both the left  and  right  borders  are  padded
+                     evenly.  The default is 1i.
+
+              -pady pad
+                     Sets  the  vertical  padding  for the top and bottom page
+                     borders. The borders are exterior to the plot.   Pad  can
+                     be a list of one or two screen distances.  If pad has two
+                     elements, the top border is padded by the first  distance
+                     and the bottom border by the second.  If pad has just one
+                     distance, both the top  and  bottom  borders  are  padded
+                     evenly.  The default is 1i.
+
+              -paperheight pixels
+                     Sets the height of the postscript page.  This can be used
+                     to select between different page sizes (letter, A4, etc).
+                     The default height is 11.0i.
+
+              -paperwidth pixels
+                     Sets  the width of the postscript page.  This can be used
+                     to select between different page sizes (letter, A4, etc).
+                     The default width is 8.5i.
+
+              -width pixels
+                     Sets  the  width  of  the plot.  This lets you generate a
+                     plot of a width different from that of  the  widget.   If
+                     pixels is 0, the width is the same as the widget's width.
+                     The default is 0.
+
+              Postscript configuration options may  be  also  be  set  by  the
+              option  command.  The resource name and class are postscript and
+              Postscript respectively.  option add  *Barchart.postscript.Deco-
+
+       with  a  particular  element, so that when the element is hidden or un-
+       hidden, so is the marker.  By  default,  markers  are  the  last  items
+       drawn,  so  that  data  elements  will  appear in behind them.  You can
+       change this by configuring the -under option.
+
+       Markers, in contrast to elements, don't affect the scaling of the coor-
+       dinate axes.  They can also have elastic coordinates (specified by -Inf
+       and Inf respectively) that translate into the minimum or maximum  limit
+       of  the axis.  For example, you can place a marker so it always remains
+       in the lower left corner of the plotting area, by using the coordinates
+       -Inf,-Inf.
+
+       The following operations are available for markers.
+
+       pathName marker after markerId ?afterId?
+              Changes the order of the markers, drawing the first marker after
+              the second.  If no second afterId  argument  is  specified,  the
+              marker  is  placed at the end of the display list.  This command
+              can be used to control how markers are displayed  since  markers
+              are drawn in the order of this display list.
+
+       pathName marker before markerId ?beforeId?
+              Changes  the  order  of  the  markers,  drawing the first marker
+              before the second.  If no second beforeId argument is specified,
+              the marker is placed at the beginning of the display list.  This
+              command can be used to control how markers are  displayed  since
+              markers are drawn in the order of this display list.
+
+       pathName marker bind tagName ?sequence?  ?command?
+              Associates  command  with  tagName  such that whenever the event
+              sequence given by sequence occurs for a marker  with  this  tag,
+              command will be invoked.  The syntax is similar to the bind com-
+              mand except that it operates on graph markers, rather than  wid-
+              gets. See the bind manual entry for complete details on 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 tag-
+              Name.  If the first character of command is + then command  aug-
+              ments  an existing binding rather than replacing it.  If no com-
+              mand argument is provided then the command currently  associated
+              with  tagName  and  sequence (it's an error occurs if there's no
+              such binding) is returned.  If both  command  and  sequence  are
+              missing  then  a list of all the event sequences for which bind-
+              ings have been defined for tagName.
+
+       pathName marker cget option
+              Returns the current value of  the  marker  configuration  option
+              given  by  option.   Option may be any option described below in
+              the configure operation.
+
+       pathName marker configure markerId ?option value?...
+                     determine  how  events for markers are handled.  Each tag
+                     in the list matching the current event sequence will have
+                     its  Tcl  command  executed.   Implicitly the name of the
+                     marker is always the first tag in the list.  The  default
+                     value is all.
+
+              -coords coordList
+                     Specifies  the coordinates of the marker.  CoordList is a
+                     list of graph-coordinates.   The  number  of  coordinates
+                     required  is  dependent  on  the  type  of marker.  Text,
+                     image, and window markers need only two  coordinates  (an
+                     X-Y  coordinate).   Bitmap markers can take either two or
+                     four coordinates (if four, they represent the corners  of
+                     the bitmap). Line markers need at least four coordinates,
+                     polygons at least six.  If coordList is  "",  the  marker
+                     will not be displayed.  The default is "".
+
+              -element elemName
+                     Links  the  marker with the element elemName.  The marker
+                     is drawn only if the element is also currently  displayed
+                     (see  the  element's show operation).  If elemName is "",
+                     the marker is always drawn.  The default is "".
+
+              -hide boolean
+                     Indicates whether the marker  is  drawn.  If  boolean  is
+                     true, the marker is not drawn.  The default is no.
+
+              -mapx xAxis
+                     Specifies  the  X-axis  to map the marker's X-coordinates
+                     onto.  XAxis must the name of an axis.  The default is x.
+
+              -mapy yAxis
+                     Specifies  the  Y-axis  to map the marker's Y-coordinates
+                     onto.  YAxis must the name of an axis.  The default is y.
+
+              -name markerId
+                     Changes  the  identifier  for the marker.  The identifier
+                     markerId can not already be used by another  marker.   If
+                     this   option  isn't  specified,  the  marker's  name  is
+                     uniquely generated.
+
+              -under boolean
+                     Indicates whether the marker is  drawn  below/above  data
+                     elements.   If  boolean  is  true, the marker is be drawn
+                     underneath the data elements.  Otherwise, the  marker  is
+                     drawn on top of the element.  The default is 0.
+
+              -xoffset pixels
+                     Specifies a screen distance to offset the marker horizon-
+                     tally.  Pixels is a valid screen distance, such as  2  or
+                     1.2i.  The default is 0.
+
+              Creates  a marker of the selected type. Type may be either text,
+              line, bitmap, image, polygon, or window.  This  command  returns
+              the  marker  identifier,  used  as  the markerId argument in the
+              other marker-related commands.  If the  -name  option  is  used,
+              this  overrides  the normal marker identifier.  If the name pro-
+              vided is already used for another marker, the  new  marker  will
+              replace the old.
+
+       pathName marker delete ?name?...
+              Removes  one  of  more markers.  The graph will automatically be
+              redrawn without the marker..
+
+       pathName marker exists markerId
+              Returns 1 if the marker markerId exists and 0 otherwise.
+
+       pathName marker names ?pattern?
+              Returns the names of all the markers that currently  exist.   If
+              pattern  is  supplied,  only  those markers whose names match it
+              will be returned.
+
+       pathName marker type markerId
+              Returns the type of the marker given by markerId, such  as  line
+              or  text.  If markerId is not a valid a marker identifier, "" is
+              returned.
+
+   BITMAP MARKERS
+       A bitmap marker displays a bitmap.  The size  of  the  bitmap  is  con-
+       trolled  by  the  number of coordinates specified.  If two coordinates,
+       they specify the position of the top-left corner of  the  bitmap.   The
+       bitmap  retains  its normal width and height.  If four coordinates, the
+       first and second pairs of coordinates represent the corners of the bit-
+       map.   The bitmap will be stretched or reduced as necessary to fit into
+       the bounding rectangle.
+
+       Bitmap markers are created with the marker's create  operation  in  the
+       form:  pathName  marker  create  bitmap ?option value?...  There may be
+       many option-value pairs, each sets  a  configuration  options  for  the
+       marker.   These  same  option-value pairs may be used with the marker's
+       configure operation.
+
+       The following options are specific to bitmap markers:
+
+       -background color
+              Same as the -fill option.
+
+       -bitmap bitmap
+              Specifies the bitmap to be displayed.   If  bitmap  is  "",  the
+              marker will not be displayed.  The default is "".
+
+       -fill color
+              Sets  the background color of the bitmap.  If color is the empty
+              string, no background will be transparent.   The  default  back-
+
+       -rotate theta
+              Sets  the rotation of the bitmap.  Theta is a real number repre-
+              senting the angle of rotation in degrees.  The marker  is  first
+              rotated  and  then placed according to its anchor position.  The
+              default rotation is 0.0.
+
+   IMAGE MARKERS
+       A image marker displays an image.  Image markers are created  with  the
+       marker's  create  operation  in  the form: pathName marker create image
+       ?option value?...  There may be many option-value pairs,  each  sets  a
+       configuration option for the marker.  These same option-value pairs may
+       be used with the marker's configure operation.
+
+       The following options are specific to image markers:
+
+       -anchor anchor
+              Anchor tells how to position the image relative to the position-
+              ing  point  for the image. For example, if anchor is center then
+              the image is centered on the point;  if anchor  is  n  then  the
+              image  will be drawn such that the top center point of the rect-
+              angular region occupied by the image will be at the  positioning
+              point.  This option defaults to center.
+
+       -image image
+              Specifies  the  image  to  be drawn.  If image is "", the marker
+              will not be drawn.  The default is "".
+
+   LINE MARKERS
+       A line marker displays one or more connected line segments.  Line mark-
+       ers  are  created  with marker's create operation in the form: pathName
+       marker create line ?option value?...  There may  be  many  option-value
+       pairs,  each  sets  a  configuration option for the marker.  These same
+       option-value pairs may be used with the marker's configure operation.
+
+       The following options are specific to line markers:
+
+       -dashes dashList
+              Sets the dash style of the line. DashList is a list of up to  11
+              numbers that alternately represent the lengths of the dashes and
+              gaps on the line.  Each number must be between 1  and  255.   If
+              dashList is "", the marker line will be solid.
+
+       -fill color
+              Sets  the background color of the line.  This color is used with
+              striped lines (see the -fdashesoption). If color  is  the  empty
+              string,  no  background color is drawn (the line will be dashed,
+              not striped).  The default background color is "".
+
+       -linewidth pixels
+              Sets the width of the lines.  The default width is 0.
+
+       in  the  form:  pathName marker create polygon ?option value?...  There
+       may be many option-value pairs, each sets a  configuration  option  for
+       the  marker.  These same option-value pairs may be used with the marker
+       configure command to change the marker's configuration.  The  following
+       options are supported for polygon markers:
+
+       -dashes dashList
+              Sets the dash style of the outline of the polygon. DashList is a
+              list of up to 11 numbers that alternately represent the  lengths
+              of  the  dashes  and  gaps  on the outline.  Each number must be
+              between 1 and 255. If dashList is "",  the  outline  will  be  a
+              solid line.
+
+       -fill color
+              Sets  the  fill  color of the polygon.  If color is "", then the
+              interior of the polygon is transparent.  The default is white.
+
+       -linewidth pixels
+              Sets the width of the outline of the polygon. If pixels is zero,
+              no outline is drawn. The default is 0.
+
+       -outline color
+              Sets the color of the outline of the polygon.  If the polygon is
+              stippled (see the -stipple option),  then  this  represents  the
+              foreground color of the stipple.  The default is black.
+
+       -stipple bitmap
+              Specifies  that the polygon should be drawn with a stippled pat-
+              tern rather than a solid color. Bitmap specifies a bitmap to use
+              as  the  stipple  pattern.  If bitmap is "", then the polygon is
+              filled with a solid color (if the -fill  option  is  set).   The
+              default is "".
+
+   TEXT MARKERS
+       A  text  marker displays a string of characters on one or more lines of
+       text.  Embedded newlines cause line breaks.  They may be used to  anno-
+       tate  regions  of  the graph.  Text markers are created with the create
+       operation in the form: pathName marker create  text  ?option  value?...
+       There  may be many option-value pairs, each sets a configuration option
+       for the text marker.  These same option-value pairs may  be  used  with
+       the marker's configure operation.
+
+       The following options are specific to text markers:
+
+       -anchor anchor
+              Anchor  tells how to position the text relative to the position-
+              ing point for the text. For example, if anchor  is  center  then
+              the  text is centered on the point; if anchor is n then the text
+              will be drawn such that the top center point of the  rectangular
+              region  occupied  by  the text will be at the positioning point.
+              This default is center.
+
+
+       -justify justify
+              Specifies  how  the text should be justified.  This matters only
+              when the marker contains more than one  line  of  text.  Justify
+              must be left, right, or center.  The default is center.
+
+       -outline color
+              Sets the color of the text. The default value is black.
+
+       -padx pad
+              Sets  the  padding  to the left and right exteriors of the text.
+              Pad can be a list of one or two screen distances.   If  pad  has
+              two  elements,  the left side of the text is padded by the first
+              distance and the right side by the second.  If pad has just  one
+              distance,  both the left and right sides are padded evenly.  The
+              default is 4.
+
+       -pady pad
+              Sets the padding above and below the text.  Pad can be a list of
+              one  or two screen distances.  If pad has two elements, the area
+              above the text is padded by the  first  distance  and  the  area
+              below  by the second.  If pad is just one distance, both the top
+              and bottom areas are padded evenly.  The default is 4.
+
+       -rotate theta
+              Specifies the number of degrees to rotate the text.  Theta is  a
+              real  number  representing the angle of rotation.  The marker is
+              first rotated along its center and is then  drawn  according  to
+              its anchor position. The default is 0.0.
+
+       -text text
+              Specifies  the  text  of  the marker.  The exact way the text is
+              displayed may be affected by other options such  as  -anchor  or
+              -rotate.
+
+   WINDOW MARKERS
+       A  window marker displays a widget at a given position.  Window markers
+       are created with the marker's create operation in  the  form:  pathName
+       marker  create window ?option value?...  There may be many option-value
+       pairs, each sets a configuration option for  the  marker.   These  same
+       option-value pairs may be used with the marker's configure command.
+
+       The following options are specific to window markers:
+
+       -anchor anchor
+              Anchor  tells  how  to position the widget relative to the posi-
+              tioning point for the widget. For example, if anchor  is  center
+              then  the  widget  is centered on the point; if anchor is n then
+              the widget will be displayed such that the top center  point  of
+              the  rectangular  region  occupied  by the widget will be at the
+              positioning point.  This option defaults to center.
+
+
+
+

GRAPH COMPONENT BINDINGS

+       Specific barchart components, such  as  elements,  markers  and  legend
+       entries,  can  have  a  command trigger when event occurs in them, much
+       like canvas items in Tk's canvas widget.  Not all event  sequences  are
+       valid.  The only binding events that may be specified are those related
+       to the mouse and keyboard (such as Enter, Leave,  ButtonPress,  Motion,
+       and KeyPress).
+
+       Only  one element or marker can be picked during an event.  This means,
+       that if the mouse is directly over both an element and a  marker,  only
+       the  uppermost  component  is  selected.   This  isn't  true for legend
+       entries.  Both a legend entry and an element (or marker)  binding  com-
+       mands will be invoked if both items are picked.
+
+       It is possible for multiple bindings to match a particular event.  This
+       could occur, for example, if one binding is associated with the element
+       name  and another is associated with one of the element's tags (see the
+       -bindtags option).  When this occurs, all of the matching bindings  are
+       invoked.   A binding associated with the element name is invoked first,
+       followed by one binding for each of the element's bindtags.   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 terminates that script and
+       skips any remaining scripts for the event, just as for  the  bind  com-
+       mand.
+
+       The  -bindtags  option for these components controls addition tag names
+       which can be matched.  Implicitly elements and markers always have tags
+       matching  their  names.   Setting  the  value  of  the -bindtags option
+       doesn't change this.
+
+
+
+

C LANGUAGE API

+       You can manipulate data elements from the C  language.   There  may  be
+       situations  where it is too expensive to translate the data values from
+       ASCII strings.  Or you might want to read data in a special  file  for-
+       mat.
+
+       Data  can manipulated from the C language using BLT vectors.  You spec-
+       ify the X-Y data coordinates of an element as  vectors  and  manipulate
+       the  vector  from  C.  The barchart will be redrawn automatically after
+       the vectors are updated.
+
+       From Tcl, create the vectors and configure the  element  to  use  them.
+       vector  X  Y  .g  element configure line1 -xdata X -ydata Y To set data
+       points from C, you pass the values  as  arrays  of  doubles  using  the
+       Blt_ResetVector call.  The vector is reset with the new data and at the
+       next idle point (when Tk re-enters its event loop), the graph  will  be
+       redrawn automatically.  #include <tcl.h> #include <blt.h>
+
+       register int i; Blt_Vector *xVec, *yVec; double x[50], y[50];
+
+       /*  Get  the  BLT  vectors  "X"  and "Y" (created above from Tcl) */ if
+       There may be cases where the bar chart 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.
+
+       o Try  to  minimize  the  number  of data points.  The more data points
+         looked at, the more work the bar chart must do.
+
+       o If your data is generated as floating point values, the time required
+         to  convert the data values to and from ASCII strings can be signifi-
+         cant, especially when there any many data points.  You can avoid  the
+         redundant  string-to-decimal  conversions using the C API to BLT vec-
+         tors.
+
+       o Don't stipple or dash the element.  Solid bars are much faster.
+
+       o If you update data elements frequently, try turning off the  widget's
+         -bufferelements  option.   When  the bar chart is first displayed, it
+         draws data elements into an internal pixmap.  The pixmap  acts  as  a
+         cache,  so that when the bar chart needs to be redrawn again, and the
+         data elements or coordinate axes haven't changed, the pixmap is  sim-
+         ply  copied  to  the  screen.  This is especially useful when you are
+         using markers to highlight points and regions on the bar chart.   But
+         if  the  bar chart 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  Refer-
+       ence  Manual,  page 568).  The work-around is to break the polygon into
+       separate pieces.
+
+
+
+

KEYWORDS

+       bar chart, widget
+
+
+
+BLT                               BLT_VERSION                      barchart(n)
+
+
+
+Man(1) output converted with +man2html +
+ + diff --git a/doc/graph.html b/doc/graph.html new file mode 100644 index 0000000..412c817 --- /dev/null +++ b/doc/graph.html @@ -0,0 +1,1751 @@ + + +
+
+
+
+

SYNOPSIS

+       graph pathName ?option value?...
+
+
+
+

DESCRIPTION

+       The  graph  command  creates  a graph for plotting two-dimensional data
+       (X-Y coordinates). It  has  many  configurable  components:  coordinate
+       axes,  elements,  legend, grid lines, cross hairs, etc.  They allow you
+       to customize the look and feel of the graph.
+
+
+
+

INTRODUCTION

+       The graph command creates a new  window  for  plotting  two-dimensional
+       data  (X-Y coordinates).  Data points are plotted in a rectangular area
+       displayed in the center of the new window.  This is the plotting  area.
+       The  coordinate axes are drawn in the margins around the plotting area.
+       By default, the legend is displayed in the right margin.  The title  is
+       displayed in top margin.
+
+       The  graph  widget  is composed of several components: coordinate axes,
+       data elements, legend, grid, cross hairs, pens, postscript, and annota-
+       tion markers.
+
+       axis      The  graph has four standard axes (x, x2, y, and y2), but you
+                 can create and display any number of axes.  Axes control what
+                 region  of data is displayed and how the data is scaled. Each
+                 axis consists of the axis line, title, major and minor ticks,
+                 and tick labels.  Tick labels display the value at each major
+                 tick.
+
+       crosshairs
+                 Cross hairs are used to position the mouse  pointer  relative
+                 to  the  X  and  Y  coordinate axes. Two perpendicular lines,
+                 intersecting at the current location  of  the  mouse,  extend
+                 across the plotting area to the coordinate axes.
+
+       element   An  element  represents a set of data points. Elements can be
+                 plotted with a symbol at each data point and lines connecting
+                 the  points.  The appearance of the element, such as its sym-
+                 bol, line width, and color is configurable.
+
+       grid      Extends the major and minor ticks of the X-axis and/or Y-axis
+                 across the plotting area.
+
+       legend    The legend displays the name and symbol of each data element.
+                 The legend can be drawn in any  margin  or  in  the  plotting
+                 area.
+
+       marker    Markers  are  used  annotate or highlight areas of the graph.
+                 For example, you could use a polygon marker to fill  an  area
+                 under  a  curve,  or a text marker to label a particular data
+                 point. Markers come in various forms: text strings,  bitmaps,
+                 connected  line  segments, images, polygons, or embedded wid-
+                 gets.
+
+       graph  pathName ?option value?...  The graph command creates a new win-
+       dow pathName and makes it into a graph widget.  At the time  this  com-
+       mand  is  invoked,  there  must  not exist a window named pathName, but
+       pathName's parent must exist.  Additional options may be  specified  on
+       the  command line or in the option database to configure aspects of the
+       graph such as its colors and font.  See the configure  operation  below
+       for the exact details about what option and value pairs are valid.
+
+       If successful, graph returns the path name of the widget.  It also cre-
+       ates a new Tcl command by the same name.  You can use this  command  to
+       invoke  various operations that query or modify the graph.  The general
+       form is: pathName operation ?arg?...  Both operation and its  arguments
+       determine  the exact behavior of the command.  The operations available
+       for the graph are described in the GRAPH OPERATIONS section.
+
+       The command can also be used to access components of the graph.   path-
+       Name component operation ?arg?...  The operation, now located after the
+       name of the component, is the function to be performed on  that  compo-
+       nent. Each component has its own set of operations that manipulate that
+       component.  They will be described below in their own sections.
+
+
+
+

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" A graph has several components. To access
+       a particular 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-Y coordinates are specified using lists of
+       numbers.  Alternately, BLT vectors could be used to hold the X-Y  coor-
+       dinates.   # 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 reflect the new values.  # Change the y  coordinate  of  the
+       first  point.   set yVector(0) 25.18 An element named e1 is now created
+       in .b.  It is automatically added to the display list of elements.  You
+       can  use this list to control in what order elements are displayed.  To
+       query or reset the element display list, you  use  the  element's  show
+       operation.   #  Get  the  current display list set elemList [.b element
+       show] # Remove the first element so it won't be displayed.  .b  element
+       show  [lrange $elemList 0 end] The element will be displayed by as many
+       bars as there are data points (in this case there are ten).   The  bars
+       will  be drawn centered at the x-coordinate of the data point.  All the
+       bars will have the same attributes (colors, stipple, etc).   The  width
+       of each bar is by default one unit.  You can change this with using the
+       example, you change the scale of the Y-axis from linear  to  log  using
+       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  par-
+       ticular  data  region.   Zooming  is done by simply specifying new axis
+       limits using the -min and -max configuration options.  .g axis  config-
+       ure  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  operations  with  some
+       user  interaction  (such  as pressing the mouse button), using the bind
+       command.  To convert between screen  and  graph  coordinates,  use  the
+       invtransform  operation.   # 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 con-
+       figuration 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  proce-
+       dures  called  markers.  They can be used to highlight or annotate data
+       in the graph. The types of markers available are bitmaps, images, poly-
+       gons,  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 are created using the marker component.  # 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 config-
+       ure 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 con-
+       figure -hide no -dashes { 2 2 } # Set up a binding  to  reposition  the
+       crosshairs.  bind .g <Motion> {
+           .g crosshairs configure -position @%x,%y } The crosshairs are repo-
+       sitioned as the mouse pointer is moved in the graph.  The  pointer  X-Y
+       coordinates define the center of the crosshairs.
+
+       Finally, to get hardcopy of the graph, use the postscript component.  #
+       Print the graph into file "file.ps" .g postscript output file.ps  -max-
+       pect  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  backgrounds  should  be  drawn
+              option.   Option  may be any option described below for the con-
+              figure operation.
+
+       pathName configure ?option value?...
+              Queries or modifies the configuration options of the graph.   If
+              option  isn't  specified,  a list 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.
+
+              -aspect width/height
+                     Force a fixed aspect ratio of  width/height,  a  floating
+                     point number.
+
+              -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 bor-
+                     der is to be drawn.  The default is 2.
+
+              -bottommargin pixels
+                     If non-zero, overrides the computed size  of  the  margin
+                     extending  below  the X-coordinate axis.  If pixels is 0,
+                     the automatically computed size is used.  The default  is
+                     0.
+
+              -bufferelements boolean
+                     Indicates  whether  an internal pixmap to buffer the dis-
+                     play 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 section.  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-Normal-*-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
+                     text.  Justify  must  be  left,  right,  or  center.  The
+                     default is center.
+
+              -leftmargin pixels
+                     If non-zero, overrides the computed size  of  the  margin
+                     extending from the left edge of the window to the Y-coor-
+                     dinate axis.  If pixels is 0, the automatically  computed
+                     size is used.  The default is 0.
+
+              -plotbackground color
+                     Specifies the background color of the plotting 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 distance, 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 distances.  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  area.   Relief
+                     specifies  how  the  interior of 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 widget.  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
+                     If non-zero, overrides the computed size  of  the  margin
+
+              -tile image
+                     Specifies  a  tiled  background for the widget.  If image
+                     isn't "", the background is tiled  using  image.   Other-
+                     wise,  the  normal  background  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
+                     If non-zero, overrides the computed size  of  the  margin
+                     above  the  x2  axis.   If pixels is 0, the automatically
+                     computed size is used.  The default is 0.
+
+              -width pixels
+                     Specifies the requested width of the widget.  The default
+                     is 5i.
+
+       pathName crosshairs operation ?arg?
+              See the CROSSHAIRS COMPONENT section.
+
+       pathName element operation ?arg?...
+              See the ELEMENT COMPONENTS section.
+
+       pathName extents item
+              Returns  the  size of a particular item in the graph.  Item must
+              be  either  leftmargin,  rightmargin,  topmargin,  bottommargin,
+              plotwidth, or plotheight.
+
+       pathName grid operation ?arg?...
+              See the GRID COMPONENT section.
+
+       pathName invtransform winX winY
+              Performs  an  inverse  coordinate transformation, mapping window
+              coordinates back to graph coordinates, using the standard X-axis
+              and  Y-axis.  Returns a list of containing the X-Y graph coordi-
+              nates.
+
+       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?...
+                        photo  Saves a Tk photo image.  OutputName  represents
+                               the  name of a Tk photo image that must already
+                               have been created.
+
+                        wmf    Saves an Aldus Placeable Metafile.   OutputName
+                               represents  the  filename where the metafile is
+                               written.  If outputName is CLIPBOARD, then out-
+                               put  is  written  directly to the Windows clip-
+                               board.  This format  is  available  only  under
+                               Microsoft Windows.
+
+                        emf    Saves  an  Enhanced Metafile. OutputName repre-
+                               sents the filename where the metafile is  writ-
+                               ten.   If  outputName is CLIPBOARD, then output
+                               is written directly to the  Windows  clipboard.
+                               This  format  is available only under Microsoft
+                               Windows.
+
+              -height size
+                        Specifies the height of the graph.  Size is  a  screen
+                        distance.  The graph will be redrawn using this dimen-
+                        sion, rather than its current window height.
+
+              -width size
+                        Specifies the width of the graph.  Size  is  a  screen
+                        distance.  The graph will be redrawn using this dimen-
+                        sion, rather than its current window width.
+
+       pathName transform x y
+              Performs a coordinate transformation, mapping graph  coordinates
+              to  window  coordinates,  using  the standard X-axis and Y-axis.
+              Returns a list containing the X-Y screen coordinates.
+
+       pathName xaxis operation ?arg?...
+
+       pathName x2axis operation ?arg?...
+
+       pathName yaxis operation ?arg?...
+
+       pathName y2axis operation ?arg?...
+              See the AXIS COMPONENTS section.
+
+
+
+

GRAPH COMPONENTS

+       A graph is composed of several components: coordinate axes,  data  ele-
+       ments,  legend,  grid, cross hairs, postscript, and annotation markers.
+       Instead of one big set of configuration  options  and  operations,  the
+       graph  is  partitioned,  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
+       You can have 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  ele-
+       ment'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
+       Any number of axes can be displayed simultaneously. They are  drawn  in
+       the  margins  surrounding  the plotting area.  The default axes x and y
+       are drawn in the bottom and left margins. The axes x2 and y2 are  drawn
+       in  top  and  right  margins.  By default, only x and y are shown. Note
+       that the axes can have different scales.
+
+       To display a different axis or more than one axis, you  invoke  one  of
+       the  following components: xaxis, yaxis, x2axis, and y2axis.  Each com-
+       ponent has a use operation that designates the axis  (or  axes)  to  be
+       drawn  in  that 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 The use operation
+       takes a list of axis names as its last argument.  This is the  list  of
+       axes to be drawn in this margin.
+
+       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 bind tagName ?sequence?  ?command?
+              Associates  command  with  tagName  such that whenever the event
+              sequence given by sequence occurs for an  axis  with  this  tag,
+              command will be invoked.  The syntax is similar to the bind com-
+              mand except that it operates on graph axes, rather than widgets.
+              See  the  bind manual entry for complete details on 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 tag-
+              Name.  If the first character of command is + then command  aug-
+              ments  an existing binding rather than replacing it.  If no com-
+              mand argument is provided then the command currently  associated
+              with  tagName  and  sequence (it's an error occurs if there's no
+              such binding) is returned.  If both  command  and  sequence  are
+              missing  then  a list of all the event sequences for which bind-
+              ings have been defined for tagName.
+
+       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.
+                     the  list  matching  the current event sequence will have
+                     its Tcl command executed.  Implicitly  the  name  of  the
+                     element is always the first tag in the list.  The default
+                     value is all.
+
+              -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 formatted 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 "".
+
+                     Please note that this  procedure  is  invoked  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 monotoni-
+                     cally increasing or decreasing.  If boolean is true,  the
+                     axis values will be decreasing.  The default is 0.
+
+              -hide boolean
+                     Indicates  if  the axis is displayed. If boolean is false
+                     the axis will be displayed. Any  element  mapped  to  the
+                     axis is displayed regardless.  The default value is 0.
+
+              -justify justify
+                     Specifies  how  the axis title should be justified.  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 format the minimum
+                     and maximum limits of the axis.  The limits are displayed
+                     at the top/bottom or left/right  sides  of  the  plotting
+                     area.   FormatStr is a list of one or two format descrip-
+                     tions.  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  dis-
+                     loosely, at the outer tick intervals.  If the axis  limit
+                     is  set  with  the -min or -max option, the axes are dis-
+                     played tightly.  If boolean is true, the  axis  range  is
+                     "loose".  The default is 0.
+
+              -majorticks majorList
+                     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 com-
+                     puted. The default is "".
+
+              -max value
+                     Sets the maximum  limit  of  axisName.   Any  data  point
+                     greater than value is not displayed.  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 inter-
+                     vals. 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 automati-
+                     cally 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.
+
+              -scrollcommand command
+                     Specify the prefix for a command used to communicate with
+                     scrollbars for this axis, such as .sbar set.
+
+              -scrollmax value
+                     Sets the maximum limit of the  axis  scroll  region.   If
+                     value  is  "",  the maximum limit is calculated using the
+                     largest data value.  The default is "".
+
+              -scrollmin value
+                     Sets the minimum limit of axis scroll region.   If  value
+                     is "", the minimum limit is calculated using the smallest
+                     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.
+
+              -titlealternate boolean
+                     Indicates  to  display  the  axis  title in its alternate
+                     location.  Normally the axis title is centered along  the
+                     axis.   This  option  places the axis either to the right
+                     (horizontal axes) or above (vertical axes) the axis.  The
+                     default is 0.
+
+              -titlecolor color
+                     Sets the color of the axis title. The default is black.
+
+              -titlefont fontName
+                     Specifies  the font for axis title. The default is *-Hel-
+                     vetica-Bold-R-Normal-*-14-140-*.
+
+              Axis configuration options may be also be set by the option com-
+              mand.   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 ele-
+              ments.
+
+       pathName axis invtransform axisName value
+              Performs the inverse transformation, changing the screen coordi-
+              nate  value  to  a graph coordinate, mapping the value mapped to
+
+       pathName axis view axisName
+              Change the viewable area of this axis. Use as an argument  to  a
+              scrollbar's "-command".
+
+       The  default  axes are x, y, x2, and y2.  But you can display more than
+       four axes simultaneously.  You can also swap in a different  axis  with
+       use operation of the special axis components: 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 compo-
+       nent does.  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.  When more than one axis is displayed in a
+       margin, it represents the first axis displayed.
+
+       The  following  operations  are available for axes. They mirror exactly
+       the operations of the axis component.  The axis argument must be xaxis,
+       x2axis,  yaxis,  or y2axis.  This feature is deprecated since more than
+       one axis can now be used a margin.  You  should  only  use  the  xaxis,
+       x2axis,  yaxis,  and y2axis components with the use operation.  For all
+       other operations, use the general axis component instead.
+
+       pathName axis cget option
+
+       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  loca-
+              tion.   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 vertical and one
+       horizontal) drawn completely across the plotting area.  They  are  used
+       to  position the mouse in relation 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 with-
+       out redrawing the entire graph.
+
+       The following operations 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  dashList  is
+                     "", the cross hairs will be 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  map-
+              ping 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  dis-
+       played  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
+              replacing  any  existing  binding for the same sequence and tag-
+              Name.  If the first character of command is + then command  aug-
+              ments  an existing binding rather than replacing it.  If no com-
+              mand argument is provided then the command currently  associated
+              with  tagName  and  sequence (it's an error occurs if there's no
+              such binding) is returned.  If both  command  and  sequence  are
+              missing  then  a list of all the event sequences for which bind-
+              ings have been defined for tagName.
+
+       pathName element cget elemName option
+              Returns the current value of the  element  configuration  option
+              given  by  option.   Option  may be any of the options described
+              below for the element configure operation.
+
+       pathName element closest x y ?option value?... ?elemName?...
+              Searches for the data point closest to the window coordinates  x
+              and  y.  By default, all elements are searched.  Hidden elements
+              (see the -hide option is false) are ignored.  You can limit  the
+              search  by  specifying  only the elements you want to be consid-
+              ered.  ElemName must be the name of an element that can  not  be
+              hidden.   It returns a key-value list containing the name of the
+              closest element, the index of the closest data  point,  and  the
+              graph-coordinates  of  the  point.  Returns "", if no data point
+              within the  threshold  distance  can  be  found.  The  following
+              option-value pairs are available.
+
+              -along direction
+                     Search for the closest element using the following crite-
+                     ria:
+
+                     x      Find closest element vertically from the given  X-
+                            coordinate.
+
+                     y      Find  the  closest  element  horizontally from the
+                            given Y-coordinate.
+
+                     both   Find the  closest  element  for  the  given  point
+                            (using both the X and Y coordinates).
+
+              -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 string
+                     Indicates whether to consider projections that lie  along
+                     the  line  segments connecting data points when searching
+                     for the closest point.  The default value is 0. The  val-
+                     ues for string are described below.
+
+                     no          Search only for the closest data point.
+
+              -activepen penName
+                     Specifies pen to use to draw active element.  If  penName
+                     is  "", no active elements will be drawn.  The default is
+                     activeLine.
+
+              -areabackground color
+                     Specifies the background color  of  the  area  under  the
+                     curve.  The  background area color is drawn only for bit-
+                     maps (see the -areapattern option).  If color is "",  the
+                     background is transparent.  The default is black.
+
+              -areaforeground color
+                     Specifies  the  foreground  color  of  the area under the
+                     curve.  The default is black.
+
+              -areapattern pattern
+                     Specifies how to fill the area under the curve.   Pattern
+                     may  be  the  name  of  a  Tk  bitmap,  solid, or "".  If
+                     "solid", then the area under the curve is drawn with  the
+                     color  designated  by  the  -areaforeground option.  If a
+                     bitmap, then the bitmap  is  stippled  across  the  area.
+                     Here  the  bitmap colors are controlled by the -areafore-
+                     ground and -areabackground options.  If pattern is "", no
+                     filled area is drawn.  The default is "".
+
+              -areatile image
+                     Specifies  the  name of a Tk image to be used to tile the
+                     area under the curve.  This option supersedes the -areap-
+                     attern option.  Image must be a photo image.  If image is
+                     "", no tiling is performed.  The default is "".
+
+              -bindtags tagList
+                     Specifies the binding tags for the element.  TagList is a
+                     list of binding tag names.  The tags and their order will
+                     determine how events are handled for elements.  Each  tag
+                     in the list matching the current event sequence will have
+                     its Tcl command executed.  Implicitly  the  name  of  the
+                     element is always the first tag in the list.  The default
+                     value is all.
+
+              -color color
+                     Sets the color of the traces connecting the data  points.
+
+              -dashes dashList
+                     Sets  the  dash style of element line. DashList 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 dashList is "", the
+                     lines will be solid.
+
+              -data coordList
+                     Specifies  the X-Y coordinates of the data.  CoordList is
+                     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 symbols.  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 of an axis. The default  is
+                     y.
+
+              -offdash color
+                     Sets the color of the stripes when traces are dashed (see
+                     the -dashes option).  If color is "", then the "off" pix-
+                     els  will represent 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  def-
+                     color,  then  the  color  will  be the same as the -color
+                     option.  The default is defcolor.
+
+              -pen penname
+                     Set the pen to use for this element.
+
+              -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 -pixels 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
+                     dratic 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 specification, 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
+                     specified it defaults to the index  of  the  pen  in  the
+                     list.   Note  that  this  affects only symbol attributes.
+                     Line attributes, such as line  width,  dashes,  etc.  are
+                     ignored.
+
+              -symbol symbol
+                     Specifies  the  symbol  for  data  points.  Symbol 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 bit-
+                     map'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
+                     increasing, connecting lines will be drawn  only  between
+                     those data points where X-coordinate values are monotoni-
+                     cally 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 represent-
+                     ing 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.
+
+              -ydata yVec
+                     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 com-
+              mand.   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 exists elemName
+              Returns  1  if an element elemName currently exists and 0 other-
+              wise.
+
+       pathName element names ?pattern?...
+              Returns the elements matching one or more pattern.  If  no  pat-
+              tern is given, the names of all elements is returned.
+
+       pathName element show ?nameList?
+              Queries  or modifies the element display list.  The element dis-
+              play 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  dis-
+              play 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 horizon-
+       tally or vertically across the plotting area.  The following operations
+       are available for grid lines.
+
+       pathName grid cget option
+              Returns  the current value of the grid line configuration option
+              given by option.  Option may be any option described  below  for
+              the grid configure operation.
+
+       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 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 grid line option option is set to value.  The  follow-
+              ing 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. DashList 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 dashList is "", the
+                     grid will be solid lines.
+
+              -hide boolean
+                     Indicates whether the grid should be drawn. If boolean is
+
+              -minor boolean
+                     Indicates  whether  the  grid  lines  should be drawn for
+                     minor ticks.  If boolean is true, the lines  will  appear
+                     at minor tick intervals.  The default is 1.
+
+              Grid  configuration  options  may also be set by the option com-
+              mand.  The resource name and class are  grid  and  Grid  respec-
+              tively.    option   add   *Graph.grid.LineWidth   2  option  add
+              *Graph.Grid.Color     black
+
+       pathName grid off
+              Turns off the display the grid lines.
+
+       pathName grid on
+              Turns on the display the grid lines.
+
+       pathName grid toggle
+              Toggles the display of the grid.
+
+   LEGEND COMPONENT
+       The legend displays a list of the data elements.  Each  entry  consists
+       of the element's symbol and label.  The legend can appear in any margin
+       (the default location is in the right margin).  It can  also  be  posi-
+       tioned anywhere within the plotting area.
+
+       The following operations are valid for the legend.
+
+       pathName legend activate pattern...
+              Selects  legend entries to be drawn using the active legend col-
+              ors and relief.  All entries whose element names  match  pattern
+              are  selected.  To be selected, the element name must match only
+              one pattern.
+
+       pathName legend bind tagName ?sequence?  ?command?
+              Associates command with tagName such  that  whenever  the  event
+              sequence  given  by sequence occurs for a legend entry with this
+              tag, command will be invoked.  Implicitly the element  names  in
+              the  entry  are tags.  The syntax is similar to the bind command
+              except that it operates on legend entries, rather than  widgets.
+              See  the  bind manual entry for complete details on 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 tag-
+              Name.  If the first character of command is + then command  aug-
+              ments  an existing binding rather than replacing it.  If no com-
+              mand argument is provided then the command currently  associated
+              with  tagName  and  sequence (it's an error occurs if there's no
+              such binding) is returned.  If both  command  and  sequence  are
+              missing  then  a list of all the event sequences for which bind-
+              ings have been defined for tagName.
+
+              -activebackground color
+                     Sets the background color for active legend entries.  All
+                     legend  entries  marked  active  (see the legend activate
+                     operation) are drawn using this background color.
+
+              -activeborderwidth pixels
+                     Sets the width of the 3-D border around the outside  edge
+                     of the active legend entries.  The default is 2.
+
+              -activeforeground color
+                     Sets the foreground color for active legend entries.  All
+                     legend entries marked as active (see the legend  activate
+                     operation) are drawn using this foreground color.
+
+              -activerelief relief
+                     Specifies  the  3-D  effect  desired  for  active  legend
+                     entries.  Relief denotes how the interior  of  the  entry
+                     should appear relative to the legend; for example, raised
+                     means the entry should appear to protrude from  the  leg-
+                     end,  relative to the surface of the legend.  The default
+                     is flat.
+
+              -anchor anchor
+                     Tells how to position the legend relative  to  the  posi-
+                     tioning  point  for the legend.  This is dependent on the
+                     value of the -position option.  The default is center.
+
+                     left or right
+                                 The anchor describes how to position the leg-
+                                 end vertically.
+
+                     top or bottom
+                                 The anchor describes how to position the leg-
+                                 end horizontally.
+
+                     @x,y        The anchor specifies how to position the leg-
+                                 end  relative  to  the positioning point. For
+                                 example, if anchor is center then the  legend
+                                 is centered on the point; if anchor is n then
+                                 the legend will be drawn such  that  the  top
+                                 center  point of the rectangular region occu-
+                                 pied by the legend will be at the positioning
+                                 point.
+
+                     plotarea    The anchor specifies how to position the leg-
+                                 end relative to the plotting area. For  exam-
+                                 ple,  if  anchor is center then the legend is
+                                 centered in the plotting area; if  anchor  is
+                                 ne  then  the  legend will be drawn such that
+                                 occupies the upper right corner of the  plot-
+                                 ting area.
+
+                     Sets  the width of the 3-D border around the outside edge
+                     of the legend (if such border is being drawn; the  relief
+                     option determines this).  The default is 2 pixels.
+
+              -font fontName
+                     FontName  specifies a font to use when drawing the labels
+                     of each element into the legend.  The default  is  *-Hel-
+                     vetica-Bold-R-Normal-*-12-120-*.
+
+              -foreground color
+                     Sets  the foreground color of the text drawn for the ele-
+                     ment's label.  The default is black.
+
+              -hide boolean
+                     Indicates whether the  legend  should  be  displayed.  If
+                     boolean  is  true,  the  legend  will  not  be draw.  The
+                     default is no.
+
+              -ipadx pad
+                     Sets the amount of internal padding to be  added  to  the
+                     width  of each legend entry.  Pad can be a list of one or
+                     two screen distances.  If pad has two elements, the  left
+                     side  of the legend entry is padded by the first distance
+                     and the right side by the second.  If  pad  is  just  one
+                     distance,  both  the  left  and  right  sides  are padded
+                     evenly.  The default is 2.
+
+              -ipady pad
+                     Sets an amount of internal padding to  be  added  to  the
+                     height of each legend entry.  Pad can be a list of one or
+                     two screen distances.  If pad has two elements,  the  top
+                     of the entry is padded by the first distance and the bot-
+                     tom by the second.  If pad is just one distance, both the
+                     top  and  bottom  of  the  entry  are padded evenly.  The
+                     default is 2.
+
+              -padx pad
+                     Sets the padding to the left and right exteriors  of  the
+                     legend.   Pad  can  be  a  list of one or two screen dis-
+                     tances.  If pad has two elements, the left  side  of  the
+                     legend is padded by the first distance and the right side
+                     by the second.  If pad has just one  distance,  both  the
+                     left  and  right sides are padded evenly.  The default is
+                     4.
+
+              -pady pad
+                     Sets the padding above and below the legend.  Pad can  be
+                     a  list  of  one or two screen distances.  If pad has two
+                     elements, the area above the  legend  is  padded  by  the
+                     first  distance and the area below by the second.  If pad
+                     is just one distance, both the top and bottom  areas  are
+                     padded evenly.  The default is 0.
+                     plotting area.  If boolean is true, the  legend  will  be
+                     drawn  on  top  of  any elements that may overlap it. The
+                     default is no.
+
+              -relief relief
+                     Specifies the 3-D effect for the border around  the  leg-
+                     end.   Relief  specifies  how  the interior of the legend
+                     should appear relative to the graph; for example,  raised
+                     means  the  legend  should  appear  to  protrude from the
+                     graph, relative to the surface of the graph.  The default
+                     is sunken.
+
+              Legend  configuration options may also be set by the option com-
+              mand.  The resource name and class are legend and Legend respec-
+              tively.   option  add  *Graph.legend.Foreground  blue option add
+              *Graph.Legend.Relief     raised
+
+       pathName legend deactivate pattern...
+              Selects legend entries to be drawn using the normal legend  col-
+              ors  and  relief.  All entries whose element names match pattern
+              are selected.  To be selected, the element name must match  only
+              one pattern.
+
+       pathName legend get pos
+              Returns  the  name  of  the element whose entry is at the screen
+              position pos in the legend.  Pos must be  in  the  form  "@x,y",
+              where  x and y are window coordinates.  If the given coordinates
+              do not lie over a legend entry, "" is returned.
+
+   PEN COMPONENTS
+       Pens define attributes (both symbol and line style) for elements.  Pens
+       mirror  the  configuration options of data elements that pertain to how
+       symbols and lines are drawn.  Data elements use pens to  determine  how
+       they  are drawn.  A data element may use several pens at once.  In this
+       case, the pen used for a particular data point is determined from  each
+       element's weight vector (see the element's -weight and -style options).
+
+       One pen, called activeLine, is automatically created.  It's used as the
+       default  active  pen  for  elements.  So  you  can  change  the  active
+       attributes for all elements by simply reconfiguring this pen.   .g  pen
+       configure  "activeLine"  -color  green  You  can create and use several
+       pens. To create a pen, invoke the pen component and its  create  opera-
+       tion.   .g pen create myPen You map pens to a data element using either
+       the element's -pen or -activepen options.  .g  element  create  "line1"
+       -xdata $x -ydata $tempData \
+           -pen myPen An element can use several pens at once. This is done by
+       specifying the name of the pen in the element's  style  list  (see  the
+       -styles  option).  .g element configure "line1" -styles { myPen 2.0 3.0
+       } This says that any data point with a weight between 2.0 and 3.0 is to
+       be drawn using the pen myPen.  All other points are drawn with the ele-
+       ment's default attributes.
+
+              specified,  then  for each pair, the pen option option is set to
+              value.  The following options are valid for pens.
+
+              -color color
+                     Sets the color of the traces connecting the data  points.
+
+              -dashes dashList
+                     Sets  the  dash style of element line. DashList 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 dashList is "", the
+                     lines will be solid.
+
+              -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.
+
+              -linewidth pixels
+                     Sets the width  of  the  connecting  lines  between  data
+                     points.   If  pixels  is  0,  no connecting lines will be
+                     drawn between symbols.  The default is 0.
+
+              -offdash color
+                     Sets the color of the stripes when traces are dashed (see
+                     the -dashes option).  If color is "", then the "off" pix-
+                     els will represent 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 def-
+                     color, 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.
+
+              -symbol symbol
+                     Specifies the symbol for  data  points.   Symbol  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  bit-
+                     map's optional mask.  The default is circle.
+
+              Creates a new pen by the name penName.  No pen by the same  name
+              can  already  exist.  Option and value are described in above in
+              the pen configure operation.
+
+       pathName pen delete ?penName?...
+              Deletes the named pens. A pen is not really deleted until it  is
+              not  longer  in  use, so it's safe to delete pens mapped to ele-
+              ments.
+
+       pathName pen names ?pattern?...
+              Returns a list of pens matching zero or more  patterns.   If  no
+              pattern argument is give, the names of all pens are returned.
+
+   POSTSCRIPT COMPONENT
+       The  graph can generate encapsulated PostScript output.  There are sev-
+       eral configuration options you can specify to control how the plot will
+       be  generated.   You  can  change the page dimensions and borders.  The
+       plot itself can be scaled, centered,  or  rotated  to  landscape.   The
+       PostScript output can be written directly to a file or returned through
+       the interpreter.
+
+       The following postscript operations are available.
+
+       pathName postscript cget option
+              Returns the current value of  the  postscript  option  given  by
+              option.   Option may be any option described below for the post-
+              script configure operation.
+
+       pathName postscript configure ?option value?...
+              Queries or modifies the  configuration  options  for  PostScript
+              generation.   If  option  isn't specified, a list describing the
+              current postscript 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  postscript  option option is set to
+              value.  The following postscript options are available.
+
+              -center boolean
+                     Indicates whether the plot  should  be  centered  on  the
+                     PostScript  page.   If boolean is false, the plot will be
+                     placed in the upper left corner of the page.  The default
+                     is 1.
+
+              -colormap varName
+                     VarName  must be the name of a global array variable that
+                     specifies a color mapping from the X color name to  Post-
+                     Script.   Each  element  of varName must consist of Post-
+                     Script code to set a particular color value  (e.g.  ``1.0
+                     1.0  0.0  setrgbcolor'').  When generating color informa-
+                     tion in PostScript, the array variable varName is checked
+                     if  an element of the name as the color exists. If so, it
+                     uses its value as  the  PostScript  command  to  set  the
+                     Script.   Each  element  of varName must consist of a Tcl
+                     list with one or two elements; the name and point size of
+                     a  PostScript  font.  When outputting PostScript commands
+                     for a particular font,  the  array  variable  varName  is
+                     checked  to  see  if  an  element  by  the specified font
+                     exists.  If there is  such  an  element,  then  the  font
+                     information  contained  in  that  element  is used in the
+                     PostScript output.  (If the point size  is  omitted  from
+                     the  list, the point size of the X font is used).  Other-
+                     wise the X font is examined in an attempt to  guess  what
+                     PostScript  font to use.  This works only for fonts whose
+                     foundry property is  Adobe  (such  as  Times,  Helvetica,
+                     Courier,  etc.).   If  all  of  this  fails then the font
+                     defaults to Helvetica-Bold.
+
+              -decorations boolean
+                     Indicates whether PostScript commands to  generate  color
+                     backgrounds  and  3-D borders will be output.  If boolean
+                     is false, the background will be white and no 3-D borders
+                     will be generated. The default is 1.
+
+              -height pixels
+                     Sets  the  height  of  the plot.  This lets you print the
+                     graph with a height different from the one drawn  on  the
+                     screen.   If  pixels  is 0, the height is the same as the
+                     widget's height.  The default is 0.
+
+              -landscape boolean
+                     If boolean is true, this specifies 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 0.
+
+              -maxpect boolean
+                     Indicates  to  scale  the plot so that it fills the Post-
+                     Script page.  The aspect ratio  of  the  graph  is  still
+                     retained.  The default is 0.
+
+              -padx pad
+                     Sets  the  horizontal padding for the left and right page
+                     borders.  The borders are exterior to the plot.  Pad  can
+                     be a list of one or two screen distances.  If pad has two
+                     elements, the left border is padded by the first distance
+                     and  the right border by the second.  If pad has just one
+                     distance, both the left  and  right  borders  are  padded
+                     evenly.  The default is 1i.
+
+              -pady pad
+                     Sets  the  vertical  padding  for the top and bottom page
+                     borders. The borders are exterior to the plot.   Pad  can
+                     The default width is 8.5i.
+
+              -width pixels
+                     Sets  the  width  of  the plot.  This lets you generate a
+                     plot of a width different from that of  the  widget.   If
+                     pixels is 0, the width is the same as the widget's width.
+                     The default is 0.
+
+              Postscript configuration options may  be  also  be  set  by  the
+              option  command.  The resource name and class are postscript and
+              Postscript respectively.  option  add  *Graph.postscript.Decora-
+              tions false option add *Graph.Postscript.Landscape   true
+
+       pathName postscript output ?fileName? ?option value?...
+              Outputs  a file of encapsulated PostScript.  If a fileName argu-
+              ment isn't present, the command returns the PostScript.  If  any
+              option-value  pairs  are present, they set configuration options
+              controlling how the PostScript is generated.  Option  and  value
+              can  be  anything accepted by the postscript configure operation
+              above.
+
+   MARKER COMPONENTS
+       Markers are simple drawing procedures used  to  annotate  or  highlight
+       areas of the graph.  Markers have various types: text strings, bitmaps,
+       images, connected lines, windows, or polygons.  They can be  associated
+       with  a  particular  element, so that when the element is hidden or un-
+       hidden, so is the marker.  By  default,  markers  are  the  last  items
+       drawn,  so  that  data  elements  will  appear in behind them.  You can
+       change this by configuring the -under option.
+
+       Markers, in contrast to elements, don't affect the scaling of the coor-
+       dinate axes.  They can also have elastic coordinates (specified by -Inf
+       and Inf respectively) that translate into the minimum or maximum  limit
+       of  the axis.  For example, you can place a marker so it always remains
+       in the lower left corner of the plotting area, by using the coordinates
+       -Inf,-Inf.
+
+       The following operations are available for markers.
+
+       pathName marker after markerId ?afterId?
+              Changes the order of the markers, drawing the first marker after
+              the second.  If no second afterId  argument  is  specified,  the
+              marker  is  placed at the end of the display list.  This command
+              can be used to control how markers are displayed  since  markers
+              are drawn in the order of this display list.
+
+       pathName marker before markerId ?beforeId?
+              Changes  the  order  of  the  markers,  drawing the first marker
+              before the second.  If no second beforeId argument is specified,
+              the marker is placed at the beginning of the display list.  This
+              command can be used to control how markers are  displayed  since
+              markers are drawn in the order of this display list.
+              with  tagName  and  sequence (it's an error occurs if there's no
+              such binding) is returned.  If both  command  and  sequence  are
+              missing  then  a list of all the event sequences for which bind-
+              ings have been defined for tagName.
+
+       pathName marker cget option
+              Returns the current value of  the  marker  configuration  option
+              given  by  option.   Option may be any option described below in
+              the configure operation.
+
+       pathName marker configure markerId ?option value?...
+              Queries or modifies the configuration options for  markers.   If
+              option  isn't  specified,  a list describing the current options
+              for markerId 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 marker option option is set to value.
+
+              The  following  options are valid for all markers.  Each type of
+              marker  also  has  its  own  type-specific  options.   They  are
+              described in the sections below.
+
+              -bindtags tagList
+                     Specifies  the binding tags for the marker.  TagList is a
+                     list of binding tag names.  The tags and their order will
+                     determine  how  events for markers are handled.  Each tag
+                     in the list matching the current event sequence will have
+                     its  Tcl  command  executed.   Implicitly the name of the
+                     marker is always the first tag in the list.  The  default
+                     value is all.
+
+              -coords coordList
+                     Specifies  the coordinates of the marker.  CoordList is a
+                     list of graph coordinates.   The  number  of  coordinates
+                     required  is  dependent  on  the  type  of marker.  Text,
+                     image, and window markers need only two  coordinates  (an
+                     X-Y  coordinate).   Bitmap markers can take either two or
+                     four coordinates (if four, they represent the corners  of
+                     the bitmap). Line markers need at least four coordinates,
+                     polygons at least six.  If coordList is  "",  the  marker
+                     will not be displayed.  The default is "".
+
+              -element elemName
+                     Links  the  marker with the element elemName.  The marker
+                     is drawn only if the element is also currently  displayed
+                     (see  the  element's show operation).  If elemName is "",
+                     the marker is always drawn.  The default is "".
+
+              -hide boolean
+                     Indicates whether the marker  is  drawn.  If  boolean  is
+                     true, the marker is not drawn.  The default is no.
+
+              -under boolean
+                     Indicates whether the marker is  drawn  below/above  data
+                     elements.   If  boolean  is  true, the marker is be drawn
+                     underneath the data element symbols  and  lines.   Other-
+                     wise,  the  marker  is  drawn on top of the element.  The
+                     default is 0.
+
+              -xoffset pixels
+                     Specifies a screen distance to offset the marker horizon-
+                     tally.   Pixels  is a valid screen distance, such as 2 or
+                     1.2i.  The default is 0.
+
+              -yoffset pixels
+                     Specifies a screen distance to offset the markers  verti-
+                     cally.   Pixels  is a valid screen distance, such as 2 or
+                     1.2i.  The default is 0.
+
+              Marker configuration options may also be set by the option  com-
+              mand.   The resource class is either BitmapMarker,  ImageMarker,
+              LineMarker, PolygonMarker, TextMarker, or WindowMarker,  depend-
+              ing on the type of marker.  The resource name is the name of the
+              marker.  option add  *Graph.TextMarker.Foreground  white  option
+              add     *Graph.BitmapMarker.Foreground    white    option    add
+              *Graph.m1.Background     blue
+
+       pathName marker create type ?option value?...
+              Creates a marker of the selected type. Type may be either  text,
+              line,  bitmap,  image, polygon, or window.  This command returns
+              the marker identifier, used as  the  markerId  argument  in  the
+              other  marker-related  commands.   If  the -name option is used,
+              this overrides the normal marker identifier.  If the  name  pro-
+              vided  is  already  used for another marker, the new marker will
+              replace the old.
+
+       pathName marker delete ?name?...
+              Removes one of more markers.  The graph  will  automatically  be
+              redrawn without the marker..
+
+       pathName marker exists markerId
+              Returns 1 if the marker markerId exists and 0 otherwise.
+
+       pathName marker names ?pattern?
+              Returns  the  names of all the markers that currently exist.  If
+              pattern is supplied, only those markers  whose  names  match  it
+              will be returned.
+
+       pathName marker type markerId
+              Returns  the  type of the marker given by markerId, such as line
+              or text.  If markerId is not a valid a marker identifier, ""  is
+              returned.
+
+   BITMAP MARKERS
+       The following options are specific to bitmap markers:
+
+       -background color
+              Same as the -fill option.
+
+       -bitmap bitmap
+              Specifies  the  bitmap  to  be  displayed.  If bitmap is "", the
+              marker will not be displayed.  The default is "".
+
+       -fill color
+              Sets the background color of the bitmap.  If color is the  empty
+              string,  no  background  will be transparent.  The default back-
+              ground color is "".
+
+       -foreground color
+              Same as the -outline option.
+
+       -mask mask
+              Specifies a mask for the bitmap to be displayed. This mask is  a
+              bitmap  itself,  denoting  the  pixels that are transparent.  If
+              mask is "", all pixels of the bitmap will be drawn.  The default
+              is "".
+
+       -outline color
+              Sets  the  foreground  color of the bitmap. The default value is
+              black.
+
+       -rotate theta
+              Sets the rotation of the bitmap.  Theta is a real number  repre-
+              senting  the  angle of rotation in degrees.  The marker is first
+              rotated and then placed according to its anchor  position.   The
+              default rotation is 0.0.
+
+   IMAGE MARKERS
+       A  image  marker displays an image.  Image markers are created with the
+       marker's create operation in the form:  pathName  marker  create  image
+       ?option  value?...   There  may be many option-value pairs, each sets a
+       configuration option for the marker.  These same option-value pairs may
+       be used with the marker's configure operation.
+
+       The following options are specific to image markers:
+
+       -anchor anchor
+              Anchor tells how to position the image relative to the position-
+              ing point for the image. For example, if anchor is  center  then
+              the  image  is  centered  on the point;  if anchor is n then the
+              image will be drawn such that the top center point of the  rect-
+              angular  region occupied by the image will be at the positioning
+              point.  This option defaults to center.
+
+       -image image
+              Specifies the image to be drawn.  If image  is  "",  the  marker
+              gaps  on  the  line.  Each number must be between 1 and 255.  If
+              dashList is "", the marker line will be solid.
+
+       -fill color
+              Sets the background color of the line.  This color is used  with
+              striped  lines  (see the -fdashes option). If color is the empty
+              string, no background color is drawn (the line will  be  dashed,
+              not striped).  The default background color is "".
+
+       -linewidth pixels
+              Sets the width of the lines.  The default width is 0.
+
+       -outline color
+              Sets  the  foreground  color  of  the line. The default value is
+              black.
+
+       -stipple bitmap
+              Specifies a stipple pattern used to draw the line, rather than a
+              solid  line.   Bitmap  specifies  a bitmap to use as the stipple
+              pattern.  If bitmap is "", then the line is  drawn  in  a  solid
+              fashion. The default is "".
+
+   POLYGON MARKERS
+       A polygon marker displays a closed region described as two or more con-
+       nected line segments.  It is assumed the first and last points are con-
+       nected.   Polygon markers are created using the marker create operation
+       in the form: pathName marker create polygon  ?option  value?...   There
+       may  be  many  option-value pairs, each sets a configuration option for
+       the marker.  These same option-value pairs may be used with the  marker
+       configure  command to change the marker's configuration.  The following
+       options are supported for polygon markers:
+
+       -dashes dashList
+              Sets the dash style of the outline of the polygon. DashList is a
+              list  of up to 11 numbers that alternately represent the lengths
+              of the dashes and gaps on the  outline.   Each  number  must  be
+              between  1  and  255.  If  dashList is "", the outline will be a
+              solid line.
+
+       -fill color
+              Sets the fill color of the polygon.  If color is  "",  then  the
+              interior of the polygon is transparent.  The default is white.
+
+       -linewidth pixels
+              Sets the width of the outline of the polygon. If pixels is zero,
+              no outline is drawn. The default is 0.
+
+       -outline color
+              Sets the color of the outline of the polygon.  If the polygon is
+              stippled  (see  the  -stipple  option), then this represents the
+              foreground color of the stipple.  The default is black.
+
+       the marker's configure operation.
+
+       The following options are specific to text markers:
+
+       -anchor anchor
+              Anchor tells how to position the text relative to the  position-
+              ing  point  for  the text. For example, if anchor is center then
+              the text is centered on the point; if anchor is n then the  text
+              will  be drawn such that the top center point of the rectangular
+              region occupied by the text will be at  the  positioning  point.
+              This default is center.
+
+       -background color
+              Same as the -fill option.
+
+       -font fontName
+              Specifies  the  font  of  the text.  The default is *-Helvetica-
+              Bold-R-Normal-*-120-*.
+
+       -fill color
+              Sets the background color of the text.  If color  is  the  empty
+              string,  no  background  will be transparent.  The default back-
+              ground color is "".
+
+       -foreground color
+              Same as the -outline option.
+
+       -justify justify
+              Specifies how the text should be justified.  This  matters  only
+              when  the  marker  contains  more than one line of text. Justify
+              must be left, right, or center.  The default is center.
+
+       -outline color
+              Sets the color of the text. The default value is black.
+
+       -padx pad
+              Sets the padding to the left and right exteriors  of  the  text.
+              Pad  can  be  a list of one or two screen distances.  If pad has
+              two elements, the left side of the text is padded by  the  first
+              distance  and the right side by the second.  If pad has just one
+              distance, both the left and right sides are padded evenly.   The
+              default is 4.
+
+       -pady pad
+              Sets the padding above and below the text.  Pad can be a list of
+              one or two screen distances.  If pad has two elements, the  area
+              above  the  text  is  padded  by the first distance and the area
+              below by the second.  If pad is just one distance, both the  top
+              and bottom areas are padded evenly.  The default is 4.
+
+       -rotate theta
+              Specifies  the number of degrees to rotate the text.  Theta is a
+
+       option-value pairs may be used with the marker's configure command.
+
+       The following options are specific to window markers:
+
+       -anchor anchor
+              Anchor tells how to position the widget relative  to  the  posi-
+              tioning  point  for the widget. For example, if anchor is center
+              then the widget is centered on the point; if anchor  is  n  then
+              the  widget  will be displayed such that the top center point of
+              the rectangular region occupied by the widget  will  be  at  the
+              positioning point.  This option defaults to center.
+
+       -height pixels
+              Specifies  the height to assign to the marker's window.  If this
+              option isn't specified, or if it is specified as  "",  then  the
+              window  is given whatever height the widget requests internally.
+
+       -width pixels
+              Specifies the width to assign to the marker's window.   If  this
+              option  isn't  specified,  or if it is specified as "", then the
+              window is given whatever width the widget requests internally.
+
+       -window pathName
+              Specifies the widget to be managed by the graph.  PathName  must
+              be a child of the graph widget.
+
+
+
+

GRAPH COMPONENT BINDINGS

+       Specific  graph  components,  such  as  elements,  markers  and  legend
+       entries, can have a command trigger when event  occurs  in  them,  much
+       like  canvas  items in Tk's canvas widget.  Not all event sequences are
+       valid.  The only binding events that may be specified are those related
+       to  the  mouse and keyboard (such as Enter, Leave, ButtonPress, Motion,
+       and KeyPress).
+
+       Only one element or marker can be picked during an event.  This  means,
+       that  if  the mouse is directly over both an element and a marker, only
+       the uppermost component  is  selected.   This  isn't  true  for  legend
+       entries.   Both  a legend entry and an element (or marker) binding com-
+       mands will be invoked if both items are picked.
+
+       It is possible for multiple bindings to match a particular event.  This
+       could occur, for example, if one binding is associated with the element
+       name and another is associated with one of the element's tags (see  the
+       -bindtags  option).  When this occurs, all of the matching bindings are
+       invoked.  A binding associated with the element name is invoked  first,
+       followed  by  one binding for each of the element's bindtags.  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 terminates that script  and
+       skips  any  remaining  scripts for the event, just as for the bind com-
+       mand.
+
+       vectors are updated.
+
+       From  Tcl,  create  the  vectors and configure the element to use them.
+       vector X Y .g element configure line1 -xdata X -ydata  Y  To  set  data
+       points  from  C,  you  pass  the  values as arrays of doubles using the
+       Blt_ResetVector call.  The vector is reset with the new data and at the
+       next  idle  point (when Tk re-enters its event loop), the graph will be
+       redrawn automatically.  #include <tcl.h> #include <blt.h>
+
+       register int i; Blt_Vector *xVec, *yVec; double x[50], y[50];
+
+       /* Get the BLT vectors "X" and "Y"  (created  above  from  Tcl)  */  if
+       ((Blt_GetVector(interp, "X", &xVec) != TCL_OK) ||
+           (Blt_GetVector(interp, "Y", &yVec) != TCL_OK)) {
+           return TCL_ERROR; }
+
+       for (i = 0; i < 50; i++) {
+           x[i] = i * 0.02;
+           y[i] = sin(x[i]); }
+
+       /*  Put  the data into BLT vectors */ if ((Blt_ResetVector(xVec, x, 50,
+       50, TCL_VOLATILE) != TCL_OK) ||
+           (Blt_ResetVector(yVec, y, 50, 50, TCL_VOLATILE) != TCL_OK)) {
+          return TCL_ERROR; } See the vector manual page for more details.
+
+
+
+

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.
+
+       o Try to minimize the number of data points.  The more data points  the
+         looked at, the more work the graph must do.
+
+       o If your data is generated as floating point values, the time required
+         to convert the data values to and from ASCII strings can be  signifi-
+         cant,  especially when there any many data points.  You can avoid the
+         redundant string-to-decimal conversions using the C API to  BLT  vec-
+         tors.
+
+       o 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 symbols such as splus and scross.
+
+       o Don't stipple or dash the element.  Solid lines are much faster.
+
+       o 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  ele-
+         ments 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
+
+
+
+BLT                               BLT_VERSION                         graph(n)
+
+
+
+Man(1) output converted with +man2html +
+ + diff --git a/doc/vector.html b/doc/vector.html new file mode 100644 index 0000000..37ad3c3 --- /dev/null +++ b/doc/vector.html @@ -0,0 +1,704 @@ + + +
+
+
+
+

SYNOPSIS

+       blt::vector create vecName ?vecName...? ?switches?
+
+       blt::vector destroy vecName ?vecName...?
+
+       blt::vector expr expression
+
+       blt::vector names ?pattern...?
+
+
+
+

DESCRIPTION

+       The vector command creates an array of floating point values.  The vec-
+       tor's components can be manipulated in three ways: through a Tcl  array
+       variable, a Tcl command, or the C API.
+
+
+
+

INTRODUCTION

+       A vector is an ordered set of real numbers.  The components of a vector
+       are indexed by integers.
+
+       Vectors are common data structures for many applications.  For example,
+       a  graph  may  use  two vectors to represent the X-Y coordinates of the
+       data plotted.  The graph will automatically be redrawn when the vectors
+       are  updated or changed. By using vectors, you can separate data analy-
+       sis from the graph widget.  This makes it easier, for example,  to  add
+       data  transformations, such as splines.  It's possible to plot the same
+       data to in multiple graphs, where each graph presents a different  view
+       or scale of the data.
+
+       You  could  try to use Tcl's associative arrays as vectors.  Tcl arrays
+       are easy to use.  You can access individual elements randomly by speci-
+       fying  the  index,  or  the set the entire array by providing a list of
+       index and value pairs for each element.  The disadvantages of  associa-
+       tive  arrays  as  vectors  lie in the fact they are implemented as hash
+       tables.
+
+       o There's no implied ordering to the associative arrays.  If  you  used
+         vectors  for  plotting, you would want to insure the second component
+         comes after the first, an so on.  This isn't  possible  since  arrays
+         are actually hash tables.  For example, you can't get a range of val-
+         ues between two indices.  Nor can you sort an array.
+
+       o Arrays consume lots of memory when the  number  of  elements  becomes
+         large  (tens of thousands).  This is because each element's index and
+         value are stored as strings in the hash table.
+
+       o The C programming interface is unwieldy.  Normally with vectors,  you
+         would  like to view the Tcl array as you do a C array, as an array of
+         floats or doubles.  But with hash tables, you must convert  both  the
+         index  and  value to and from decimal strings, just to access an ele-
+         ment in the array.  This makes it cumbersome to perform operations on
+         the array as a whole.
+
+       The  vector  command  tries to overcome these disadvantages while still
+       0.0.  In addition, both a Tcl command and array variable, both named y,
+       are created.  You can use either the command or variable  to  query  or
+       modify components of the vector.  # Set the first value.  set y(0) 9.25
+       puts "y has [y length] components" The array y can be used to  read  or
+       set individual components of the vector.  Vector components are indexed
+       from zero.  The array index must be a number less than  the  number  of
+       components.  For example, it's an error if you try to set the 51st ele-
+       ment of y.  # This is an error. The vector only has 50 components.  set
+       y(50) 0.02 You can also specify a range of indices using a colon (:) to
+       separate the first and last indices of the range.  # Set the first  six
+       components  of y set y(0:5) 25.2 If you don't include an index, then it
+       will default to the first and/or last component of the vector.  # Print
+       out  all  the  components  of y puts "y = $y(:)" There are special non-
+       numeric indices.  The index end, specifies the last  component  of  the
+       vector.  It's an error to use this index if the vector is empty (length
+       is zero).  The index ++end can be used to extend the vector by one com-
+       ponent  and initialize it to a specific value.  You can't read from the
+       array using this index, though.  # Extend the vector by one  component.
+       set  y(++end)  0.02  The  other  special indices are min and max.  They
+       return the current smallest and largest components of  the  vector.   #
+       Print the bounds of the vector puts "min=$y(min) max=$y(max)" To delete
+       components from a vector, simply unset the corresponding array element.
+       In the following example, the first component of y is deleted.  All the
+       remaining components of y will be moved down by one index as the length
+       of  the  vector  is reduced by one.  # Delete the first component unset
+       y(0) puts "new first element is $y(0)" The  vector's  Tcl  command  can
+       also  be  used to query or set the vector.  # Create and set the compo-
+       nents of a new vector blt::vector create x x set { 0.02 0.04 0.06  0.08
+       0.10 0.12 0.14 0.16 0.18 0.20 } Here we've created a vector x without a
+       initial length specification.  In this case, the length is  zero.   The
+       set  operation  resets  the vector, extending it and setting values for
+       each new component.
+
+       There are several operations for vectors.  The  range  operation  lists
+       the  components of a vector between two indices.  # List the components
+       puts "x = [x range 0 end]" You can search for a particular value  using
+       the  search  operation.  It returns a list of indices of the components
+       with the same value.  If no component has the same  value,  it  returns
+       "".   #  Find  the index of the biggest component set indices [x search
+       $x(max)] Other operations copy,  append,  or  sort  vectors.   You  can
+       append  vectors  or  new values onto an existing vector with the append
+       operation.  # Append assorted vectors and values to x x append x2 x3  {
+       2.3  4.5  }  x4 The sort operation sorts the vector.  If any additional
+       vectors are specified, they are rearranged in the  same  order  as  the
+       vector.   For example, you could use it to sort data points represented
+       by x and y vectors.  # Sort the data points x sort y The  vector  x  is
+       sorted  while  the  components of y are rearranged so that the original
+       x,y coordinate pairs are retained.
+
+       The expr operation lets you perform arithmetic on vectors.  The  result
+       is stored in the vector.  # Add the two vectors and a scalar x expr { x
+       + y } x expr { x * 2 } When a vector is modified, resized, or  deleted,
+       Vectors are created using the vector create operation.  Th create oper-
+       ation can be invoked in one of three forms:
+
+       blt::vector create vecName
+              This  creates a new vector vecName which initially has no compo-
+              nents.
+
+       blt::vector create vecName(size)
+              This second form creates a new vector which  will  contain  size
+              number  of  components.  The components will be indexed starting
+              from zero (0). The default value for the components is 0.0.
+
+       blt::vector create vecName(first:last)
+              The last form creates a new  vector  of  indexed  first  through
+              last.   First and last can be any integer value so long as first
+              is less than last.
+
+       Vector names must start with a letter and consist of  letters,  digits,
+       or  underscores.   #  Error:  must start with letter blt::vector create
+       1abc You can automatically generate vector names using the "#auto" vec-
+       tor  name.   The  create  operation will generate a unique vector name.
+       set vec [blt::vector create #auto] puts "$vec has [$vec length]  compo-
+       nents"
+
+   VECTOR INDICES
+       Vectors  are indexed by integers.  You can access the individual vector
+       components via its array variable or Tcl command.   The  string  repre-
+       senting  the index can be an integer, a numeric expression, a range, or
+       a special keyword.
+
+       The index must lie within the current range of the vector, otherwise an
+       an  error  message  is  returned.  Normally the indices of a vector are
+       start from 0.  But you can use the offset operation to  change  a  vec-
+       tor's  indices  on-the-fly.   puts  $vecName(0)  vecName offset -5 puts
+       $vecName(-5) You can also use  numeric  expressions  as  indices.   The
+       result  of  the expression must be an integer value.  set n 21 set vec-
+       Name($n+3) 50.2 The following special non-numeric  indices  are  avail-
+       able:  min,  max, end, and ++end.  puts "min = $vecName($min)" set vec-
+       Name(end) -1.2 The indices min and max will return the minimum and max-
+       imum values of the vector.  The index end returns the value of the last
+       component in the vector.  The index ++end is used to append  new  value
+       onto  the vector.  It automatically extends the vector by one component
+       and sets its value.  # Append an new component  to  the  end  set  vec-
+       Name(++end)  3.2 A range of indices can be indicated by a colon (:).  #
+       Set the first six components to 1.0 set vecName(0:5) 1.0 If no index is
+       supplied the first or last component is assumed.  # Print the values of
+       all the components puts $vecName(:)
+
+
+
+

VECTOR OPERATIONS

+       blt::vector create vecName?(size)?... ?switches?
+              The create operation creates a new vector vecName.  Both  a  Tcl
+              command  and  array variable vecName are also created.  The name
+                     then  no  variable  will be mapped.  You can always map a
+                     variable back to the vector using the  vector's  variable
+                     operation.
+
+              -command cmdName
+                     Maps  a  Tcl  command  to  the  vector. The vector can be
+                     accessed using cmdName and one  of  the  vector  instance
+                     operations.   A  Tcl  command by that name cannot already
+                     exist.  If cmdName is the empty string, no  command  map-
+                     ping will be made.
+
+              -watchunset boolean
+                     Indicates  that  the  vector  should automatically delete
+                     itself if the variable  associated  with  the  vector  is
+                     unset.  By default, the vector will not be deleted.  This
+                     is different from  previous  releases.   Set  boolean  to
+                     "true" to get the old behavior.
+
+       blt::vector destroy vecName ?vecName...?
+              Deletes  one  or  more  vectors.  Both the Tcl command and array
+              variable are removed also.
+
+       blt::vector expr expression
+              All binary operators take vectors  as  operands  (remember  that
+              numbers are treated as one-component vectors).  The exact action
+              of binary operators depends upon the length of the second  oper-
+              and.   If  the  second operand has only one component, then each
+              element of the first vector operand is computed by  that  value.
+              For  example,  the  expression "x * 2" multiples all elements of
+              the vector x by 2.  If the second operand has more than one com-
+              ponent,  both  operands  must  be the same length.  Each pair of
+              corresponding elements are computed.  So "x + y"  adds  the  the
+              first components of x and y together, the second, and so on.
+
+              The  valid  operators  are  listed  below, grouped in decreasing
+              order of precedence:
+
+              -  !                Unary minus  and  logical  NOT.   The  unary
+                                  minus  flips  the  sign of each component in
+                                  the  vector.   The  logical   not   operator
+                                  returns  a vector of whose values are 0.0 or
+                                  1.0.  For each  non-zero  component  1.0  is
+                                  returned, 0.0 otherwise.
+
+              ^                   Exponentiation.
+
+              *  /  %             Multiply, divide, remainder.
+
+              +  -                Add and subtract.
+
+              <<  >>              Left and right shift.  Circularly shifts the
+                                  values of the vector (not implemented  yet).
+
+              &&                  Logical AND.  Produces a 1  result  if  both
+                                  operands are non-zero, 0 otherwise.
+
+              ||                  Logical OR.  Produces a 0 result if both op-
+                                  erands are zero, 1 otherwise.
+
+              x?y:z               If-then-else, as  in  C.   (Not  implemented
+                                  yet).
+
+              See  the  C  manual  for more details on the results produced by
+              each operator.  All of the binary operators group  left-to-right
+              within the same precedence level.
+
+              Several  mathematical functions are supported for vectors.  Each
+              of the following functions invokes the math library function  of
+              the  same name; see the manual entries for the library functions
+              for details on what they do.  The operation is  applied  to  all
+              elements     of    the    vector    returning    the    results.
+              acos        cos         hypot      sinh
+              asin        cosh        log        sqrt
+              atan        exp         log10      tan
+              ceil        floor       sin        tanh   Additional   functions
+              are:
+
+              abs       Returns the absolute value of each component.
+
+              random    Returns a vector of non-negative values uniformly dis-
+                        tributed  between  [0.0, 1.0) using drand48.  The seed
+                        comes from the internal clock of the machine or may be
+                        set manual with the srandom function.
+
+              round     Rounds each component of the vector.
+
+              srandom   Initializes the random number generator using srand48.
+                        The high order 32-bits are set using the integral por-
+                        tion  of  the first vector component. All other compo-
+                        nents are ignored.  The low order 16-bits are  set  to
+                        an arbitrary value.
+
+              The following functions return a single value.
+
+              adev      Returns  the  average deviation (defined as the sum of
+                        the absolute values of the differences between  compo-
+                        nent  and  the mean, divided by the length of the vec-
+                        tor).
+
+              kurtosis  Returns the degree of peakedness  (fourth  moment)  of
+                        the vector.
+
+              length    Returns the number of components in the vector.
+
+              max       Returns the vector's maximum value.
+                        root of the variance) of the vector.
+
+              skew      Returns the skewness (or third moment) of the  vector.
+                        This characterizes the degree of asymmetry of the vec-
+                        tor about the mean.
+
+              sum       Returns the sum of the components.
+
+              var       Returns the variance of the vector.  The  sum  of  the
+                        squared  differences  between  each  component and the
+                        mean is computed.  The variance is the sum divided  by
+                        the length of the vector minus 1.
+
+              The  last  set  returns a vector of the same length as the argu-
+              ment.
+
+              norm      Scales the values of the vector to lie  in  the  range
+                        [0.0..1.0].
+
+              sort      Returns  the  vector  components  sorted  in ascending
+                        order.
+
+       vector names ?pattern?
+
+
+
+

INSTANCE OPERATIONS

+       You can also use the vector's Tcl command to query or modify  it.   The
+       general  form  is  vecName  operation  ?arg?...  Both operation and its
+       arguments determine the exact behavior of the command.  The  operations
+       available for vectors are listed below.
+
+       vecName append item ?item?...
+              Appends  the component values from item to vecName.  Item can be
+              either the name of a vector or a list of numeric values.
+
+       vecName binread channel ?length? ?switches?
+              Reads binary values  from  a  Tcl  channel.  Values  are  either
+              appended  to  the  end  of the vector or placed at a given index
+              (using the -at option), overwriting existing  values.   Data  is
+              read  until EOF is found on the channel or a specified number of
+              values length are read (note that this is  not  necessarily  the
+              same  as  the  number of bytes). The following switches are sup-
+              ported:
+
+              -swap  Swap bytes and words.  The default  endian  is  the  host
+                     machine.
+
+              -at index
+                     New  values  will start at vector index index.  This will
+                     overwrite any current values.
+
+              -format format
+                     Specifies the format of the data.  Format can be  one  of
+
+              This command removes the index and value strings from the array.
+              This is useful when the vector is large.
+
+       vecName delete index ?index?...
+              Deletes the indexth component from the vector vecName.  Index is
+              the index of the element to be deleted.  This  is  the  same  as
+              unsetting  the array variable element index.  The vector is com-
+              pacted after all the indices have been deleted.
+
+       vecName dup destName
+              Copies vecName to destName. DestName is the name of  a  destina-
+              tion  vector.   If a vector destName already exists, it is over-
+              written with the components of vecName.  Otherwise a new  vector
+              is created.
+
+       vecName expr expression
+              Computes  the  expression  and  resets  the values of the vector
+              accordingly.   Both  scalar  and  vector  math  operations   are
+              allowed.   All  values in expressions are either real numbers or
+              names of vectors.  All numbers are treated as one component vec-
+              tors.
+
+       vecName length ?newSize?
+              Queries  or resets the number of components in vecName.  NewSize
+              is a number specifying the new size of the vector.   If  newSize
+              is  smaller  than  the current size of vecName, vecName is trun-
+              cated.  If newSize is greater, the vector is  extended  and  the
+              new  components  are initialized to 0.0.  If no newSize argument
+              is present, the current length of the vector is returned.
+
+       vecName merge srcName ?srcName?...
+              Merges the named vectors into a single  vector.   The  resulting
+              vector is formed by merging the components of each source vector
+              one index at a time.
+
+       vecName notify keyword
+              Controls how vector clients are notified of changes to the  vec-
+              tor.  The exact behavior is determined by keyword.
+
+              always Indicates  that  clients  are  to be notified immediately
+                     whenever the vector is updated.
+
+              never  Indicates that no clients are to be notified.
+
+              whenidle
+                     Indicates that clients are to be  notified  at  the  next
+                     idle point whenever the vector is updated.
+
+              now    If  any  client  notifications is currently pending, they
+                     are notified immediately.
+
+              cancel Cancels pending notifications of clients using  the  vec-
+              interval between each of the original components will contain  a
+              density  number  of new components, whose values are evenly dis-
+              tributed between the original components values.  This is useful
+              for generating abscissas to be interpolated along a spline.
+
+       vecName range firstIndex ?lastIndex?...
+              Returns  a list of numeric values representing the vector compo-
+              nents between two indices. Both  firstIndex  and  lastIndex  are
+              indices  representing the range of components to be returned. If
+              lastIndex is less than firstIndex, the components are listed  in
+              reverse order.
+
+       vecName search value ?value?
+              Searches  for a value or range of values among the components of
+              vecName.  If one value argument is given, a list of  indices  of
+              the components which equal value is returned.  If a second value
+              is also provided, then the indices of all components  which  lie
+              within  the  range of the two values are returned.  If no compo-
+              nents are found, then "" is returned.
+
+       vecName set item
+              Resets the components of the vector to item. Item can be  either
+              a list of numeric expressions or another vector.
+
+       vecName seq start ?finish? ?step?
+              Generates  a  sequence  of values starting with the value start.
+              Finish indicates the terminating value  of  the  sequence.   The
+              vector  is  automatically  resized to contain just the sequence.
+              If three arguments are present, step designates the interval.
+
+              With only two arguments (no finish argument), the sequence  will
+              continue  until  the  vector  is filled.  With one argument, the
+              interval defaults to 1.0.
+
+       vecName sort ?-reverse? ?argName?...
+              Sorts the vector vecName in increasing order.  If  the  -reverse
+              flag  is  present, the vector is sorted in decreasing order.  If
+              other arguments argName are present, they are the names of  vec-
+              tors  which  will  be  rearranged in the same manner as vecName.
+              Each vector must be the same length as vecName.  You  could  use
+              this  to sort the x vector of a graph, while still retaining the
+              same x,y coordinate pairs in a y vector.
+
+       vecName variable varName
+              Maps a Tcl variable to the vector, creating  another  means  for
+              accessing the vector.  The variable varName can't already exist.
+              This overrides any current variable mapping the vector may have.
+
+
+
+

C LANGUAGE API

+       You  can create, modify, and destroy vectors from C code, using library
+       routines.  You need to include the header file blt.h. It  contains  the
+       definition  of  the  structure Blt_Vector, which represents the vector.
+
+       Blt_CreateVector
+
+         Synopsis: int Blt_CreateVector (interp, vecName, length, vecPtrPtr)
+                      Tcl_Interp *interp; char *vecName; int length;  Blt_Vec-
+                      tor **vecPtrPtr;
+
+         Description:
+                   Creates  a  new  vector  vecName  with  a length of length.
+                   Blt_CreateVector creates both a new Tcl command  and  array
+                   variable  vecName.   Neither  a  command nor variable named
+                   vecName can already exist.  A  pointer  to  the  vector  is
+                   placed into vecPtrPtr.
+
+         Results:  Returns  TCL_OK  if the vector is successfully created.  If
+                   length is negative,  a  Tcl  variable  or  command  vecName
+                   already  exists, or memory cannot be allocated for the vec-
+                   tor, then TCL_ERROR is  returned  and  interp->result  will
+                   contain an error message.
+
+
+       Blt_DeleteVectorByName
+
+         Synopsis: int Blt_DeleteVectorByName (interp, vecName)
+                      Tcl_Interp *interp; char *vecName;
+
+         Description:
+                   Removes  the vector vecName.  VecName is the name of a vec-
+                   tor which must already exist.  Both  the  Tcl  command  and
+                   array  variable  vecName are destroyed.  All clients of the
+                   vector will be notified immediately  that  the  vector  has
+                   been destroyed.
+
+         Results:  Returns  TCL_OK  if the vector is successfully deleted.  If
+                   vecName is  not  the  name  a  vector,  then  TCL_ERROR  is
+                   returned  and interp->result will contain an error message.
+
+
+       Blt_DeleteVector
+
+         Synopsis: int Blt_DeleteVector (vecPtr)
+                      Blt_Vector *vecPtr;
+
+         Description:
+                   Removes the vector pointed  to  by  vecPtr.   VecPtr  is  a
+                   pointer  to  a  vector,  typically  set by Blt_GetVector or
+                   Blt_CreateVector.  Both the Tcl command and array  variable
+                   of  the  vector  are  destroyed.  All clients of the vector
+                   will be notified  immediately  that  the  vector  has  been
+                   destroyed.
+
+         Results:  Returns  TCL_OK  if the vector is successfully deleted.  If
+
+         Results:  Returns TCL_OK if the vector is successfully retrieved.  If
+                   vecName is not the name of  a  vector,  then  TCL_ERROR  is
+                   returned  and interp->result will contain an error message.
+
+
+       Blt_ResetVector
+
+
+         Synopsis: int Blt_ResetVector (vecPtr,  dataArr,              numVal-
+                   ues, arraySize, freeProc)
+                      Blt_Vector *vecPtr; double *dataArr; int *numValues; int
+                      *arraySize; Tcl_FreeProc *freeProc;
+
+         Description:
+                   Resets the components of the vector pointed to  by  vecPtr.
+                   Calling Blt_ResetVector will trigger the vector to dispatch
+                   notifications to its clients. DataArr is the array of  dou-
+                   bles  which  represents  the  vector data. NumValues is the
+                   number of elements in the array. ArraySize  is  the  actual
+                   size  of the array (the array may be bigger than the number
+                   of values stored in it). FreeProc indicates how the storage
+                   for the vector component array (dataArr) was allocated.  It
+                   is used to determine how to reallocate memory when the vec-
+                   tor  is  resized  or  destroyed.   It  must be TCL_DYNAMIC,
+                   TCL_STATIC, TCL_VOLATILE, or a pointer  to  a  function  to
+                   free the memory allocated for the vector array. If freeProc
+                   is TCL_VOLATILE, it indicates that dataArr must  be  copied
+                   and  saved.   If freeProc is TCL_DYNAMIC, it indicates that
+                   dataArr was dynamically allocated and that Tcl should  free
+                   dataArr if necessary.  Static indicates that nothing should
+                   be done to release storage for dataArr.
+
+         Results:  Returns TCL_OK if the vector is successfully  resized.   If
+                   newSize  is  negative,  a vector vecName does not exist, or
+                   memory cannot be allocated for the vector,  then  TCL_ERROR
+                   is  returned  and interp->result will contain an error mes-
+                   sage.
+
+
+       Blt_ResizeVector
+
+         Synopsis: int Blt_ResizeVector (vecPtr, newSize)
+                      Blt_Vector *vecPtr; int newSize;
+
+         Description:
+                   Resets the length of the vector pointed  to  by  vecPtr  to
+                   newSize.   If  newSize  is smaller than the current size of
+                   the vector, it is truncated.  If newSize  is  greater,  the
+                   vector  is  extended and the new components are initialized
+                   to 0.0.  Calling Blt_ResetVector will trigger the vector to
+                   dispatch notifications.
+
+            Results:  Returns 1 if a vector vecName exists and 0 otherwise.
+
+
+         If your application needs to be notified when a  vector  changes,  it
+         can allocate a unique client identifier for itself.  Using this iden-
+         tifier, you can then register a call-back to  be  made  whenever  the
+         vector  is updated or destroyed.  By default, the call-backs are made
+         at the next idle point.  This can be changed to occur at the time the
+         vector  is modified.  An application can allocate more than one iden-
+         tifier for any vector.  When the client application is done with  the
+         vector, it should free the identifier.
+
+         The call-back routine must of the following type.
+
+                typedef void (Blt_VectorChangedProc) (Tcl_Interp *interp,
+                   ClientData clientData, Blt_VectorNotify notify);
+
+         ClientData  is passed to this routine whenever it is called.  You can
+         use this to pass information to the call-back.  The  notify  argument
+         indicates  whether the vector has been updated of destroyed. It is an
+         enumerated type.
+
+                typedef enum {
+                    BLT_VECTOR_NOTIFY_UPDATE=1,
+                    BLT_VECTOR_NOTIFY_DESTROY=2 } Blt_VectorNotify;
+
+
+         Blt_AllocVectorId
+
+            Synopsis: Blt_VectorId Blt_AllocVectorId (interp, vecName)
+                        Tcl_Interp *interp; char *vecName;
+
+            Description:
+                      Allocates an client identifier for with the vector  vec-
+                      Name.   This  identifier  can be used to specify a call-
+                      back which is triggered when the vector  is  updated  or
+                      destroyed.
+
+            Results:  Returns  a  client identifier if successful.  If vecName
+                      is not the name of a vector, then NULL is  returned  and
+                      interp->result will contain an error message.
+
+
+         Blt_GetVectorById
+
+            Synopsis: int Blt_GetVector (interp, clientId, vecPtrPtr)
+                        Tcl_Interp  *interp; Blt_VectorId clientId; Blt_Vector
+                        **vecPtrPtr;
+
+            Description:
+                      Retrieves the vector used by clientId.   ClientId  is  a
+
+            Description:
+                      Specifies a call-back routine to be called whenever  the
+                      vector  associated  with clientId is updated or deleted.
+                      Proc is a pointer to call-back routine and  must  be  of
+                      the  type  Blt_VectorChangedProc.   ClientData is a one-
+                      word value to be  passed  to  the  routine  when  it  is
+                      invoked.  If  proc is NULL, then the client is not noti-
+                      fied.
+
+            Results:  The designated call-back procedure will be invoked  when
+                      the vector is updated or destroyed.
+
+
+         Blt_FreeVectorId
+
+            Synopsis: void Blt_FreeVectorId (clientId);
+                        Blt_VectorId clientId;
+
+            Description:
+                      Frees  the  client identifier.  Memory allocated for the
+                      identifier is released.  The client will  no  longer  be
+                      notified when the vector is modified.
+
+            Results:  The  designated call-back procedure will be no longer be
+                      invoked when the vector is updated or destroyed.
+
+
+         Blt_NameOfVectorId
+
+            Synopsis: char *Blt_NameOfVectorId (clientId);
+                        Blt_VectorId clientId;
+
+            Description:
+                      Retrieves the name of the  vector  associated  with  the
+                      client identifier clientId.
+
+            Results:  Returns the name of the vector associated with clientId.
+                      If clientId is not an identifier or the vector has  been
+                      destroyed, NULL is returned.
+
+
+         Blt_InstallIndexProc
+
+            Synopsis: void Blt_InstallIndexProc (indexName, procPtr)
+                        char *indexName; Blt_VectorIndexProc *procPtr;
+
+            Description:
+                      Registers a function to be called to retrieved the index
+                      indexName from the vector's array variable.
+
+                      typedef double Blt_VectorIndexProc(Vector *vecPtr);
+
+       difference  what  the  initial  size  of the vector is since it will be
+       reset shortly. The vector is updated  when  lt_ResetVector  is  called.
+       Blt_ResetVector  makes  the  changes  visible  to the Tcl interface and
+       other vector clients (such as a graph widget).
+
+       #include   <tcl.h>   #include   <blt.h>                      Blt_Vector
+       *vecPtr;  double  *newArr;  FILE *f; struct stat statBuf; int numBytes,
+       numValues;
+
+       f = fopen("binary.dat", "r"); fstat(fileno(f),  &statBuf);  numBytes  =
+       (int)statBuf.st_size;
+
+       /*  Allocate an array big enough to hold all the data */ newArr = (dou-
+       ble  *)malloc(numBytes);  numValues  =   numBytes   /   sizeof(double);
+       fread((void *)newArr, numValues, sizeof(double), f); fclose(f);
+
+       if (Blt_VectorExists(interp, "data"))  {
+           if   (Blt_GetVector(interp,   "data",   &vecPtr)   !=   TCL_OK)   {
+                   return TCL_ERROR;
+           } } else {
+          if  (Blt_CreateVector(interp,  "data",  0,  &vecPtr)  !=  TCL_OK)  {
+                   return TCL_ERROR;
+          } } /*
+        * Reset the vector. Clients will be notified when Tk is idle.
+        * TCL_DYNAMIC tells the vector to free the memory allocated
+        * if it needs to reallocate or destroy the vector.
+        */   if   (Blt_ResetVector(vecPtr,   newArr,   numValues,   numValues,
+                   TCL_DYNAMIC) != TCL_OK) {
+           return TCL_ERROR; }
+
+
+
+

INCOMPATIBILITIES

+       In previous versions, if the array variable isn't global (i.e. local to
+       a Tcl procedure), the vector is automatically destroyed when the proce-
+       dure returns.  proc doit {} {
+           # Temporary vector x
+           vector x(10)
+           set x(9) 2.0
+             ...  }
+
+       This has changed.  Variables are not automatically destroyed when their
+       variable  is  unset.   You  can restore the old behavior by setting the
+       "-watchunset" switch.
+
+
+
+

KEYWORDS

+       vector, graph, widget
+
+
+
+BLT                               BLT_VERSION                   blt::vector(n)
+
+
+
+Man(1) output converted with +man2html +
+ + -- cgit v0.12