diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2019-08-04 17:07:46 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2019-08-04 17:07:46 (GMT) |
| commit | 8ae29328c9c05cd5a901c12e64dbe067a3d0b598 (patch) | |
| tree | 50bb9a8a6c4b1495e4eff46b860706670cf36d18 /doc | |
| parent | e37cea80afd9fd9c73570f8546d4499a4a374b60 (diff) | |
| parent | caf3d505d3fa5e2ac57956321220b78351c5903b (diff) | |
| download | blt-8ae29328c9c05cd5a901c12e64dbe067a3d0b598.zip blt-8ae29328c9c05cd5a901c12e64dbe067a3d0b598.tar.gz blt-8ae29328c9c05cd5a901c12e64dbe067a3d0b598.tar.bz2 | |
Merge branch 'master' into devel
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/BLT.html | 74 | ||||
| -rw-r--r-- | doc/BLT.n | 76 | ||||
| -rw-r--r-- | doc/barchart.html | 1640 | ||||
| -rw-r--r-- | doc/barchart.n | 2239 | ||||
| -rw-r--r-- | doc/graph.html | 1759 | ||||
| -rw-r--r-- | doc/graph.n | 2408 | ||||
| -rw-r--r-- | doc/vector.html | 704 | ||||
| -rw-r--r-- | doc/vector.n | 1134 |
8 files changed, 10034 insertions, 0 deletions
diff --git a/doc/BLT.html b/doc/BLT.html new file mode 100644 index 0000000..55e4e38 --- /dev/null +++ b/doc/BLT.html @@ -0,0 +1,74 @@ +<HTML> +<BODY> +<PRE> +<!-- Manpage converted by man2html 3.0.1 --> + +</PRE> +<H2>DESCRIPTION</H2><PRE> + BLT is a library of extensions to the Tk library. It adds new commands + and variables to the application's interpreter. + + + +</PRE> +<H2>COMMANDS</H2><PRE> + The following commands are added to the interpreter from the BLT + library: + + <B>graph</B> A 2D plotting widget. Plots two variable data in a win- + dow with an optional legend and annotations. It has of + several components; coordinate axes, crosshairs, a leg- + end, and a collection of elements and tags. + + <B>barchart</B> A barchart widget. Plots two-variable data as rectangu- + lar bars in a window. The x-coordinate values designate + the position of the bar along the x-axis, while the y- + coordinate values designate the magnitude. The <B>barchart</B> + widget has of several components; coordinate axes, + crosshairs, a legend, and a collection of elements and + tags. + + <B>vector</B> Creates a vector of floating point values. The vector's + components can be manipulated in three ways: through a + Tcl array variable, a Tcl command, or the C API. + + +</PRE> +<H2>ADDING BLT TO YOUR APPLICATIONS</H2><PRE> + It's easy to add BLT to an existing Tk application. BLT requires no + patches or edits to the Tcl or Tk libraries. To add BLT, simply add + the following code snippet to your application's tkAppInit.c file. + + if (Tkblt_Init(interp) != TCL_OK) { + + return TCL_ERROR; + + } + + Recompile and link with the tkblt library and that's it. + + Alternately, you can dynamically load tkblt, simply by invoking the + command + + % package require tkblt + + from your Tcl script. + + +</PRE> +<H2>BUGS</H2><PRE> + Send bug reports, requests, suggestions, etc. to wjoye@cfa.harvard.edu + + +</PRE> +<H2>KEYWORDS</H2><PRE> + BLT + +</PRE> +<HR> +<ADDRESS> +Man(1) output converted with +<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> +</ADDRESS> +</BODY> +</HTML> diff --git a/doc/BLT.n b/doc/BLT.n new file mode 100644 index 0000000..6f63aa8 --- /dev/null +++ b/doc/BLT.n @@ -0,0 +1,76 @@ +'\" +'\" Smithsonian Astrophysical Observatory, Cambridge, MA, USA +'\" This code has been modified under the terms listed below and is made +'\" available under the same terms. +'\" +'\" Copyright 1991-1997 by Bell Labs Innovations for Lucent Technologies. +'\" +'\" Permission to use, copy, modify, and distribute this software and its +'\" documentation for any purpose and without fee is hereby granted, provided +'\" that the above copyright notice appear in all copies and that both that the +'\" copyright notice and warranty disclaimer appear in supporting documentation, +'\" and that the names of Lucent Technologies any of their entities not be used +'\" in advertising or publicity pertaining to distribution of the software +'\" without specific, written prior permission. +'\" +'\" Lucent Technologies disclaims all warranties with regard to this software, +'\" including all implied warranties of merchantability and fitness. In no event +'\" shall Lucent Technologies be liable for any special, indirect or +'\" consequential damages or any damages whatsoever resulting from loss of use, +'\" data or profits, whether in an action of contract, negligence or other +'\" tortuous action, arising out of or in connection with the use or performance +'\" of this software. +'\" +.TH intro n BLT_VERSION BLT "BLT Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +BLT \- Introduction to the BLT library +.BE +.SH DESCRIPTION +BLT is a library of extensions to the Tk library. It adds new +commands and variables to the application's interpreter. +.LP +.SH COMMANDS +The following commands are added to the interpreter from the BLT library: +.TP 15 +\fBgraph\fR +A 2D plotting widget. Plots two variable data in a window with an optional +legend and annotations. It has of several components; coordinate axes, +crosshairs, a legend, and a collection of elements and tags. +.TP 15 +\fBbarchart\fR +A barchart widget. Plots two-variable data as rectangular bars in a +window. The x-coordinate values designate the position of the bar along +the x-axis, while the y-coordinate values designate the magnitude. +The \fBbarchart\fR widget has of several components; coordinate axes, +crosshairs, a legend, and a collection of elements and tags. +.TP 15 +\fBvector\fR +Creates a vector of floating point values. The vector's components +can be manipulated in three ways: through a Tcl array variable, a Tcl +command, or the C API. +.SH ADDING BLT TO YOUR APPLICATIONS +It's easy to add BLT to an existing Tk application. BLT requires no +patches or edits to the Tcl or Tk libraries. To add BLT, simply add the +following code snippet to your application's tkAppInit.c file. +.PP +if (Tkblt_Init(interp) != TCL_OK) { +.PP + return TCL_ERROR; +.PP +} +.TP 15 +Recompile and link with the tkblt library and that's it. +.PP +Alternately, you can dynamically load tkblt, simply by invoking the +command +.PP +% package require tkblt +.PP +from your Tcl script. +.SH BUGS +Send bug reports, requests, suggestions, etc. to +wjoye@cfa.harvard.edu +.SH KEYWORDS +BLT diff --git a/doc/barchart.html b/doc/barchart.html new file mode 100644 index 0000000..7f04d25 --- /dev/null +++ b/doc/barchart.html @@ -0,0 +1,1640 @@ +<HTML> +<BODY> +<PRE> +<!-- Manpage converted by man2html 3.0.1 --> + +</PRE> +<H2>SYNOPSIS</H2><PRE> + <B>barchart</B> <I>pathName</I> ?<I>option</I> <I>value</I>?... + + +</PRE> +<H2>DESCRIPTION</H2><PRE> + The <B>barchart</B> 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. + + +</PRE> +<H2>INTRODUCTION</H2><PRE> + The <B>barchart</B> 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 <I>plotting</I> <I>area</I>. 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 <B>barchart</B> 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 <B>-weight</B> and <B>-style</B> options). + + postscript + The widget can generate encapsulated PostScript output. This + component has several options to configure how the PostScript + is generated. + + +</PRE> +<H2>SYNTAX</H2><PRE> + <B>barchart</B> <I>pathName</I> ?<I>option</I> <I>value</I>?... The <B>barchart</B> command creates a new + window <I>pathName</I> and makes it into a <B>barchart</B> widget. At the time this + command is invoked, there must not exist a window named <I>pathName</I>, but + <I>pathName</I>'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 <B>configure</B> operation below + for the exact details about what <I>option</I> and <I>value</I> pairs are valid. + + If successful, <B>barchart</B> 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: <I>pathName</I> <I>operation</I> ?<I>arg</I>?... Both <I>operation</I> and its argu- + ments determine the exact behavior of the command. The operations + available for the graph are described in the <B>BARCHART</B> <B>OPERATIONS</B> sec- + tion. + + The command can also be used to access components of the graph. <I>path-</I> + <I>Name</I> <I>component</I> <I>operation</I> ?<I>arg</I>?... 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. + + +</PRE> +<H2>EXAMPLE</H2><PRE> + The <B>barchart</B> 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 <B>configure</B> operation. # + Change the title. .b configure -title "My Plot" To add data elements, + you use the command and the <B>element</B> 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 <B>-barmode</B> 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 <B>configure</B> 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 <B>-mapx</B> and <B>-mapy</B> 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 <B>axis</B> 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 <B>-min</B> and <B>-max</B> 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 the<B>axis</B> <B>configure</B> + operations with some user interaction (such as pressing the mouse but- + ton), using the <B>bind</B> command. To convert between screen and graph + coordinates, use the <B>invtransform</B> 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 <B>-min</B> and <B>-max</B> 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 <B>legend</B> 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 <B>-hide</B> option. # Don't display the legend. .b + legend configure -hide yes The <B>barchart</B> 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 <B>-maxpect</B> says to scale the + plot to the size of the page. Turning off the <B>-decorations</B> 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). + + +</PRE> +<H2>SYNTAX</H2><PRE> + <B>barchart</B> <I>pathName</I> ?<I>option</I> <I>value</I>?... The <B>barchart</B> command creates a new + window <I>pathName</I> and makes it into a barchart widget. At the time this + command is invoked, there must not exist a window named <I>pathName</I>, but + <I>pathName</I>'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 <B>configure</B> operation + below for the exact details as to what <I>option</I> and <I>value</I> pairs are + valid. + + If successful, <B>barchart</B> returns <I>pathName</I>. It also creates a new Tcl + command <I>pathName</I>. This command may be used to invoke various opera- + tions to query or modify the bar chart. It has the general form: <I>path-</I> + <I>Name</I> <I>operation</I> ?<I>arg</I>?... Both <I>operation</I> and its arguments determine the + exact behavior of the command. The operations available for the bar + chart are described in the following section. + + +</PRE> +<H2>BARCHART OPERATIONS</H2><PRE> + <I>pathName</I> <B>bar</B> <I>elemName</I> ?<I>option</I> <I>value</I>?... + Creates a new barchart element <I>elemName</I>. It's an error if an + element <I>elemName</I> already exists. See the manual for <B>barchart</B> + for details about what <I>option</I> and <I>value</I> pairs are valid. + + <I>pathName</I> <B>cget</B> <I>option</I> + Returns the current value of the configuration option given by + <I>option</I>. <I>Option</I> may be any option described below for the <B>con-</B> + <B>figure</B> operation. + + <I>pathName</I> <B>configure</B> ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options of the graph. If + <I>option</I> isn't specified, a list describing the current options + for <I>pathName</I> is returned. If <I>option</I> is specified, but not + <I>value</I>, then a list describing <I>option</I> is returned. If one or + more <I>option</I> and <I>value</I> pairs are specified, then for each pair, + the option <I>option</I> is set to <I>value</I>. The following options are + valid. + + <B>-background</B> <I>color</I> + Sets the background color. This includes the margins and + legend, but not the plotting area. + + <B>-barmode</B> <I>mode</I> + Indicates how related bar elements will be drawn. + Related elements have data points with the same abscissas + (X-coordinates). <I>Mode</I> indicates how those segments should + + <B>-barwidth</B> <I>value</I> + Specifies the width of the bars. This value can be over- + rided by the individual elements using their <B>-barwidth</B> + configuration option. <I>Value</I> is the width in terms of + graph-coordinates. The default width is 1.0. + + <B>-borderwidth</B> <I>pixels</I> + Sets the width of the 3-D border around the outside edge + of the widget. The <B>-relief</B> option determines if the bor- + der is to be drawn. The default is 2. + + <B>-bottommargin</B> <I>pixels</I> + Specifies the size of the margin below the X-coordinate + axis. If <I>pixels</I> is 0, the size of the margin is selected + automatically. The default is 0. + + <B>-bufferelements</B> <I>boolean</I> + Indicates whether an internal pixmap to buffer the dis- + play of data elements should be used. If <I>boolean</I> 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 <B>SPEED</B> + <B>TIPS</B> section. The default is 1. + + <B>-cursor</B> <I>cursor</I> + Specifies the widget's cursor. The default cursor is + crosshair. + + <B>-font</B> <I>fontName</I> + Specifies the font of the graph title. The default is + *-Helvetica-Bold-R-Normal-*-18-180-*. + + <B>-halo</B> <I>pixels</I> + Specifies a maximum distance to consider when searching + for the closest data point (see the element's <B>closest</B> + operation below). Data points further than <I>pixels</I> away + are ignored. The default is 0.5i. + + <B>-height</B> <I>pixels</I> + Specifies the requested height of widget. The default is + 4i. + + <B>-invertxy</B> <I>boolean</I> + Indicates whether the placement X-axis and Y-axis should + be inverted. If <I>boolean</I> is true, the X and Y axes are + swapped. The default is 0. + + <B>-justify</B> <I>justify</I> + Specifies how the title should be justified. This mat- + ters only when the title contains more than one line of + area. The <B>-plotrelief</B> option determines if a border is + drawn. The default is 2. + + <B>-plotpadx</B> <I>pad</I> + Sets the amount of padding to be added to the left and + right sides of the plotting area. <I>Pad</I> can be a list of + one or two screen distances. If <I>pad</I> 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 <I>pad</I> + is just one distance, both the left and right sides are + padded evenly. The default is 8. + + <B>-plotpady</B> <I>pad</I> + Sets the amount of padding to be added to the top and + bottom of the plotting area. <I>Pad</I> can be a list of one or + two screen distances. If <I>pad</I> has two elements, the top + of the plotting area is padded by the first distance and + the bottom by the second. If <I>pad</I> is just one distance, + both the top and bottom are padded evenly. The default + is 8. + + <B>-plotrelief</B> <I>relief</I> + Specifies the 3-D effect for the plotting area. <I>Relief</I> + 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. + + <B>-relief</B> <I>relief</I> + Specifies the 3-D effect for the barchart widget. <I>Relief</I> + 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. + + <B>-rightmargin</B> <I>pixels</I> + 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 <I>pixels</I> is than 1, the margin + size is selected automatically. + + <B>-takefocus</B> <I>focus</I> + Provides information used when moving the focus from win- + dow to window via keyboard traversal (e.g., Tab and + Shift-Tab). If <I>focus</I> 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 "". + + <B>-tile</B> <I>image</I> + <B>-width</B> <I>pixels</I> + Specifies the requested width of the widget. The default + is 5i. + + <I>pathName</I> <B>crosshairs</B> <I>operation</I> ?<I>arg</I>? + See the <B>CROSSHAIRS</B> <B>COMPONENT</B> section. + + <I>pathName</I> <B>element</B> <I>operation</I> ?<I>arg</I>?... + See the <B>ELEMENT</B> <B>COMPONENTS</B> section. + + <I>pathName</I> <B>extents</B> <I>item</I> + Returns the size of a particular item in the graph. <I>Item</I> must + be either leftmargin, rightmargin, topmargin, bottommargin, + plotwidth, or plotheight. + + <I>pathName</I> <B>grid</B> <I>operation</I> ?<I>arg</I>?... + See the <B>GRID</B> <B>COMPONENT</B> section. + + <I>pathName</I> <B>invtransform</B> <I>winX</I> <I>winY</I> + 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. + + <I>pathName</I> <B>inside</B> <I>x</I> <I>y</I> + Returns 1 is the designated screen-coordinate (<I>x</I> and <I>y</I>) is + inside the plotting area and 0 otherwise. + + <I>pathName</I> <B>legend</B> <I>operation</I> ?<I>arg</I>?... + See the <B>LEGEND</B> <B>COMPONENT</B> section. + + <I>pathName</I> <B>line</B> <B>operation</B> <B>arg</B>... + The operation is the same as <B>element</B>. + + <I>pathName</I> <B>marker</B> <I>operation</I> ?<I>arg</I>?... + See the <B>MARKER</B> <B>COMPONENTS</B> section. + + <I>pathName</I> <B>metafile</B> ?<I>fileName</I>? + <I>This</I> <I>operation</I> <I>is</I> <I>for</I> <I>Window</I> <I>platforms</I> <I>only</I>. Creates a Windows + enhanced metafile of the barchart. If present, <I>fileName</I> is the + file name of the new metafile. Otherwise, the metafile is auto- + matically added to the clipboard. + + <I>pathName</I> <B>postscript</B> <I>operation</I> ?<I>arg</I>?... + See the <B>POSTSCRIPT</B> <B>COMPONENT</B> section. + + <I>pathName</I> <B>snap</B> <I>photoName</I> + Takes a snapshot of the graph and stores the contents in the + photo image <I>photoName</I>. <I>PhotoName</I> is the name of a Tk photo + image that must already exist. + + <I>pathName</I> <B>transform</B> <I>x</I> <I>y</I> + 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. + + <B>AXIS</B> <B>COMPONENTS</B> + 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: <B>xaxis</B>, <B>yaxis</B>, <B>x2axis</B>, and <B>y2axis</B>. The <B>use</B> operation designates + the axis to be drawn in the corresponding margin: <B>xaxis</B> in the bottom, + <B>yaxis</B> in the left, <B>x2axis</B> in the top, and <B>y2axis</B> 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. + + + <B>-autorange</B> <I>range</I> + Sets the range of values for the axis to <I>range</I>. The axis + limits are automatically reset to display the most recent + data points in this range. If <I>range</I> is 0.0, the range is + determined from the limits of the data. If <B>-min</B> or <B>-max</B> + are specified, they override this option. The default is + 0.0. + + <B>-color</B> <I>color</I> + Sets the color of the axis and tick labels. The default + is black. + + <B>-command</B> <I>prefix</I> + Specifies a Tcl command to be invoked when formatting the + axis tick labels. <I>Prefix</I> 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 <I>prefix</I> 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. + + <B>-descending</B> <I>boolean</I> + Indicates whether the values along the axis are monotoni- + cally increasing or decreasing. If <I>boolean</I> is true, the + axis values will be decreasing. The default is 0. + + <B>-hide</B> <I>boolean</I> + Indicates whether the axis is displayed. + + <B>-justify</B> <I>justify</I> + Specifies how the axis title should be justified. This + matters only when the axis title contains more than one + line of text. <I>Justify</I> must be left, right, or center. + The default is center. + + <B>-limits</B> <I>formatStr</I> + 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. <I>FormatStr</I> 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 + <I>boolean</I> is true, the axis range is "loose". The default + is 0. + + <B>-majorticks</B> <I>majorList</I> + Specifies where to display major axis ticks. You can use + this option to display ticks at non-uniform intervals. + <I>MajorList</I> is a list of axis coordinates designating the + location of major ticks. No minor ticks are drawn. If + <I>majorList</I> is "", major ticks will be automatically com- + puted. The default is "". + + <B>-max</B> <I>value</I> + Sets the maximum limit of <I>axisName</I>. Any data point + greater than <I>value</I> is not displayed. If <I>value</I> is "", the + maximum limit is calculated using the largest data value. + The default is "". + + <B>-min</B> <I>value</I> + Sets the minimum limit of <I>axisName</I>. Any data point less + than <I>value</I> is not displayed. If <I>value</I> is "", the minimum + limit is calculated using the smallest data value. The + default is "". + + <B>-minorticks</B> <I>minorList</I> + Specifies where to display minor axis ticks. You can use + this option to display minor ticks at non-uniform inter- + vals. <I>MinorList</I> 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 <B>-majortick</B> option is also + set. If <I>minorList</I> is "", minor ticks will be automati- + cally computed. The default is "". + + <B>-rotate</B> <I>theta</I> + Specifies the how many degrees to rotate the axis tick + labels. <I>Theta</I> is a real value representing the number of + degrees to rotate the tick labels. The default is 0.0 + degrees. + + <B>-shiftby</B> <I>value</I> + 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 <I>value</I>. + You can use this option to prevent the axis limits from + being recomputed at each new time point. If <I>value</I> is 0.0, + then no automatic shifting is down. The default is 0.0. + + <B>-showticks</B> <I>boolean</I> + Indicates whether axis ticks should be drawn. If <I>boolean</I> + is true, ticks are drawn. If false, only the axis line + + <B>-tickfont</B> <I>fontName</I> + Specifies the font for axis tick labels. The default is + *-Courier-Bold-R-Normal-*-100-*. + + <B>-ticklength</B> <I>pixels</I> + Sets the length of major and minor ticks (minor ticks are + half the length of major ticks). If <I>pixels</I> is less than + zero, the axis will be inverted with ticks drawn pointing + towards the plot. The default is 0.1i. + + <B>-title</B> <I>text</I> + Sets the title of the axis. If <I>text</I> is "", no axis title + will be displayed. + + <B>-titlecolor</B> <I>color</I> + Sets the color of the axis title. The default is black. + + <B>-titlefont</B> <I>fontName</I> + 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 <B>option</B> 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 + + <I>pathName</I> <B>axis</B> <B>create</B> <I>axisName</I> ?<I>option</I> <I>value</I>?... + Creates a new axis by the name <I>axisName</I>. No axis by the same + name can already exist. <I>Option</I> and <I>value</I> are described in above + in the axis <B>configure</B> operation. + + <I>pathName</I> <B>axis</B> <B>delete</B> ?<I>axisName</I>?... + 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. + + <I>pathName</I> <B>axis</B> <B>invtransform</B> <I>axisName</I> <I>value</I> + Performs the inverse transformation, changing the screen-coordi- + nate <I>value</I> to a graph-coordinate, mapping the value mapped to + <I>axisName</I>. Returns the graph-coordinate. + + <I>pathName</I> <B>axis</B> <B>limits</B> <I>axisName</I> + Returns a list of the minimum and maximum limits for <I>axisName</I>. + The order of the list is min max. + + <I>pathName</I> <B>axis</B> <B>names</B> ?<I>pattern</I>?... + Returns a list of axes matching zero or more patterns. If no + <I>pattern</I> argument is give, the names of all axes are returned. + + <I>pathName</I> <B>axis</B> <B>transform</B> <I>axisName</I> <I>value</I> + Transforms the coordinate <I>value</I> to a screen-coordinate by map- + + right Y-axis. + + They implicitly control the axis that is currently using to that loca- + tion. By default, <B>xaxis</B> uses the x axis, <B>yaxis</B> uses y, <B>x2axis</B> uses x2, + and <B>y2axis</B> 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 <B>axis</B> component. The <I>axis</I> argument must be <B>xaxis</B>, + <B>x2axis</B>, <B>yaxis</B>, or <B>y2axis</B>. + + <I>pathName</I> <I>axis</I> <B>cget</B> <I>option</I> + + <I>pathName</I> <I>axis</I> <B>configure</B> ?<I>option</I> <I>value</I>?... + + <I>pathName</I> <I>axis</I> <B>invtransform</B> <I>value</I> + + <I>pathName</I> <I>axis</I> <B>limits</B> + + <I>pathName</I> <I>axis</I> <B>transform</B> <I>value</I> + + <I>pathName</I> <I>axis</I> <B>use</B> ?<I>axisName</I>? + Designates the axis <I>axisName</I> is to be displayed at this loca- + tion. <I>AxisName</I> can not be already in use at another location. + This command returns the name of the axis currently using this + location. + + <B>CROSSHAIRS</B> <B>COMPONENT</B> + 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: + + <I>pathName</I> <B>crosshairs</B> <B>cget</B> <I>option</I> + Returns the current value of the cross hairs configuration + option given by <I>option</I>. <I>Option</I> may be any option described + below for the cross hairs <B>configure</B> operation. + + <I>pathName</I> <B>crosshairs</B> <B>configure</B> ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options of the cross + hairs. If <I>option</I> isn't specified, a list describing all the + current options for the cross hairs is returned. If <I>option</I> is + specified, but not <I>value</I>, then a list describing <I>option</I> is + returned. If one or more <I>option</I> and <I>value</I> pairs are specified, + then for each pair, the cross hairs option <I>option</I> is set to + <I>value</I>. The following options are available for cross hairs. + + <B>-linewidth</B> <I>pixels</I> + Set the width of the cross hair lines. The default is 1. + + <B>-position</B> <I>pos</I> + Specifies the screen position where the cross hairs + intersect. <I>Pos</I> must be in the form "<I>@x,y</I>", where <I>x</I> and <I>y</I> + are the window coordinates of the intersection. + + Cross hairs configuration options may be also be set by the + <B>option</B> 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 + + <I>pathName</I> <B>crosshairs</B> <B>off</B> + Turns off the cross hairs. + + <I>pathName</I> <B>crosshairs</B> <B>on</B> + Turns on the display of the cross hairs. + + <I>pathName</I> <B>crosshairs</B> <B>toggle</B> + Toggles the current state of the cross hairs, alternately map- + ping and unmapping the cross hairs. + + +</PRE> +<H2>ELEMENTS</H2><PRE> + 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. + + <I>pathName</I> <B>element</B> <B>activate</B> <I>elemName</I> ?<I>index</I>?... + Specifies the data points of element <I>elemName</I> to be drawn using + active foreground and background colors. <I>ElemName</I> is the name + of the element and <I>index</I> is a number representing the index of + the data point. If no indices are present then all data points + become active. + + <I>pathName</I> <B>element</B> <B>bind</B> <I>tagName</I> ?<I>sequence</I>? ?<I>command</I>? + Associates <I>command</I> with <I>tagName</I> such that whenever the event + sequence given by <I>sequence</I> occurs for an element with this tag, + <I>command</I> will be invoked. The syntax is similar to the <B>bind</B> com- + mand except that it operates on graph elements, rather than wid- + gets. See the <B>bind</B> manual entry for complete details on <I>sequence</I> + and the substitutions performed on <I>command</I> before invoking it. + + + <I>pathName</I> <B>element</B> <B>closest</B> <I>x</I> <I>y</I> ?<I>option</I> <I>value</I>?... ?<I>elemName</I>?... + Finds the data point representing the bar closest to the window + coordinates <I>x</I> and <I>y</I> in the element <I>elemName</I>. <I>ElemName</I> 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 + <I>option</I>-<I>value</I> pairs are available. + + <B>-halo</B> <I>pixels</I> + Specifies a threshold distance where selected data points + are ignored. <I>Pixels</I> 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 <B>barchart</B>'s <B>-halo</B> option. + + <I>pathName</I> <B>element</B> <B>configure</B> <I>elemName</I> ?<I>elemName</I>... ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options for elements. + Several elements can be modified at the same time. If <I>option</I> + isn't specified, a list describing all the current options for + <I>elemName</I> is returned. If <I>option</I> is specified, but not <I>value</I>, + then a list describing the option <I>option</I> is returned. If one or + more <I>option</I> and <I>value</I> pairs are specified, then for each pair, + the element option <I>option</I> is set to <I>value</I>. The following + options are valid for elements. + + <B>-activepen</B> <I>penName</I> + Specifies pen to use to draw active element. If <I>penName</I> + is "", no active elements will be drawn. The default is + activeLine. + + <B>-bindtags</B> <I>tagList</I> + Specifies the binding tags for the element. <I>TagList</I> 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. + + <B>-background</B> <I>color</I> + Sets the the color of the border around each bar. The + default is white. + + <B>-barwidth</B> <I>value</I> + Specifies the width the bars drawn for the element. + <I>Value</I> is the width in X-coordinates. If this option + isn't specified, the width of each bar is the value of + the widget's <B>-barwidth</B> option. + + a list of numeric expressions representing the X-Y coor- + dinate pairs of each data point. + + <B>-foreground</B> <I>color</I> + Sets the color of the interior of the bars. + + <B>-hide</B> <I>boolean</I> + Indicates whether the element is displayed. The default + is no. + + <B>-label</B> <I>text</I> + Sets the element's label in the legend. If <I>text</I> is "", + the element will have no entry in the legend. The + default label is the element's name. + + <B>-mapx</B> <I>xAxis</I> + Selects the X-axis to map the element's X-coordinates + onto. <I>XAxis</I> must be the name of an axis. The default is + x. + + <B>-mapy</B> <I>yAxis</I> + Selects the Y-axis to map the element's Y-coordinates + onto. <I>YAxis</I> must be the name of an axis. The default is + y. + + <B>-relief</B> <I>string</I> + Specifies the 3-D effect desired for bars. <I>Relief</I> 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. + + <B>-stipple</B> <I>bitmap</I> + Specifies a stipple pattern with which to draw the bars. + If <I>bitmap</I> is "", then the bar is drawn in a solid fash- + ion. + + <B>-xdata</B> <I>xVector</I> + Specifies the x-coordinate vector of the data. <I>XVector</I> + is the name of a BLT vector or a list of numeric expres- + sions. + + <B>-ydata</B> <I>yVector</I> + Specifies the y-coordinate vector of the data. <I>YVector</I> + is the name of a BLT vector or a list of numeric expres- + sions. + + Element configuration options may also be set by the <B>option</B> com- + mand. The resource names in the option database are prefixed + by elem. option add *Barchart.Element.background blue + + <I>pathName</I> <B>element</B> <B>create</B> <I>elemName</I> ?<I>option</I> <I>value</I>?... + + <I>pathName</I> <B>element</B> <B>exists</B> <I>elemName</I> + Returns 1 if an element <I>elemName</I> currently exists and 0 other- + wise. + + <I>pathName</I> <B>element</B> <B>names</B> ?<I>pattern</I>?... + Returns the elements matching one or more pattern. If no <I>pat-</I> + <I>tern</I> is given, the names of all elements is returned. + + <I>pathName</I> <B>element</B> <B>show</B> ?<I>nameList</I>? + Queries or modifies the element display list. The element dis- + play list designates the elements drawn and in what order. + <I>NameList</I> is a list of elements to be displayed in the order they + are named. If there is no <I>nameList</I> argument, the current dis- + play list is returned. + + <I>pathName</I> <B>element</B> <B>type</B> <I>elemName</I> + Returns the type of <I>elemName</I>. If the element is a bar element, + the commands returns the string "bar", otherwise it returns + "line". + + <B>GRID</B> <B>COMPONENT</B> + 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. + + <I>pathName</I> <B>grid</B> <B>cget</B> <I>option</I> + Returns the current value of the grid line configuration option + given by <I>option</I>. <I>Option</I> may be any option described below for + the grid <B>configure</B> operation. + + <I>pathName</I> <B>grid</B> <B>configure</B> ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options for grid lines. + If <I>option</I> isn't specified, a list describing all the current + grid options for <I>pathName</I> is returned. If <I>option</I> is specified, + but not <I>value</I>, then a list describing <I>option</I> is returned. If + one or more <I>option</I> and <I>value</I> pairs are specified, then for each + pair, the grid line option <I>option</I> is set to <I>value</I>. The follow- + ing options are valid for grid lines. + + <B>-color</B> <I>color</I> + Sets the color of the grid lines. The default is black. + + <B>-dashes</B> <I>dashList</I> + Sets the dash style of the grid lines. <I>DashList</I> 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 <I>dashList</I> is "", the + grid will be solid lines. + + <B>-hide</B> <I>boolean</I> + Indicates whether the grid should be drawn. If <I>boolean</I> is + + <B>-minor</B> <I>boolean</I> + Indicates whether the grid lines should be drawn for + minor ticks. If <I>boolean</I> is true, the lines will appear + at minor tick intervals. The default is 1. + + Grid configuration options may also be set by the <B>option</B> 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 + + <I>pathName</I> <B>grid</B> <B>off</B> + Turns off the display the grid lines. + + <I>pathName</I> <B>grid</B> <B>on</B> + Turns on the display the grid lines. + + <I>pathName</I> <B>grid</B> <B>toggle</B> + Toggles the display of the grid. + + <B>LEGEND</B> <B>COMPONENT</B> + 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. + + <I>pathName</I> <B>legend</B> <B>activate</B> <I>pattern</I>... + Selects legend entries to be drawn using the active legend col- + ors and relief. All entries whose element names match <I>pattern</I> + are selected. To be selected, the element name must match only + one <I>pattern</I>. + + <I>pathName</I> <B>legend</B> <B>bind</B> <I>tagName</I> ?<I>sequence</I>? ?<I>command</I>? + Associates <I>command</I> with <I>tagName</I> such that whenever the event + sequence given by <I>sequence</I> occurs for a legend entry with this + tag, <I>command</I> will be invoked. Implicitly the element names in + the entry are tags. The syntax is similar to the <B>bind</B> command + except that it operates on legend entries, rather than widgets. + See the <B>bind</B> manual entry for complete details on <I>sequence</I> and + the substitutions performed on <I>command</I> before invoking it. + + If all arguments are specified then a new binding is created, + replacing any existing binding for the same <I>sequence</I> and <I>tag-</I> + <I>Name</I>. If the first character of <I>command</I> is + then <I>command</I> aug- + ments an existing binding rather than replacing it. If no <I>com-</I> + <I>mand</I> argument is provided then the command currently associated + with <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no + such binding) is returned. If both <I>command</I> and <I>sequence</I> are + missing then a list of all the event sequences for which bind- + ings have been defined for <I>tagName</I>. + + <B>-activebackground</B> <I>color</I> + Sets the background color for active legend entries. All + legend entries marked active (see the legend <B>activate</B> + operation) are drawn using this background color. + + <B>-activeborderwidth</B> <I>pixels</I> + Sets the width of the 3-D border around the outside edge + of the active legend entries. The default is 2. + + <B>-activeforeground</B> <I>color</I> + Sets the foreground color for active legend entries. All + legend entries marked as active (see the legend <B>activate</B> + operation) are drawn using this foreground color. + + <B>-activerelief</B> <I>relief</I> + Specifies the 3-D effect desired for active legend + entries. <I>Relief</I> 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. + + <B>-anchor</B> <I>anchor</I> + Tells how to position the legend relative to the posi- + tioning point for the legend. This is dependent on the + value of the <B>-position</B> 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 <I>anchor</I> is center then the legend + is centered on the point; if <I>anchor</I> 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 <I>anchor</I> is center then the legend is + centered in the plotting area; if <I>anchor</I> 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 <B>relief</B> + option determines this). The default is 2 pixels. + + <B>-font</B> <I>fontName</I> + <I>FontName</I> 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-*. + + <B>-foreground</B> <I>color</I> + Sets the foreground color of the text drawn for the ele- + ment's label. The default is black. + + <B>-hide</B> <I>boolean</I> + Indicates whether the legend should be displayed. If + <I>boolean</I> is true, the legend will not be draw. The + default is no. + + <B>-ipadx</B> <I>pad</I> + Sets the amount of internal padding to be added to the + width of each legend entry. <I>Pad</I> can be a list of one or + two screen distances. If <I>pad</I> has two elements, the left + side of the legend entry is padded by the first distance + and the right side by the second. If <I>pad</I> is just one + distance, both the left and right sides are padded + evenly. The default is 2. + + <B>-ipady</B> <I>pad</I> + Sets an amount of internal padding to be added to the + height of each legend entry. <I>Pad</I> can be a list of one or + two screen distances. If <I>pad</I> has two elements, the top + of the entry is padded by the first distance and the bot- + tom by the second. If <I>pad</I> is just one distance, both the + top and bottom of the entry are padded evenly. The + default is 2. + + <B>-padx</B> <I>pad</I> + Sets the padding to the left and right exteriors of the + legend. <I>Pad</I> can be a list of one or two screen dis- + tances. If <I>pad</I> has two elements, the left side of the + legend is padded by the first distance and the right side + by the second. If <I>pad</I> has just one distance, both the + left and right sides are padded evenly. The default is + 4. + + <B>-pady</B> <I>pad</I> + Sets the padding above and below the legend. <I>Pad</I> can be + a list of one or two screen distances. If <I>pad</I> has two + elements, the area above the legend is padded by the + first distance and the area below by the second. If <I>pad</I> + 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. + + <B>-relief</B> <I>relief</I> + Specifies the 3-D effect for the border around the leg- + end. <I>Relief</I> 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 <B>option</B> 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 + + <I>pathName</I> <B>legend</B> <B>deactivate</B> <I>pattern</I>... + Selects legend entries to be drawn using the normal legend col- + ors and relief. All entries whose element names match <I>pattern</I> + are selected. To be selected, the element name must match only + one <I>pattern</I>. + + <I>pathName</I> <B>legend</B> <B>get</B> <I>pos</I> + Returns the name of the element whose entry is at the screen + position <I>pos</I> in the legend. <I>Pos</I> must be in the form "<I>@x,y</I>", + where <I>x</I> and <I>y</I> are window coordinates. If the given coordinates + do not lie over a legend entry, "" is returned. + + <B>PEN</B> <B>COMPONENTS</B> + 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 <B>-weight</B> and <B>-style</B> 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 <B>-pen</B> or <B>-activepen</B> 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 + <B>-styles</B> 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. + <I>value</I>. The following options are valid for pens. + + <B>-background</B> <I>color</I> + Sets the the color of the border around each bar. The + default is white. + + <B>-borderwidth</B> <I>pixels</I> + Sets the border width of the 3-D border drawn around the + outside of each bar. The <B>-relief</B> option determines if + such a border is drawn. <I>Pixels</I> must be a valid screen + distance like 2 or 0.25i. The default is 2. + + <B>-foreground</B> <I>color</I> + Sets the color of the interior of the bars. + + <B>-relief</B> <I>string</I> + Specifies the 3-D effect desired for bars. <I>Relief</I> 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. + + <B>-stipple</B> <I>bitmap</I> + Specifies a stipple pattern with which to draw the bars. + If <I>bitmap</I> is "", then the bar is drawn in a solid fash- + ion. + + <B>-type</B> <I>elemType</I> + 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 <B>option</B> 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 + + <I>pathName</I> <B>pen</B> <B>create</B> <I>penName</I> ?<I>option</I> <I>value</I>?... + Creates a new pen by the name <I>penName</I>. No pen by the same name + can already exist. <I>Option</I> and <I>value</I> are described in above in + the pen <B>configure</B> operation. + + <I>pathName</I> <B>pen</B> <B>delete</B> ?<I>penName</I>?... + 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. + + <I>pathName</I> <B>pen</B> <B>names</B> ?<I>pattern</I>?... + Returns a list of pens matching zero or more patterns. If no + <I>option</I>. <I>Option</I> may be any option described below for the post- + script <B>configure</B> operation. + + <I>pathName</I> <B>postscript</B> <B>configure</B> ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options for PostScript + generation. If <I>option</I> isn't specified, a list describing the + current postscript options for <I>pathName</I> is returned. If <I>option</I> + is specified, but not <I>value</I>, then a list describing <I>option</I> is + returned. If one or more <I>option</I> and <I>value</I> pairs are specified, + then for each pair, the postscript option <I>option</I> is set to + <I>value</I>. The following postscript options are available. + + <B>-center</B> <I>boolean</I> + Indicates whether the plot should be centered on the + PostScript page. If <I>boolean</I> is false, the plot will be + placed in the upper left corner of the page. The default + is 1. + + <B>-colormap</B> <I>varName</I> + <I>VarName</I> 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 <I>varName</I> 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 <I>varName</I> 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 <I>varName</I> for a given color, then it uses + the red, green, and blue intensities from the X color. + + <B>-colormode</B> <I>mode</I> + Specifies how to output color information. <I>Mode</I> 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. + + <B>-fontmap</B> <I>varName</I> + <I>VarName</I> 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 <I>varName</I> 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 <I>varName</I> 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. + + <B>-landscape</B> <I>boolean</I> + If <I>boolean</I> 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. + + <B>-maxpect</B> <I>boolean</I> + 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. + + <B>-padx</B> <I>pad</I> + Sets the horizontal padding for the left and right page + borders. The borders are exterior to the plot. <I>Pad</I> can + be a list of one or two screen distances. If <I>pad</I> has two + elements, the left border is padded by the first distance + and the right border by the second. If <I>pad</I> has just one + distance, both the left and right borders are padded + evenly. The default is 1i. + + <B>-pady</B> <I>pad</I> + Sets the vertical padding for the top and bottom page + borders. The borders are exterior to the plot. <I>Pad</I> can + be a list of one or two screen distances. If <I>pad</I> has two + elements, the top border is padded by the first distance + and the bottom border by the second. If <I>pad</I> has just one + distance, both the top and bottom borders are padded + evenly. The default is 1i. + + <B>-paperheight</B> <I>pixels</I> + 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. + + <B>-paperwidth</B> <I>pixels</I> + 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. + + <B>-width</B> <I>pixels</I> + Sets the width of the plot. This lets you generate a + plot of a width different from that of the widget. If + <I>pixels</I> 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 + <B>option</B> 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 <B>-under</B> option. + + Markers, in contrast to elements, don't affect the scaling of the coor- + dinate axes. They can also have <I>elastic</I> 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. + + <I>pathName</I> <B>marker</B> <B>after</B> <I>markerId</I> ?<I>afterId</I>? + Changes the order of the markers, drawing the first marker after + the second. If no second <I>afterId</I> 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. + + <I>pathName</I> <B>marker</B> <B>before</B> <I>markerId</I> ?<I>beforeId</I>? + Changes the order of the markers, drawing the first marker + before the second. If no second <I>beforeId</I> 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. + + <I>pathName</I> <B>marker</B> <B>bind</B> <I>tagName</I> ?<I>sequence</I>? ?<I>command</I>? + Associates <I>command</I> with <I>tagName</I> such that whenever the event + sequence given by <I>sequence</I> occurs for a marker with this tag, + <I>command</I> will be invoked. The syntax is similar to the <B>bind</B> com- + mand except that it operates on graph markers, rather than wid- + gets. See the <B>bind</B> manual entry for complete details on <I>sequence</I> + and the substitutions performed on <I>command</I> before invoking it. + + If all arguments are specified then a new binding is created, + replacing any existing binding for the same <I>sequence</I> and <I>tag-</I> + <I>Name</I>. If the first character of <I>command</I> is + then <I>command</I> aug- + ments an existing binding rather than replacing it. If no <I>com-</I> + <I>mand</I> argument is provided then the command currently associated + with <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no + such binding) is returned. If both <I>command</I> and <I>sequence</I> are + missing then a list of all the event sequences for which bind- + ings have been defined for <I>tagName</I>. + + <I>pathName</I> <B>marker</B> <B>cget</B> <I>option</I> + Returns the current value of the marker configuration option + given by <I>option</I>. <I>Option</I> may be any option described below in + the <B>configure</B> operation. + + <I>pathName</I> <B>marker</B> <B>configure</B> <I>markerId</I> ?<I>option</I> <I>value</I>?... + 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. + + <B>-coords</B> <I>coordList</I> + Specifies the coordinates of the marker. <I>CoordList</I> 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 <I>coordList</I> is "", the marker + will not be displayed. The default is "". + + <B>-element</B> <I>elemName</I> + Links the marker with the element <I>elemName</I>. The marker + is drawn only if the element is also currently displayed + (see the element's <B>show</B> operation). If <I>elemName</I> is "", + the marker is always drawn. The default is "". + + <B>-hide</B> <I>boolean</I> + Indicates whether the marker is drawn. If <I>boolean</I> is + true, the marker is not drawn. The default is no. + + <B>-mapx</B> <I>xAxis</I> + Specifies the X-axis to map the marker's X-coordinates + onto. <I>XAxis</I> must the name of an axis. The default is x. + + <B>-mapy</B> <I>yAxis</I> + Specifies the Y-axis to map the marker's Y-coordinates + onto. <I>YAxis</I> must the name of an axis. The default is y. + + <B>-name</B> <I>markerId</I> + Changes the identifier for the marker. The identifier + <I>markerId</I> can not already be used by another marker. If + this option isn't specified, the marker's name is + uniquely generated. + + <B>-under</B> <I>boolean</I> + Indicates whether the marker is drawn below/above data + elements. If <I>boolean</I> 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. + + <B>-xoffset</B> <I>pixels</I> + Specifies a screen distance to offset the marker horizon- + tally. <I>Pixels</I> is a valid screen distance, such as 2 or + 1.2i. The default is 0. + + Creates a marker of the selected type. <I>Type</I> may be either text, + line, bitmap, image, polygon, or window. This command returns + the marker identifier, used as the <I>markerId</I> argument in the + other marker-related commands. If the <B>-name</B> 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. + + <I>pathName</I> <B>marker</B> <B>delete</B> ?<I>name</I>?... + Removes one of more markers. The graph will automatically be + redrawn without the marker.. + + <I>pathName</I> <B>marker</B> <B>exists</B> <I>markerId</I> + Returns 1 if the marker <I>markerId</I> exists and 0 otherwise. + + <I>pathName</I> <B>marker</B> <B>names</B> ?<I>pattern</I>? + Returns the names of all the markers that currently exist. If + <I>pattern</I> is supplied, only those markers whose names match it + will be returned. + + <I>pathName</I> <B>marker</B> <B>type</B> <I>markerId</I> + Returns the type of the marker given by <I>markerId</I>, such as line + or text. If <I>markerId</I> is not a valid a marker identifier, "" is + returned. + + <B>BITMAP</B> <B>MARKERS</B> + 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 <B>create</B> operation in the + form: <I>pathName</I> <B>marker</B> <B>create</B> <B>bitmap</B> ?<I>option</I> <I>value</I>?... There may be + many <I>option</I>-<I>value</I> pairs, each sets a configuration options for the + marker. These same <I>option</I>-<I>value</I> pairs may be used with the marker's + <B>configure</B> operation. + + The following options are specific to bitmap markers: + + <B>-background</B> <I>color</I> + Same as the <B>-fill</B> option. + + <B>-bitmap</B> <I>bitmap</I> + Specifies the bitmap to be displayed. If <I>bitmap</I> is "", the + marker will not be displayed. The default is "". + + <B>-fill</B> <I>color</I> + Sets the background color of the bitmap. If <I>color</I> is the empty + string, no background will be transparent. The default back- + + <B>-rotate</B> <I>theta</I> + Sets the rotation of the bitmap. <I>Theta</I> 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. + + <B>IMAGE</B> <B>MARKERS</B> + A image marker displays an image. Image markers are created with the + marker's <B>create</B> operation in the form: <I>pathName</I> <B>marker</B> <B>create</B> <B>image</B> + ?<I>option</I> <I>value</I>?... There may be many <I>option</I>-<I>value</I> pairs, each sets a + configuration option for the marker. These same <I>option</I>-<I>value</I> pairs may + be used with the marker's <B>configure</B> operation. + + The following options are specific to image markers: + + <B>-anchor</B> <I>anchor</I> + <I>Anchor</I> tells how to position the image relative to the position- + ing point for the image. For example, if <I>anchor</I> is center then + the image is centered on the point; if <I>anchor</I> 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. + + <B>-image</B> <I>image</I> + Specifies the image to be drawn. If <I>image</I> is "", the marker + will not be drawn. The default is "". + + <B>LINE</B> <B>MARKERS</B> + A line marker displays one or more connected line segments. Line mark- + ers are created with marker's <B>create</B> operation in the form: <I>pathName</I> + <B>marker</B> <B>create</B> <B>line</B> ?<I>option</I> <I>value</I>?... There may be many <I>option</I>-<I>value</I> + pairs, each sets a configuration option for the marker. These same + <I>option</I>-<I>value</I> pairs may be used with the marker's <B>configure</B> operation. + + The following options are specific to line markers: + + <B>-dashes</B> <I>dashList</I> + Sets the dash style of the line. <I>DashList</I> 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 + <I>dashList</I> is "", the marker line will be solid. + + <B>-fill</B> <I>color</I> + Sets the background color of the line. This color is used with + striped lines (see the <B>-dashes</B> option). If <I>color</I> is the empty + string, no background color is drawn (the line will be dashed, + not striped). The default background color is "". + + <B>-linewidth</B> <I>pixels</I> + Sets the width of the lines. The default width is 0. + + in the form: <I>pathName</I> <B>marker</B> <B>create</B> <B>polygon</B> ?<I>option</I> <I>value</I>?... There + may be many <I>option</I>-<I>value</I> pairs, each sets a configuration option for + the marker. These same <I>option</I>-<I>value</I> pairs may be used with the <B>marker</B> + <B>configure</B> command to change the marker's configuration. The following + options are supported for polygon markers: + + <B>-dashes</B> <I>dashList</I> + Sets the dash style of the outline of the polygon. <I>DashList</I> 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 <I>dashList</I> is "", the outline will be a + solid line. + + <B>-fill</B> <I>color</I> + Sets the fill color of the polygon. If <I>color</I> is "", then the + interior of the polygon is transparent. The default is white. + + <B>-linewidth</B> <I>pixels</I> + Sets the width of the outline of the polygon. If <I>pixels</I> is zero, + no outline is drawn. The default is 0. + + <B>-outline</B> <I>color</I> + Sets the color of the outline of the polygon. If the polygon is + stippled (see the <B>-stipple</B> option), then this represents the + foreground color of the stipple. The default is black. + + <B>-stipple</B> <I>bitmap</I> + Specifies that the polygon should be drawn with a stippled pat- + tern rather than a solid color. <I>Bitmap</I> specifies a bitmap to use + as the stipple pattern. If <I>bitmap</I> is "", then the polygon is + filled with a solid color (if the <B>-fill</B> option is set). The + default is "". + + <B>TEXT</B> <B>MARKERS</B> + 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 <B>create</B> + operation in the form: <I>pathName</I> <B>marker</B> <B>create</B> <B>text</B> ?<I>option</I> <I>value</I>?... + There may be many <I>option</I>-<I>value</I> pairs, each sets a configuration option + for the text marker. These same <I>option</I>-<I>value</I> pairs may be used with + the marker's <B>configure</B> operation. + + The following options are specific to text markers: + + <B>-anchor</B> <I>anchor</I> + <I>Anchor</I> tells how to position the text relative to the position- + ing point for the text. For example, if <I>anchor</I> is center then + the text is centered on the point; if <I>anchor</I> 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. + + + <B>-justify</B> <I>justify</I> + Specifies how the text should be justified. This matters only + when the marker contains more than one line of text. <I>Justify</I> + must be left, right, or center. The default is center. + + <B>-outline</B> <I>color</I> + Sets the color of the text. The default value is black. + + <B>-padx</B> <I>pad</I> + Sets the padding to the left and right exteriors of the text. + <I>Pad</I> can be a list of one or two screen distances. If <I>pad</I> has + two elements, the left side of the text is padded by the first + distance and the right side by the second. If <I>pad</I> has just one + distance, both the left and right sides are padded evenly. The + default is 4. + + <B>-pady</B> <I>pad</I> + Sets the padding above and below the text. <I>Pad</I> can be a list of + one or two screen distances. If <I>pad</I> has two elements, the area + above the text is padded by the first distance and the area + below by the second. If <I>pad</I> is just one distance, both the top + and bottom areas are padded evenly. The default is 4. + + <B>-rotate</B> <I>theta</I> + Specifies the number of degrees to rotate the text. <I>Theta</I> 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. + + <B>-text</B> <I>text</I> + Specifies the text of the marker. The exact way the text is + displayed may be affected by other options such as <B>-anchor</B> or + <B>-rotate</B>. + + <B>WINDOW</B> <B>MARKERS</B> + A window marker displays a widget at a given position. Window markers + are created with the marker's <B>create</B> operation in the form: <I>pathName</I> + <B>marker</B> <B>create</B> <B>window</B> ?<I>option</I> <I>value</I>?... There may be many <I>option</I>-<I>value</I> + pairs, each sets a configuration option for the marker. These same + <I>option</I>-<I>value</I> pairs may be used with the marker's <B>configure</B> command. + + The following options are specific to window markers: + + <B>-anchor</B> <I>anchor</I> + <I>Anchor</I> tells how to position the widget relative to the posi- + tioning point for the widget. For example, if <I>anchor</I> is center + then the widget is centered on the point; if <I>anchor</I> 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. + + +</PRE> +<H2>GRAPH COMPONENT BINDINGS</H2><PRE> + 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 <B>Enter</B>, <B>Leave</B>, <B>ButtonPress</B>, <B>Motion</B>, + and <B>KeyPress</B>). + + 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 + <B>-bindtags</B> 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 <B>-bindtags</B> 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 <B>-bindtags</B> option + doesn't change this. + + +</PRE> +<H2>C LANGUAGE API</H2><PRE> + 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 + <B>Blt_ResetVector</B> 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. + + <B>o</B> Try to minimize the number of data points. The more data points + looked at, the more work the bar chart must do. + + <B>o</B> 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. + + <B>o</B> Don't stipple or dash the element. Solid bars are much faster. + + <B>o</B> If you update data elements frequently, try turning off the widget's + <B>-bufferelements</B> 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. + + +</PRE> +<H2>LIMITATIONS</H2><PRE> + 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. + + +</PRE> +<H2>KEYWORDS</H2><PRE> + bar chart, widget + + + +BLT BLT_VERSION barchart(n) +</PRE> +<HR> +<ADDRESS> +Man(1) output converted with +<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> +</ADDRESS> +</BODY> +</HTML> diff --git a/doc/barchart.n b/doc/barchart.n new file mode 100644 index 0000000..7a9dac8 --- /dev/null +++ b/doc/barchart.n @@ -0,0 +1,2239 @@ +'\" +'\" Smithsonian Astrophysical Observatory, Cambridge, MA, USA +'\" This code has been modified under the terms listed below and is made +'\" available under the same terms. +'\" +'\" Copyright 1991-1998 by Bell Labs Innovations for Lucent Technologies. +'\" +'\" Permission to use, copy, modify, and distribute this software and its +'\" documentation for any purpose and without fee is hereby granted, provided +'\" that the above copyright notice appear in all copies and that both that the +'\" copyright notice and warranty disclaimer appear in supporting documentation, +'\" and that the names of Lucent Technologies any of their entities not be used +'\" in advertising or publicity pertaining to distribution of the software +'\" without specific, written prior permission. +'\" +'\" Lucent Technologies disclaims all warranties with regard to this software, +'\" including all implied warranties of merchantability and fitness. In no event +'\" shall Lucent Technologies be liable for any special, indirect or +'\" consequential damages or any damages whatsoever resulting from loss of use, +'\" data or profits, whether in an action of contract, negligence or other +'\" tortuous action, arising out of or in connection with the use or performance +'\" of this software. +'\" +'\" Barchart widget created by Sani Nassif and George Howlett. +'\" +.TH barchart n BLT_VERSION BLT "BLT Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +barchart \- Bar chart for plotting X-Y coordinate data. +.SH SYNOPSIS +\fBbarchart\fI \fIpathName \fR?\fIoption value\fR?... +.BE +.SH DESCRIPTION +The \fBbarchart\fR 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. +.SH INTRODUCTION +The \fBbarchart\fR 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 +\fIplotting area\fR. 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 displayed in top margin. +.PP +A \fBbarchart\fR widget has several configurable components: +coordinate axes, data elements, legend, grid, cross hairs, pens, +postscript, and annotation markers. Each component can be queried or +modified. +.TP 1i +\f(CWaxis\fR + +Up to four coordinate axes (two X\-coordinate and two Y\-coordinate +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. +.TP 1i +\f(CWcrosshairs\fR +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. +.TP 1i +\f(CWelement\fR +An element represents a set of data to be plotted. It contains 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-coordinate) of the data point. +The appearance of the bar, such as its color, stipple, or relief +is configurable. +.sp +A special case exists when two or more data points have the same +abscissa (X-coordinate). By default, the bars are overlayed, one on +top of the other. The bars are drawn in the order of the element +display list. But you can also configure 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 the number of data points with the same abscissa. +.TP 1i +\f(CWgrid\fR +Extends the major and minor ticks of the X\-axis and/or Y\-axis across the +plotting area. +.TP 1i +\f(CWlegend\fR +The legend displays the name and symbol of each data element. +The legend can be drawn in any margin or in the plotting area. +.TP 1i +\f(CWmarker\fR +Markers are used annotate or highlight areas of the graph. For +example, you could use a text marker to label a particular data +point. Markers come in various forms: text strings, bitmaps, connected +line segments, images, polygons, or embedded widgets. +.TP 1i +\f(CWpen\fR +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 \fB\-weight\fR +and \fB\-style\fR options). +.TP 1i +\f(CWpostscript\fR +The widget can generate encapsulated PostScript output. This component +has several options to configure how the PostScript is generated. +.SH SYNTAX +.DS +\fBbarchart \fIpathName \fR?\fIoption value\fR?... +.DE +The \fBbarchart\fR command creates a new window \fIpathName\fR and makes +it into a \fBbarchart\fR widget. At the time this command is invoked, there +must not exist a window named \fIpathName\fR, but \fIpathName\fR'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 \fBconfigure\fR operation +below for the exact details about what \fIoption\fR and \fIvalue\fR +pairs are valid. +.PP +If successful, \fBbarchart\fR 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 general form is: +.DS +\fIpathName \fIoperation\fR \fR?\fIarg\fR?... +.DE +Both \fIoperation\fR and its arguments determine the exact behavior of +the command. The operations available for the graph are described in +the +.SB "BARCHART OPERATIONS" +section. +.PP +The command can also be used to access components of the graph. +.DS +\fIpathName component operation\fR ?\fIarg\fR?... +.DE +The operation, now located after the name of the component, is the +function to be performed on that component. Each component has its own +set of operations that manipulate that component. They will be +described below in their own sections. +.SH EXAMPLE +The \fBbarchart\fR command creates a new bar chart. +.CS +# Create a new bar chart. Plotting area is black. +barchart .b -plotbackground black +.CE +A new Tcl command \f(CW.b\fR 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 \fBconfigure\fR operation. +.CS +# Change the title. +\&.b configure -title "My Plot" +.CE +To add data elements, you use the command and the \fBelement\fR component. +.CS +# 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 } +.CE +The element's X-Y coordinates are specified using lists of +numbers. Alternately, BLT vectors could be used to hold the X-Y +coordinates. +.CS +# 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 yVector +.CE +The advantage of using vectors is that when you modify one, the graph +is automatically redrawn to reflect the new values. +.CS +# Change the y coordinate of the first point. +set yVector(0) 25.18 +.CE +An element named \f(CWe1\fR is now created in \f(CW.b\fR. 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 +\fBshow\fR operation. +.CS +# 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] +.CE +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 \fB\-barwidth\fR +option. +.CS +# Change the scale of the x-coordinate data +xVector set { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 } +# Make sure we change the bar width too. +\&.b configure -barwidth 0.2 +.CE +The height of each bar is proportional to the ordinate (Y-coordinate) +of the data point. +.PP +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 \fB\-barmode\fR configuration +option), the bars are stacked, each bar above the previous. +.CS +# Display the elements as stacked. +\&.b configure -barmode stacked +.CE +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. +.CS +# Display the elements side-by-side. +\&.b configure -barmode aligned +.CE +By default, the element's label in the legend will be also +\f(CWe1\fR. You can change the label, or specify no legend entry, +again using the element's \fBconfigure\fR operation. +.CS +# Don't display "e1" in the legend. +\&.b element configure e1 -label "" +.CE +You can configure more than just the element's label. An element has +many attributes such as stipple, foreground and background colors, +relief, etc. +.CS +\&.b element configure e1 -fg red -bg pink \\ + -stipple gray50 +.CE +Four coordinate axes are automatically created: \f(CWx\fR, \f(CWx2\fR, +\f(CWy\fR, and \f(CWy2\fR. And by default, elements are mapped onto the +axes \f(CWx\fR and \f(CWy\fR. This can be changed with the \fB\-mapx\fR +and \fB\-mapy\fR options. +.CS +# Map "e1" on the alternate y axis "y2". +\&.b element configure e1 -mapy y2 +.CE +Axes can be configured in many ways too. For example, you change the +scale of the Y\-axis from linear to log using the \fBaxis\fR component. +.CS +# Y-axis is log scale. +\&.b axis configure y -logscale yes +.CE +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 \fB\-min\fR and \fB\-max\fR configuration options. +.CS +\&.b axis configure x \-min 1.0 \-max 1.5 +\&.b axis configure y \-min 12.0 \-max 55.15 +.CE +To zoom interactively, you link the\fBaxis configure\fR operations with +some user interaction (such as pressing the mouse button), using the +\fBbind\fR command. To convert between screen and graph coordinates, +use the \fBinvtransform\fR operation. +.CS +# 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] +} +.CE +By default, the limits of the axis are determined from data values. +To reset back to the default limits, set the \fB\-min\fR and +\fB\-max\fR options to the empty value. +.CS +# Reset the axes to autoscale again. +\&.b axis configure x \-min {} \-max {} +\&.b axis configure y \-min {} \-max {} +.CE +By default, the legend is drawn in the right margin. You can +change this or any legend configuration options using the +\fBlegend\fR component. +.CS +# Configure the legend font, color, and relief +\&.b legend configure -position left -relief raised \\ + -font fixed -fg blue +.CE +To prevent the legend from being displayed, turn on the \fB\-hide\fR +option. +.CS +# Don't display the legend. +\&.b legend configure \-hide yes\fR +.CE +The \fBbarchart\fR 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 value. Markers are created +using the \fBmarker\fR operation. +.CS +# Create a line represent the low water mark at 10.0 +\&.b marker create line -name "low_water" \\ + -coords { -Inf 10.0 Inf 10.0 } \\ + -dashes { 2 4 2 } -fg red -bg blue +.CE +This creates a line marker named \f(CWlow_water\fR. It will display a +horizontal line stretching across the plotting area at the +y-coordinate 10.0. The coordinates "-Inf" and "Inf" indicate the +relative minimum and maximum of the axis (in this case the x-axis). By +default, markers are drawn last, on top of the bars. You can change this +with the \fB\-under\fR option. +.CS +# Draw the marker before elements are drawn. +\&.b marker configure low_water -under yes +.CE +You can add cross hairs or grid lines using the \fBcrosshairs\fR and +\fBgrid\fR components. +.CS +# Display both cross hairs and grid lines. +\&.b crosshairs configure -hide no -color red +\&.b grid configure -hide no -dashes { 2 2 } +.CE +Finally, to get hardcopy of the graph, use the \fBpostscript\fR +component. +.CS +# Print the bar chart into file "file.ps" +\&.b postscript output file.ps -maxpect yes -decorations no +.CE +This generates a file \f(CWfile.ps\fR containing the encapsulated +PostScript of the graph. The option \fB\-maxpect\fR says to scale the +plot to the size of the page. Turning off the \fB\-decorations\fR +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). +.SH SYNTAX +.DS +\fBbarchart \fIpathName \fR?\fIoption value\fR?... +.DE +The \fBbarchart\fR command creates a new window \fIpathName\fR and makes +it into a barchart widget. At the time this command is invoked, there +must not exist a window named \fIpathName\fR, but \fIpathName\fR'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 \fBconfigure\fR operation +below for the exact details as to what \fIoption\fR and \fIvalue\fR +pairs are valid. +.PP +If successful, \fBbarchart\fR returns \fIpathName\fR. It also creates a +new Tcl command \fIpathName\fR. This command may be used to invoke +various operations to query or modify the bar chart. It has the general +form: +.DS +\fIpathName \fIoperation\fR \fR?\fIarg\fR?... +.DE +Both \fIoperation\fR and its arguments determine the exact behavior of +the command. The operations available for the bar chart are described in +the following section. +.SH "BARCHART OPERATIONS" +.TP +\fIpathName \fBbar \fIelemName \fR?\fIoption value\fR?... +Creates a new barchart element \fIelemName\fR. It's an +error if an element \fIelemName\fR already exists. +See the manual for \fBbarchart\fR for details about +what \fIoption\fR and \fIvalue\fR pairs are valid. +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given by +\fIoption\fR. \fIOption\fR may be any option described +below for the \fBconfigure\fR operation. +.TP +\fIpathName \fBconfigure \fR?\fIoption value\fR?... +Queries or modifies the configuration options of the graph. If +\fIoption\fR isn't specified, a list describing the current +options for \fIpathName\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the option \fIoption\fR is set to \fIvalue\fR. +The following options are valid. +.RS +.TP +\fB\-background \fIcolor\fR +Sets the background color. This includes the margins and +legend, but not the plotting area. +.TP +\fB\-barmode \fImode\fR +Indicates how related bar elements will be drawn. Related elements +have data points with the same abscissas (X-coordinates). \fIMode\fR +indicates how those segments should be drawn. \fIMode\fR can be +\f(CWinfront\fR, \f(CWaligned\fR, \f(CWoverlap\fR, or \f(CWstacked\fR. +The default mode is \f(CWinfront\fR. +.RS +.TP 1i +\f(CWinfront\fR +Each successive segment is drawn in front of the previous. +.TP 1i +\f(CWstacked\fR +Each successive segment is stacked vertically on top of the previous. +.TP 1i +\f(CWaligned\fR +Segments is displayed aligned from right-to-left. +.TP 1i +\f(CWoverlap\fR +Like \f(CWaligned\fR but segments slightly overlap each other. +.RE +.TP +\fB\-barwidth \fIvalue\fR +Specifies the width of the bars. This value can be overrided by the +individual elements using their \fB\-barwidth\fR configuration option. +\fIValue\fR is the width in terms of graph-coordinates. The +default width is \f(CW1.0\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the width of the 3\-D border around the outside edge of the widget. The +\fB\-relief\fR option determines if the border is to be drawn. The +default is \f(CW2\fR. +.TP +\fB\-bottommargin \fIpixels\fR +Specifies the size of the margin below the X\-coordinate axis. If +\fIpixels\fR is \f(CW0\fR, the size of the margin is selected automatically. +The default is \f(CW0\fR. +.TP +\fB\-bufferelements \fIboolean\fR +Indicates whether an internal pixmap to buffer the display of data +elements should be used. If \fIboolean\fR 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 +.SB "SPEED TIPS" +section. +The default is \f(CW1\fR. +.TP +\fB\-cursor \fIcursor\fR +Specifies the widget's cursor. The default cursor is \f(CWcrosshair\fR. +.TP +\fB\-font \fIfontName\fR +Specifies the font of the graph title. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-18-180-*\fR. +.TP +\fB\-halo \fIpixels\fR +Specifies a maximum distance to consider when searching for the +closest data point (see the element's \fBclosest\fR operation below). +Data points further than \fIpixels\fR away are ignored. The default is +\f(CW0.5i\fR. +.TP +\fB\-height \fIpixels\fR +Specifies the requested height of widget. The default is +\f(CW4i\fR. +.TP +\fB\-invertxy \fIboolean\fR +Indicates whether the placement X\-axis and Y\-axis should be inverted. If +\fIboolean\fR is true, the X and Y axes are swapped. The default is +\f(CW0\fR. +.TP +\fB\-justify \fIjustify\fR +Specifies how the title should be justified. This matters only when +the title contains more than one line of text. \fIJustify\fR must be +\f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-leftmargin \fIpixels\fR +Sets the size of the margin from the left edge of the window to +the Y\-coordinate axis. If \fIpixels\fR is \f(CW0\fR, the size is +calculated automatically. The default is \f(CW0\fR. +.TP +\fB\-plotbackground \fIcolor\fR +Specifies the background color of the plotting area. The default is +\f(CWwhite\fR. +.TP +\fB\-plotborderwidth \fIpixels\fR +Sets the width of the 3-D border around the plotting area. The +\fB\-plotrelief\fR option determines if a border is drawn. The +default is \f(CW2\fR. +.TP +\fB\-plotpadx \fIpad\fR +Sets the amount of padding to be added to the left and right sides of +the plotting area. \fIPad\fR can be a list of one or two screen +distances. If \fIpad\fR 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 \fIpad\fR is just one distance, both the left and +right sides are padded evenly. The default is \f(CW8\fR. +.TP +\fB\-plotpady \fIpad\fR +Sets the amount of padding to be added to the top and bottom of the +plotting area. \fIPad\fR can be a list of one or two screen +distances. If \fIpad\fR has two elements, the top of the plotting +area is padded by the first distance and the bottom by the second. If +\fIpad\fR is just one distance, both the top and bottom are padded +evenly. The default is \f(CW8\fR. +.TP +\fB\-plotrelief \fIrelief\fR +Specifies the 3-D effect for the plotting area. \fIRelief\fR +specifies how the interior of the plotting area should appear relative +to rest of the graph; for example, \f(CWraised\fR means the plot should +appear to protrude from the graph, relative to the surface of the +graph. The default is \f(CWsunken\fR. +.TP +\fB\-relief \fIrelief\fR +Specifies the 3-D effect for the barchart widget. \fIRelief\fR +specifies how the graph should appear relative to widget it is packed +into; for example, \f(CWraised\fR means the graph should +appear to protrude. The default is \f(CWflat\fR. +.TP +\fB\-rightmargin \fIpixels\fR +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 +\fIpixels\fR is than 1, the margin size is selected automatically. +.TP +\fB\-takefocus\fR \fIfocus\fR +Provides information used when moving the focus from window to window +via keyboard traversal (e.g., Tab and Shift-Tab). If \fIfocus\fR is +\f(CW0\fR, this means that this window should be skipped entirely during +keyboard traversal. \f(CW1\fR 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 \f(CW""\fR. +.TP +\fB\-tile \fIimage\fR +Specifies a tiled background for the widget. If \fIimage\fR isn't +\f(CW""\fR, the background is tiled using \fIimage\fR. +Otherwise, the normal background color is drawn (see the +\fB\-background\fR option). \fIImage\fR must be an image created +using the Tk \fBimage\fR command. The default is \f(CW""\fR. +.TP +\fB\-title \fItext\fR +Sets the title to \fItext\fR. If \fItext\fR is \f(CW""\fR, +no title will be displayed. +.TP +\fB\-topmargin \fIpixels\fR +Specifies the size of the margin above the x2 axis. If \fIpixels\fR +is \f(CW0\fR, the margin size is calculated automatically. +.TP +\fB\-width \fIpixels\fR +Specifies the requested width of the widget. The default is +\f(CW5i\fR. +.RE +.TP +\fIpathName \fBcrosshairs \fIoperation \fR?\fIarg\fR? +See the +.SB "CROSSHAIRS COMPONENT" +section. +.TP +\fIpathName \fBelement \fIoperation \fR?\fIarg\fR?... +See the +.SB "ELEMENT COMPONENTS" +section. +.TP +\fIpathName \fBextents \fIitem\fR +Returns the size of a particular item in the graph. \fIItem\fR must +be either \f(CWleftmargin\fR, \f(CWrightmargin\fR, \f(CWtopmargin\fR, +\f(CWbottommargin\fR, \f(CWplotwidth\fR, or \f(CWplotheight\fR. +.TP +\fIpathName \fBgrid \fIoperation \fR?\fIarg\fR?... +See the +.SB "GRID COMPONENT" +section. +.TP +\fIpathName \fBinvtransform \fIwinX winY\fR +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-coordinates. +.TP +\fIpathName \fBinside \fIx y\fR +Returns \f(CW1\fR is the designated screen-coordinate (\fIx\fR and \fIy\fR) +is inside the plotting area and \f(CW0\fR otherwise. +.TP +\fIpathName \fBlegend \fIoperation \fR?\fIarg\fR?... +See the +.SB "LEGEND COMPONENT" +section. +.TP +\fIpathName \fBline\fB operation arg\fR... +The operation is the same as \fBelement\fR. +.TP +\fIpathName \fBmarker \fIoperation \fR?\fIarg\fR?... +See the +.SB "MARKER COMPONENTS" +section. +.TP +\fIpathName\fR \fBmetafile\fR ?\fIfileName\fR? +\fIThis operation is for Window platforms only\fR. +Creates a Windows enhanced metafile of the barchart. +If present, \fIfileName\fR is the file name of the new metafile. +Otherwise, the metafile is automatically added to the clipboard. +.TP +\fIpathName \fBpostscript \fIoperation \fR?\fIarg\fR?... +See the +.SB "POSTSCRIPT COMPONENT" +section. +.TP +\fIpathName \fBsnap \fIphotoName\fR +Takes a snapshot of the graph and stores the contents in the photo +image \fIphotoName\fR. \fIPhotoName\fR is the name of a Tk photo +image that must already exist. +.TP +\fIpathName \fBtransform \fIx y\fR +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. +.TP +\fIpathName \fBxaxis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fBx2axis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fByaxis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fBy2axis \fIoperation\fR ?\fIarg\fR?... +See the +.SB "AXIS COMPONENTS" +section. +.SH "BARCHART COMPONENTS" +A graph is composed of several components: coordinate axes, data +elements, legend, grid, cross hairs, postscript, and annotation +markers. Instead of one big set of configuration options and +operations, the graph is partitioned, where each component has its own +configuration options and operations that specifically control that +aspect or part of the graph. +.SS "AXIS COMPONENTS" +Four coordinate axes are automatically created: two X\-coordinate axes +(\f(CWx\fR and \f(CWx2\fR) and two Y\-coordinate axes (\f(CWy\fR, and +\f(CWy2\fR). By default, the axis \f(CWx\fR is located in the bottom +margin, \f(CWy\fR in the left margin, \f(CWx2\fR in the top margin, and +\f(CWy2\fR in the right margin. +.PP +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. +.PP +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 plotted. By default, the minimum and maximum limits are +determined from the data, but you can reset either limit. +.PP +You can create and use several axes. To create an axis, invoke +the axis component and its create operation. +.CS +# Create a new axis called "temperature" +\&.b axis create temperature +.CE +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. +.CS +# Now map the temperature data to this axis. +\&.b element create "temp" \-xdata $x \-ydata $tempData \\ + \-mapy temperature +.CE +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 \f(CWx\fR and \f(CWy\fR are drawn in the +bottom and left margins. The axes \f(CWx2\fR and \f(CWy2\fR are drawn in +top and right margins. Only \f(CWx\fR and \f(CWy\fR are shown by +default. Note that the axes can have different scales. +.PP +To display a different axis, you invoke one of the following +components: \fBxaxis\fR, \fByaxis\fR, \fBx2axis\fR, and \fBy2axis\fR. +The \fBuse\fR operation designates the axis to be drawn in the +corresponding margin: \fBxaxis\fR in the bottom, \fByaxis\fR in the left, +\fBx2axis\fR in the top, and \fBy2axis\fR in the right. +.CS +# Display the axis temperature in the left margin. +\&.b yaxis use temperature +.CE +.PP +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. +.PP +.TP +\fIpathName \fBaxis \fBcget \fIaxisName \fIoption\fR +Returns the current value of the option given by \fIoption\fR for +\fIaxisName\fR. \fIOption\fR may be any option described below +for the axis \fBconfigure\fR operation. +.TP +\fIpathName \fBaxis \fBconfigure \fIaxisName \fR?\fIaxisName\fR?... ?\fIoption value\fR?... +Queries or modifies the configuration options of \fIaxisName\fR. +Several axes can be changed. If \fIoption\fR isn't specified, a list +describing all the current options for \fIaxisName\fR is returned. If +\fIoption\fR is specified, but not \fIvalue\fR, then a list describing +\fIoption\fR is returned. If one or more \fIoption\fR and \fIvalue\fR +pairs are specified, then for each pair, the axis option \fIoption\fR +is set to \fIvalue\fR. The following options are valid for axes. +.RS +.TP +\fB\-autorange \fIrange\fR +Sets the range of values for the axis to \fIrange\fR. The axis limits +are automatically reset to display the most recent data points in this range. +If \fIrange\fR is 0.0, the range is +determined from the limits of the data. If \fB\-min\fR or \fB-max\fR +are specified, they override this option. The default is \f(CW0.0\fR. +.TP +\fB\-color \fIcolor\fR +Sets the color of the axis and tick labels. +The default is \f(CWblack\fR. +.TP +\fB\-command \fIprefix\fR +Specifies a Tcl command to be invoked when formatting the axis tick +labels. \fIPrefix\fR 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 +\f(CW""\fR is returned, no label will appear next to the tick. You can +get the standard tick labels again by setting \fIprefix\fR to +\f(CW""\fR. The default is \f(CW""\fR. +.sp 1 +Please note that this procedure is invoked while the bar chart is redrawn. +You may query the widget's configuration options. But do not reset +options, because this can have unexpected results. +.TP +\fB\-descending \fIboolean\fR +Indicates whether the values along the axis are monotonically increasing or +decreasing. If \fIboolean\fR is true, the axis values will be +decreasing. The default is \f(CW0\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the axis is displayed. +.TP +\fB\-justify \fIjustify\fR +Specifies how the axis title should be justified. This matters only +when the axis title contains more than one line of text. \fIJustify\fR +must be \f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-limits \fIformatStr\fR +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. \fIFormatStr\fR is a list of +one or two format descriptions. If one description is supplied, both +the minimum and maximum limits are formatted in the same way. If two, +the first designates the format for the minimum limit, the second for +the maximum. If \f(CW""\fR is given as either description, then +the that limit will not be displayed. The default is \f(CW""\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the axis and tick lines. The default is \f(CW1\fR +pixel. +.TP +\fB\-logscale \fIboolean\fR +Indicates whether the scale of the axis is logarithmic or linear. If +\fIboolean\fR is true, the axis is logarithmic. The default scale is +linear. +.TP +\fB\-loose \fIboolean\fR +Indicates whether the limits of the axis should fit the data points tightly, +at the outermost data points, or loosely, at the outer tick intervals. +This is relevant only when the axis limit is automatically calculated. +If \fIboolean\fR is true, the axis range is "loose". +The default is \f(CW0\fR. +.TP +\fB\-majorticks \fImajorList\fR +Specifies where to display major axis ticks. You can use this option +to display ticks at non-uniform intervals. \fIMajorList\fR is a list +of axis coordinates designating the location of major ticks. No +minor ticks are drawn. If \fImajorList\fR is \f(CW""\fR, +major ticks will be automatically computed. The default is \f(CW""\fR. +.TP +\fB\-max \fIvalue\fR +Sets the maximum limit of \fIaxisName\fR. Any data point greater +than \fIvalue\fR is not displayed. If \fIvalue\fR is \f(CW""\fR, +the maximum limit is calculated using the largest data value. +The default is \f(CW""\fR. +.TP +\fB\-min \fIvalue\fR +Sets the minimum limit of \fIaxisName\fR. Any data point less than +\fIvalue\fR is not displayed. If \fIvalue\fR is \f(CW""\fR, +the minimum limit is calculated using the smallest data value. +The default is \f(CW""\fR. +.TP +\fB\-minorticks \fIminorList\fR +Specifies where to display minor axis ticks. You can use this option +to display minor ticks at non-uniform intervals. \fIMinorList\fR 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 \fB\-majortick\fR +option is also set. If \fIminorList\fR is \f(CW""\fR, minor ticks will +be automatically computed. The default is \f(CW""\fR. +.TP +\fB\-rotate \fItheta\fR +Specifies the how many degrees to rotate the axis tick labels. +\fITheta\fR is a real value representing the number of degrees +to rotate the tick labels. The default is \f(CW0.0\fR degrees. +.TP +\fB\-shiftby \fIvalue\fR +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 \fIvalue\fR. You can use this +option to prevent the axis limits from being recomputed +at each new time point. If \fIvalue\fR is 0.0, then no automatic +shifting is down. The default is \f(CW0.0\fR. +.TP +\fB\-showticks \fIboolean\fR +Indicates whether axis ticks should be drawn. If \fIboolean\fR is +true, ticks are drawn. If false, only the +axis line is drawn. The default is \f(CW1\fR. +.TP +\fB\-stepsize \fIvalue\fR +Specifies the interval between major axis ticks. If \fIvalue\fR isn't +a valid interval (must be less than the axis range), +the request is ignored and the step size is automatically calculated. +.TP +\fB\-subdivisions \fInumber\fR +Indicates how many minor axis ticks are +to be drawn. For example, if \fInumber\fR is two, only one minor +tick is drawn. If \fInumber\fR is one, no minor ticks are +displayed. The default is \f(CW2\fR. +.TP +\fB\-tickfont \fIfontName\fR +Specifies the font for axis tick labels. The default is +\f(CW*-Courier-Bold-R-Normal-*-100-*\fR. +.TP +\fB\-ticklength \fIpixels\fR +Sets the length of major and minor ticks (minor ticks are half the +length of major ticks). If \fIpixels\fR is less than zero, the axis +will be inverted with ticks drawn pointing towards the plot. The +default is \f(CW0.1i\fR. +.TP +\fB\-title \fItext\fR +Sets the title of the axis. If \fItext\fR is +\f(CW""\fR, no axis title will be displayed. +.TP +\fB\-titlecolor \fIcolor\fR +Sets the color of the axis title. The default is \f(CWblack\fR. +.TP +\fB\-titlefont \fIfontName\fR +Specifies the font for axis title. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-14-140-*\fR. +.PP +Axis configuration options may be also be set by the \fBoption\fR +command. The resource class is \f(CWAxis\fR. The resource names +are the names of the axes (such as \f(CWx\fR or \f(CWx2\fR). +.CS +option add *Barchart.Axis.Color blue +option add *Barchart.x.LogScale true +option add *Barchart.x2.LogScale false +.CE +.RE +.TP +\fIpathName \fBaxis \fBcreate \fIaxisName \fR?\fIoption value\fR?... +Creates a new axis by the name \fIaxisName\fR. No axis by the same +name can already exist. \fIOption\fR and \fIvalue\fR are described +in above in the axis \fBconfigure\fR operation. +.TP +\fIpathName \fBaxis \fBdelete \fR?\fIaxisName\fR?... +Deletes the named axes. An axis is not really +deleted until it is not longer in use, so it's safe to delete +axes mapped to elements. +.TP +\fIpathName \fBaxis invtransform \fIaxisName value\fR +Performs the inverse transformation, changing the screen-coordinate +\fIvalue\fR to a graph-coordinate, mapping the value mapped to +\fIaxisName\fR. Returns the graph-coordinate. +.TP +\fIpathName \fBaxis limits \fIaxisName\fR +Returns a list of the minimum and maximum limits for \fIaxisName\fR. The order +of the list is \f(CWmin max\fR. +.TP +\fIpathName \fBaxis names \fR?\fIpattern\fR?... +Returns a list of axes matching zero or more patterns. If no +\fIpattern\fR argument is give, the names of all axes are returned. +.TP +\fIpathName \fBaxis transform \fIaxisName value\fR +Transforms the coordinate \fIvalue\fR to a screen-coordinate by mapping +the it to \fIaxisName\fR. Returns the transformed screen-coordinate. +.PP +Only four axes can be displayed simultaneously. By default, they are +\f(CWx\fR, \f(CWy\fR, \f(CWx2\fR, and \f(CWy2\fR. You can swap in a different +axis with \fBuse\fR operation of the special axis components: +\fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, and \fBy2axis\fR. +.CS +\&.g create axis temp +\&.g create axis time +\&... +\&.g xaxis use temp +\&.g yaxis use time +.CE +Only the axes specified for use are displayed on the screen. +.PP +The \fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, and \fBy2axis\fR +components operate on an axis location rather than a specific axis +like the more general \fBaxis\fR component does. The \fBxaxis\fR +component manages the X-axis located in the bottom margin (whatever +axis that happens to be). Likewise, \fByaxis\fR uses the Y-axis in +the left margin, \fBx2axis\fR the top X-axis, and \fBy2axis\fR the +right Y-axis. +.PP +They implicitly control the axis that is currently using to that +location. By default, \fBxaxis\fR uses the \f(CWx\fR axis, \fByaxis\fR +uses \f(CWy\fR, \fBx2axis\fR uses \f(CWx2\fR, and \fBy2axis\fR uses +\f(CWy2\fR. These components can be more convenient to use than always +determining what axes are current being displayed by the graph. +.PP +The following operations are available for axes. They mirror exactly +the operations of the \fBaxis\fR component. The \fIaxis\fR argument +must be \fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, or \fBy2axis\fR. +.TP +\fIpathName \fIaxis \fBcget \fIoption\fR +.TP +\fIpathName \fIaxis \fBconfigure \fR?\fIoption value\fR?... +.TP +\fIpathName \fIaxis\fB invtransform \fIvalue\fR +.TP +\fIpathName \fIaxis \fBlimits\fR +.TP +\fIpathName \fIaxis\fB transform \fIvalue\fR +.TP +\fIpathName \fIaxis\fB use \fR?\fIaxisName\fR? +Designates the axis \fIaxisName\fR is to be displayed at this +location. \fIAxisName\fR can not be already in use at another location. +This command returns the name of the axis currently using this location. +.SS "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 without redrawing +the entire widget. +.PP +The following operations are available for cross hairs: +.TP +\fIpathName \fBcrosshairs cget \fIoption\fR +Returns the current value of the cross hairs configuration option +given by \fIoption\fR. \fIOption\fR may be any option +described below for the cross hairs \fBconfigure\fR operation. +.TP +\fIpathName \fBcrosshairs configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options of the cross hairs. If +\fIoption\fR isn't specified, a list describing all the current +options for the cross hairs is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the cross hairs option \fIoption\fR is set to +\fIvalue\fR. +The following options are available for cross hairs. +.RS +.TP +\fB\-color \fIcolor\fR +Sets the color of the cross hairs. The default is \f(CWblack\fR. +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the cross hairs. \fIDashList\fR 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 \fIdashList\fR is \f(CW""\fR, the cross hairs will be solid +lines. +.TP +\fB\-hide \fIboolean\fR +Indicates whether cross hairs are drawn. If \fIboolean\fR is true, +cross hairs are not drawn. The default is \f(CWyes\fR. +.TP +\fB\-linewidth \fIpixels\fR +Set the width of the cross hair lines. The default is \f(CW1\fR. +.TP +\fB\-position \fIpos\fR +Specifies the screen position where the cross hairs intersect. +\fIPos\fR must be in the form "\fI@x,y\fR", where \fIx\fR and \fIy\fR +are the window coordinates of the intersection. +.PP +Cross hairs configuration options may be also be set by the +\fBoption\fR command. The resource name and class are +\f(CWcrosshairs\fR and \f(CWCrosshairs\fR respectively. +.CS +option add *Barchart.Crosshairs.LineWidth 2 +option add *Barchart.Crosshairs.Color red +.CE +.RE +.TP +\fIpathName \fBcrosshairs off\fR +Turns off the cross hairs. +.TP +\fIpathName \fBcrosshairs on\fR +Turns on the display of the cross hairs. +.TP +\fIpathName \fBcrosshairs toggle\fR +Toggles the current state of the cross hairs, alternately mapping and +unmapping the cross hairs. +.SH "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. +.PP +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. +.PP +The following operations are available for elements. +.TP +\fIpathName \fBelement activate \fIelemName \fR?\fIindex\fR?... +Specifies the data points of element \fIelemName\fR to be drawn +using active foreground and background colors. \fIElemName\fR is the +name of the element and \fIindex\fR is a number representing the index +of the data point. If no indices are present then all data points +become active. +.TP +\fIpathName \fBelement bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for an element with this +tag, \fIcommand\fR will be invoked. The syntax is similar to the +\fBbind\fR command except that it operates on graph elements, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBelement cget \fIelemName \fIoption\fR +Returns the current value of the element configuration option given by +\fIoption\fR. \fIOption\fR may be any of the options described below +for the element \fBconfigure\fR operation. +.TP +\fIpathName \fBelement closest \fIx y\fR ?\fIoption value\fR?... ?\fIelemName\fR?... +Finds the data point representing the bar closest to the window +coordinates \fIx\fR and \fIy\fR in the element \fIelemName\fR. +\fIElemName\fR 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, +\f(CW""\fR is returned. The following \fIoption\fR-\fIvalue\fR pairs +are available. +.RS +.TP +\fB\-halo \fIpixels\fR +Specifies a threshold distance where selected data points are ignored. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +If this option isn't specified, then it defaults to the value of the +\fBbarchart\fR's \fB\-halo\fR option. +.RE +.TP +\fIpathName \fBelement configure \fIelemName \fR?\fIelemName\fR... ?\fIoption value\fR?... +Queries or modifies the configuration options for elements. Several +elements can be modified at the same time. If \fIoption\fR isn't +specified, a list describing all the current options for +\fIelemName\fR is returned. If \fIoption\fR is specified, but not +\fIvalue\fR, then a list describing the option \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the element option \fIoption\fR is set +to \fIvalue\fR. The following options are valid for elements. +.RS +.TP +\fB\-activepen \fIpenName\fR +Specifies pen to use to draw active element. If \fIpenName\fR is +\f(CW""\fR, no active elements will be drawn. The default is +\f(CWactiveLine\fR. +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for the element. \fITagList\fR 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 +\f(CWall\fR. +.TP +\fB\-background \fIcolor\fR +Sets the the color of the border around each bar. The default is +\f(CWwhite\fR. +.TP +\fB\-barwidth \fIvalue\fR +Specifies the width the bars drawn for the element. \fIValue\fR is +the width in X-coordinates. If this option isn't +specified, the width of each bar is the value of the widget's +\fB\-barwidth\fR option. +.TP +\fB\-baseline \fIvalue\fR +Specifies the baseline of the bar segments. This affects how bars are +drawn since bars are drawn from their respective y-coordinate the +baseline. By default the baseline is \f(CW0.0\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the border width of the 3-D border drawn around the outside of +each bar. The \fB\-relief\fR option determines if such a border is +drawn. \fIPixels\fR must be a valid screen distance like \f(CW2\fR or +\f(CW0.25i\fR. The default is \f(CW2\fR. +.TP +\fB\-data \fIcoordList\fR +Specifies the X\-Y coordinates of the data. \fICoordList\fR is a +list of numeric expressions representing the X\-Y coordinate pairs +of each data point. +.TP +\fB\-foreground \fIcolor\fR +Sets the color of the interior of the bars. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the element is displayed. The default is \f(CWno\fR. +.TP +\fB\-label \fItext\fR +Sets the element's label in the legend. If \fItext\fR +is \f(CW""\fR, the element will have no entry in the legend. +The default label is the element's name. +.TP +\fB\-mapx \fIxAxis\fR +Selects the X\-axis to map the element's X\-coordinates onto. +\fIXAxis\fR must be the name of an axis. The default is \f(CWx\fR. +.TP +\fB\-mapy \fIyAxis\fR +Selects the Y\-axis to map the element's Y\-coordinates onto. +\fIYAxis\fR must be the name of an axis. The default is \f(CWy\fR. +.TP +\fB\-relief \fIstring\fR +Specifies the 3-D effect desired for bars. \fIRelief\fR indicates how +the interior of the bar should appear relative to the surface of the +chart; for example, \f(CWraised\fR means the bar should appear to +protrude from the surface of the plotting area. The default is +\f(CWraised\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies a stipple pattern with which to draw the bars. If +\fIbitmap\fR is \f(CW""\fR, then the bar is drawn in a solid fashion. +.TP +\fB\-xdata \fIxVector\fR +Specifies the x-coordinate vector of the data. +\fIXVector\fR is the name of a BLT vector or a +list of numeric expressions. +.TP +\fB\-ydata \fIyVector\fR +Specifies the y-coordinate vector of the data. +\fIYVector\fR is the name of a BLT vector or a list of +numeric expressions. +.PP +Element configuration options may also be set by the +\fBoption\fR command. The resource names in the option database +are prefixed by \f(CWelem\fR. +.CS +option add *Barchart.Element.background blue +.CE +.RE +.TP +\fIpathName \fBelement create \fIelemName\fR ?\fIoption value\fR?... +Creates a new element \fIelemName\fR. Element +names must be unique, so an element \fIelemName\fR may not already +exist. If additional arguments are present, they specify any of the +element options valid for element \fBconfigure\fR operation. +.TP +\fIpathName \fBelement deactivate \fIpattern\fR... +Deactivates all the elements matching \fIpattern\fR for the graph. +Elements whose names match any of the patterns given are redrawn +using their normal colors. +.TP +\fIpathName \fBelement delete\fR ?\fIpattern\fR?... +Deletes all the elements matching \fIpattern\fR for the graph. +Elements whose names match any of the patterns given are deleted. +The graph will be redrawn without the deleted elements. +.TP +\fIpathName \fBelement exists \fIelemName\fR +Returns \f(CW1\fR if an element \fIelemName\fR currently exists and +\f(CW0\fR otherwise. +.TP +\fIpathName \fBelement names \fR?\fIpattern\fR?... +Returns the elements matching one or more pattern. If no +\fIpattern\fR is given, the names of all elements is returned. +.TP +\fIpathName \fBelement show\fR ?\fInameList\fR? +Queries or modifies the element display list. The element display +list designates the elements drawn and in what +order. \fINameList\fR is a list of elements to be displayed in the +order they are named. If there is no \fInameList\fR argument, +the current display list is returned. +.TP +\fIpathName \fBelement type\fR \fIelemName\fR +Returns the type of \fIelemName\fR. +If the element is a bar element, the commands returns the string +\f(CW"bar"\fR, otherwise it returns \f(CW"line"\fR. +.CE +.SS "GRID COMPONENT" +Grid lines extend from the major and minor ticks of each axis +horizontally or vertically across the plotting area. The following +operations are available for grid lines. +.TP +\fIpathName \fBgrid cget \fIoption\fR +Returns the current value of the grid line configuration option given by +\fIoption\fR. \fIOption\fR may be any option described below +for the grid \fBconfigure\fR operation. +.TP +\fIpathName \fBgrid configure\fR ?\fIoption value\fR?... +Queries or modifies the configuration options for grid lines. If +\fIoption\fR isn't specified, a list describing all the current +grid options for \fIpathName\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the grid line option \fIoption\fR is set to +\fIvalue\fR. The following options are valid for grid lines. +.RS +.TP +\fB\-color \fIcolor\fR +Sets the color of the grid lines. The default is \f(CWblack\fR. +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the grid lines. \fIDashList\fR 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 \fIdashList\fR is \f(CW""\fR, the grid will be solid lines. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the grid should be drawn. If \fIboolean\fR +is true, grid lines are not shown. The default is \f(CWyes\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of grid lines. The default width is \f(CW1\fR. +.TP +\fB\-mapx \fIxAxis\fR +Specifies the X\-axis to display grid lines. \fIXAxis\fR +must be the name of an axis or \f(CW""\fR for no grid lines. +The default is \f(CW""\fR. +.TP +\fB\-mapy \fIyAxis\fR +Specifies the Y\-axis to display grid lines. \fIYAxis\fR +must be the name of an axis or \f(CW""\fR for no grid lines. +The default is \f(CWy\fR. +.TP +\fB\-minor \fIboolean\fR +Indicates whether the grid lines should be drawn for minor ticks. +If \fIboolean\fR is true, the lines will appear at +minor tick intervals. The default is \f(CW1\fR. +.PP +Grid configuration options may also be set by the +\fBoption\fR command. The resource name and class are \f(CWgrid\fR and +\f(CWGrid\fR respectively. +.CS +option add *Barchart.grid.LineWidth 2 +option add *Barchart.Grid.Color black +.CE +.RE +.TP +\fIpathName \fBgrid off\fR +Turns off the display the grid lines. +.TP +\fIpathName \fBgrid on\fR +Turns on the display the grid lines. +.TP +\fIpathName \fBgrid toggle\fR +Toggles the display of the grid. +.SS "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 positioned anywhere within the plotting area. +.PP +The following operations are valid for the legend. +.TP +\fIpathName \fBlegend activate \fIpattern\fR... +Selects legend entries to be drawn using the active legend colors and relief. +All entries whose element names match \fIpattern\fR are selected. To +be selected, the element name must match only one \fIpattern\fR. +.TP +\fIpathName \fBlegend bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for a legend entry with this +tag, \fIcommand\fR will be invoked. Implicitly the element names +in the entry are tags. The syntax is similar to the +\fBbind\fR command except that it operates on legend entries, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBlegend cget \fIoption\fR +Returns the current value of a legend configuration option. +\fIOption\fR may be any option described below in the +legend \fBconfigure\fR operation. +.TP +\fIpathName \fBlegend configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options for the legend. If +\fIoption\fR isn't specified, a list describing the current +legend options for \fIpathName\fR is returned. If \fIoption\fR is +specified, but not \fIvalue\fR, then a list describing \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the legend option \fIoption\fR is set +to \fIvalue\fR. The following options are valid for the legend. +.RS +.TP +\fB\-activebackground \fIcolor\fR +Sets the background color for active legend entries. All legend +entries marked active (see the legend \fBactivate\fR operation) are +drawn using this background color. +.TP +\fB\-activeborderwidth \fIpixels\fR +Sets the width of the 3-D border around the outside edge of the active legend +entries. The default is \f(CW2\fR. +.TP +\fB\-activeforeground \fIcolor\fR +Sets the foreground color for active legend entries. All legend +entries marked as active (see the legend \fBactivate\fR operation) are +drawn using this foreground color. +.TP +\fB\-activerelief \fIrelief\fR +Specifies the 3-D effect desired for active legend entries. +\fIRelief\fR denotes how the interior of the entry should appear +relative to the legend; for example, \f(CWraised\fR means the entry +should appear to protrude from the legend, relative to the surface of +the legend. The default is \f(CWflat\fR. +.TP +\fB\-anchor \fIanchor\fR +Tells how to position the legend relative to the positioning point for +the legend. This is dependent on the value of the \fB\-position\fR +option. The default is \f(CWcenter\fR. +.RS +.TP 1.25i +\f(CWleft\fR or \f(CWright\fR +The anchor describes how to position the legend vertically. +.TP +\f(CWtop\fR or \f(CWbottom\fR +The anchor describes how to position the legend horizontally. +.TP +\f(CW@x,y\fR +The anchor specifies how to position the legend relative to the +positioning point. For example, if \fIanchor\fR is \f(CWcenter\fR then +the legend is centered on the point; if \fIanchor\fR is \f(CWn\fR then +the legend will be drawn such that the top center point of the +rectangular region occupied by the legend will be at the positioning +point. +.TP +\f(CWplotarea\fR +The anchor specifies how to position the legend relative to the +plotting area. For example, if \fIanchor\fR is \f(CWcenter\fR then the +legend is centered in the plotting area; if \fIanchor\fR is \f(CWne\fR +then the legend will be drawn such that occupies the upper right +corner of the plotting area. +.RE +.TP +\fB\-background \fIcolor\fR +Sets the background color of the legend. If \fIcolor\fR is \f(CW""\fR, +the legend background with be transparent. +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for legend entries. \fITagList\fR is a list +of binding tag names. The tags and their order will determine how +events for legend entries. Each tag in the list matching the current +event sequence will have its Tcl command executed. The default value +is \f(CWall\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the width of the 3-D border around the outside edge of the legend (if +such border is being drawn; the \fBrelief\fR option determines this). +The default is \f(CW2\fR pixels. +.TP +\fB\-font \fIfontName\fR +\fIFontName\fR specifies a font to use when drawing the labels of each +element into the legend. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-12-120-*\fR. +.TP +\fB\-foreground \fIcolor\fR +Sets the foreground color of the text drawn for the element's label. +The default is \f(CWblack\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the legend should be displayed. If \fIboolean\fR is +true, the legend will not be draw. The default is \f(CWno\fR. +.TP +\fB\-ipadx \fIpad\fR +Sets the amount of internal padding to be added to the width of each +legend entry. \fIPad\fR can be a list of one or two screen distances. If +\fIpad\fR has two elements, the left side of the legend entry is +padded by the first distance and the right side by the second. If +\fIpad\fR is just one distance, both the left and right sides are padded +evenly. The default is \f(CW2\fR. +.TP +\fB\-ipady \fIpad\fR +Sets an amount of internal padding to be added to the height of each +legend entry. \fIPad\fR can be a list of one or two screen distances. If +\fIpad\fR has two elements, the top of the entry is padded by the +first distance and the bottom by the second. If \fIpad\fR is just +one distance, both the top and bottom of the entry are padded evenly. +The default is \f(CW2\fR. +.TP +\fB\-padx \fIpad\fR +Sets the padding to the left and right exteriors of the legend. +\fIPad\fR can be a list of one or two screen distances. If \fIpad\fR +has two elements, the left side of the legend is padded by the first +distance and the right side by the second. If \fIpad\fR has just one +distance, both the left and right sides are padded evenly. The +default is \f(CW4\fR. +.TP +\fB\-pady \fIpad\fR +Sets the padding above and below the legend. \fIPad\fR can be a list +of one or two screen distances. If \fIpad\fR has two elements, the area above +the legend is padded by the first distance and the area below by the +second. If \fIpad\fR is just one distance, both the top and +bottom areas are padded evenly. The default is \f(CW0\fR. +.TP +\fB\-position \fIpos\fR +Specifies where the legend is drawn. The +\fB\-anchor\fR option also affects where the legend is positioned. If +\fIpos\fR is \f(CWleft\fR, \f(CWleft\fR, \f(CWtop\fR, or \f(CWbottom\fR, the +legend is drawn in the specified margin. If \fIpos\fR is +\f(CWplotarea\fR, then the legend is drawn inside the plotting area at a +particular anchor. If \fIpos\fR is in the form "\fI@x,y\fR", where +\fIx\fR and \fIy\fR are the window coordinates, the legend is drawn in +the plotting area at the specified coordinates. The default is +\f(CWright\fR. +.TP +\fB\-raised \fIboolean\fR +Indicates whether the legend is above or below the data elements. This +matters only if the legend is in the plotting area. If \fIboolean\fR +is true, the legend will be drawn on top of any elements that may +overlap it. The default is \f(CWno\fR. +.TP +\fB\-relief \fIrelief\fR +Specifies the 3-D effect for the border around the legend. +\fIRelief\fR specifies how the interior of the legend should appear +relative to the bar chart; for example, \f(CWraised\fR means the legend +should appear to protrude from the bar chart, relative to the surface of +the bar chart. The default is \f(CWsunken\fR. +.PP +Legend configuration options may also be set by the \fBoption\fR +command. The resource name and class are \f(CWlegend\fR and +\f(CWLegend\fR respectively. +.CS +option add *Barchart.legend.Foreground blue +option add *Barchart.Legend.Relief raised +.CE +.RE +.TP +\fIpathName \fBlegend deactivate \fIpattern\fR... +Selects legend entries to be drawn using the normal legend colors and +relief. All entries whose element names match \fIpattern\fR are +selected. To be selected, the element name must match only one +\fIpattern\fR. +.TP +\fIpathName \fBlegend get \fIpos\fR +Returns the name of the element whose entry is at the screen position +\fIpos\fR in the legend. \fIPos\fR must be in the form "\fI@x,y\fR", +where \fIx\fR and \fIy\fR are window coordinates. If the given +coordinates do not lie over a legend entry, \f(CW""\fR is returned. +.SS "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 \fB\-weight\fR and +\fB\-style\fR options). +.PP +One pen, called \f(CWactiveBar\fR, 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. +.CS +\&.g pen configure "activeBar" -fg green -bg green4 +.CE +You can create and use several pens. To create a pen, invoke +the pen component and its create operation. +.CS +\&.g pen create myPen +.CE +You map pens to a data element using either the element's +\fB\-pen\fR or \fB\-activepen\fR options. +.CS +\&.g element create "e1" -xdata $x -ydata $tempData \\ + -pen myPen +.CE +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 +\fB\-styles\fR option). +.CS +\&.g element configure "e1" -styles { myPen 2.0 3.0 } +.CE +This says that any data point with a weight between 2.0 and 3.0 +is to be drawn using the pen \f(CWmyPen\fR. All other points +are drawn with the element's default attributes. +.PP +The following operations are available for pen components. +.PP +.TP +\fIpathName \fBpen \fBcget \fIpenName \fIoption\fR +Returns the current value of the option given by \fIoption\fR for +\fIpenName\fR. \fIOption\fR may be any option described below +for the pen \fBconfigure\fR operation. +.TP +\fIpathName \fBpen \fBconfigure \fIpenName \fR?\fIpenName\fR... ?\fIoption value\fR?... +Queries or modifies the configuration options of +\fIpenName\fR. Several pens can be modified at once. If \fIoption\fR +isn't specified, a list describing the current options for +\fIpenName\fR is returned. If \fIoption\fR is specified, but not +\fIvalue\fR, then a list describing \fIoption\fR is returned. If one +or more \fIoption\fR and \fIvalue\fR pairs are specified, then for +each pair, the pen option \fIoption\fR is set to \fIvalue\fR. The +following options are valid for pens. +.RS +.TP +\fB\-background \fIcolor\fR +Sets the the color of the border around each bar. The default is +\f(CWwhite\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the border width of the 3-D border drawn around the outside of +each bar. The \fB\-relief\fR option determines if such a border is +drawn. \fIPixels\fR must be a valid screen distance like \f(CW2\fR or +\f(CW0.25i\fR. The default is \f(CW2\fR. +.TP +\fB\-foreground \fIcolor\fR +Sets the color of the interior of the bars. +.TP +\fB\-relief \fIstring\fR +Specifies the 3-D effect desired for bars. \fIRelief\fR indicates how +the interior of the bar should appear relative to the surface of the +chart; for example, \f(CWraised\fR means the bar should appear to +protrude from the bar chart, relative to the surface of the plotting +area. The default is \f(CWraised\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies a stipple pattern with which to draw the bars. If +\fIbitmap\fR is \f(CW""\fR, then the bar is drawn in a solid fashion. +.TP +\fB\-type \fIelemType\fR +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". +.PP +Pen configuration options may be also be set by the \fBoption\fR +command. The resource class is \f(CWPen\fR. The resource names +are the names of the pens. +.CS +option add *Barchart.Pen.Foreground blue +option add *Barchart.activeBar.foreground green +.CE +.RE +.TP +\fIpathName \fBpen \fBcreate \fIpenName \fR?\fIoption value\fR?... +Creates a new pen by the name \fIpenName\fR. No pen by the same +name can already exist. \fIOption\fR and \fIvalue\fR are described +in above in the pen \fBconfigure\fR operation. +.TP +\fIpathName \fBpen \fBdelete \fR?\fIpenName\fR?... +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 elements. +.TP +\fIpathName \fBpen names \fR?\fIpattern\fR?... +Returns a list of pens matching zero or more patterns. If no +\fIpattern\fR argument is give, the names of all pens are returned. +.SS "POSTSCRIPT COMPONENT" +The barchart can generate encapsulated PostScript output. There +are several 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. +.PP +The following postscript operations are available. +.TP +\fIpathName \fBpostscript cget \fIoption\fR +Returns the current value of the postscript option given by +\fIoption\fR. \fIOption\fR may be any option described +below for the postscript \fBconfigure\fR operation. +.TP +\fIpathName \fBpostscript configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options for PostScript +generation. If \fIoption\fR isn't specified, a list describing +the current postscript options for \fIpathName\fR is returned. If +\fIoption\fR is specified, but not \fIvalue\fR, then a list describing +\fIoption\fR is returned. If one or more \fIoption\fR and \fIvalue\fR +pairs are specified, then for each pair, the postscript option +\fIoption\fR is set to \fIvalue\fR. The following postscript options +are available. +.RS +.TP +\fB\-center \fIboolean\fR +Indicates whether the plot should be centered on the PostScript page. If +\fIboolean\fR is false, the plot will be placed in the upper left +corner of the page. The default is \f(CW1\fR. +.TP +\fB\-colormap \fIvarName\fR +\fIVarName\fR must be the name of a global array variable that +specifies a color mapping from the X color name to PostScript. Each +element of \fIvarName\fR must consist of PostScript code to set a +particular color value (e.g. ``\f(CW1.0 1.0 0.0 setrgbcolor\fR''). When +generating color information in PostScript, the array variable \fIvarName\fR +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 \fIvarName\fR for a given color, then it uses +the red, green, and blue intensities from the X color. +.TP +\fB\-colormode \fImode\fR +Specifies how to output color information. \fIMode\fR must be either +\f(CWcolor\fR (for full color output), \f(CWgray\fR (convert all colors to +their gray-scale equivalents) or \f(CWmono\fR (convert foreground colors +to black and background colors to white). The default mode is +\f(CWcolor\fR. +.TP +\fB\-fontmap \fIvarName\fR +\fIVarName\fR must be the name of a global array variable that +specifies a font mapping from the X font name to PostScript. Each +element of \fIvarName\fR 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 \fIvarName\fR 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). Otherwise the X font is examined in an +attempt to guess what PostScript font to use. This works only for +fonts whose foundry property is \fIAdobe\fR (such as Times, Helvetica, +Courier, etc.). If all of this fails then the font defaults to +\f(CWHelvetica-Bold\fR. +.TP +\fB\-decorations \fIboolean\fR +Indicates whether PostScript commands to generate color backgrounds and 3-D +borders will be output. If \fIboolean\fR is false, the graph will +background will be white and no 3-D borders will be generated. The +default is \f(CW1\fR. +.TP +\fB\-height \fIpixels\fR +Sets the height of the plot. This lets you print the bar chart with a +height different from the one drawn on the screen. If +\fIpixels\fR is 0, the height is the same as the widget's height. +The default is \f(CW0\fR. +.TP +\fB\-landscape \fIboolean\fR +If \fIboolean\fR 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 (``landscape'' orientation). Defaults to +\f(CW0\fR. +.TP +\fB\-maxpect \fIboolean\fR +Indicates to scale the plot so that it fills the PostScript page. +The aspect ratio of the barchart is still retained. The default is +\f(CW0\fR. +.TP +\fB\-padx \fIpad\fR +Sets the horizontal padding for the left and right page borders. The +borders are exterior to the plot. \fIPad\fR can be a list of one or +two screen distances. If \fIpad\fR has two elements, the left border is padded +by the first distance and the right border by the second. If +\fIpad\fR has just one distance, both the left and right borders are +padded evenly. The default is \f(CW1i\fR. +.TP +\fB\-pady \fIpad\fR +Sets the vertical padding for the top and bottom page borders. The +borders are exterior to the plot. \fIPad\fR can be a list of one or +two screen distances. If \fIpad\fR has two elements, the top border is padded +by the first distance and the bottom border by the second. If +\fIpad\fR has just one distance, both the top and bottom borders are +padded evenly. The default is \f(CW1i\fR. +.TP +\fB\-paperheight \fIpixels\fR +Sets the height of the postscript page. This can be used to select +between different page sizes (letter, A4, etc). The default height is +\f(CW11.0i\fR. +.TP +\fB\-paperwidth \fIpixels\fR +Sets the width of the postscript page. This can be used to select +between different page sizes (letter, A4, etc). The default width is +\f(CW8.5i\fR. +.TP +\fB\-width \fIpixels\fR +Sets the width of the plot. This lets you generate a plot +of a width different from that of the widget. If \fIpixels\fR +is 0, the width is the same as the widget's width. The default is +\f(CW0\fR. +.PP +Postscript configuration options may be also be set by the +\fBoption\fR command. The resource name and class are +\f(CWpostscript\fR and \f(CWPostscript\fR respectively. +.CS +option add *Barchart.postscript.Decorations false +option add *Barchart.Postscript.Landscape true +.CE +.RE +.TP +\fIpathName \fBpostscript output \fR?\fIfileName\fR? ?\fIoption value\fR?... +Outputs a file of encapsulated PostScript. If a +\fIfileName\fR argument isn't present, the command returns the +PostScript. If any \fIoption-value\fR pairs are present, they set +configuration options controlling how the PostScript is generated. +\fIOption\fR and \fIvalue\fR can be anything accepted by the +postscript \fBconfigure\fR operation above. +.SS "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 \fB\-under\fR +option. +.PP +Markers, in contrast to elements, don't affect the scaling of the +coordinate axes. They can also have \fIelastic\fR coordinates +(specified by \f(CW-Inf\fR and \f(CWInf\fR 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 \f(CW-Inf\fR,\f(CW-Inf\fR. +.PP +The following operations are available for markers. +.TP +\fIpathName \fBmarker after \fImarkerId\fR ?\fIafterId\fR? +Changes the order of the markers, drawing the first +marker after the second. If no second \fIafterId\fR 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. +.TP +\fIpathName \fBmarker before \fImarkerId\fR ?\fIbeforeId\fR? +Changes the order of the markers, drawing the first +marker before the second. If no second \fIbeforeId\fR 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. +.TP +\fIpathName \fBmarker bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for a marker with this +tag, \fIcommand\fR will be invoked. The syntax is similar to the +\fBbind\fR command except that it operates on graph markers, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBmarker cget \fIoption\fR +Returns the current value of the marker configuration option given by +\fIoption\fR. \fIOption\fR may be any option described +below in the \fBconfigure\fR operation. +.TP +\fIpathName \fBmarker configure \fImarkerId\fR ?\fIoption value\fR?... +Queries or modifies the configuration options for markers. If +\fIoption\fR isn't specified, a list describing the current +options for \fImarkerId\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the marker option \fIoption\fR is set to \fIvalue\fR. +.sp +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. +.RS +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for the marker. \fITagList\fR 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 \f(CWall\fR. +.TP +\fB\-coords \fIcoordList\fR +Specifies the coordinates of the marker. \fICoordList\fR 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 \fIcoordList\fR is \f(CW""\fR, the marker will not be displayed. +The default is \f(CW""\fR. +.TP +\fB\-element \fIelemName\fR +Links the marker with the element \fIelemName\fR. The marker is +drawn only if the element is also currently displayed (see the +element's \fBshow\fR operation). If \fIelemName\fR is \f(CW""\fR, the +marker is always drawn. The default is \f(CW""\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the marker is drawn. If \fIboolean\fR is true, +the marker is not drawn. The default is \f(CWno\fR. +.TP +\fB\-mapx \fIxAxis\fR +Specifies the X\-axis to map the marker's X\-coordinates onto. +\fIXAxis\fR must the name of an axis. The default is \f(CWx\fR. +.TP +\fB\-mapy \fIyAxis\fR +Specifies the Y\-axis to map the marker's Y\-coordinates onto. +\fIYAxis\fR must the name of an axis. The default is \f(CWy\fR. +.TP +\fB\-name \fImarkerId\fR +Changes the identifier for the marker. The identifier \fImarkerId\fR +can not already be used by another marker. If this option +isn't specified, the marker's name is uniquely generated. +.TP +\fB\-under \fIboolean\fR +Indicates whether the marker is drawn below/above data +elements. If \fIboolean\fR is true, the marker is be drawn +underneath the data elements. Otherwise, the marker is +drawn on top of the element. The default is \f(CW0\fR. +.TP +\fB\-xoffset \fIpixels\fR +Specifies a screen distance to offset the marker horizontally. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +The default is \f(CW0\fR. +.TP +\fB\-yoffset \fIpixels\fR +Specifies a screen distance to offset the markers vertically. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +The default is \f(CW0\fR. +.PP +Marker configuration options may also be set by the \fBoption\fR command. +The resource class is either \f(CWBitmapMarker\fR, \f(CWImageMarker\fR, +\f(CWLineMarker\fR, \f(CWPolygonMarker\fR, \f(CWTextMarker\fR, or \f(CWWindowMarker\fR, +depending on the type of marker. The resource name is the name of the +marker. +.CS +option add *Barchart.TextMarker.Foreground white +option add *Barchart.BitmapMarker.Foreground white +option add *Barchart.m1.Background blue +.CE +.RE +.TP +\fIpathName \fBmarker create \fItype\fR ?\fIoption value\fR?... +Creates a marker of the selected type. \fIType\fR may be either +\f(CWtext\fR, \f(CWline\fR, \f(CWbitmap\fR, \f(CWimage\fR, \f(CWpolygon\fR, or +\f(CWwindow\fR. This command returns the marker identifier, +used as the \fImarkerId\fR argument in the other marker-related +commands. If the \fB\-name\fR option is used, this overrides the +normal marker identifier. If the name provided is already used for +another marker, the new marker will replace the old. +.TP +\fIpathName \fBmarker delete\fR ?\fIname\fR?... +Removes one of more markers. The graph will automatically be redrawn +without the marker.\fR. +.TP +\fIpathName \fBmarker exists \fImarkerId\fR +Returns \f(CW1\fR if the marker \fImarkerId\fR exists and \f(CW0\fR +otherwise. +.TP +\fIpathName \fBmarker names\fR ?\fIpattern\fR? +Returns the names of all the markers that currently exist. If +\fIpattern\fR is supplied, only those markers whose names match it +will be returned. +.TP +\fIpathName \fBmarker type \fImarkerId\fR +Returns the type of the marker given by \fImarkerId\fR, such as +\f(CWline\fR or \f(CWtext\fR. If \fImarkerId\fR is not a valid a marker +identifier, \f(CW""\fR is returned. +.SS "BITMAP MARKERS" +A bitmap marker displays a bitmap. The size of the +bitmap is controlled 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 bitmap. The bitmap will be stretched or reduced as +necessary to fit into the bounding rectangle. +.PP +Bitmap markers are created with the marker's \fBcreate\fR operation in +the form: +.DS +\fIpathName \fBmarker create bitmap \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR pairs, each +sets a configuration options for the marker. These +same \fIoption\fR\-\fIvalue\fR pairs may be used with the marker's +\fBconfigure\fR operation. +.PP +The following options are specific to bitmap markers: +.TP +\fB\-background \fIcolor\fR +Same as the \fB\-fill\fR option. +.TP +\fB\-bitmap \fIbitmap\fR +Specifies the bitmap to be displayed. If \fIbitmap\fR is \f(CW""\fR, +the marker will not be displayed. The default is \f(CW""\fR. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the bitmap. If \fIcolor\fR is the empty +string, no background will be transparent. The default background color is +\f(CW""\fR. +.TP +\fB\-foreground \fIcolor\fR +Same as the \fB\-outline\fR option. +.TP +\fB\-mask \fImask\fR +Specifies a mask for the bitmap to be displayed. This mask is a bitmap +itself, denoting the pixels that are transparent. If \fImask\fR is +\f(CW""\fR, all pixels of the bitmap will be drawn. The default is +\f(CW""\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the foreground color of the bitmap. The default value is \f(CWblack\fR. +.TP +\fB\-rotate \fItheta\fR +Sets the rotation of the bitmap. \fITheta\fR is a real number +representing the angle of rotation in degrees. The marker is first +rotated and then placed according to its anchor position. The default +rotation is \f(CW0.0\fR. +.SS "IMAGE MARKERS" +A image marker displays an image. Image markers are +created with the marker's \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create image \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR operation. +.PP +The following options are specific to image markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the image relative to the +positioning point for the image. For example, if \fIanchor\fR +is \f(CWcenter\fR then the image is centered on the point; if +\fIanchor\fR is \f(CWn\fR then the image will be drawn such that +the top center point of the rectangular region occupied by the +image will be at the positioning point. +This option defaults to \f(CWcenter\fR. +.TP +\fB\-image \fIimage\fR +Specifies the image to be drawn. +If \fIimage\fR is \f(CW""\fR, the marker will not be +drawn. The default is \f(CW""\fR. +.SS "LINE MARKERS" +A line marker displays one or more connected line segments. +Line markers are created with marker's \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create line \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR operation. +.PP +The following options are specific to line markers: +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the line. \fIDashList\fR 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 +\fIdashList\fR is \f(CW""\fR, the marker line will be solid. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the line. This color is used with +striped lines (see the \fB\-dashes\fR option). If \fIcolor\fR is +the empty string, no background color is drawn (the line will be +dashed, not striped). The default background color is \f(CW""\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the lines. +The default width is \f(CW0\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the foreground color of the line. The default value is \f(CWblack\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies a stipple pattern used to draw the line, rather than +a solid line. +\fIBitmap\fR specifies a bitmap to use as the stipple +pattern. If \fIbitmap\fR is \f(CW""\fR, then the +line is drawn in a solid fashion. The default is \f(CW""\fR. +.SS "POLYGON MARKERS" +A polygon marker displays a closed region described as two or more +connected line segments. It is assumed the first and +last points are connected. Polygon markers are created using the +marker \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create polygon \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the \fBmarker configure\fR command to change the marker's +configuration. +The following options are supported for polygon markers: +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the outline of the polygon. \fIDashList\fR 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 \fIdashList\fR is \f(CW""\fR, the outline will be a solid line. +.TP +\fB\-fill \fIcolor\fR +Sets the fill color of the polygon. If \fIcolor\fR is \f(CW""\fR, then +the interior of the polygon is transparent. +The default is \f(CWwhite\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the outline of the polygon. If \fIpixels\fR is zero, +no outline is drawn. The default is \f(CW0\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the color of the outline of the polygon. If the polygon is +stippled (see the \fB\-stipple\fR option), then this represents the +foreground color of the stipple. The default is \f(CWblack\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies that the polygon should be drawn with a stippled pattern +rather than a solid color. \fIBitmap\fR specifies a bitmap to use as +the stipple pattern. If \fIbitmap\fR is \f(CW""\fR, then the polygon is +filled with a solid color (if the \fB\-fill\fR option is set). The +default is \f(CW""\fR. +.SS "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 +annotate regions of the graph. Text markers are created with the +\fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create text \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR pairs, +each sets a configuration option for the text marker. +These same \fIoption\fR\-\fIvalue\fR pairs may be used with the +marker's \fBconfigure\fR operation. +.PP +The following options are specific to text markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the text relative to the +positioning point for the text. For example, if \fIanchor\fR is +\f(CWcenter\fR then the text is centered on the point; if +\fIanchor\fR is \f(CWn\fR 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 \f(CWcenter\fR. +.TP +\fB\-background \fIcolor\fR +Same as the \fB\-fill\fR option. +.TP +\fB\-font \fIfontName\fR +Specifies the font of the text. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-120-*\fR. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the text. If \fIcolor\fR is the empty +string, no background will be transparent. The default background color is +\f(CW""\fR. +.TP +\fB\-foreground \fIcolor\fR +Same as the \fB\-outline\fR option. +.TP +\fB\-justify \fIjustify\fR +Specifies how the text should be justified. This matters only when +the marker contains more than one line of text. \fIJustify\fR must be +\f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the color of the text. The default value is \f(CWblack\fR. +.TP +\fB\-padx \fIpad\fR +Sets the padding to the left and right exteriors of the text. +\fIPad\fR can be a list of one or two screen distances. If \fIpad\fR +has two elements, the left side of the text is padded by the first +distance and the right side by the second. If \fIpad\fR has just one +distance, both the left and right sides are padded evenly. The +default is \f(CW4\fR. +.TP +\fB\-pady \fIpad\fR +Sets the padding above and below the text. \fIPad\fR can be a list of +one or two screen distances. If \fIpad\fR has two elements, the area above the +text is padded by the first distance and the area below by the second. +If \fIpad\fR is just one distance, both the top and bottom areas +are padded evenly. The default is \f(CW4\fR. +.TP +\fB\-rotate \fItheta\fR +Specifies the number of degrees to rotate the text. \fITheta\fR 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 \f(CW0.0\fR. +.TP +\fB\-text \fItext\fR +Specifies the text of the marker. The exact way the text is +displayed may be affected by other options such as \fB\-anchor\fR or +\fB\-rotate\fR. +.SS "WINDOW MARKERS" +A window marker displays a widget at a given position. +Window markers are created with the marker's \fBcreate\fR operation in +the form: +.DS +\fIpathName \fBmarker create window \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR command. +.PP +The following options are specific to window markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the widget relative to the +positioning point for the widget. For example, if \fIanchor\fR is +\f(CWcenter\fR then the widget is centered on the point; if \fIanchor\fR +is \f(CWn\fR 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 \f(CWcenter\fR. +.TP +\fB\-height \fIpixels\fR +Specifies the height to assign to the marker's window. If this option +isn't specified, or if it is specified as \f(CW""\fR, then the window is +given whatever height the widget requests internally. +.TP +\fB\-width \fIpixels\fR +Specifies the width to assign to the marker's window. If this option +isn't specified, or if it is specified as \f(CW""\fR, then the window is +given whatever width the widget requests internally. +.TP +\fB\-window \fIpathName\fR +Specifies the widget to be managed by the barchart. \fIPathName\fR must +be a child of the \fBbarchart\fR widget. +.SH "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 \fBEnter\fR, \fBLeave\fR, +\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR). +.PP +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 commands +will be invoked if both items are picked. +.PP +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 \fB\-bindtags\fR 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 command. +.PP +The \fB\-bindtags\fR 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 \fB\-bindtags\fR option doesn't change this. +.SH "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 format. +.PP +Data can manipulated from the C language using BLT vectors. +You specify 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. +.PP +From Tcl, create the vectors and configure the element to use them. +.CS +vector X Y +\&.g element configure line1 -xdata X -ydata Y +.CE +To set data points from C, you pass the values as arrays of doubles +using the \fBBlt_ResetVector\fR 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. +.CS +#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", 50, &xVec) != TCL_OK) || + (Blt_GetVector(interp, "Y", 50, &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; +} +.CE +See the \fBvector\fR manual page for more details. +.SH SPEED TIPS +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. +.TP 2 +\(bu +Try to minimize the number of data points. The more data points +looked at, the more work the bar chart must do. +.TP 2 +\(bu +If your data is generated as floating point values, the time required +to convert the data values to and from ASCII strings can be +significant, especially when there any many data points. You can +avoid the redundant string-to-decimal conversions using the C API to +BLT vectors. +.TP 2 +\(bu +Don't stipple or dash the element. Solid bars are much faster. +.TP 2 +\(bu +If you update data elements frequently, try turning off the +widget's \fB\-bufferelements\fR 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 +simply 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. +.SH LIMITATIONS +Auto-scale routines do not use requested min/max limits +as boundaries when the axis is logarithmically scaled. +.PP +The PostScript output generated for polygons with more than 1500 +points may exceed the limits of some printers (See PostScript Language +Reference Manual, page 568). The work-around is to break the polygon +into separate pieces. +.SH KEYWORDS +bar chart, widget diff --git a/doc/graph.html b/doc/graph.html new file mode 100644 index 0000000..70f1e6f --- /dev/null +++ b/doc/graph.html @@ -0,0 +1,1759 @@ +<HTML> +<BODY> +<PRE> +<!-- Manpage converted by man2html 3.0.1 --> + +</PRE> +<H2>SYNOPSIS</H2><PRE> + <B>graph</B> <I>pathName</I> ?<I>option</I> <I>value</I>?... + + +</PRE> +<H2>DESCRIPTION</H2><PRE> + The <B>graph</B> 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. + + +</PRE> +<H2>INTRODUCTION</H2><PRE> + The <B>graph</B> 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 <I>plotting</I> <I>area</I>. + 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 <B>graph</B> 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. + + <B>graph</B> <I>pathName</I> ?<I>option</I> <I>value</I>?... The <B>graph</B> command creates a new win- + dow <I>pathName</I> and makes it into a <B>graph</B> widget. At the time this com- + mand is invoked, there must not exist a window named <I>pathName</I>, but + <I>pathName</I>'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 <B>configure</B> operation below + for the exact details about what <I>option</I> and <I>value</I> pairs are valid. + + If successful, <B>graph</B> 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: <I>pathName</I> <I>operation</I> ?<I>arg</I>?... Both <I>operation</I> and its arguments + determine the exact behavior of the command. The operations available + for the graph are described in the <B>GRAPH</B> <B>OPERATIONS</B> section. + + The command can also be used to access components of the graph. <I>path-</I> + <I>Name</I> <I>component</I> <I>operation</I> ?<I>arg</I>?... 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. + + +</PRE> +<H2>EXAMPLE</H2><PRE> + The <B>graph</B> 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 <B>configure</B> 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 <B>element</B> 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 <B>yVector(0)</B> 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 <B>show</B> + 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 <B>axis</B> 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 <B>-min</B> and <B>-max</B> 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 <B>axis</B> <B>configure</B> operations with some + user interaction (such as pressing the mouse button), using the <B>bind</B> + command. To convert between screen and graph coordinates, use the + <B>invtransform</B> 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 <B>-min</B> and <B>-max</B> 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 <B>legend</B> 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 <B>-hide</B> option. # Don't display the legend. .g + legend configure -hide yes The <B>graph</B> 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 <B>marker</B> 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 <B>-anchor</B>, <B>-xoffset</B>, and <B>-yoffset</B> 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 <B>-under</B> + 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 <B>crosshairs</B> and <B>grid</B> 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 <B>postscript</B> 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 <B>-maxpect</B> says to + scale the plot to the size of the page. Turning off the <B>-decorations</B> + option denotes that no borders or color backgrounds should be drawn + <I>option</I>. <I>Option</I> may be any option described below for the <B>con-</B> + <B>figure</B> operation. + + <I>pathName</I> <B>configure</B> ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options of the graph. If + <I>option</I> isn't specified, a list describing the current options + for <I>pathName</I> is returned. If <I>option</I> is specified, but not + <I>value</I>, then a list describing <I>option</I> is returned. If one or + more <I>option</I> and <I>value</I> pairs are specified, then for each pair, + the option <I>option</I> is set to <I>value</I>. The following options are + valid. + + <B>-aspect</B> <I>width/height</I> + Force a fixed aspect ratio of <I>width/height</I>, a floating + point number. + + <B>-background</B> <I>color</I> + Sets the background color. This includes the margins and + legend, but not the plotting area. + + <B>-borderwidth</B> <I>pixels</I> + Sets the width of the 3-D border around the outside edge + of the widget. The <B>-relief</B> option determines if the bor- + der is to be drawn. The default is 2. + + <B>-bottommargin</B> <I>pixels</I> + If non-zero, overrides the computed size of the margin + extending below the X-coordinate axis. If <I>pixels</I> is 0, + the automatically computed size is used. The default is + 0. + + <B>-bufferelements</B> <I>boolean</I> + Indicates whether an internal pixmap to buffer the dis- + play of data elements should be used. If <I>boolean</I> 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 <B>SPEED</B> + <B>TIPS</B> section. The default is 1. + + <B>-cursor</B> <I>cursor</I> + Specifies the widget's cursor. The default cursor is + crosshair. + + <B>-font</B> <I>fontName</I> + Specifies the font of the graph title. The default is + *-Helvetica-Bold-R-Normal-*-18-180-*. + + <B>-halo</B> <I>pixels</I> + Specifies a maximum distance to consider when searching + for the closest data point (see the element's <B>closest</B> + operation below). Data points further than <I>pixels</I> away + text. <I>Justify</I> must be left, right, or center. The + default is center. + + <B>-leftmargin</B> <I>pixels</I> + 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 <I>pixels</I> is 0, the automatically computed + size is used. The default is 0. + + <B>-plotbackground</B> <I>color</I> + Specifies the background color of the plotting area. The + default is white. + + <B>-plotborderwidth</B> <I>pixels</I> + Sets the width of the 3-D border around the plotting + area. The <B>-plotrelief</B> option determines if a border is + drawn. The default is 2. + + <B>-plotpadx</B> <I>pad</I> + Sets the amount of padding to be added to the left and + right sides of the plotting area. <I>Pad</I> can be a list of + one or two screen distances. If <I>pad</I> 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 <I>pad</I> + is just one distance, both the left and right sides are + padded evenly. The default is 8. + + <B>-plotpady</B> <I>pad</I> + Sets the amount of padding to be added to the top and + bottom of the plotting area. <I>Pad</I> can be a list of one or + two screen distances. If <I>pad</I> has two elements, the top + of the plotting area is padded by the first distance and + the bottom by the second. If <I>pad</I> is just one distance, + both the top and bottom are padded evenly. The default + is 8. + + <B>-plotrelief</B> <I>relief</I> + Specifies the 3-D effect for the plotting area. <I>Relief</I> + 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. + + <B>-relief</B> <I>relief</I> + Specifies the 3-D effect for the graph widget. <I>Relief</I> + 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. + + <B>-rightmargin</B> <I>pixels</I> + If non-zero, overrides the computed size of the margin + + <B>-tile</B> <I>image</I> + Specifies a tiled background for the widget. If <I>image</I> + isn't "", the background is tiled using <I>image</I>. Other- + wise, the normal background color is drawn (see the + <B>-background</B> option). <I>Image</I> must be an image created + using the Tk <B>image</B> command. The default is "". + + <B>-title</B> <I>text</I> + Sets the title to <I>text</I>. If <I>text</I> is "", no title will be + displayed. + + <B>-topmargin</B> <I>pixels</I> + If non-zero, overrides the computed size of the margin + above the x2 axis. If <I>pixels</I> is 0, the automatically + computed size is used. The default is 0. + + <B>-width</B> <I>pixels</I> + Specifies the requested width of the widget. The default + is 5i. + + <I>pathName</I> <B>crosshairs</B> <I>operation</I> ?<I>arg</I>? + See the <B>CROSSHAIRS</B> <B>COMPONENT</B> section. + + <I>pathName</I> <B>element</B> <I>operation</I> ?<I>arg</I>?... + See the <B>ELEMENT</B> <B>COMPONENTS</B> section. + + <I>pathName</I> <B>extents</B> <I>item</I> + Returns the size of a particular item in the graph. <I>Item</I> must + be either leftmargin, rightmargin, topmargin, bottommargin, + plotwidth, or plotheight. + + <I>pathName</I> <B>grid</B> <I>operation</I> ?<I>arg</I>?... + See the <B>GRID</B> <B>COMPONENT</B> section. + + <I>pathName</I> <B>invtransform</B> <I>winX</I> <I>winY</I> + 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. + + <I>pathName</I> <B>inside</B> <I>x</I> <I>y</I> + Returns 1 is the designated screen coordinate (<I>x</I> and <I>y</I>) is + inside the plotting area and 0 otherwise. + + <I>pathName</I> <B>legend</B> <I>operation</I> ?<I>arg</I>?... + See the <B>LEGEND</B> <B>COMPONENT</B> section. + + <I>pathName</I> <B>line</B> <B>operation</B> <B>arg</B>... + The operation is the same as <B>element</B>. + + <I>pathName</I> <B>marker</B> <I>operation</I> ?<I>arg</I>?... + photo Saves a Tk photo image. <I>OutputName</I> represents + the name of a Tk photo image that must already + have been created. + + wmf Saves an Aldus Placeable Metafile. <I>OutputName</I> + represents the filename where the metafile is + written. If <I>outputName</I> 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. <I>OutputName</I> repre- + sents the filename where the metafile is writ- + ten. If <I>outputName</I> is CLIPBOARD, then output + is written directly to the Windows clipboard. + This format is available only under Microsoft + Windows. + + <B>-height</B> <I>size</I> + Specifies the height of the graph. <I>Size</I> is a screen + distance. The graph will be redrawn using this dimen- + sion, rather than its current window height. + + <B>-width</B> <I>size</I> + Specifies the width of the graph. <I>Size</I> is a screen + distance. The graph will be redrawn using this dimen- + sion, rather than its current window width. + + <I>pathName</I> <B>transform</B> <I>x</I> <I>y</I> + 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. + + <I>pathName</I> <B>xaxis</B> <I>operation</I> ?<I>arg</I>?... + + <I>pathName</I> <B>x2axis</B> <I>operation</I> ?<I>arg</I>?... + + <I>pathName</I> <B>yaxis</B> <I>operation</I> ?<I>arg</I>?... + + <I>pathName</I> <B>y2axis</B> <I>operation</I> ?<I>arg</I>?... + See the <B>AXIS</B> <B>COMPONENTS</B> section. + + +</PRE> +<H2>GRAPH COMPONENTS</H2><PRE> + 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. + + <B>AXIS</B> <B>COMPONENTS</B> + 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: <B>xaxis</B>, <B>yaxis</B>, <B>x2axis</B>, and <B>y2axis</B>. Each com- + ponent has a <B>use</B> operation that designates the axis (or axes) to be + drawn in that corresponding margin: <B>xaxis</B> in the bottom, <B>yaxis</B> in the + left, <B>x2axis</B> in the top, and <B>y2axis</B> in the right. # Display the axis + tempAxis in the left margin. .g yaxis use tempAxis The <B>use</B> 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. + + + <I>pathName</I> <B>axis</B> <B>bind</B> <I>tagName</I> ?<I>sequence</I>? ?<I>command</I>? + Associates <I>command</I> with <I>tagName</I> such that whenever the event + sequence given by <I>sequence</I> occurs for an axis with this tag, + <I>command</I> will be invoked. The syntax is similar to the <B>bind</B> com- + mand except that it operates on graph axes, rather than widgets. + See the <B>bind</B> manual entry for complete details on <I>sequence</I> and + the substitutions performed on <I>command</I> before invoking it. + + If all arguments are specified then a new binding is created, + replacing any existing binding for the same <I>sequence</I> and <I>tag-</I> + <I>Name</I>. If the first character of <I>command</I> is + then <I>command</I> aug- + ments an existing binding rather than replacing it. If no <I>com-</I> + <I>mand</I> argument is provided then the command currently associated + with <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no + such binding) is returned. If both <I>command</I> and <I>sequence</I> are + missing then a list of all the event sequences for which bind- + ings have been defined for <I>tagName</I>. + + <I>pathName</I> <B>axis</B> <B>cget</B> <I>axisName</I> <I>option</I> + Returns the current value of the option given by <I>option</I> for + <I>axisName</I>. <I>Option</I> may be any option described below for the axis + <B>configure</B> 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. + + <B>-color</B> <I>color</I> + Sets the color of the axis and tick labels. The default + is black. + + <B>-descending</B> <I>boolean</I> + Indicates whether the values along the axis are monotoni- + cally increasing or decreasing. If <I>boolean</I> is true, the + axis values will be decreasing. The default is 0. + + <B>-hide</B> <I>boolean</I> + Indicates if the axis is displayed. If <I>boolean</I> is false + the axis will be displayed. Any element mapped to the + axis is displayed regardless. The default value is 0. + + <B>-justify</B> <I>justify</I> + Specifies how the axis title should be justified. This + matters only when the axis title contains more than one + line of text. <I>Justify</I> must be left, right, or center. + The default is center. + + <B>-limits</B> <I>formatStr</I> + 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. <I>FormatStr</I> 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 <I>boolean</I> is true, the axis range is + "loose". The default is 0. + + <B>-majorticks</B> <I>majorList</I> + Specifies where to display major axis ticks. You can use + this option to display ticks at non-uniform intervals. + <I>MajorList</I> is a list of axis coordinates designating the + location of major ticks. No minor ticks are drawn. If + <I>majorList</I> is "", major ticks will be automatically com- + puted. The default is "". + + <B>-max</B> <I>value</I> + Sets the maximum limit of <I>axisName</I>. Any data point + greater than <I>value</I> is not displayed. If <I>value</I> is "", the + maximum limit is calculated using the largest data value. + The default is "". + + <B>-min</B> <I>value</I> + Sets the minimum limit of <I>axisName</I>. Any data point less + than <I>value</I> is not displayed. If <I>value</I> is "", the minimum + limit is calculated using the smallest data value. The + default is "". + + <B>-minorticks</B> <I>minorList</I> + Specifies where to display minor axis ticks. You can use + this option to display minor ticks at non-uniform inter- + vals. <I>MinorList</I> 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 <B>-majortick</B> option is also + set. If <I>minorList</I> is "", minor ticks will be automati- + cally computed. The default is "". + + <B>-rotate</B> <I>theta</I> + Specifies the how many degrees to rotate the axis tick + labels. <I>Theta</I> is a real value representing the number of + degrees to rotate the tick labels. The default is 0.0 + degrees. + + <B>-scrollcommand</B> <I>command</I> + Specify the prefix for a command used to communicate with + scrollbars for this axis, such as <I>.sbar</I> <I>set</I>. + + <B>-scrollmax</B> <I>value</I> + Sets the maximum limit of the axis scroll region. If + <I>value</I> is "", the maximum limit is calculated using the + largest data value. The default is "". + + <B>-scrollmin</B> <I>value</I> + Sets the minimum limit of axis scroll region. If <I>value</I> + is "", the minimum limit is calculated using the smallest + Indicates how many minor axis ticks are to be drawn. For + example, if <I>number</I> is two, only one minor tick is drawn. + If <I>number</I> is one, no minor ticks are displayed. The + default is 2. + + <B>-tickfont</B> <I>fontName</I> + Specifies the font for axis tick labels. The default is + *-Courier-Bold-R-Normal-*-100-*. + + <B>-tickformat</B> <I>formatStr</I> + Specifies a printf-like description to format teh axis + tick labels. You can get the standard tick labels again by + setting <I>formatStr</I> to "". The default is "". + + <B>-tickformatcommand</B>, <B>-command</B> <I>prefix</I> + Specifies a Tcl command to be invoked when formatting the + axis tick labels. <I>Prefix</I> 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 <I>prefix</I> to "". The default is "". + + The numeric value for the tick might change when using the + <B>-logscale</B> and <B>-tickformat</B> options. + + 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. + + <B>-ticklength</B> <I>pixels</I> + Sets the length of major and minor ticks (minor ticks are + half the length of major ticks). If <I>pixels</I> is less than + zero, the axis will be inverted with ticks drawn pointing + towards the plot. The default is 0.1i. + + <B>-title</B> <I>text</I> + Sets the title of the axis. If <I>text</I> is "", no axis title + will be displayed. + + <B>-titlealternate</B> <I>boolean</I> + 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. + + <B>-titlecolor</B> <I>color</I> + Sets the color of the axis title. The default is black. + + <B>-titlefont</B> <I>fontName</I> + 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 <B>option</B> 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 + + <I>pathName</I> <B>axis</B> <B>create</B> <I>axisName</I> ?<I>option</I> <I>value</I>?... + Creates a new axis by the name <I>axisName</I>. No axis by the same + name can already exist. <I>Option</I> and <I>value</I> are described in above + in the axis <B>configure</B> operation. + + <I>pathName</I> <B>axis</B> <B>delete</B> ?<I>axisName</I>?... + 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. + + <I>pathName</I> <B>axis</B> <B>invtransform</B> <I>axisName</I> <I>value</I> + Performs the inverse transformation, changing the screen coordi- + nate <I>value</I> to a graph coordinate, mapping the value mapped to + + <I>pathName</I> <B>axis</B> <B>view</B> <I>axisName</I> + Change the viewable area of this axis. Use as an argument to a + scrollbar's "<I>-command</I>". + + 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 + <B>use</B> operation of the special axis components: <B>xaxis</B>, <B>x2axis</B>, <B>yaxis</B>, and + <B>y2axis</B>. .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 <B>xaxis</B>, <B>x2axis</B>, <B>yaxis</B>, and <B>y2axis</B> components operate on an axis + location rather than a specific axis like the more general <B>axis</B> compo- + nent does. They implicitly control the axis that is currently using to + that location. By default, <B>xaxis</B> uses the x axis, <B>yaxis</B> uses y, <B>x2axis</B> + uses x2, and <B>y2axis</B> 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 <B>axis</B> component. The <I>axis</I> argument must be <B>xaxis</B>, + <B>x2axis</B>, <B>yaxis</B>, or <B>y2axis</B>. This feature is deprecated since more than + one axis can now be used a margin. You should only use the <B>xaxis</B>, + <B>x2axis</B>, <B>yaxis</B>, and <B>y2axis</B> components with the <B>use</B> operation. For all + other operations, use the general <B>axis</B> component instead. + + <I>pathName</I> <I>axis</I> <B>cget</B> <I>option</I> + + <I>pathName</I> <I>axis</I> <B>configure</B> ?<I>option</I> <I>value</I>?... + + <I>pathName</I> <I>axis</I> <B>invtransform</B> <I>value</I> + + <I>pathName</I> <I>axis</I> <B>limits</B> + + <I>pathName</I> <I>axis</I> <B>transform</B> <I>value</I> + + <I>pathName</I> <I>axis</I> <B>use</B> ?<I>axisName</I>? + Designates the axis <I>axisName</I> is to be displayed at this loca- + tion. <I>AxisName</I> can not be already in use at another location. + This command returns the name of the axis currently using this + location. + + <B>CROSSHAIRS</B> <B>COMPONENT</B> + 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: + + <B>-color</B> <I>color</I> + Sets the color of the cross hairs. The default is black. + + <B>-dashes</B> <I>dashList</I> + Sets the dash style of the cross hairs. <I>DashList</I> 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 <I>dashList</I> is + "", the cross hairs will be solid lines. + + <B>-hide</B> <I>boolean</I> + Indicates whether cross hairs are drawn. If <I>boolean</I> is + true, cross hairs are not drawn. The default is yes. + + <B>-linewidth</B> <I>pixels</I> + Set the width of the cross hair lines. The default is 1. + + <B>-position</B> <I>pos</I> + Specifies the screen position where the cross hairs + intersect. <I>Pos</I> must be in the form "<I>@x,y</I>", where <I>x</I> and <I>y</I> + are the window coordinates of the intersection. + + Cross hairs configuration options may be also be set by the + <B>option</B> command. The resource name and class are crosshairs and + Crosshairs respectively. option add *Graph.Crosshairs.LineWidth + 2 option add *Graph.Crosshairs.Color red + + <I>pathName</I> <B>crosshairs</B> <B>off</B> + Turns off the cross hairs. + + <I>pathName</I> <B>crosshairs</B> <B>on</B> + Turns on the display of the cross hairs. + + <I>pathName</I> <B>crosshairs</B> <B>toggle</B> + Toggles the current state of the cross hairs, alternately map- + ping and unmapping the cross hairs. + + <B>ELEMENT</B> <B>COMPONENTS</B> + 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. + + <I>pathName</I> <B>element</B> <B>activate</B> <I>elemName</I> ?<I>index</I>?... + Specifies the data points of element <I>elemName</I> to be drawn using + replacing any existing binding for the same <I>sequence</I> and <I>tag-</I> + <I>Name</I>. If the first character of <I>command</I> is + then <I>command</I> aug- + ments an existing binding rather than replacing it. If no <I>com-</I> + <I>mand</I> argument is provided then the command currently associated + with <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no + such binding) is returned. If both <I>command</I> and <I>sequence</I> are + missing then a list of all the event sequences for which bind- + ings have been defined for <I>tagName</I>. + + <I>pathName</I> <B>element</B> <B>cget</B> <I>elemName</I> <I>option</I> + Returns the current value of the element configuration option + given by <I>option</I>. <I>Option</I> may be any of the options described + below for the element <B>configure</B> operation. + + <I>pathName</I> <B>element</B> <B>closest</B> <I>x</I> <I>y</I> ?<I>option</I> <I>value</I>?... ?<I>elemName</I>?... + Searches for the data point closest to the window coordinates <I>x</I> + and <I>y</I>. By default, all elements are searched. Hidden elements + (see the <B>-hide</B> option is false) are ignored. You can limit the + search by specifying only the elements you want to be consid- + ered. <I>ElemName</I> 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 + <I>option</I>-<I>value</I> pairs are available. + + <B>-along</B> <I>direction</I> + 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). + + <B>-halo</B> <I>pixels</I> + Specifies a threshold distance where selected data points + are ignored. <I>Pixels</I> 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 <B>-halo</B> option. + + <B>-interpolate</B> <I>string</I> + 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 <I>string</I> are described below. + + no Search only for the closest data point. + + <B>-activepen</B> <I>penName</I> + Specifies pen to use to draw active element. If <I>penName</I> + is "", no active elements will be drawn. The default is + activeLine. + + <B>-areabackground</B> <I>color</I> + Specifies the background color of the area under the + curve. The background area color is drawn only for bit- + maps (see the <B>-areapattern</B> option). If <I>color</I> is "", the + background is transparent. The default is black. + + <B>-areaforeground</B> <I>color</I> + Specifies the foreground color of the area under the + curve. The default is black. + + <B>-areapattern</B> <I>pattern</I> + Specifies how to fill the area under the curve. <I>Pattern</I> + 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 <B>-areaforeground</B> option. If a + bitmap, then the bitmap is stippled across the area. + Here the bitmap colors are controlled by the <B>-areafore-</B> + <B>ground</B> and <B>-areabackground</B> options. If <I>pattern</I> is "", no + filled area is drawn. The default is "". + + <B>-areatile</B> <I>image</I> + Specifies the name of a Tk image to be used to tile the + area under the curve. This option supersedes the <B>-areap-</B> + <B>attern</B> option. <I>Image</I> must be a photo image. If <I>image</I> is + "", no tiling is performed. The default is "". + + <B>-bindtags</B> <I>tagList</I> + Specifies the binding tags for the element. <I>TagList</I> 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. + + <B>-color</B> <I>color</I> + Sets the color of the traces connecting the data points. + + <B>-dashes</B> <I>dashList</I> + Sets the dash style of element line. <I>DashList</I> 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 <I>dashList</I> is "", the + lines will be solid. + + <B>-data</B> <I>coordList</I> + Specifies the X-Y coordinates of the data. <I>CoordList</I> is + Sets the element's label in the legend. If <I>text</I> is "", + the element will have no entry in the legend. The + default label is the element's name. + + <B>-linewidth</B> <I>pixels</I> + Sets the width of the connecting lines between data + points. If <I>pixels</I> is 0, no connecting lines will be + drawn between symbols. The default is 0. + + <B>-mapx</B> <I>xAxis</I> + Selects the X-axis to map the element's X-coordinates + onto. <I>XAxis</I> must be the name of an axis. The default is + x. + + <B>-mapy</B> <I>yAxis</I> + Selects the Y-axis to map the element's Y-coordinates + onto. <I>YAxis</I> must be the name of an axis. The default is + y. + + <B>-offdash</B> <I>color</I> + Sets the color of the stripes when traces are dashed (see + the <B>-dashes</B> option). If <I>color</I> is "", then the "off" pix- + els will represent gaps instead of stripes. If <I>color</I> is + defcolor, then the color will be the same as the <B>-color</B> + option. The default is defcolor. + + <B>-outline</B> <I>color</I> + Sets the color or the outline around each symbol. If + <I>color</I> is "", then no outline is drawn. If <I>color</I> is def- + color, then the color will be the same as the <B>-color</B> + option. The default is defcolor. + + <B>-pen</B> <I>penname</I> + Set the pen to use for this element. + + <B>-outlinewidth</B> <I>pixels</I> + Sets the width of the outline bordering each symbol. If + <I>pixels</I> is 0, no outline will be drawn. The default is 1. + + <B>-pixels</B> <I>pixels</I> + Sets the size of symbols. If <I>pixels</I> is 0, no symbols + will be drawn. The default is 0.125i. + + <B>-scalesymbols</B> <I>boolean</I> + If <I>boolean</I> is true, the size of the symbols drawn for + <I>elemName</I> 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 <B>-pixels</B> 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 <I>boolean</I> is + dratic spline is used. The default is <I>linear</I>. + + <B>-styles</B> <I>styleList</I> + Specifies what pen to use based on the range of weights + given. <I>StyleList</I> 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 <B>-weight</B> 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. + + <B>-symbol</B> <I>symbol</I> + Specifies the symbol for data points. <I>Symbol</I> can be + either square, circle, diamond, plus, cross, splus, + scross, triangle, "" (where no symbol is drawn), or a + bitmap. Bitmaps are specified as "<I>source</I> ?<I>mask</I>?", where + <I>source</I> is the name of the bitmap, and <I>mask</I> is the bit- + map's optional mask. The default is circle. + + <B>-trace</B> <I>direction</I> + Indicates whether connecting lines between data points + (whose X-coordinate values are either increasing or + decreasing) are drawn. <I>Direction</I> must be increasing, + decreasing, or both. For example, if <I>direction</I> is + increasing, connecting lines will be drawn only between + those data points where X-coordinate values are monotoni- + cally increasing. If <I>direction</I> is both, connecting lines + will be draw between all data points. The default is + both. + + <B>-weights</B> <I>wVec</I> + Specifies the weights of the individual data points. + This, with the list pen styles (see the <B>-styles</B> option), + controls how data points are drawn. <I>WVec</I> is the name of + a BLT vector or a list of numeric expressions represent- + ing the weights for each data point. + + <B>-xdata</B> <I>xVec</I> + Specifies the X-coordinates of the data. <I>XVec</I> is the + name of a BLT vector or a list of numeric expressions. + + <B>-ydata</B> <I>yVec</I> + Specifies the Y-coordinates of the data. <I>YVec</I> is the + name of a BLT vector or a list of numeric expressions. + + Element configuration options may also be set by the <B>option</B> 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 + + <I>pathName</I> <B>element</B> <B>exists</B> <I>elemName</I> + Returns 1 if an element <I>elemName</I> currently exists and 0 other- + wise. + + <I>pathName</I> <B>element</B> <B>names</B> ?<I>pattern</I>?... + Returns the elements matching one or more pattern. If no <I>pat-</I> + <I>tern</I> is given, the names of all elements is returned. + + <I>pathName</I> <B>element</B> <B>show</B> ?<I>nameList</I>? + Queries or modifies the element display list. The element dis- + play list designates the elements drawn and in what order. + <I>NameList</I> is a list of elements to be displayed in the order they + are named. If there is no <I>nameList</I> argument, the current dis- + play list is returned. + + <I>pathName</I> <B>element</B> <B>type</B> <I>elemName</I> + Returns the type of <I>elemName</I>. If the element is a bar element, + the commands returns the string "bar", otherwise it returns + "line". + + <B>GRID</B> <B>COMPONENT</B> + 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. + + <I>pathName</I> <B>grid</B> <B>cget</B> <I>option</I> + Returns the current value of the grid line configuration option + given by <I>option</I>. <I>Option</I> may be any option described below for + the grid <B>configure</B> operation. + + <I>pathName</I> <B>grid</B> <B>configure</B> ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options for grid lines. + If <I>option</I> isn't specified, a list describing all the current + grid options for <I>pathName</I> is returned. If <I>option</I> is specified, + but not <I>value</I>, then a list describing <I>option</I> is returned. If + one or more <I>option</I> and <I>value</I> pairs are specified, then for each + pair, the grid line option <I>option</I> is set to <I>value</I>. The follow- + ing options are valid for grid lines. + + <B>-color</B> <I>color</I> + Sets the color of the grid lines. The default is black. + + <B>-dashes</B> <I>dashList</I> + Sets the dash style of the grid lines. <I>DashList</I> 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 <I>dashList</I> is "", the + grid will be solid lines. + + <B>-hide</B> <I>boolean</I> + Indicates whether the grid should be drawn. If <I>boolean</I> is + + <B>-minor</B> <I>boolean</I> + Indicates whether the grid lines should be drawn for + minor ticks. If <I>boolean</I> is true, the lines will appear + at minor tick intervals. The default is 1. + + Grid configuration options may also be set by the <B>option</B> 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 + + <I>pathName</I> <B>grid</B> <B>off</B> + Turns off the display the grid lines. + + <I>pathName</I> <B>grid</B> <B>on</B> + Turns on the display the grid lines. + + <I>pathName</I> <B>grid</B> <B>toggle</B> + Toggles the display of the grid. + + <B>LEGEND</B> <B>COMPONENT</B> + 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. + + <I>pathName</I> <B>legend</B> <B>activate</B> <I>pattern</I>... + Selects legend entries to be drawn using the active legend col- + ors and relief. All entries whose element names match <I>pattern</I> + are selected. To be selected, the element name must match only + one <I>pattern</I>. + + <I>pathName</I> <B>legend</B> <B>bind</B> <I>tagName</I> ?<I>sequence</I>? ?<I>command</I>? + Associates <I>command</I> with <I>tagName</I> such that whenever the event + sequence given by <I>sequence</I> occurs for a legend entry with this + tag, <I>command</I> will be invoked. Implicitly the element names in + the entry are tags. The syntax is similar to the <B>bind</B> command + except that it operates on legend entries, rather than widgets. + See the <B>bind</B> manual entry for complete details on <I>sequence</I> and + the substitutions performed on <I>command</I> before invoking it. + + If all arguments are specified then a new binding is created, + replacing any existing binding for the same <I>sequence</I> and <I>tag-</I> + <I>Name</I>. If the first character of <I>command</I> is + then <I>command</I> aug- + ments an existing binding rather than replacing it. If no <I>com-</I> + <I>mand</I> argument is provided then the command currently associated + with <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no + such binding) is returned. If both <I>command</I> and <I>sequence</I> are + missing then a list of all the event sequences for which bind- + ings have been defined for <I>tagName</I>. + + <B>-activebackground</B> <I>color</I> + Sets the background color for active legend entries. All + legend entries marked active (see the legend <B>activate</B> + operation) are drawn using this background color. + + <B>-activeborderwidth</B> <I>pixels</I> + Sets the width of the 3-D border around the outside edge + of the active legend entries. The default is 2. + + <B>-activeforeground</B> <I>color</I> + Sets the foreground color for active legend entries. All + legend entries marked as active (see the legend <B>activate</B> + operation) are drawn using this foreground color. + + <B>-activerelief</B> <I>relief</I> + Specifies the 3-D effect desired for active legend + entries. <I>Relief</I> 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. + + <B>-anchor</B> <I>anchor</I> + Tells how to position the legend relative to the posi- + tioning point for the legend. This is dependent on the + value of the <B>-position</B> 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 <I>anchor</I> is center then the legend + is centered on the point; if <I>anchor</I> 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 <I>anchor</I> is center then the legend is + centered in the plotting area; if <I>anchor</I> 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 <B>relief</B> + option determines this). The default is 2 pixels. + + <B>-font</B> <I>fontName</I> + <I>FontName</I> 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-*. + + <B>-foreground</B> <I>color</I> + Sets the foreground color of the text drawn for the ele- + ment's label. The default is black. + + <B>-hide</B> <I>boolean</I> + Indicates whether the legend should be displayed. If + <I>boolean</I> is true, the legend will not be draw. The + default is no. + + <B>-ipadx</B> <I>pad</I> + Sets the amount of internal padding to be added to the + width of each legend entry. <I>Pad</I> can be a list of one or + two screen distances. If <I>pad</I> has two elements, the left + side of the legend entry is padded by the first distance + and the right side by the second. If <I>pad</I> is just one + distance, both the left and right sides are padded + evenly. The default is 2. + + <B>-ipady</B> <I>pad</I> + Sets an amount of internal padding to be added to the + height of each legend entry. <I>Pad</I> can be a list of one or + two screen distances. If <I>pad</I> has two elements, the top + of the entry is padded by the first distance and the bot- + tom by the second. If <I>pad</I> is just one distance, both the + top and bottom of the entry are padded evenly. The + default is 2. + + <B>-padx</B> <I>pad</I> + Sets the padding to the left and right exteriors of the + legend. <I>Pad</I> can be a list of one or two screen dis- + tances. If <I>pad</I> has two elements, the left side of the + legend is padded by the first distance and the right side + by the second. If <I>pad</I> has just one distance, both the + left and right sides are padded evenly. The default is + 4. + + <B>-pady</B> <I>pad</I> + Sets the padding above and below the legend. <I>Pad</I> can be + a list of one or two screen distances. If <I>pad</I> has two + elements, the area above the legend is padded by the + first distance and the area below by the second. If <I>pad</I> + is just one distance, both the top and bottom areas are + padded evenly. The default is 0. + plotting area. If <I>boolean</I> is true, the legend will be + drawn on top of any elements that may overlap it. The + default is no. + + <B>-relief</B> <I>relief</I> + Specifies the 3-D effect for the border around the leg- + end. <I>Relief</I> 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 <B>option</B> 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 + + <I>pathName</I> <B>legend</B> <B>deactivate</B> <I>pattern</I>... + Selects legend entries to be drawn using the normal legend col- + ors and relief. All entries whose element names match <I>pattern</I> + are selected. To be selected, the element name must match only + one <I>pattern</I>. + + <I>pathName</I> <B>legend</B> <B>get</B> <I>pos</I> + Returns the name of the element whose entry is at the screen + position <I>pos</I> in the legend. <I>Pos</I> must be in the form "<I>@x,y</I>", + where <I>x</I> and <I>y</I> are window coordinates. If the given coordinates + do not lie over a legend entry, "" is returned. + + <B>PEN</B> <B>COMPONENTS</B> + 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 <B>-weight</B> and <B>-style</B> 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 <B>-pen</B> or <B>-activepen</B> 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 + <B>-styles</B> 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 <I>option</I> is set to + <I>value</I>. The following options are valid for pens. + + <B>-color</B> <I>color</I> + Sets the color of the traces connecting the data points. + + <B>-dashes</B> <I>dashList</I> + Sets the dash style of element line. <I>DashList</I> 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 <I>dashList</I> is "", the + lines will be solid. + + <B>-fill</B> <I>color</I> + Sets the interior color of symbols. If <I>color</I> is "", then + the interior of the symbol is transparent. If <I>color</I> is + defcolor, then the color will be the same as the <B>-color</B> + option. The default is defcolor. + + <B>-linewidth</B> <I>pixels</I> + Sets the width of the connecting lines between data + points. If <I>pixels</I> is 0, no connecting lines will be + drawn between symbols. The default is 0. + + <B>-offdash</B> <I>color</I> + Sets the color of the stripes when traces are dashed (see + the <B>-dashes</B> option). If <I>color</I> is "", then the "off" pix- + els will represent gaps instead of stripes. If <I>color</I> is + defcolor, then the color will be the same as the <B>-color</B> + option. The default is defcolor. + + <B>-outline</B> <I>color</I> + Sets the color or the outline around each symbol. If + <I>color</I> is "", then no outline is drawn. If <I>color</I> is def- + color, then the color will be the same as the <B>-color</B> + option. The default is defcolor. + + <B>-outlinewidth</B> <I>pixels</I> + Sets the width of the outline bordering each symbol. If + <I>pixels</I> is 0, no outline will be drawn. The default is 1. + + <B>-pixels</B> <I>pixels</I> + Sets the size of symbols. If <I>pixels</I> is 0, no symbols + will be drawn. The default is 0.125i. + + <B>-symbol</B> <I>symbol</I> + Specifies the symbol for data points. <I>Symbol</I> can be + either square, circle, diamond, plus, cross, splus, + scross, triangle, "" (where no symbol is drawn), or a + bitmap. Bitmaps are specified as "<I>source</I> ?<I>mask</I>?", where + <I>source</I> is the name of the bitmap, and <I>mask</I> is the bit- + map's optional mask. The default is circle. + + Creates a new pen by the name <I>penName</I>. No pen by the same name + can already exist. <I>Option</I> and <I>value</I> are described in above in + the pen <B>configure</B> operation. + + <I>pathName</I> <B>pen</B> <B>delete</B> ?<I>penName</I>?... + 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. + + <I>pathName</I> <B>pen</B> <B>names</B> ?<I>pattern</I>?... + Returns a list of pens matching zero or more patterns. If no + <I>pattern</I> argument is give, the names of all pens are returned. + + <B>POSTSCRIPT</B> <B>COMPONENT</B> + 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. + + <I>pathName</I> <B>postscript</B> <B>cget</B> <I>option</I> + Returns the current value of the postscript option given by + <I>option</I>. <I>Option</I> may be any option described below for the post- + script <B>configure</B> operation. + + <I>pathName</I> <B>postscript</B> <B>configure</B> ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options for PostScript + generation. If <I>option</I> isn't specified, a list describing the + current postscript options for <I>pathName</I> is returned. If <I>option</I> + is specified, but not <I>value</I>, then a list describing <I>option</I> is + returned. If one or more <I>option</I> and <I>value</I> pairs are specified, + then for each pair, the postscript option <I>option</I> is set to + <I>value</I>. The following postscript options are available. + + <B>-center</B> <I>boolean</I> + Indicates whether the plot should be centered on the + PostScript page. If <I>boolean</I> is false, the plot will be + placed in the upper left corner of the page. The default + is 1. + + <B>-colormap</B> <I>varName</I> + <I>VarName</I> 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 <I>varName</I> 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 <I>varName</I> 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 <I>varName</I> 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 <I>varName</I> 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 <I>Adobe</I> (such as Times, Helvetica, + Courier, etc.). If all of this fails then the font + defaults to Helvetica-Bold. + + <B>-decorations</B> <I>boolean</I> + Indicates whether PostScript commands to generate color + backgrounds and 3-D borders will be output. If <I>boolean</I> + is false, the background will be white and no 3-D borders + will be generated. The default is 1. + + <B>-height</B> <I>pixels</I> + Sets the height of the plot. This lets you print the + graph with a height different from the one drawn on the + screen. If <I>pixels</I> is 0, the height is the same as the + widget's height. The default is 0. + + <B>-landscape</B> <I>boolean</I> + If <I>boolean</I> 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. + + <B>-maxpect</B> <I>boolean</I> + 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. + + <B>-padx</B> <I>pad</I> + Sets the horizontal padding for the left and right page + borders. The borders are exterior to the plot. <I>Pad</I> can + be a list of one or two screen distances. If <I>pad</I> has two + elements, the left border is padded by the first distance + and the right border by the second. If <I>pad</I> has just one + distance, both the left and right borders are padded + evenly. The default is 1i. + + <B>-pady</B> <I>pad</I> + Sets the vertical padding for the top and bottom page + borders. The borders are exterior to the plot. <I>Pad</I> can + The default width is 8.5i. + + <B>-width</B> <I>pixels</I> + Sets the width of the plot. This lets you generate a + plot of a width different from that of the widget. If + <I>pixels</I> 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 + <B>option</B> command. The resource name and class are postscript and + Postscript respectively. option add *Graph.postscript.Decora- + tions false option add *Graph.Postscript.Landscape true + + <I>pathName</I> <B>postscript</B> <B>output</B> ?<I>fileName</I>? ?<I>option</I> <I>value</I>?... + Outputs a file of encapsulated PostScript. If a <I>fileName</I> argu- + ment isn't present, the command returns the PostScript. If any + <I>option-value</I> pairs are present, they set configuration options + controlling how the PostScript is generated. <I>Option</I> and <I>value</I> + can be anything accepted by the postscript <B>configure</B> operation + above. + + <B>MARKER</B> <B>COMPONENTS</B> + 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 <B>-under</B> option. + + Markers, in contrast to elements, don't affect the scaling of the coor- + dinate axes. They can also have <I>elastic</I> 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. + + <I>pathName</I> <B>marker</B> <B>after</B> <I>markerId</I> ?<I>afterId</I>? + Changes the order of the markers, drawing the first marker after + the second. If no second <I>afterId</I> 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. + + <I>pathName</I> <B>marker</B> <B>before</B> <I>markerId</I> ?<I>beforeId</I>? + Changes the order of the markers, drawing the first marker + before the second. If no second <I>beforeId</I> 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 <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no + such binding) is returned. If both <I>command</I> and <I>sequence</I> are + missing then a list of all the event sequences for which bind- + ings have been defined for <I>tagName</I>. + + <I>pathName</I> <B>marker</B> <B>cget</B> <I>option</I> + Returns the current value of the marker configuration option + given by <I>option</I>. <I>Option</I> may be any option described below in + the <B>configure</B> operation. + + <I>pathName</I> <B>marker</B> <B>configure</B> <I>markerId</I> ?<I>option</I> <I>value</I>?... + Queries or modifies the configuration options for markers. If + <I>option</I> isn't specified, a list describing the current options + for <I>markerId</I> is returned. If <I>option</I> is specified, but not + <I>value</I>, then a list describing <I>option</I> is returned. If one or + more <I>option</I> and <I>value</I> pairs are specified, then for each pair, + the marker option <I>option</I> is set to <I>value</I>. + + 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. + + <B>-bindtags</B> <I>tagList</I> + Specifies the binding tags for the marker. <I>TagList</I> 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. + + <B>-coords</B> <I>coordList</I> + Specifies the coordinates of the marker. <I>CoordList</I> 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 <I>coordList</I> is "", the marker + will not be displayed. The default is "". + + <B>-element</B> <I>elemName</I> + Links the marker with the element <I>elemName</I>. The marker + is drawn only if the element is also currently displayed + (see the element's <B>show</B> operation). If <I>elemName</I> is "", + the marker is always drawn. The default is "". + + <B>-hide</B> <I>boolean</I> + Indicates whether the marker is drawn. If <I>boolean</I> is + true, the marker is not drawn. The default is no. + + <B>-under</B> <I>boolean</I> + Indicates whether the marker is drawn below/above data + elements. If <I>boolean</I> 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. + + <B>-xoffset</B> <I>pixels</I> + Specifies a screen distance to offset the marker horizon- + tally. <I>Pixels</I> is a valid screen distance, such as 2 or + 1.2i. The default is 0. + + <B>-yoffset</B> <I>pixels</I> + Specifies a screen distance to offset the markers verti- + cally. <I>Pixels</I> is a valid screen distance, such as 2 or + 1.2i. The default is 0. + + Marker configuration options may also be set by the <B>option</B> 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 + + <I>pathName</I> <B>marker</B> <B>create</B> <I>type</I> ?<I>option</I> <I>value</I>?... + Creates a marker of the selected type. <I>Type</I> may be either text, + line, bitmap, image, polygon, or window. This command returns + the marker identifier, used as the <I>markerId</I> argument in the + other marker-related commands. If the <B>-name</B> 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. + + <I>pathName</I> <B>marker</B> <B>delete</B> ?<I>name</I>?... + Removes one of more markers. The graph will automatically be + redrawn without the marker.. + + <I>pathName</I> <B>marker</B> <B>exists</B> <I>markerId</I> + Returns 1 if the marker <I>markerId</I> exists and 0 otherwise. + + <I>pathName</I> <B>marker</B> <B>names</B> ?<I>pattern</I>? + Returns the names of all the markers that currently exist. If + <I>pattern</I> is supplied, only those markers whose names match it + will be returned. + + <I>pathName</I> <B>marker</B> <B>type</B> <I>markerId</I> + Returns the type of the marker given by <I>markerId</I>, such as line + or text. If <I>markerId</I> is not a valid a marker identifier, "" is + returned. + + <B>BITMAP</B> <B>MARKERS</B> + The following options are specific to bitmap markers: + + <B>-background</B> <I>color</I> + Same as the <B>-fill</B> option. + + <B>-bitmap</B> <I>bitmap</I> + Specifies the bitmap to be displayed. If <I>bitmap</I> is "", the + marker will not be displayed. The default is "". + + <B>-fill</B> <I>color</I> + Sets the background color of the bitmap. If <I>color</I> is the empty + string, no background will be transparent. The default back- + ground color is "". + + <B>-foreground</B> <I>color</I> + Same as the <B>-outline</B> option. + + <B>-mask</B> <I>mask</I> + Specifies a mask for the bitmap to be displayed. This mask is a + bitmap itself, denoting the pixels that are transparent. If + <I>mask</I> is "", all pixels of the bitmap will be drawn. The default + is "". + + <B>-outline</B> <I>color</I> + Sets the foreground color of the bitmap. The default value is + black. + + <B>-rotate</B> <I>theta</I> + Sets the rotation of the bitmap. <I>Theta</I> 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. + + <B>IMAGE</B> <B>MARKERS</B> + A image marker displays an image. Image markers are created with the + marker's <B>create</B> operation in the form: <I>pathName</I> <B>marker</B> <B>create</B> <B>image</B> + ?<I>option</I> <I>value</I>?... There may be many <I>option</I>-<I>value</I> pairs, each sets a + configuration option for the marker. These same <I>option</I>-<I>value</I> pairs may + be used with the marker's <B>configure</B> operation. + + The following options are specific to image markers: + + <B>-anchor</B> <I>anchor</I> + <I>Anchor</I> tells how to position the image relative to the position- + ing point for the image. For example, if <I>anchor</I> is center then + the image is centered on the point; if <I>anchor</I> 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. + + <B>-image</B> <I>image</I> + Specifies the image to be drawn. If <I>image</I> is "", the marker + gaps on the line. Each number must be between 1 and 255. If + <I>dashList</I> is "", the marker line will be solid. + + <B>-fill</B> <I>color</I> + Sets the background color of the line. This color is used with + striped lines (see the <B>-fdashes</B> option). If <I>color</I> is the empty + string, no background color is drawn (the line will be dashed, + not striped). The default background color is "". + + <B>-linewidth</B> <I>pixels</I> + Sets the width of the lines. The default width is 0. + + <B>-outline</B> <I>color</I> + Sets the foreground color of the line. The default value is + black. + + <B>-stipple</B> <I>bitmap</I> + Specifies a stipple pattern used to draw the line, rather than a + solid line. <I>Bitmap</I> specifies a bitmap to use as the stipple + pattern. If <I>bitmap</I> is "", then the line is drawn in a solid + fashion. The default is "". + + <B>POLYGON</B> <B>MARKERS</B> + 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 <B>create</B> operation + in the form: <I>pathName</I> <B>marker</B> <B>create</B> <B>polygon</B> ?<I>option</I> <I>value</I>?... There + may be many <I>option</I>-<I>value</I> pairs, each sets a configuration option for + the marker. These same <I>option</I>-<I>value</I> pairs may be used with the <B>marker</B> + <B>configure</B> command to change the marker's configuration. The following + options are supported for polygon markers: + + <B>-dashes</B> <I>dashList</I> + Sets the dash style of the outline of the polygon. <I>DashList</I> 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 <I>dashList</I> is "", the outline will be a + solid line. + + <B>-fill</B> <I>color</I> + Sets the fill color of the polygon. If <I>color</I> is "", then the + interior of the polygon is transparent. The default is white. + + <B>-linewidth</B> <I>pixels</I> + Sets the width of the outline of the polygon. If <I>pixels</I> is zero, + no outline is drawn. The default is 0. + + <B>-outline</B> <I>color</I> + Sets the color of the outline of the polygon. If the polygon is + stippled (see the <B>-stipple</B> option), then this represents the + foreground color of the stipple. The default is black. + + the marker's <B>configure</B> operation. + + The following options are specific to text markers: + + <B>-anchor</B> <I>anchor</I> + <I>Anchor</I> tells how to position the text relative to the position- + ing point for the text. For example, if <I>anchor</I> is center then + the text is centered on the point; if <I>anchor</I> 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. + + <B>-background</B> <I>color</I> + Same as the <B>-fill</B> option. + + <B>-font</B> <I>fontName</I> + Specifies the font of the text. The default is *-Helvetica- + Bold-R-Normal-*-120-*. + + <B>-fill</B> <I>color</I> + Sets the background color of the text. If <I>color</I> is the empty + string, no background will be transparent. The default back- + ground color is "". + + <B>-foreground</B> <I>color</I> + Same as the <B>-outline</B> option. + + <B>-justify</B> <I>justify</I> + Specifies how the text should be justified. This matters only + when the marker contains more than one line of text. <I>Justify</I> + must be left, right, or center. The default is center. + + <B>-outline</B> <I>color</I> + Sets the color of the text. The default value is black. + + <B>-padx</B> <I>pad</I> + Sets the padding to the left and right exteriors of the text. + <I>Pad</I> can be a list of one or two screen distances. If <I>pad</I> has + two elements, the left side of the text is padded by the first + distance and the right side by the second. If <I>pad</I> has just one + distance, both the left and right sides are padded evenly. The + default is 4. + + <B>-pady</B> <I>pad</I> + Sets the padding above and below the text. <I>Pad</I> can be a list of + one or two screen distances. If <I>pad</I> has two elements, the area + above the text is padded by the first distance and the area + below by the second. If <I>pad</I> is just one distance, both the top + and bottom areas are padded evenly. The default is 4. + + <B>-rotate</B> <I>theta</I> + Specifies the number of degrees to rotate the text. <I>Theta</I> is a + + <I>option</I>-<I>value</I> pairs may be used with the marker's <B>configure</B> command. + + The following options are specific to window markers: + + <B>-anchor</B> <I>anchor</I> + <I>Anchor</I> tells how to position the widget relative to the posi- + tioning point for the widget. For example, if <I>anchor</I> is center + then the widget is centered on the point; if <I>anchor</I> 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. + + <B>-height</B> <I>pixels</I> + 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. + + <B>-width</B> <I>pixels</I> + 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. + + <B>-window</B> <I>pathName</I> + Specifies the widget to be managed by the graph. <I>PathName</I> must + be a child of the <B>graph</B> widget. + + +</PRE> +<H2>GRAPH COMPONENT BINDINGS</H2><PRE> + 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 <B>Enter</B>, <B>Leave</B>, <B>ButtonPress</B>, <B>Motion</B>, + and <B>KeyPress</B>). + + 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 + <B>-bindtags</B> 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 + <B>Blt_ResetVector</B> 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 <B>vector</B> manual page for more details. + + +</PRE> +<H2>SPEED TIPS</H2><PRE> + 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. + + <B>o</B> Try to minimize the number of data points. The more data points the + looked at, the more work the graph must do. + + <B>o</B> 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. + + <B>o</B> Data elements without symbols are drawn faster than with symbols. + Set the data element's <B>-symbol</B> option to none. If you need to draw + symbols, try using the simple symbols such as splus and scross. + + <B>o</B> Don't stipple or dash the element. Solid lines are much faster. + + <B>o</B> If you update data elements frequently, try turning off the widget's + <B>-bufferelements</B> 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) +</PRE> +<HR> +<ADDRESS> +Man(1) output converted with +<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> +</ADDRESS> +</BODY> +</HTML> diff --git a/doc/graph.n b/doc/graph.n new file mode 100644 index 0000000..fbbbb9b --- /dev/null +++ b/doc/graph.n @@ -0,0 +1,2408 @@ +'\" +'\" Smithsonian Astrophysical Observatory, Cambridge, MA, USA +'\" This code has been modified under the terms listed below and is made +'\" available under the same terms. +'\" +'\" Copyright 1991-1998 by Bell Labs Innovations for Lucent Technologies. +'\" +'\" Permission to use, copy, modify, and distribute this software and its +'\" documentation for any purpose and without fee is hereby granted, provided +'\" that the above copyright notice appear in all copies and that both that the +'\" copyright notice and warranty disclaimer appear in supporting documentation, +'\" and that the names of Lucent Technologies any of their entities not be used +'\" in advertising or publicity pertaining to distribution of the software +'\" without specific, written prior permission. +'\" +'\" Lucent Technologies disclaims all warranties with regard to this software, +'\" including all implied warranties of merchantability and fitness. In no event +'\" shall Lucent Technologies be liable for any special, indirect or +'\" consequential damages or any damages whatsoever resulting from loss of use, +'\" data or profits, whether in an action of contract, negligence or other +'\" tortuous action, arising out of or in connection with the use or performance +'\" of this software. +'\" +'\" Graph widget created by Sani Nassif and George Howlett. +'\" +.TH graph n BLT_VERSION BLT "BLT Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +graph \- 2D graph for plotting X\-Y coordinate data. +.SH SYNOPSIS +\fBgraph\fI \fIpathName \fR?\fIoption value\fR?... +.BE +.SH DESCRIPTION +The \fBgraph\fR 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. +.SH INTRODUCTION +The \fBgraph\fR 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 +\fIplotting area\fR. 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. +.PP +The \fBgraph\fR widget is composed of several components: coordinate +axes, data elements, legend, grid, cross hairs, pens, postscript, and +annotation markers. +.TP 1i +\f(CWaxis\fR +The graph has four standard axes (\f(CWx\fR, \f(CWx2\fR, +\f(CWy\fR, and \f(CWy2\fR), 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. +.TP 1i +\f(CWcrosshairs\fR +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. +.TP 1i +\f(CWelement\fR +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 symbol, line width, and +color is configurable. +.TP 1i +\f(CWgrid\fR +Extends the major and minor ticks of the X\-axis and/or Y\-axis across the +plotting area. +.TP 1i +\f(CWlegend\fR +The legend displays the name and symbol of each data element. +The legend can be drawn in any margin or in the plotting area. +.TP 1i +\f(CWmarker\fR +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 widgets. +.TP 1i +\f(CWpen\fR +Pens define attributes (both symbol and line style) 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 \fB\-weight\fR and \fB\-style\fR options). +.TP 1i +\f(CWpostscript\fR +The widget can generate encapsulated PostScript output. This component +has several options to configure how the PostScript is generated. +.SH SYNTAX +.DS +\fBgraph \fIpathName \fR?\fIoption value\fR?... +.DE +The \fBgraph\fR command creates a new window \fIpathName\fR and makes +it into a \fBgraph\fR widget. At the time this command is invoked, there +must not exist a window named \fIpathName\fR, but \fIpathName\fR'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 \fBconfigure\fR operation +below for the exact details about what \fIoption\fR and \fIvalue\fR +pairs are valid. +.PP +If successful, \fBgraph\fR 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 general form is: +.DS +\fIpathName \fIoperation\fR \fR?\fIarg\fR?... +.DE +Both \fIoperation\fR and its arguments determine the exact behavior of +the command. The operations available for the graph are described in +the +.SB "GRAPH OPERATIONS" +section. +.PP +The command can also be used to access components of the graph. +.DS +\fIpathName component operation\fR ?\fIarg\fR?... +.DE +The operation, now located after the name of the component, is the +function to be performed on that component. Each component has its own +set of operations that manipulate that component. They will be +described below in their own sections. +.SH EXAMPLE +The \fBgraph\fR command creates a new graph. +.CS +# Create a new graph. Plotting area is black. +graph .g \-plotbackground black +.CE +A new Tcl command \f(CW.g\fR 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 +\fBconfigure\fR operation. +.CS +# Change the title. +\&.g configure \-title "My Plot" +.CE +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 \fBelement\fR component. +.CS +# 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 } +.CE +The element's X-Y coordinates are specified using lists of +numbers. Alternately, BLT vectors could be used to hold the X\-Y +coordinates. +.CS +# 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 +.CE +The advantage of using vectors is that when you modify one, the graph +is automatically redrawn to reflect the new values. +.CS +# Change the y coordinate of the first point. +set yVector(0) 25.18 +.CE +An element named \f(CWe1\fR is now created in \f(CW.b\fR. 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 +\fBshow\fR operation. +.CS +# 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] +.CE +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 \fB\-barwidth\fR +option. +.CS +# Change the X\-Y coordinates of the first point. +set xVec(0) 0.18 +set yVec(0) 25.18 +.CE +An element named \f(CWline1\fR is now created in \f(CW.g\fR. By +default, the element's label in the legend will be also \f(CWline1\fR. +You can change the label, or specify no legend entry, again using the +element's \fBconfigure\fR operation. +.CS +# Don't display "line1" in the legend. +\&.g element configure line1 \-label "" +.CE +You can configure more than just the element's label. An element has +many attributes such as symbol type and size, dashed or solid lines, +colors, line width, etc. +.CS +\&.g element configure line1 \-symbol square \-color red \\ + \-dashes { 2 4 2 } \-linewidth 2 \-pixels 2c +.CE +Four coordinate axes are automatically created: \f(CWx\fR, \f(CWx2\fR, +\f(CWy\fR, and \f(CWy2\fR. And by default, elements are mapped onto the +axes \f(CWx\fR and \f(CWy\fR. This can be changed with the \fB\-mapx\fR +and \fB\-mapy\fR options. +.CS +# Map "line1" on the alternate Y\-axis "y2". +\&.g element configure line1 \-mapy y2 +.CE +Axes can be configured in many ways too. For example, you change the +scale of the Y\-axis from linear to log using the \fBaxis\fR component. +.CS +# Y\-axis is log scale. +\&.g axis configure y \-logscale yes +.CE +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 \fB\-min\fR and \fB\-max\fR configuration options. +.CS +\&.g axis configure x \-min 1.0 \-max 1.5 +\&.g axis configure y \-min 12.0 \-max 55.15 +.CE +To zoom interactively, you link the \fBaxis configure\fR operations with +some user interaction (such as pressing the mouse button), using the +\fBbind\fR command. To convert between screen and graph coordinates, +use the \fBinvtransform\fR operation. +.CS +# 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] +} +.CE +By default, the limits of the axis are determined from data values. +To reset back to the default limits, set the \fB\-min\fR and +\fB\-max\fR options to the empty value. +.CS +# Reset the axes to autoscale again. +\&.g axis configure x \-min {} \-max {} +\&.g axis configure y \-min {} \-max {} +.CE +By default, the legend is drawn in the right margin. You can +change this or any legend configuration options using the +\fBlegend\fR component. +.CS +# Configure the legend font, color, and relief +\&.g legend configure \-position left \-relief raised \\ + \-font fixed \-fg blue +.CE +To prevent the legend from being displayed, turn on the \fB\-hide\fR +option. +.CS +# Don't display the legend. +\&.g legend configure \-hide yes\fR +.CE +The \fBgraph\fR widget has simple drawing procedures called markers. +They can be used to highlight or annotate data in the graph. The types +of markers available are bitmaps, images, polygons, lines, or windows. +Markers can be used, for example, to mark or brush points. In this +example, is a text marker that labels the data first point. Markers +are created using the \fBmarker\fR component. +.CS +# 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 +.CE +This creates a text marker named \f(CWfirst_marker\fR. It will display +the text "start" near the coordinates of the first data point. The +\fB\-anchor\fR, \fB\-xoffset\fR, and \fB\-yoffset\fR 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 +\fB\-under\fR option. +.CS +# Draw the label before elements are drawn. +\&.g marker configure first_marker \-under yes +.CE +You can add cross hairs or grid lines using the \fBcrosshairs\fR and +\fBgrid\fR components. +.CS +# Display both cross hairs and grid lines. +\&.g crosshairs configure \-hide no \-color red +\&.g grid configure \-hide no \-dashes { 2 2 } +# Set up a binding to reposition the crosshairs. +bind .g <Motion> { + .g crosshairs configure -position @%x,%y +} +.CE +The crosshairs are repositioned as the mouse pointer is moved +in the graph. The pointer X-Y coordinates define the center +of the crosshairs. +.PP +Finally, to get hardcopy of the graph, use the \fBpostscript\fR +component. +.CS +# Print the graph into file "file.ps" +\&.g postscript output file.ps \-maxpect yes \-decorations no +.CE +This generates a file \f(CWfile.ps\fR containing the encapsulated +PostScript of the graph. The option \fB\-maxpect\fR says to scale the +plot to the size of the page. Turning off the \fB\-decorations\fR +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). +.SH "GRAPH OPERATIONS" +.TP +\fIpathName \fBaxis \fIoperation \fR?\fIarg\fR?... +See the +.SB "AXIS COMPONENTS" +section. +.TP +\fIpathName \fBbar \fIelemName \fR?\fIoption value\fR?... +Creates a new barchart element \fIelemName\fR. It's an +error if an element \fIelemName\fR already exists. +See the manual for \fBbarchart\fR for details about +what \fIoption\fR and \fIvalue\fR pairs are valid. +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given by +\fIoption\fR. \fIOption\fR may be any option described +below for the \fBconfigure\fR operation. +.TP +\fIpathName \fBconfigure \fR?\fIoption value\fR?... +Queries or modifies the configuration options of the graph. If +\fIoption\fR isn't specified, a list describing the current +options for \fIpathName\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the option \fIoption\fR is set to \fIvalue\fR. +The following options are valid. +.RS +.TP +\fB\-aspect \fIwidth/height\fR +Force a fixed aspect ratio of \fIwidth/height\fR, a floating point number. +.TP +\fB\-background \fIcolor\fR +Sets the background color. This includes the margins and +legend, but not the plotting area. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the width of the 3\-D border around the outside edge of the widget. The +\fB\-relief\fR option determines if the border is to be drawn. The +default is \f(CW2\fR. +.TP +\fB\-bottommargin \fIpixels\fR +If non-zero, overrides the computed size of the margin extending +below the X\-coordinate axis. +If \fIpixels\fR is \f(CW0\fR, the automatically computed size is used. +The default is \f(CW0\fR. +.TP +\fB\-bufferelements \fIboolean\fR +Indicates whether an internal pixmap to buffer the display of data +elements should be used. If \fIboolean\fR 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 +.SB "SPEED TIPS" +section. +The default is \f(CW1\fR. +.TP +\fB\-cursor \fIcursor\fR +Specifies the widget's cursor. The default cursor is \f(CWcrosshair\fR. +.TP +\fB\-font \fIfontName\fR +Specifies the font of the graph title. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-18-180-*\fR. +.TP +\fB\-halo \fIpixels\fR +Specifies a maximum distance to consider when searching for the +closest data point (see the element's \fBclosest\fR operation below). +Data points further than \fIpixels\fR away are ignored. The default is +\f(CW0.5i\fR. +.TP +\fB\-height \fIpixels\fR +Specifies the requested height of widget. The default is +\f(CW4i\fR. +.TP +\fB\-invertxy \fIboolean\fR +Indicates whether the placement X\-axis and Y\-axis should be inverted. If +\fIboolean\fR is true, the X and Y axes are swapped. The default is +\f(CW0\fR. +.TP +\fB\-justify \fIjustify\fR +Specifies how the title should be justified. This matters only when +the title contains more than one line of text. \fIJustify\fR must be +\f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-leftmargin \fIpixels\fR +If non-zero, overrides the computed size of the margin extending +from the left edge of the window to the Y\-coordinate axis. +If \fIpixels\fR is \f(CW0\fR, the automatically computed size is used. +The default is \f(CW0\fR. +.TP +\fB\-plotbackground \fIcolor\fR +Specifies the background color of the plotting area. The default is +\f(CWwhite\fR. +.TP +\fB\-plotborderwidth \fIpixels\fR +Sets the width of the 3-D border around the plotting area. The +\fB\-plotrelief\fR option determines if a border is drawn. The +default is \f(CW2\fR. +.TP +\fB\-plotpadx \fIpad\fR +Sets the amount of padding to be added to the left and right sides of +the plotting area. \fIPad\fR can be a list of one or two screen +distances. If \fIpad\fR 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 \fIpad\fR is just one distance, both the left and +right sides are padded evenly. The default is \f(CW8\fR. +.TP +\fB\-plotpady \fIpad\fR +Sets the amount of padding to be added to the top and bottom of the +plotting area. \fIPad\fR can be a list of one or two screen +distances. If \fIpad\fR has two elements, the top of the plotting +area is padded by the first distance and the bottom by the second. If +\fIpad\fR is just one distance, both the top and bottom are padded +evenly. The default is \f(CW8\fR. +.TP +\fB\-plotrelief \fIrelief\fR +Specifies the 3-D effect for the plotting area. \fIRelief\fR +specifies how the interior of the plotting area should appear relative +to rest of the graph; for example, \f(CWraised\fR means the plot should +appear to protrude from the graph, relative to the surface of the +graph. The default is \f(CWsunken\fR. +.TP +\fB\-relief \fIrelief\fR +Specifies the 3-D effect for the graph widget. \fIRelief\fR +specifies how the graph should appear relative to widget it is packed +into; for example, \f(CWraised\fR means the graph should +appear to protrude. The default is \f(CWflat\fR. +.TP +\fB\-rightmargin \fIpixels\fR +If non-zero, overrides the computed size of the margin extending +from the plotting area to the right edge of +the window. By default, the legend is drawn in this margin. +If \fIpixels\fR is \f(CW0\fR, the automatically computed size is used. +The default is \f(CW0\fR. +.TP +\fB\-takefocus\fR \fIfocus\fR +Provides information used when moving the focus from window to window +via keyboard traversal (e.g., Tab and Shift-Tab). If \fIfocus\fR is +\f(CW0\fR, this means that this window should be skipped entirely during +keyboard traversal. \f(CW1\fR 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 \f(CW""\fR. +.TP +\fB\-tile \fIimage\fR +Specifies a tiled background for the widget. If \fIimage\fR isn't +\f(CW""\fR, the background is tiled using \fIimage\fR. +Otherwise, the normal background color is drawn (see the +\fB\-background\fR option). \fIImage\fR must be an image created +using the Tk \fBimage\fR command. The default is \f(CW""\fR. +.TP +\fB\-title \fItext\fR +Sets the title to \fItext\fR. If \fItext\fR is \f(CW""\fR, +no title will be displayed. +.TP +\fB\-topmargin \fIpixels\fR +If non-zero, overrides the computed size of the margin above the x2 +axis. If \fIpixels\fR is \f(CW0\fR, the automatically computed size +is used. The default is \f(CW0\fR. +.TP +\fB\-width \fIpixels\fR +Specifies the requested width of the widget. The default is +\f(CW5i\fR. +.RE +.TP +\fIpathName \fBcrosshairs \fIoperation \fR?\fIarg\fR? +See the +.SB "CROSSHAIRS COMPONENT" +section. +.TP +\fIpathName \fBelement \fIoperation \fR?\fIarg\fR?... +See the +.SB "ELEMENT COMPONENTS" +section. +.TP +\fIpathName \fBextents \fIitem\fR +Returns the size of a particular item in the graph. \fIItem\fR must +be either \f(CWleftmargin\fR, \f(CWrightmargin\fR, \f(CWtopmargin\fR, +\f(CWbottommargin\fR, \f(CWplotwidth\fR, or \f(CWplotheight\fR. +.TP +\fIpathName \fBgrid \fIoperation \fR?\fIarg\fR?... +See the +.SB "GRID COMPONENT" +section. +.TP +\fIpathName \fBinvtransform \fIwinX winY\fR +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 coordinates. +.TP +\fIpathName \fBinside \fIx y\fR +Returns \f(CW1\fR is the designated screen coordinate (\fIx\fR and \fIy\fR) +is inside the plotting area and \f(CW0\fR otherwise. +.TP +\fIpathName \fBlegend \fIoperation \fR?\fIarg\fR?... +See the +.SB "LEGEND COMPONENT" +section. +.TP +\fIpathName \fBline\fB operation arg\fR... +The operation is the same as \fBelement\fR. +.TP +\fIpathName \fBmarker \fIoperation \fR?\fIarg\fR?... +See the +.SB "MARKER COMPONENTS" +section. +.TP +\fIpathName \fBpostscript \fIoperation \fR?\fIarg\fR?... +See the +.SB "POSTSCRIPT COMPONENT" +section. +.TP +\fIpathName \fBsnap \fR?\fIswitches\fR? \fIoutputName\fR +Takes a snapshot of the graph, saving the output in \fIoutputName\fR. +The following switches are available. +.RS +.TP 1i +\fB\-format\fR \fIformat\fR +Specifies how the snapshot is output. \fIFormat\fR may be one of +the following listed below. The default is \f(CWphoto\fR. +.RS +.TP +\f(CWphoto\fR +Saves a Tk photo image. \fIOutputName\fR represents the name of a +Tk photo image that must already have been created. +.TP +\f(CWwmf\fR +Saves an Aldus Placeable Metafile. \fIOutputName\fR represents the +filename where the metafile is written. If \fIoutputName\fR is +\f(CWCLIPBOARD\fR, then output is written directly to the Windows +clipboard. This format is available only under Microsoft Windows. +.TP +\f(CWemf\fR +Saves an Enhanced Metafile. \fIOutputName\fR represents the filename +where the metafile is written. If \fIoutputName\fR is +\f(CWCLIPBOARD\fR, then output is written directly to the Windows +clipboard. This format is available only under Microsoft Windows. +.RE +.TP 1i +\fB\-height\fR \fIsize\fR +Specifies the height of the graph. \fISize\fR is a screen distance. +The graph will be redrawn using this dimension, rather than its +current window height. +.TP 1i +\fB\-width\fR \fIsize\fR +Specifies the width of the graph. \fISize\fR is a screen distance. +The graph will be redrawn using this dimension, rather than its +current window width. +.RE +.TP +\fIpathName \fBtransform \fIx y\fR +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. +.TP +\fIpathName \fBxaxis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fBx2axis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fByaxis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fBy2axis \fIoperation\fR ?\fIarg\fR?... +See the +.SB "AXIS COMPONENTS" +section. +.SH "GRAPH COMPONENTS" +A graph is composed of several components: coordinate axes, data +elements, legend, grid, cross hairs, postscript, and annotation +markers. Instead of one big set of configuration options and +operations, the graph is partitioned, where each component has its own +configuration options and operations that specifically control that +aspect or part of the graph. +.SS "AXIS COMPONENTS" +Four coordinate axes are automatically created: two X\-coordinate axes +(\f(CWx\fR and \f(CWx2\fR) and two Y\-coordinate axes (\f(CWy\fR, and +\f(CWy2\fR). By default, the axis \f(CWx\fR is located in the bottom +margin, \f(CWy\fR in the left margin, \f(CWx2\fR in the top margin, and +\f(CWy2\fR in the right margin. +.PP +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. +.PP +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 plotted. By default, the minimum and maximum limits are +determined from the data, but you can reset either limit. +.PP +You can have several axes. To create an axis, invoke +the axis component and its create operation. +.CS +# Create a new axis called "tempAxis" +\&.g axis create tempAxis +.CE +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. +.CS +# Now map the tempAxis data to this axis. +\&.g element create "e1" \-xdata $x \-ydata $y \-mapy tempAxis +.CE +Any number of axes can be displayed simultaneously. They are drawn in +the margins surrounding the plotting area. The default axes \f(CWx\fR +and \f(CWy\fR are drawn in the bottom and left margins. The axes +\f(CWx2\fR and \f(CWy2\fR are drawn in top and right margins. By +default, only \f(CWx\fR and \f(CWy\fR are shown. Note that the axes +can have different scales. +.PP +To display a different axis or more than one axis, you invoke one of +the following components: \fBxaxis\fR, \fByaxis\fR, \fBx2axis\fR, and +\fBy2axis\fR. Each component has a \fBuse\fR operation that +designates the axis (or axes) to be drawn in that corresponding +margin: \fBxaxis\fR in the bottom, \fByaxis\fR in the left, +\fBx2axis\fR in the top, and \fBy2axis\fR in the right. +.CS +# Display the axis tempAxis in the left margin. +\&.g yaxis use tempAxis +.CE +The \fBuse\fR operation takes a list of axis names as its last +argument. This is the list of axes to be drawn in this margin. +.PP +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. +.PP +.TP +\fIpathName \fBaxis bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for an axis with this +tag, \fIcommand\fR will be invoked. The syntax is similar to the +\fBbind\fR command except that it operates on graph axes, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBaxis \fBcget \fIaxisName \fIoption\fR +Returns the current value of the option given by \fIoption\fR for +\fIaxisName\fR. \fIOption\fR may be any option described below +for the axis \fBconfigure\fR operation. +.TP +\fIpathName \fBaxis \fBconfigure \fIaxisName \fR?\fIaxisName\fR?... ?\fIoption value\fR?... +Queries or modifies the configuration options of \fIaxisName\fR. +Several axes can be changed. If \fIoption\fR isn't specified, a list +describing all the current options for \fIaxisName\fR is returned. If +\fIoption\fR is specified, but not \fIvalue\fR, then a list describing +\fIoption\fR is returned. If one or more \fIoption\fR and \fIvalue\fR +pairs are specified, then for each pair, the axis option \fIoption\fR +is set to \fIvalue\fR. The following options are valid for axes. +.RS +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for the axis. \fITagList\fR is a list +of binding tag names. The tags and their order will determine how +events for axes are handled. 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 +\f(CWall\fR. +.TP +\fB\-color \fIcolor\fR +Sets the color of the axis and tick labels. +The default is \f(CWblack\fR. +.TP +\fB\-descending \fIboolean\fR +Indicates whether the values along the axis are monotonically increasing or +decreasing. If \fIboolean\fR is true, the axis values will be +decreasing. The default is \f(CW0\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates if the axis is displayed. If \fIboolean\fR is false the axis +will be displayed. Any element mapped to the axis is displayed regardless. +The default value is \f(CW0\fR. +.TP +\fB\-justify \fIjustify\fR +Specifies how the axis title should be justified. This matters only +when the axis title contains more than one line of text. \fIJustify\fR +must be \f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-limits \fIformatStr\fR +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. \fIFormatStr\fR is a list of +one or two format descriptions. If one description is supplied, both +the minimum and maximum limits are formatted in the same way. If two, +the first designates the format for the minimum limit, the second for +the maximum. If \f(CW""\fR is given as either description, then +the that limit will not be displayed. The default is \f(CW""\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the axis and tick lines. The default is \f(CW1\fR +pixel. +.TP +\fB\-logscale \fIboolean\fR +Indicates whether the scale of the axis is logarithmic or linear. If +\fIboolean\fR is true, the axis is logarithmic. The default scale is +linear. +.TP +\fB\-loose \fIboolean\fR +Indicates whether the limits of the axis should fit the data points tightly, +at the outermost data points, or loosely, at the outer tick intervals. +If the axis limit is set with the -min or -max option, the axes are +displayed tightly. +If \fIboolean\fR is true, the axis range is "loose". +The default is \f(CW0\fR. +.TP +\fB\-majorticks \fImajorList\fR +Specifies where to display major axis ticks. You can use this option +to display ticks at non-uniform intervals. \fIMajorList\fR is a list +of axis coordinates designating the location of major ticks. No +minor ticks are drawn. If \fImajorList\fR is \f(CW""\fR, +major ticks will be automatically computed. The default is \f(CW""\fR. +.TP +\fB\-max \fIvalue\fR +Sets the maximum limit of \fIaxisName\fR. Any data point greater +than \fIvalue\fR is not displayed. If \fIvalue\fR is \f(CW""\fR, +the maximum limit is calculated using the largest data value. +The default is \f(CW""\fR. +.TP +\fB\-min \fIvalue\fR +Sets the minimum limit of \fIaxisName\fR. Any data point less than +\fIvalue\fR is not displayed. If \fIvalue\fR is \f(CW""\fR, +the minimum limit is calculated using the smallest data value. +The default is \f(CW""\fR. +.TP +\fB\-minorticks \fIminorList\fR +Specifies where to display minor axis ticks. You can use this option +to display minor ticks at non-uniform intervals. \fIMinorList\fR 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 \fB\-majortick\fR +option is also set. If \fIminorList\fR is \f(CW""\fR, minor ticks will +be automatically computed. The default is \f(CW""\fR. +.TP +\fB\-rotate \fItheta\fR +Specifies the how many degrees to rotate the axis tick labels. +\fITheta\fR is a real value representing the number of degrees +to rotate the tick labels. The default is \f(CW0.0\fR degrees. +.TP +\fB\-scrollcommand \fIcommand\fR +Specify the prefix for a command used to communicate with scrollbars +for this axis, such as \fI.sbar set\fP. +.TP +\fB\-scrollmax \fIvalue\fR +Sets the maximum limit of the axis scroll region. If \fIvalue\fR is +\f(CW""\fR, the maximum limit is calculated using the largest data +value. The default is \f(CW""\fR. +.TP +\fB\-scrollmin \fIvalue\fR +Sets the minimum limit of axis scroll region. If \fIvalue\fR is +\f(CW""\fR, the minimum limit is calculated using the smallest data +value. The default is \f(CW""\fR. +.TP +\fB\-showticks \fIboolean\fR +Indicates whether axis ticks should be drawn. If \fIboolean\fR is +true, ticks are drawn. If false, only the +axis line is drawn. The default is \f(CW1\fR. +.TP +\fB\-stepsize \fIvalue\fR +Specifies the interval between major axis ticks. If \fIvalue\fR isn't +a valid interval (must be less than the axis range), +the request is ignored and the step size is automatically calculated. +.TP +\fB\-subdivisions \fInumber\fR +Indicates how many minor axis ticks are +to be drawn. For example, if \fInumber\fR is two, only one minor +tick is drawn. If \fInumber\fR is one, no minor ticks are +displayed. The default is \f(CW2\fR. +.TP +\fB\-tickfont \fIfontName\fR +Specifies the font for axis tick labels. The default is +\f(CW*-Courier-Bold-R-Normal-*-100-*\fR. +.TP +\fB\-tickformat\fR \fIformatStr\fR +Specifies a printf-like description to format teh axis +tick labels. You can get the standard tick labels again by +setting \fIformatStr\fR to \f(CW""\fR. The default is \f(CW""\fR. +.TP +\fB\-tickformatcommand\fR, \fB\-command \fIprefix\fR +Specifies a Tcl command to be invoked when formatting the axis tick +labels. \fIPrefix\fR 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 +\f(CW""\fR is returned, no label will appear next to the tick. You can +get the standard tick labels again by setting \fIprefix\fR to +\f(CW""\fR. The default is \f(CW""\fR. +.sp 1 +The numeric value for the tick might change when using the +\fB\-logscale\fR and \fB\-tickformat\fR options. +.sp 1 +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. +.TP +\fB\-ticklength \fIpixels\fR +Sets the length of major and minor ticks (minor ticks are half the +length of major ticks). If \fIpixels\fR is less than zero, the axis +will be inverted with ticks drawn pointing towards the plot. The +default is \f(CW0.1i\fR. +.TP +\fB\-title \fItext\fR +Sets the title of the axis. If \fItext\fR is +\f(CW""\fR, no axis title will be displayed. +.TP +\fB\-titlealternate \fIboolean\fR +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 \f(CW0\fR. +.TP +\fB\-titlecolor \fIcolor\fR +Sets the color of the axis title. The default is \f(CWblack\fR. +.TP +\fB\-titlefont \fIfontName\fR +Specifies the font for axis title. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-14-140-*\fR. +.PP +Axis configuration options may be also be set by the \fBoption\fR +command. The resource class is \f(CWAxis\fR. The resource names +are the names of the axes (such as \f(CWx\fR or \f(CWx2\fR). +.CS +option add *Graph.Axis.Color blue +option add *Graph.x.LogScale true +option add *Graph.x2.LogScale false +.CE +.RE +.TP +\fIpathName \fBaxis \fBcreate \fIaxisName \fR?\fIoption value\fR?... +Creates a new axis by the name \fIaxisName\fR. No axis by the same +name can already exist. \fIOption\fR and \fIvalue\fR are described +in above in the axis \fBconfigure\fR operation. +.TP +\fIpathName \fBaxis \fBdelete \fR?\fIaxisName\fR?... +Deletes the named axes. An axis is not really +deleted until it is not longer in use, so it's safe to delete +axes mapped to elements. +.TP +\fIpathName \fBaxis invtransform \fIaxisName value\fR +Performs the inverse transformation, changing the screen coordinate +\fIvalue\fR to a graph coordinate, mapping the value mapped to +\fIaxisName\fR. Returns the graph coordinate. +.TP +\fIpathName \fBaxis limits \fIaxisName\fR +Returns a list of the minimum and maximum limits for \fIaxisName\fR. The order +of the list is \f(CWmin max\fR. +.TP +\fIpathName \fBaxis names \fR?\fIpattern\fR?... +Returns a list of axes matching zero or more patterns. If no +\fIpattern\fR argument is give, the names of all axes are returned. +.TP +\fIpathName \fBaxis transform \fIaxisName value\fR +Transforms the coordinate \fIvalue\fR to a screen coordinate by mapping +the it to \fIaxisName\fR. Returns the transformed screen coordinate. +.TP +\fIpathName \fBaxis view \fIaxisName\fR +Change the viewable area of this axis. Use as an argument to a scrollbar's "\fI\-command\fR". +.PP +The default axes are \f(CWx\fR, \f(CWy\fR, \f(CWx2\fR, and \f(CWy2\fR. +But you can display more than four axes simultaneously. You can also +swap in a different axis with \fBuse\fR operation of the special axis +components: \fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, and \fBy2axis\fR. +.CS +\&.g create axis temp +\&.g create axis time +\&... +\&.g xaxis use temp +\&.g yaxis use time +.CE +Only the axes specified for use are displayed on the screen. +.PP +The \fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, and \fBy2axis\fR +components operate on an axis location rather than a specific axis +like the more general \fBaxis\fR component does. They implicitly +control the axis that is currently using to that location. By +default, \fBxaxis\fR uses the \f(CWx\fR axis, \fByaxis\fR uses +\f(CWy\fR, \fBx2axis\fR uses \f(CWx2\fR, and \fBy2axis\fR uses +\f(CWy2\fR. When more than one axis is displayed in a margin, it +represents the first axis displayed. +.PP +The following operations are available for axes. They mirror exactly +the operations of the \fBaxis\fR component. The \fIaxis\fR argument +must be \fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, or \fBy2axis\fR. This +feature is deprecated since more than one axis can now be used a +margin. You should only use the \fBxaxis\fR, \fBx2axis\fR, +\fByaxis\fR, and \fBy2axis\fR components with the \fBuse\fR operation. +For all other operations, use the general \fBaxis\fR component +instead. +.TP +\fIpathName \fIaxis \fBcget \fIoption\fR +.TP +\fIpathName \fIaxis \fBconfigure \fR?\fIoption value\fR?... +.TP +\fIpathName \fIaxis\fB invtransform \fIvalue\fR +.TP +\fIpathName \fIaxis \fBlimits\fR +.TP +\fIpathName \fIaxis\fB transform \fIvalue\fR +.TP +\fIpathName \fIaxis\fB use \fR?\fIaxisName\fR? +Designates the axis \fIaxisName\fR is to be displayed at this +location. \fIAxisName\fR can not be already in use at another location. +This command returns the name of the axis currently using this location. +.SS "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 without redrawing +the entire graph. +.PP +The following operations are available for cross hairs: +.TP +\fIpathName \fBcrosshairs cget \fIoption\fR +Returns the current value of the cross hairs configuration option +given by \fIoption\fR. \fIOption\fR may be any option +described below for the cross hairs \fBconfigure\fR operation. +.TP +\fIpathName \fBcrosshairs configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options of the cross hairs. If +\fIoption\fR isn't specified, a list describing all the current +options for the cross hairs is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the cross hairs option \fIoption\fR is set to +\fIvalue\fR. +The following options are available for cross hairs. +.RS +.TP +\fB\-color \fIcolor\fR +Sets the color of the cross hairs. The default is \f(CWblack\fR. +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the cross hairs. \fIDashList\fR 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 \fIdashList\fR is \f(CW""\fR, the cross hairs will be solid +lines. +.TP +\fB\-hide \fIboolean\fR +Indicates whether cross hairs are drawn. If \fIboolean\fR is true, +cross hairs are not drawn. The default is \f(CWyes\fR. +.TP +\fB\-linewidth \fIpixels\fR +Set the width of the cross hair lines. The default is \f(CW1\fR. +.TP +\fB\-position \fIpos\fR +Specifies the screen position where the cross hairs intersect. +\fIPos\fR must be in the form "\fI@x,y\fR", where \fIx\fR and \fIy\fR +are the window coordinates of the intersection. +.PP +Cross hairs configuration options may be also be set by the +\fBoption\fR command. The resource name and class are +\f(CWcrosshairs\fR and \f(CWCrosshairs\fR respectively. +.CS +option add *Graph.Crosshairs.LineWidth 2 +option add *Graph.Crosshairs.Color red +.CE +.RE +.TP +\fIpathName \fBcrosshairs off\fR +Turns off the cross hairs. +.TP +\fIpathName \fBcrosshairs on\fR +Turns on the display of the cross hairs. +.TP +\fIpathName \fBcrosshairs toggle\fR +Toggles the current state of the cross hairs, alternately mapping and +unmapping the cross hairs. +.SS "ELEMENT COMPONENTS" +A data element represents a set of data. It contains x and y vectors +containing the coordinates of the data points. Elements can be +displayed with a symbol at each data point and lines connecting the +points. Elements also control the appearance of the data, such as the +symbol type, line width, color etc. +.PP +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. +.PP +The following operations are available for elements. +.TP +\fIpathName \fBelement activate \fIelemName \fR?\fIindex\fR?... +Specifies the data points of element \fIelemName\fR to be drawn +using active foreground and background colors. \fIElemName\fR is the +name of the element and \fIindex\fR is a number representing the index +of the data point. If no indices are present then all data points +become active. +.TP +\fIpathName \fBelement bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for an element with this +tag, \fIcommand\fR will be invoked. The syntax is similar to the +\fBbind\fR command except that it operates on graph elements, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBelement cget \fIelemName \fIoption\fR +Returns the current value of the element configuration option given by +\fIoption\fR. \fIOption\fR may be any of the options described below +for the element \fBconfigure\fR operation. +.TP +\fIpathName \fBelement closest \fIx y\fR ?\fIoption value\fR?... ?\fIelemName\fR?... +Searches for the data point closest to the window coordinates \fIx\fR +and \fIy\fR. By default, all elements are searched. Hidden elements +(see the \fB\-hide\fR option is false) are ignored. You can limit the +search by specifying only the elements you want to be considered. +\fIElemName\fR 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 \f(CW""\fR, if no data point within the threshold distance +can be found. The following +\fIoption\fR\-\fIvalue\fR pairs are available. +.RS +.TP +\fB\-along \fIdirection\fR +Search for the closest element using the following criteria: +.RS +.TP +\f(CWx\fR +Find closest element vertically from the given X-coordinate. +.TP +\f(CWy\fR +Find the closest element horizontally from the given Y-coordinate. +.TP +\f(CWboth\fR +Find the closest element for the given point (using both the X and Y +coordinates). +.RE +.TP +\fB\-halo \fIpixels\fR +Specifies a threshold distance where selected data points are ignored. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +If this option isn't specified, then it defaults to the value of the +graph's \fB\-halo\fR option. +.TP +\fB\-interpolate \fIstring\fR +Indicates whether to consider projections that lie along the line segments +connecting data points when searching for the closest point. +The default value is \f(CW0\fR. The values for \fIstring\fR are +described below. +.RS +.TP 1.25i +\f(CWno\fR +Search only for the closest data point. +.TP +\f(CWyes\fR +Search includes projections that lie along the +line segments connecting the data points. +.RE +.RE +.TP +\fIpathName \fBelement configure \fIelemName \fR?\fIelemName\fR... ?\fIoption value\fR?... +Queries or modifies the configuration options for elements. Several +elements can be modified at the same time. If \fIoption\fR isn't +specified, a list describing all the current options for +\fIelemName\fR is returned. If \fIoption\fR is specified, but not +\fIvalue\fR, then a list describing the option \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the element option \fIoption\fR is set +to \fIvalue\fR. The following options are valid for elements. +.RS +.TP +\fB\-activepen \fIpenName\fR +Specifies pen to use to draw active element. If \fIpenName\fR is +\f(CW""\fR, no active elements will be drawn. The default is +\f(CWactiveLine\fR. +.TP +\fB\-areabackground \fIcolor\fR +Specifies the background color of the area under the curve. The +background area color is drawn only for bitmaps (see the +\fB\-areapattern\fR option). If \fIcolor\fR is \f(CW""\fR, the +background is transparent. The default is \f(CWblack\fR. +.TP +\fB\-areaforeground \fIcolor\fR +Specifies the foreground color of the area under the curve. +The default is \f(CWblack\fR. +.TP +\fB\-areapattern \fIpattern\fR +Specifies how to fill the area under the curve. \fIPattern\fR may be +the name of a Tk bitmap, \f(CWsolid\fR, or \f(CW""\fR. If "solid", +then the area under the curve is drawn with the color designated by +the \fB\-areaforeground\fR option. If a bitmap, then the bitmap is +stippled across the area. Here the bitmap colors are controlled by the +\fB\-areaforeground\fR and \fB\-areabackground\fR options. If +\fIpattern\fR is \f(CW""\fR, no filled area is drawn. The default is +\f(CW""\fR. +.TP +\fB\-areatile \fIimage\fR +Specifies the name of a Tk image to be used to tile the area under the +curve. This option supersedes the \fB\-areapattern\fR option. +\fIImage\fR must be a photo image. If \fIimage\fR is \f(CW""\fR, no +tiling is performed. The default is \f(CW""\fR. +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for the element. \fITagList\fR 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 +\f(CWall\fR. +.TP +\fB\-color \fIcolor\fR +Sets the color of the traces connecting the data points. +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of element line. \fIDashList\fR 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 +\fIdashList\fR is \f(CW""\fR, the lines will be solid. +.TP +\fB\-data \fIcoordList\fR +Specifies the X\-Y coordinates of the data. \fICoordList\fR is a +list of numeric expressions representing the X\-Y coordinate pairs +of each data point. +.TP +\fB\-fill \fIcolor\fR +Sets the interior color of symbols. If \fIcolor\fR is \f(CW""\fR, then +the interior of the symbol is transparent. If \fIcolor\fR is +\f(CWdefcolor\fR, then the color will be the same as the \fB\-color\fR +option. The default is \f(CWdefcolor\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the element is displayed. +The default is \f(CWno\fR. +.TP +\fB\-label \fItext\fR +Sets the element's label in the legend. If \fItext\fR +is \f(CW""\fR, the element will have no entry in the legend. +The default label is the element's name. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the connecting lines between data points. If +\fIpixels\fR is \f(CW0\fR, no connecting lines will be drawn between +symbols. The default is \f(CW0\fR. +.TP +\fB\-mapx \fIxAxis\fR +Selects the X\-axis to map the element's X\-coordinates onto. +\fIXAxis\fR must be the name of an axis. The default is \f(CWx\fR. +.TP +\fB\-mapy \fIyAxis\fR +Selects the Y\-axis to map the element's Y\-coordinates onto. +\fIYAxis\fR must be the name of an axis. The default is \f(CWy\fR. +.TP +\fB\-offdash \fIcolor\fR +Sets the color of the stripes when traces are dashed (see the +\fB\-dashes\fR option). If \fIcolor\fR is \f(CW""\fR, then the "off" +pixels will represent gaps instead of stripes. If \fIcolor\fR is +\f(CWdefcolor\fR, then the color will be the same as the \fB\-color\fR +option. The default is \f(CWdefcolor\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the color or the outline around each symbol. If \fIcolor\fR is +\f(CW""\fR, then no outline is drawn. If \fIcolor\fR is \f(CWdefcolor\fR, +then the color will be the same as the \fB\-color\fR option. The +default is \f(CWdefcolor\fR. +.TP +\fB\-pen \fIpenname\fR +Set the pen to use for this element. +.TP +\fB\-outlinewidth \fIpixels\fR +Sets the width of the outline bordering each symbol. If \fIpixels\fR +is \f(CW0\fR, no outline will be drawn. The default is \f(CW1\fR. +.TP +\fB\-pixels \fIpixels\fR +Sets the size of symbols. If \fIpixels\fR is \f(CW0\fR, no symbols will +be drawn. The default is \f(CW0.125i\fR. +.TP +\fB\-scalesymbols \fIboolean\fR +If \fIboolean\fR is true, the size of the symbols +drawn for \fIelemName\fR 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 \fB\-pixels\fR +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 \fIboolean\fR +is false, the element's symbols are drawn at the designated size, +regardless of axis scales. The default is \f(CW0\fR. +.TP +\fB\-smooth \fIsmooth\fR +Specifies how connecting line segments are drawn between data points. +\fISmooth\fR can be either \f(CWlinear\fR, \f(CWstep\fR, \f(CWnatural\fR, or +\f(CWquadratic\fR. If \fIsmooth\fR is \f(CWlinear\fR, a single line +segment is drawn, connecting both data points. When \fIsmooth\fR is +\f(CWstep\fR, two line segments are drawn. The first is a horizontal +line segment that steps the next X\-coordinate. The second is a +vertical line, moving to the next Y\-coordinate. Both \fInatural\fR and +\fIquadratic\fR generate multiple segments between data points. If +\fInatural\fR, the segments are generated using a cubic spline. If +\fIquadratic\fR, a quadratic spline is used. The default is +\fIlinear\fR. +.TP +\fB\-styles \fIstyleList\fR +Specifies what pen to use based on the range of weights given. +\fIStyleList\fR 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 \fB\-weight\fR 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. +.TP +\fB\-symbol \fIsymbol\fR +Specifies the symbol for data points. \fISymbol\fR can be either +\f(CWsquare\fR, \f(CWcircle\fR, \f(CWdiamond\fR, \f(CWplus\fR, \f(CWcross\fR, +\f(CWsplus\fR, \f(CWscross\fR, \f(CWtriangle\fR, \f(CW""\fR (where no symbol +is drawn), or a bitmap. Bitmaps are specified as "\fIsource\fR +?\fImask\fR?", where \fIsource\fR is the name of the bitmap, and +\fImask\fR is the bitmap's optional mask. The default is +\f(CWcircle\fR. +.TP +\fB\-trace \fIdirection\fR +Indicates whether connecting lines between data points (whose +X\-coordinate values are either increasing or decreasing) are drawn. +\fIDirection\fR +must be \f(CWincreasing\fR, \f(CWdecreasing\fR, or \f(CWboth\fR. For +example, if \fIdirection\fR is \f(CWincreasing\fR, connecting lines will +be drawn only between those data points where X\-coordinate values are +monotonically increasing. If \fIdirection\fR is \f(CWboth\fR, +connecting lines will be draw between all data points. The default is +\f(CWboth\fR. +.TP +\fB\-weights \fIwVec\fR +Specifies the weights of the individual data points. This, +with the list pen styles (see the \fB\-styles\fR option), +controls how data points are drawn. \fIWVec\fR is the name of a BLT +vector or a list of numeric expressions representing the weights for +each data point. +.TP +\fB\-xdata \fIxVec\fR +Specifies the X\-coordinates of the data. \fIXVec\fR is the name of +a BLT vector or a list of numeric expressions. +.TP +\fB\-ydata \fIyVec\fR +Specifies the Y\-coordinates of the data. \fIYVec\fR is the name of +a BLT vector or a list of numeric expressions. +.PP +Element configuration options may also be set by the \fBoption\fR +command. The resource class is \f(CWElement\fR. The resource name is +the name of the element. +.CS +option add *Graph.Element.symbol line +option add *Graph.e1.symbol line +.CE +.RE +.TP +\fIpathName \fBelement create \fIelemName\fR ?\fIoption value\fR?... +Creates a new element \fIelemName\fR. It's an error is +an element \fIelemName\fR already exists. If +additional arguments are present, they specify options valid for +the element \fBconfigure\fR operation. +.TP +\fIpathName \fBelement deactivate \fIelemName\fR ?\fIelemName\fR?... +Deactivates all the elements matching \fIpattern\fR. +Elements whose names match any of the patterns given are redrawn using +their normal colors. +.TP +\fIpathName \fBelement delete\fR ?\fIelemName\fR?... +Deletes all the named elements. The graph is automatically redrawn. +.TP +\fIpathName \fBelement exists \fIelemName\fR +Returns \f(CW1\fR if an element \fIelemName\fR currently exists and +\f(CW0\fR otherwise. +.TP +\fIpathName \fBelement names \fR?\fIpattern\fR?... +Returns the elements matching one or more pattern. If no +\fIpattern\fR is given, the names of all elements is returned. +.TP +\fIpathName \fBelement show\fR ?\fInameList\fR? +Queries or modifies the element display list. The element display +list designates the elements drawn and in what +order. \fINameList\fR is a list of elements to be displayed in the +order they are named. If there is no \fInameList\fR argument, +the current display list is returned. +.TP +\fIpathName \fBelement type\fR \fIelemName\fR +Returns the type of \fIelemName\fR. +If the element is a bar element, the commands returns the string +\f(CW"bar"\fR, otherwise it returns \f(CW"line"\fR. +.CE +.SS "GRID COMPONENT" +Grid lines extend from the major and minor ticks of each axis +horizontally or vertically across the plotting area. The following +operations are available for grid lines. +.TP +\fIpathName \fBgrid cget \fIoption\fR +Returns the current value of the grid line configuration option given by +\fIoption\fR. \fIOption\fR may be any option described below +for the grid \fBconfigure\fR operation. +.TP +\fIpathName \fBgrid configure\fR ?\fIoption value\fR?... +Queries or modifies the configuration options for grid lines. If +\fIoption\fR isn't specified, a list describing all the current +grid options for \fIpathName\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the grid line option \fIoption\fR is set to +\fIvalue\fR. The following options are valid for grid lines. +.RS +.TP +\fB\-color \fIcolor\fR +Sets the color of the grid lines. The default is \f(CWblack\fR. +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the grid lines. \fIDashList\fR 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 \fIdashList\fR is \f(CW""\fR, the grid will be solid lines. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the grid should be drawn. If \fIboolean\fR +is true, grid lines are not shown. The default is \f(CWyes\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of grid lines. The default width is \f(CW1\fR. +.TP +\fB\-mapx \fIxAxis\fR +Specifies the X\-axis to display grid lines. \fIXAxis\fR +must be the name of an axis or \f(CW""\fR for no grid lines. +The default is \f(CW""\fR. +.TP +\fB\-mapy \fIyAxis\fR +Specifies the Y\-axis to display grid lines. \fIYAxis\fR +must be the name of an axis or \f(CW""\fR for no grid lines. +The default is \f(CWy\fR. +.TP +\fB\-minor \fIboolean\fR +Indicates whether the grid lines should be drawn for minor ticks. +If \fIboolean\fR is true, the lines will appear at +minor tick intervals. The default is \f(CW1\fR. +.PP +Grid configuration options may also be set by the +\fBoption\fR command. The resource name and class are \f(CWgrid\fR and +\f(CWGrid\fR respectively. +.CS +option add *Graph.grid.LineWidth 2 +option add *Graph.Grid.Color black +.CE +.RE +.TP +\fIpathName \fBgrid off\fR +Turns off the display the grid lines. +.TP +\fIpathName \fBgrid on\fR +Turns on the display the grid lines. +.TP +\fIpathName \fBgrid toggle\fR +Toggles the display of the grid. +.SS "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 positioned anywhere within the plotting area. +.PP +The following operations are valid for the legend. +.TP +\fIpathName \fBlegend activate \fIpattern\fR... +Selects legend entries to be drawn using the active legend colors and relief. +All entries whose element names match \fIpattern\fR are selected. To +be selected, the element name must match only one \fIpattern\fR. +.TP +\fIpathName \fBlegend bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for a legend entry with this +tag, \fIcommand\fR will be invoked. Implicitly the element names +in the entry are tags. The syntax is similar to the +\fBbind\fR command except that it operates on legend entries, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBlegend cget \fIoption\fR +Returns the current value of a legend configuration option. +\fIOption\fR may be any option described below in the +legend \fBconfigure\fR operation. +.TP +\fIpathName \fBlegend configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options for the legend. If +\fIoption\fR isn't specified, a list describing the current +legend options for \fIpathName\fR is returned. If \fIoption\fR is +specified, but not \fIvalue\fR, then a list describing \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the legend option \fIoption\fR is set +to \fIvalue\fR. The following options are valid for the legend. +.RS +.TP +\fB\-activebackground \fIcolor\fR +Sets the background color for active legend entries. All legend +entries marked active (see the legend \fBactivate\fR operation) are +drawn using this background color. +.TP +\fB\-activeborderwidth \fIpixels\fR +Sets the width of the 3-D border around the outside edge of the active legend +entries. The default is \f(CW2\fR. +.TP +\fB\-activeforeground \fIcolor\fR +Sets the foreground color for active legend entries. All legend +entries marked as active (see the legend \fBactivate\fR operation) are +drawn using this foreground color. +.TP +\fB\-activerelief \fIrelief\fR +Specifies the 3-D effect desired for active legend entries. +\fIRelief\fR denotes how the interior of the entry should appear +relative to the legend; for example, \f(CWraised\fR means the entry +should appear to protrude from the legend, relative to the surface of +the legend. The default is \f(CWflat\fR. +.TP +\fB\-anchor \fIanchor\fR +Tells how to position the legend relative to the positioning point for +the legend. This is dependent on the value of the \fB\-position\fR +option. The default is \f(CWcenter\fR. +.RS +.TP 1.25i +\f(CWleft\fR or \f(CWright\fR +The anchor describes how to position the legend vertically. +.TP +\f(CWtop\fR or \f(CWbottom\fR +The anchor describes how to position the legend horizontally. +.TP +\f(CW@x,y\fR +The anchor specifies how to position the legend relative to the +positioning point. For example, if \fIanchor\fR is \f(CWcenter\fR then +the legend is centered on the point; if \fIanchor\fR is \f(CWn\fR then +the legend will be drawn such that the top center point of the +rectangular region occupied by the legend will be at the positioning +point. +.TP +\f(CWplotarea\fR +The anchor specifies how to position the legend relative to the +plotting area. For example, if \fIanchor\fR is \f(CWcenter\fR then the +legend is centered in the plotting area; if \fIanchor\fR is \f(CWne\fR +then the legend will be drawn such that occupies the upper right +corner of the plotting area. +.RE +.TP +\fB\-background \fIcolor\fR +Sets the background color of the legend. If \fIcolor\fR is \f(CW""\fR, +the legend background with be transparent. +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for legend entries. \fITagList\fR is a list +of binding tag names. The tags and their order will determine how +events are handled for legend entries. Each tag in the list matching +the current event sequence will have its Tcl command executed. The +default value is \f(CWall\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the width of the 3-D border around the outside edge of the legend (if +such border is being drawn; the \fBrelief\fR option determines this). +The default is \f(CW2\fR pixels. +.TP +\fB\-font \fIfontName\fR +\fIFontName\fR specifies a font to use when drawing the labels of each +element into the legend. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-12-120-*\fR. +.TP +\fB\-foreground \fIcolor\fR +Sets the foreground color of the text drawn for the element's label. +The default is \f(CWblack\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the legend should be displayed. If \fIboolean\fR is +true, the legend will not be draw. The default is \f(CWno\fR. +.TP +\fB\-ipadx \fIpad\fR +Sets the amount of internal padding to be added to the width of each +legend entry. \fIPad\fR can be a list of one or two screen distances. If +\fIpad\fR has two elements, the left side of the legend entry is +padded by the first distance and the right side by the second. If +\fIpad\fR is just one distance, both the left and right sides are padded +evenly. The default is \f(CW2\fR. +.TP +\fB\-ipady \fIpad\fR +Sets an amount of internal padding to be added to the height of each +legend entry. \fIPad\fR can be a list of one or two screen distances. If +\fIpad\fR has two elements, the top of the entry is padded by the +first distance and the bottom by the second. If \fIpad\fR is just +one distance, both the top and bottom of the entry are padded evenly. +The default is \f(CW2\fR. +.TP +\fB\-padx \fIpad\fR +Sets the padding to the left and right exteriors of the legend. +\fIPad\fR can be a list of one or two screen distances. If \fIpad\fR +has two elements, the left side of the legend is padded by the first +distance and the right side by the second. If \fIpad\fR has just one +distance, both the left and right sides are padded evenly. The +default is \f(CW4\fR. +.TP +\fB\-pady \fIpad\fR +Sets the padding above and below the legend. \fIPad\fR can be a list +of one or two screen distances. If \fIpad\fR has two elements, the area above +the legend is padded by the first distance and the area below by the +second. If \fIpad\fR is just one distance, both the top and +bottom areas are padded evenly. The default is \f(CW0\fR. +.TP +\fB\-position \fIpos\fR +Specifies where the legend is drawn. The +\fB\-anchor\fR option also affects where the legend is positioned. If +\fIpos\fR is \f(CWleft\fR, \f(CWleft\fR, \f(CWtop\fR, or \f(CWbottom\fR, the +legend is drawn in the specified margin. If \fIpos\fR is +\f(CWplotarea\fR, then the legend is drawn inside the plotting area at a +particular anchor. If \fIpos\fR is in the form "\fI@x,y\fR", where +\fIx\fR and \fIy\fR are the window coordinates, the legend is drawn in +the plotting area at the specified coordinates. The default is +\f(CWright\fR. +.TP +\fB\-raised \fIboolean\fR +Indicates whether the legend is above or below the data elements. This +matters only if the legend is in the plotting area. If \fIboolean\fR +is true, the legend will be drawn on top of any elements that may +overlap it. The default is \f(CWno\fR. +.TP +\fB\-relief \fIrelief\fR +Specifies the 3-D effect for the border around the legend. +\fIRelief\fR specifies how the interior of the legend should appear +relative to the graph; for example, \f(CWraised\fR means the legend +should appear to protrude from the graph, relative to the surface of +the graph. The default is \f(CWsunken\fR. +.PP +Legend configuration options may also be set by the \fBoption\fR +command. The resource name and class are \f(CWlegend\fR and +\f(CWLegend\fR respectively. +.CS +option add *Graph.legend.Foreground blue +option add *Graph.Legend.Relief raised +.CE +.RE +.TP +\fIpathName \fBlegend deactivate \fIpattern\fR... +Selects legend entries to be drawn using the normal legend colors and +relief. All entries whose element names match \fIpattern\fR are +selected. To be selected, the element name must match only one +\fIpattern\fR. +.TP +\fIpathName \fBlegend get \fIpos\fR +Returns the name of the element whose entry is at the screen position +\fIpos\fR in the legend. \fIPos\fR must be in the form "\fI@x,y\fR", +where \fIx\fR and \fIy\fR are window coordinates. If the given +coordinates do not lie over a legend entry, \f(CW""\fR is returned. +.SS "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 \fB\-weight\fR and +\fB\-style\fR options). +.PP +One pen, called \f(CWactiveLine\fR, 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. +.CS +\&.g pen configure "activeLine" -color green +.CE +You can create and use several pens. To create a pen, invoke +the pen component and its create operation. +.CS +\&.g pen create myPen +.CE +You map pens to a data element using either the element's +\fB\-pen\fR or \fB\-activepen\fR options. +.CS +\&.g element create "line1" -xdata $x -ydata $tempData \\ + -pen myPen +.CE +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 +\fB\-styles\fR option). +.CS +\&.g element configure "line1" -styles { myPen 2.0 3.0 } +.CE +This says that any data point with a weight between 2.0 and 3.0 +is to be drawn using the pen \f(CWmyPen\fR. All other points +are drawn with the element's default attributes. +.PP +The following operations are available for pen components. +.PP +.TP +\fIpathName \fBpen \fBcget \fIpenName \fIoption\fR +Returns the current value of the option given by \fIoption\fR for +\fIpenName\fR. \fIOption\fR may be any option described below +for the pen \fBconfigure\fR operation. +.TP +\fIpathName \fBpen \fBconfigure \fIpenName \fR?\fIpenName\fR... ?\fIoption value\fR?... +Queries or modifies the configuration options of +\fIpenName\fR. Several pens can be modified at once. If \fIoption\fR +isn't specified, a list describing the current options for +\fIpenName\fR is returned. If \fIoption\fR is specified, but not +\fIvalue\fR, then a list describing \fIoption\fR is returned. If one +or more \fIoption\fR and \fIvalue\fR pairs are specified, then for +each pair, the pen option \fIoption\fR is set to \fIvalue\fR. The +following options are valid for pens. +.RS +.TP +\fB\-color \fIcolor\fR +Sets the color of the traces connecting the data points. +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of element line. \fIDashList\fR 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 +\fIdashList\fR is \f(CW""\fR, the lines will be solid. +.TP +\fB\-fill \fIcolor\fR +Sets the interior color of symbols. If \fIcolor\fR is \f(CW""\fR, then +the interior of the symbol is transparent. If \fIcolor\fR is +\f(CWdefcolor\fR, then the color will be the same as the \fB\-color\fR +option. The default is \f(CWdefcolor\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the connecting lines between data points. If +\fIpixels\fR is \f(CW0\fR, no connecting lines will be drawn between +symbols. The default is \f(CW0\fR. +.TP +\fB\-offdash \fIcolor\fR +Sets the color of the stripes when traces are dashed (see the +\fB\-dashes\fR option). If \fIcolor\fR is \f(CW""\fR, then the "off" +pixels will represent gaps instead of stripes. If \fIcolor\fR is +\f(CWdefcolor\fR, then the color will be the same as the \fB\-color\fR +option. The default is \f(CWdefcolor\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the color or the outline around each symbol. If \fIcolor\fR is +\f(CW""\fR, then no outline is drawn. If \fIcolor\fR is \f(CWdefcolor\fR, +then the color will be the same as the \fB\-color\fR option. The +default is \f(CWdefcolor\fR. +.TP +\fB\-outlinewidth \fIpixels\fR +Sets the width of the outline bordering each symbol. If \fIpixels\fR +is \f(CW0\fR, no outline will be drawn. The default is \f(CW1\fR. +.TP +\fB\-pixels \fIpixels\fR +Sets the size of symbols. If \fIpixels\fR is \f(CW0\fR, no symbols will +be drawn. The default is \f(CW0.125i\fR. +.TP +\fB\-symbol \fIsymbol\fR +Specifies the symbol for data points. \fISymbol\fR can be either +\f(CWsquare\fR, \f(CWcircle\fR, \f(CWdiamond\fR, \f(CWplus\fR, \f(CWcross\fR, +\f(CWsplus\fR, \f(CWscross\fR, \f(CWtriangle\fR, \f(CW""\fR (where no symbol +is drawn), or a bitmap. Bitmaps are specified as "\fIsource\fR +?\fImask\fR?", where \fIsource\fR is the name of the bitmap, and +\fImask\fR is the bitmap's optional mask. The default is +\f(CWcircle\fR. +.TP +\fB\-type \fIelemType\fR +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 "line". +.PP +Pen configuration options may be also be set by the \fBoption\fR +command. The resource class is \f(CWPen\fR. The resource names +are the names of the pens. +.CS +option add *Graph.Pen.Color blue +option add *Graph.activeLine.color green +.CE +.RE +.TP +\fIpathName \fBpen \fBcreate \fIpenName \fR?\fIoption value\fR?... +Creates a new pen by the name \fIpenName\fR. No pen by the same +name can already exist. \fIOption\fR and \fIvalue\fR are described +in above in the pen \fBconfigure\fR operation. +.TP +\fIpathName \fBpen \fBdelete \fR?\fIpenName\fR?... +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 elements. +.TP +\fIpathName \fBpen names \fR?\fIpattern\fR?... +Returns a list of pens matching zero or more patterns. If no +\fIpattern\fR argument is give, the names of all pens are returned. +.SS "POSTSCRIPT COMPONENT" +The graph can generate encapsulated PostScript output. There +are several 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. +.PP +The following postscript operations are available. +.TP +\fIpathName \fBpostscript cget \fIoption\fR +Returns the current value of the postscript option given by +\fIoption\fR. \fIOption\fR may be any option described +below for the postscript \fBconfigure\fR operation. +.TP +\fIpathName \fBpostscript configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options for PostScript +generation. If \fIoption\fR isn't specified, a list describing +the current postscript options for \fIpathName\fR is returned. If +\fIoption\fR is specified, but not \fIvalue\fR, then a list describing +\fIoption\fR is returned. If one or more \fIoption\fR and \fIvalue\fR +pairs are specified, then for each pair, the postscript option +\fIoption\fR is set to \fIvalue\fR. The following postscript options +are available. +.RS +.TP +\fB\-center \fIboolean\fR +Indicates whether the plot should be centered on the PostScript page. If +\fIboolean\fR is false, the plot will be placed in the upper left +corner of the page. The default is \f(CW1\fR. +.TP +\fB\-colormap \fIvarName\fR +\fIVarName\fR must be the name of a global array variable that +specifies a color mapping from the X color name to PostScript. Each +element of \fIvarName\fR must consist of PostScript code to set a +particular color value (e.g. ``\f(CW1.0 1.0 0.0 setrgbcolor\fR''). When +generating color information in PostScript, the array variable \fIvarName\fR +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 \fIvarName\fR for a given color, then it uses +the red, green, and blue intensities from the X color. +.TP +\fB\-colormode \fImode\fR +Specifies how to output color information. \fIMode\fR must be either +\f(CWcolor\fR (for full color output), \f(CWgray\fR (convert all colors to +their gray-scale equivalents) or \f(CWmono\fR (convert foreground colors +to black and background colors to white). The default mode is +\f(CWcolor\fR. +.TP +\fB\-fontmap \fIvarName\fR +\fIVarName\fR must be the name of a global array variable that +specifies a font mapping from the X font name to PostScript. Each +element of \fIvarName\fR 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 \fIvarName\fR 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). Otherwise the X font is examined in an +attempt to guess what PostScript font to use. This works only for +fonts whose foundry property is \fIAdobe\fR (such as Times, Helvetica, +Courier, etc.). If all of this fails then the font defaults to +\f(CWHelvetica-Bold\fR. +.TP +\fB\-decorations \fIboolean\fR +Indicates whether PostScript commands to generate color backgrounds and 3-D +borders will be output. If \fIboolean\fR is false, the background will be +white and no 3-D borders will be generated. The +default is \f(CW1\fR. +.TP +\fB\-height \fIpixels\fR +Sets the height of the plot. This lets you print the graph with a +height different from the one drawn on the screen. If +\fIpixels\fR is 0, the height is the same as the widget's height. +The default is \f(CW0\fR. +.TP +\fB\-landscape \fIboolean\fR +If \fIboolean\fR 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 (``landscape'' orientation). Defaults to +\f(CW0\fR. +.TP +\fB\-maxpect \fIboolean\fR +Indicates to scale the plot so that it fills the PostScript page. +The aspect ratio of the graph is still retained. The default is +\f(CW0\fR. +.TP +\fB\-padx \fIpad\fR +Sets the horizontal padding for the left and right page borders. The +borders are exterior to the plot. \fIPad\fR can be a list of one or +two screen distances. If \fIpad\fR has two elements, the left border is padded +by the first distance and the right border by the second. If +\fIpad\fR has just one distance, both the left and right borders are +padded evenly. The default is \f(CW1i\fR. +.TP +\fB\-pady \fIpad\fR +Sets the vertical padding for the top and bottom page borders. The +borders are exterior to the plot. \fIPad\fR can be a list of one or +two screen distances. If \fIpad\fR has two elements, the top border is padded +by the first distance and the bottom border by the second. If +\fIpad\fR has just one distance, both the top and bottom borders are +padded evenly. The default is \f(CW1i\fR. +.TP +\fB\-paperheight \fIpixels\fR +Sets the height of the postscript page. This can be used to select +between different page sizes (letter, A4, etc). The default height is +\f(CW11.0i\fR. +.TP +\fB\-paperwidth \fIpixels\fR +Sets the width of the postscript page. This can be used to select +between different page sizes (letter, A4, etc). The default width is +\f(CW8.5i\fR. +.TP +\fB\-width \fIpixels\fR +Sets the width of the plot. This lets you generate a plot +of a width different from that of the widget. If \fIpixels\fR +is 0, the width is the same as the widget's width. The default is +\f(CW0\fR. +.PP +Postscript configuration options may be also be set by the +\fBoption\fR command. The resource name and class are +\f(CWpostscript\fR and \f(CWPostscript\fR respectively. +.CS +option add *Graph.postscript.Decorations false +option add *Graph.Postscript.Landscape true +.CE +.RE +.TP +\fIpathName \fBpostscript output \fR?\fIfileName\fR? ?\fIoption value\fR?... +Outputs a file of encapsulated PostScript. If a +\fIfileName\fR argument isn't present, the command returns the +PostScript. If any \fIoption-value\fR pairs are present, they set +configuration options controlling how the PostScript is generated. +\fIOption\fR and \fIvalue\fR can be anything accepted by the +postscript \fBconfigure\fR operation above. +.SS "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 \fB\-under\fR +option. +.PP +Markers, in contrast to elements, don't affect the scaling of the +coordinate axes. They can also have \fIelastic\fR coordinates +(specified by \f(CW-Inf\fR and \f(CWInf\fR 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 \f(CW-Inf\fR,\f(CW-Inf\fR. +.PP +The following operations are available for markers. +.TP +\fIpathName \fBmarker after \fImarkerId\fR ?\fIafterId\fR? +Changes the order of the markers, drawing the first +marker after the second. If no second \fIafterId\fR 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. +.TP +\fIpathName \fBmarker before \fImarkerId\fR ?\fIbeforeId\fR? +Changes the order of the markers, drawing the first +marker before the second. If no second \fIbeforeId\fR 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. +.TP +\fIpathName \fBmarker bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for a marker with this +tag, \fIcommand\fR will be invoked. The syntax is similar to the +\fBbind\fR command except that it operates on graph markers, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBmarker cget \fIoption\fR +Returns the current value of the marker configuration option given by +\fIoption\fR. \fIOption\fR may be any option described +below in the \fBconfigure\fR operation. +.TP +\fIpathName \fBmarker configure \fImarkerId\fR ?\fIoption value\fR?... +Queries or modifies the configuration options for markers. If +\fIoption\fR isn't specified, a list describing the current +options for \fImarkerId\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the marker option \fIoption\fR is set to \fIvalue\fR. +.sp +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. +.RS +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for the marker. \fITagList\fR 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 \f(CWall\fR. +.TP +\fB\-coords \fIcoordList\fR +Specifies the coordinates of the marker. \fICoordList\fR 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 \fIcoordList\fR is \f(CW""\fR, the marker will not be displayed. +The default is \f(CW""\fR. +.TP +\fB\-element \fIelemName\fR +Links the marker with the element \fIelemName\fR. The marker is +drawn only if the element is also currently displayed (see the +element's \fBshow\fR operation). If \fIelemName\fR is \f(CW""\fR, the +marker is always drawn. The default is \f(CW""\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the marker is drawn. If \fIboolean\fR is true, +the marker is not drawn. The default is \f(CWno\fR. +.TP +\fB\-mapx \fIxAxis\fR +Specifies the X\-axis to map the marker's X\-coordinates onto. +\fIXAxis\fR must the name of an axis. The default is \f(CWx\fR. +.TP +\fB\-mapy \fIyAxis\fR +Specifies the Y\-axis to map the marker's Y\-coordinates onto. +\fIYAxis\fR must the name of an axis. The default is \f(CWy\fR. +.TP +\fB\-name \fImarkerId\fR +Changes the identifier for the marker. The identifier \fImarkerId\fR +can not already be used by another marker. If this option +isn't specified, the marker's name is uniquely generated. +.TP +\fB\-under \fIboolean\fR +Indicates whether the marker is drawn below/above data +elements. If \fIboolean\fR is true, the marker is be drawn +underneath the data element symbols and lines. Otherwise, the marker is +drawn on top of the element. The default is \f(CW0\fR. +.TP +\fB\-xoffset \fIpixels\fR +Specifies a screen distance to offset the marker horizontally. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +The default is \f(CW0\fR. +.TP +\fB\-yoffset \fIpixels\fR +Specifies a screen distance to offset the markers vertically. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +The default is \f(CW0\fR. +.PP +Marker configuration options may also be set by the \fBoption\fR command. +The resource class is either \f(CWBitmapMarker\fR, \f(CWImageMarker\fR, +\f(CWLineMarker\fR, \f(CWPolygonMarker\fR, \f(CWTextMarker\fR, or \f(CWWindowMarker\fR, +depending on the type of marker. The resource name is the name of the +marker. +.CS +option add *Graph.TextMarker.Foreground white +option add *Graph.BitmapMarker.Foreground white +option add *Graph.m1.Background blue +.CE +.RE +.TP +\fIpathName \fBmarker create \fItype\fR ?\fIoption value\fR?... +Creates a marker of the selected type. \fIType\fR may be either +\f(CWtext\fR, \f(CWline\fR, \f(CWbitmap\fR, \f(CWimage\fR, \f(CWpolygon\fR, or +\f(CWwindow\fR. This command returns the marker identifier, +used as the \fImarkerId\fR argument in the other marker-related +commands. If the \fB\-name\fR option is used, this overrides the +normal marker identifier. If the name provided is already used for +another marker, the new marker will replace the old. +.TP +\fIpathName \fBmarker delete\fR ?\fIname\fR?... +Removes one of more markers. The graph will automatically be redrawn +without the marker.\fR. +.TP +\fIpathName \fBmarker exists \fImarkerId\fR +Returns \f(CW1\fR if the marker \fImarkerId\fR exists and \f(CW0\fR +otherwise. +.TP +\fIpathName \fBmarker names\fR ?\fIpattern\fR? +Returns the names of all the markers that currently exist. If +\fIpattern\fR is supplied, only those markers whose names match it +will be returned. +.TP +\fIpathName \fBmarker type \fImarkerId\fR +Returns the type of the marker given by \fImarkerId\fR, such as +\f(CWline\fR or \f(CWtext\fR. If \fImarkerId\fR is not a valid a marker +identifier, \f(CW""\fR is returned. +.SS "BITMAP MARKERS" +A bitmap marker displays a bitmap. The size of the +bitmap is controlled 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 bitmap. The bitmap will be stretched or reduced as +necessary to fit into the bounding rectangle. +.PP +Bitmap markers are created with the marker's \fBcreate\fR operation in +the form: +.DS +\fIpathName \fBmarker create bitmap \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR pairs, each +sets a configuration options for the marker. These +same \fIoption\fR\-\fIvalue\fR pairs may be used with the marker's +\fBconfigure\fR operation. +.PP +The following options are specific to bitmap markers: +.TP +\fB\-background \fIcolor\fR +Same as the \fB\-fill\fR option. +.TP +\fB\-bitmap \fIbitmap\fR +Specifies the bitmap to be displayed. If \fIbitmap\fR is \f(CW""\fR, +the marker will not be displayed. The default is \f(CW""\fR. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the bitmap. If \fIcolor\fR is the empty +string, no background will be transparent. The default background color is +\f(CW""\fR. +.TP +\fB\-foreground \fIcolor\fR +Same as the \fB\-outline\fR option. +.TP +\fB\-mask \fImask\fR +Specifies a mask for the bitmap to be displayed. This mask is a bitmap +itself, denoting the pixels that are transparent. If \fImask\fR is +\f(CW""\fR, all pixels of the bitmap will be drawn. The default is +\f(CW""\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the foreground color of the bitmap. The default value is \f(CWblack\fR. +.TP +\fB\-rotate \fItheta\fR +Sets the rotation of the bitmap. \fITheta\fR is a real number +representing the angle of rotation in degrees. The marker is first +rotated and then placed according to its anchor position. The default +rotation is \f(CW0.0\fR. +.SS "IMAGE MARKERS" +A image marker displays an image. Image markers are +created with the marker's \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create image \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR operation. +.PP +The following options are specific to image markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the image relative to the +positioning point for the image. For example, if \fIanchor\fR +is \f(CWcenter\fR then the image is centered on the point; if +\fIanchor\fR is \f(CWn\fR then the image will be drawn such that +the top center point of the rectangular region occupied by the +image will be at the positioning point. +This option defaults to \f(CWcenter\fR. +.TP +\fB\-image \fIimage\fR +Specifies the image to be drawn. +If \fIimage\fR is \f(CW""\fR, the marker will not be +drawn. The default is \f(CW""\fR. +.SS "LINE MARKERS" +A line marker displays one or more connected line segments. +Line markers are created with marker's \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create line \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR operation. +.PP +The following options are specific to line markers: +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the line. \fIDashList\fR 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 +\fIdashList\fR is \f(CW""\fR, the marker line will be solid. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the line. This color is used with +striped lines (see the \fB\-fdashes\fR option). If \fIcolor\fR is +the empty string, no background color is drawn (the line will be +dashed, not striped). The default background color is \f(CW""\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the lines. +The default width is \f(CW0\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the foreground color of the line. The default value is \f(CWblack\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies a stipple pattern used to draw the line, rather than +a solid line. +\fIBitmap\fR specifies a bitmap to use as the stipple +pattern. If \fIbitmap\fR is \f(CW""\fR, then the +line is drawn in a solid fashion. The default is \f(CW""\fR. +.SS "POLYGON MARKERS" +A polygon marker displays a closed region described as two or more +connected line segments. It is assumed the first and +last points are connected. Polygon markers are created using the +marker \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create polygon \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the \fBmarker configure\fR command to change the marker's +configuration. +The following options are supported for polygon markers: +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the outline of the polygon. \fIDashList\fR 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 \fIdashList\fR is \f(CW""\fR, the outline will be a solid line. +.TP +\fB\-fill \fIcolor\fR +Sets the fill color of the polygon. If \fIcolor\fR is \f(CW""\fR, then +the interior of the polygon is transparent. +The default is \f(CWwhite\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the outline of the polygon. If \fIpixels\fR is zero, +no outline is drawn. The default is \f(CW0\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the color of the outline of the polygon. If the polygon is +stippled (see the \fB\-stipple\fR option), then this represents the +foreground color of the stipple. The default is \f(CWblack\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies that the polygon should be drawn with a stippled pattern +rather than a solid color. \fIBitmap\fR specifies a bitmap to use as +the stipple pattern. If \fIbitmap\fR is \f(CW""\fR, then the polygon is +filled with a solid color (if the \fB\-fill\fR option is set). The +default is \f(CW""\fR. +.SS "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 +annotate regions of the graph. Text markers are created with the +\fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create text \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR pairs, +each sets a configuration option for the text marker. +These same \fIoption\fR\-\fIvalue\fR pairs may be used with the +marker's \fBconfigure\fR operation. +.PP +The following options are specific to text markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the text relative to the +positioning point for the text. For example, if \fIanchor\fR is +\f(CWcenter\fR then the text is centered on the point; if +\fIanchor\fR is \f(CWn\fR 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 \f(CWcenter\fR. +.TP +\fB\-background \fIcolor\fR +Same as the \fB\-fill\fR option. +.TP +\fB\-font \fIfontName\fR +Specifies the font of the text. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-120-*\fR. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the text. If \fIcolor\fR is the empty +string, no background will be transparent. The default background color is +\f(CW""\fR. +.TP +\fB\-foreground \fIcolor\fR +Same as the \fB\-outline\fR option. +.TP +\fB\-justify \fIjustify\fR +Specifies how the text should be justified. This matters only when +the marker contains more than one line of text. \fIJustify\fR must be +\f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the color of the text. The default value is \f(CWblack\fR. +.TP +\fB\-padx \fIpad\fR +Sets the padding to the left and right exteriors of the text. +\fIPad\fR can be a list of one or two screen distances. If \fIpad\fR +has two elements, the left side of the text is padded by the first +distance and the right side by the second. If \fIpad\fR has just one +distance, both the left and right sides are padded evenly. The +default is \f(CW4\fR. +.TP +\fB\-pady \fIpad\fR +Sets the padding above and below the text. \fIPad\fR can be a list of +one or two screen distances. If \fIpad\fR has two elements, the area above the +text is padded by the first distance and the area below by the second. +If \fIpad\fR is just one distance, both the top and bottom areas +are padded evenly. The default is \f(CW4\fR. +.TP +\fB\-rotate \fItheta\fR +Specifies the number of degrees to rotate the text. \fITheta\fR 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 \f(CW0.0\fR. +.TP +\fB\-text \fItext\fR +Specifies the text of the marker. The exact way the text is +displayed may be affected by other options such as \fB\-anchor\fR or +\fB\-rotate\fR. +.SS "WINDOW MARKERS" +A window marker displays a widget at a given position. +Window markers are created with the marker's \fBcreate\fR operation in +the form: +.DS +\fIpathName \fBmarker create window \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR command. +.PP +The following options are specific to window markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the widget relative to the +positioning point for the widget. For example, if \fIanchor\fR is +\f(CWcenter\fR then the widget is centered on the point; if \fIanchor\fR +is \f(CWn\fR 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 \f(CWcenter\fR. +.TP +\fB\-height \fIpixels\fR +Specifies the height to assign to the marker's window. If this option +isn't specified, or if it is specified as \f(CW""\fR, then the window is +given whatever height the widget requests internally. +.TP +\fB\-width \fIpixels\fR +Specifies the width to assign to the marker's window. If this option +isn't specified, or if it is specified as \f(CW""\fR, then the window is +given whatever width the widget requests internally. +.TP +\fB\-window \fIpathName\fR +Specifies the widget to be managed by the graph. \fIPathName\fR must +be a child of the \fBgraph\fR widget. +.SH "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 \fBEnter\fR, \fBLeave\fR, +\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR). +.PP +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 commands +will be invoked if both items are picked. +.PP +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 \fB\-bindtags\fR 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 command. +.PP +The \fB\-bindtags\fR 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 \fB\-bindtags\fR option doesn't change this. +.SH "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 format. +.PP +Data can manipulated from the C language using BLT vectors. +You specify the X-Y data coordinates of an element as vectors and +manipulate the vector from C. The graph will be redrawn automatically +after the vectors are updated. +.PP +From Tcl, create the vectors and configure the element to use them. +.CS +vector X Y +\&.g element configure line1 -xdata X -ydata Y +.CE +To set data points from C, you pass the values as arrays of doubles +using the \fBBlt_ResetVector\fR 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. +.CS +#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; +} +.CE +See the \fBvector\fR manual page for more details. +.SH 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. +.TP 2 +\(bu +Try to minimize the number of data points. The more data points +the looked at, the more work the graph must do. +.TP 2 +\(bu +If your data is generated as floating point values, the time required +to convert the data values to and from ASCII strings can be +significant, especially when there any many data points. You can +avoid the redundant string-to-decimal conversions using the C API to +BLT vectors. +.TP 2 +\(bu +Data elements without symbols are drawn faster than with symbols. +Set the data element's \fB\-symbol\fR option to \f(CWnone\fR. If you need to +draw symbols, try using the simple symbols such as \f(CWsplus\fR and +\f(CWscross\fR. +.TP 2 +\(bu +Don't stipple or dash the element. Solid lines are much faster. +.TP 2 +\(bu +If you update data elements frequently, try turning off the +widget's \fB\-bufferelements\fR option. When the graph is first +displayed, it draws data elements into an internal pixmap. The pixmap +acts as a cache, so that when the graph needs to be redrawn again, and +the data elements or coordinate axes haven't changed, the pixmap is +simply copied to the screen. This is especially useful when you are +using markers to highlight points and regions on the graph. But if +the graph is updated frequently, changing either the element data or +coordinate axes, the buffering becomes redundant. +.SH LIMITATIONS +Auto-scale routines do not use requested min/max limits as boundaries +when the axis is logarithmically scaled. +.PP +The PostScript output generated for polygons with more than 1500 +points may exceed the limits of some printers (See PostScript Language +Reference Manual, page 568). The work-around is to break the polygon +into separate pieces. +.SH KEYWORDS +graph, widget diff --git a/doc/vector.html b/doc/vector.html new file mode 100644 index 0000000..ef097c6 --- /dev/null +++ b/doc/vector.html @@ -0,0 +1,704 @@ +<HTML> +<BODY> +<PRE> +<!-- Manpage converted by man2html 3.0.1 --> + +</PRE> +<H2>SYNOPSIS</H2><PRE> + <B>blt::vector</B> <B>create</B> <I>vecName</I> ?<I>vecName</I>...? ?<I>switches</I>? + + <B>blt::vector</B> <B>destroy</B> <I>vecName</I> ?<I>vecName</I>...? + + <B>blt::vector</B> <B>expr</B> <I>expression</I> + + <B>blt::vector</B> <B>names</B> ?<I>pattern</I>...? + + +</PRE> +<H2>DESCRIPTION</H2><PRE> + The <B>vector</B> 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. + + +</PRE> +<H2>INTRODUCTION</H2><PRE> + 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. + + <B>o</B> 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. + + <B>o</B> 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. + + <B>o</B> 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 <B>vector</B> 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 <B>y(0)</B> 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 + <B>y(50)</B> 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 + <B>y(0)</B> puts "new first element is $<B>y(0)</B>" 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 + <B>set</B> operation resets the vector, extending it and setting values for + each new component. + + There are several operations for vectors. The <B>range</B> 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 <B>search</B> 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 <B>append</B> + operation. # Append assorted vectors and values to x x append x2 x3 { + 2.3 4.5 } x4 The <B>sort</B> 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 <B>expr</B> 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 <B>vector</B> <B>create</B> operation. Th <B>create</B> oper- + ation can be invoked in one of three forms: + + <B>blt::vector</B> <B>create</B> <I>vecName</I> + This creates a new vector <I>vecName</I> which initially has no compo- + nents. + + <B>blt::vector</B> <B>create</B> <I>vecName</I>(<I>size</I>) + This second form creates a new vector which will contain <I>size</I> + number of components. The components will be indexed starting + from zero (0). The default value for the components is 0.0. + + <B>blt::vector</B> <B>create</B> <I>vecName</I>(<I>first</I>:<I>last</I>) + The last form creates a new vector of indexed <I>first</I> through + <I>last</I>. <I>First</I> and <I>last</I> can be any integer value so long as <I>first</I> + is less than <I>last</I>. + + 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 <B>create</B> operation will generate a unique vector name. + set vec [blt::vector create #auto] puts "$vec has [$vec length] compo- + nents" + + <B>VECTOR</B> <B>INDICES</B> + 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 <B>offset</B> operation to change a vec- + tor's indices on-the-fly. puts $<B>vecName(0)</B> 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(:) + + +</PRE> +<H2>VECTOR OPERATIONS</H2><PRE> + <B>blt::vector</B> <B>create</B> <I>vecName</I>?(<I>size</I>)?... ?<I>switches</I>? + The <B>create</B> operation creates a new vector <I>vecName</I>. Both a Tcl + command and array variable <I>vecName</I> 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 <B>variable</B> + operation. + + <B>-command</B> <I>cmdName</I> + Maps a Tcl command to the vector. The vector can be + accessed using <I>cmdName</I> and one of the vector instance + operations. A Tcl command by that name cannot already + exist. If <I>cmdName</I> is the empty string, no command map- + ping will be made. + + <B>-watchunset</B> <I>boolean</I> + 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 <I>boolean</I> to + "true" to get the old behavior. + + <B>blt::vector</B> <B>destroy</B> <I>vecName</I> ?<I>vecName...</I>? + Deletes one or more vectors. Both the Tcl command and array + variable are removed also. + + <B>blt::vector</B> <B>expr</B> <I>expression</I> + 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: + + <B>-</B> <B>!</B> 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. + + <B>^</B> Exponentiation. + + <B>*</B> <B>/</B> <B>%</B> Multiply, divide, remainder. + + <B>+</B> <B>-</B> Add and subtract. + + <B><<</B> <B>>></B> Left and right shift. Circularly shifts the + values of the vector (not implemented yet). + + <B>&&</B> Logical AND. Produces a 1 result if both + operands are non-zero, 0 otherwise. + + <B>||</B> Logical OR. Produces a 0 result if both op- + erands are zero, 1 otherwise. + + <I>x</I><B>?</B><I>y</I><B>:</B><I>z</I> 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. + <B>acos</B> <B>cos</B> <B>hypot</B> <B>sinh</B> <B>asin</B> <B>cosh</B> <B>log</B> <B>sqrt</B> + <B>atan</B> <B>exp</B> <B>log10</B> <B>tan</B> <B>ceil</B> <B>floor</B> <B>sin</B> <B>tanh</B> + + Additional functions are: + + <B>abs</B> Returns the absolute value of each component. + + <B>random</B> Returns a vector of non-negative values uniformly dis- + tributed between [0.0, 1.0) using <I>drand48</I>. The seed + comes from the internal clock of the machine or may be + set manual with the srandom function. + + <B>round</B> Rounds each component of the vector. + + <B>srandom</B> Initializes the random number generator using <I>srand48</I>. + 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. + + <B>adev</B> 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). + + <B>kurtosis</B> Returns the degree of peakedness (fourth moment) of + the vector. + + <B>length</B> Returns the number of components in the vector. + + <B>max</B> Returns the vector's maximum value. + + + <B>skew</B> Returns the skewness (or third moment) of the vector. + This characterizes the degree of asymmetry of the vec- + tor about the mean. + + <B>sum</B> Returns the sum of the components. + + <B>var</B> 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. + + <B>norm</B> Scales the values of the vector to lie in the range + [0.0..1.0]. + + <B>sort</B> Returns the vector components sorted in ascending + order. + + <B>vector</B> <B>names</B> ?<I>pattern</I>? + + +</PRE> +<H2>INSTANCE OPERATIONS</H2><PRE> + You can also use the vector's Tcl command to query or modify it. The + general form is <I>vecName</I> <I>operation</I> ?<I>arg</I>?... Both <I>operation</I> and its + arguments determine the exact behavior of the command. The operations + available for vectors are listed below. + + <I>vecName</I> <B>append</B> <I>item</I> ?<I>item</I>?... + Appends the component values from <I>item</I> to <I>vecName</I>. <I>Item</I> can be + either the name of a vector or a list of numeric values. + + <I>vecName</I> <B>binread</B> <I>channel</I> ?<I>length</I>? ?<I>switches</I>? + 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 <B>-at</B> option), overwriting existing values. Data is + read until EOF is found on the channel or a specified number of + values <I>length</I> are read (note that this is not necessarily the + same as the number of bytes). The following switches are sup- + ported: + + <B>-swap</B> Swap bytes and words. The default endian is the host + machine. + + <B>-at</B> <I>index</I> + New values will start at vector index <I>index</I>. This will + overwrite any current values. + + <B>-format</B> <I>format</I> + Specifies the format of the data. <I>Format</I> can be one of + the following: "i1", "i2", "i4", "i8", "u1, "u2", "u4", + + This is useful when the vector is large. + + <I>vecName</I> <B>delete</B> <I>index</I> ?<I>index</I>?... + Deletes the <I>index</I>th component from the vector <I>vecName</I>. <I>Index</I> is + the index of the element to be deleted. This is the same as + unsetting the array variable element <I>index</I>. The vector is com- + pacted after all the indices have been deleted. + + <I>vecName</I> <B>dup</B> <I>destName</I> + Copies <I>vecName</I> to <I>destName</I>. <I>DestName</I> is the name of a destina- + tion vector. If a vector <I>destName</I> already exists, it is over- + written with the components of <I>vecName</I>. Otherwise a new vector + is created. + + <I>vecName</I> <B>expr</B> <I>expression</I> + 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. + + <I>vecName</I> <B>length</B> ?<I>newSize</I>? + Queries or resets the number of components in <I>vecName</I>. <I>NewSize</I> + is a number specifying the new size of the vector. If <I>newSize</I> + is smaller than the current size of <I>vecName</I>, <I>vecName</I> is trun- + cated. If <I>newSize</I> is greater, the vector is extended and the + new components are initialized to 0.0. If no <I>newSize</I> argument + is present, the current length of the vector is returned. + + <I>vecName</I> <B>merge</B> <I>srcName</I> ?<I>srcName</I>?... + 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. + + <I>vecName</I> <B>notify</B> <I>keyword</I> + Controls how vector clients are notified of changes to the vec- + tor. The exact behavior is determined by <I>keyword</I>. + + 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- + tor. + + <I>density</I> 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. + + <I>vecName</I> <B>range</B> <I>firstIndex</I> ?<I>lastIndex</I>?... + Returns a list of numeric values representing the vector compo- + nents between two indices. Both <I>firstIndex</I> and <I>lastIndex</I> are + indices representing the range of components to be returned. If + <I>lastIndex</I> is less than <I>firstIndex</I>, the components are listed in + reverse order. + + <I>vecName</I> <B>search</B> <I>value</I> ?<I>value</I>? + Searches for a value or range of values among the components of + <I>vecName</I>. If one <I>value</I> argument is given, a list of indices of + the components which equal <I>value</I> is returned. If a second <I>value</I> + 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. + + <I>vecName</I> <B>set</B> <I>item</I> + Resets the components of the vector to <I>item</I>. <I>Item</I> can be either + a list of numeric expressions or another vector. + + <I>vecName</I> <B>seq</B> <I>start</I> ?<I>finish</I>? ?<I>step</I>? + Generates a sequence of values starting with the value <I>start</I>. + <I>Finish</I> indicates the terminating value of the sequence. The + vector is automatically resized to contain just the sequence. + If three arguments are present, <I>step</I> designates the interval. + + With only two arguments (no <I>finish</I> argument), the sequence will + continue until the vector is filled. With one argument, the + interval defaults to 1.0. + + <I>vecName</I> <B>sort</B> ?<B>-reverse</B>? ?<I>argName</I>?... + Sorts the vector <I>vecName</I> in increasing order. If the <B>-reverse</B> + flag is present, the vector is sorted in decreasing order. If + other arguments <I>argName</I> are present, they are the names of vec- + tors which will be rearranged in the same manner as <I>vecName</I>. + Each vector must be the same length as <I>vecName</I>. 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. + + <I>vecName</I> <B>variable</B> <I>varName</I> + Maps a Tcl variable to the vector, creating another means for + accessing the vector. The variable <I>varName</I> can't already exist. + This overrides any current variable mapping the vector may have. + + +</PRE> +<H2>C LANGUAGE API</H2><PRE> + 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 <B>Blt_Vector</B>, which represents the vector. + It appears below. typedef struct { + <B>Blt_CreateVector</B> + + Synopsis: int <B>Blt_CreateVector</B> (<I>interp</I>, <I>vecName</I>, <I>length</I>, <I>vecPtrPtr</I>) + Tcl_Interp *<I>interp</I>; char *<I>vecName</I>; int <I>length</I>; Blt_Vec- + tor **<I>vecPtrPtr</I>; + + Description: + Creates a new vector <I>vecName</I> with a length of <I>length</I>. + <B>Blt_CreateVector</B> creates both a new Tcl command and array + variable <I>vecName</I>. Neither a command nor variable named + <I>vecName</I> can already exist. A pointer to the vector is + placed into <I>vecPtrPtr</I>. + + Results: Returns TCL_OK if the vector is successfully created. If + <I>length</I> is negative, a Tcl variable or command <I>vecName</I> + already exists, or memory cannot be allocated for the vec- + tor, then TCL_ERROR is returned and <I>interp->result</I> will + contain an error message. + + + <B>Blt_DeleteVectorByName</B> + + Synopsis: int <B>Blt_DeleteVectorByName</B> (<I>interp</I>, <I>vecName</I>) + Tcl_Interp *<I>interp</I>; char *<I>vecName</I>; + + Description: + Removes the vector <I>vecName</I>. <I>VecName</I> is the name of a vec- + tor which must already exist. Both the Tcl command and + array variable <I>vecName</I> 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 + <I>vecName</I> is not the name a vector, then TCL_ERROR is + returned and <I>interp->result</I> will contain an error message. + + + <B>Blt_DeleteVector</B> + + Synopsis: int <B>Blt_DeleteVector</B> (<I>vecPtr</I>) + Blt_Vector *<I>vecPtr</I>; + + Description: + Removes the vector pointed to by <I>vecPtr</I>. <I>VecPtr</I> is a + pointer to a vector, typically set by <B>Blt_GetVector</B> or + <B>Blt_CreateVector</B>. 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 + <I>vecName</I> is not the name a vector, then TCL_ERROR is + + Results: Returns TCL_OK if the vector is successfully retrieved. If + <I>vecName</I> is not the name of a vector, then TCL_ERROR is + returned and <I>interp->result</I> will contain an error message. + + + <B>Blt_ResetVector</B> + + + Synopsis: int <B>Blt_ResetVector</B> (<I>vecPtr</I>, <I>dataArr</I>, <I>numValues</I>, + <I>arraySize</I>, <I>freeProc</I>) + Blt_Vector *<I>vecPtr</I>; double *<I>dataArr</I>; int *<I>numValues</I>; int + *<I>arraySize</I>; Tcl_FreeProc *<I>freeProc</I>; + + Description: + Resets the components of the vector pointed to by <I>vecPtr</I>. + Calling <B>Blt_ResetVector</B> will trigger the vector to dispatch + notifications to its clients. <I>DataArr</I> is the array of dou- + bles which represents the vector data. <I>NumValues</I> is the + number of elements in the array. <I>ArraySize</I> is the actual + size of the array (the array may be bigger than the number + of values stored in it). <I>FreeProc</I> indicates how the storage + for the vector component array (<I>dataArr</I>) 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 <I>freeProc</I> + is TCL_VOLATILE, it indicates that <I>dataArr</I> must be copied + and saved. If <I>freeProc</I> is TCL_DYNAMIC, it indicates that + <I>dataArr</I> was dynamically allocated and that Tcl should free + <I>dataArr</I> if necessary. Static indicates that nothing should + be done to release storage for <I>dataArr</I>. + + Results: Returns TCL_OK if the vector is successfully resized. If + <I>newSize</I> is negative, a vector <I>vecName</I> does not exist, or + memory cannot be allocated for the vector, then TCL_ERROR + is returned and <I>interp->result</I> will contain an error mes- + sage. + + + <B>Blt_ResizeVector</B> + + Synopsis: int <B>Blt_ResizeVector</B> (<I>vecPtr</I>, <I>newSize</I>) + Blt_Vector *<I>vecPtr</I>; int <I>newSize</I>; + + Description: + Resets the length of the vector pointed to by <I>vecPtr</I> to + <I>newSize</I>. If <I>newSize</I> is smaller than the current size of + the vector, it is truncated. If <I>newSize</I> is greater, the + vector is extended and the new components are initialized + to 0.0. Calling <B>Blt_ResetVector</B> will trigger the vector to + dispatch notifications. + + Results: Returns 1 if a vector <I>vecName</I> exists and 0 otherwise. + + + If your application needs to be notified when a vector changes, it + can allocate a unique <I>client</I> <I>identifier</I> 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 (<B>Blt_VectorChangedProc</B>) (Tcl_Interp *<I>interp</I>, + ClientData <I>clientData</I>, Blt_VectorNotify <I>notify</I>); + + <I>ClientData</I> is passed to this routine whenever it is called. You can + use this to pass information to the call-back. The <I>notify</I> 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 } <B>Blt_VectorNotify</B>; + + + <B>Blt_AllocVectorId</B> + + Synopsis: Blt_VectorId <B>Blt_AllocVectorId</B> (<I>interp</I>, <I>vecName</I>) + Tcl_Interp *<I>interp</I>; char *<I>vecName</I>; + + Description: + Allocates an client identifier for with the vector <I>vec-</I> + <I>Name</I>. 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 <I>vecName</I> + is not the name of a vector, then NULL is returned and + <I>interp->result</I> will contain an error message. + + + <B>Blt_GetVectorById</B> + + Synopsis: int <B>Blt_GetVector</B> (<I>interp</I>, <I>clientId</I>, <I>vecPtrPtr</I>) + Tcl_Interp *<I>interp</I>; Blt_VectorId <I>clientId</I>; Blt_Vector + **<I>vecPtrPtr</I>; + + Description: + Retrieves the vector used by <I>clientId</I>. <I>ClientId</I> is a + valid vector client identifier allocated by + Specifies a call-back routine to be called whenever the + vector associated with <I>clientId</I> is updated or deleted. + <I>Proc</I> is a pointer to call-back routine and must be of + the type <B>Blt_VectorChangedProc</B>. <I>ClientData</I> is a one- + word value to be passed to the routine when it is + invoked. If <I>proc</I> 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. + + + <B>Blt_FreeVectorId</B> + + Synopsis: void <B>Blt_FreeVectorId</B> (<I>clientId</I>); + Blt_VectorId <I>clientId</I>; + + 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. + + + <B>Blt_NameOfVectorId</B> + + Synopsis: char *<B>Blt_NameOfVectorId</B> (<I>clientId</I>); + Blt_VectorId <I>clientId</I>; + + Description: + Retrieves the name of the vector associated with the + client identifier <I>clientId</I>. + + Results: Returns the name of the vector associated with <I>clientId</I>. + If <I>clientId</I> is not an identifier or the vector has been + destroyed, NULL is returned. + + + <B>Blt_InstallIndexProc</B> + + Synopsis: void <B>Blt_InstallIndexProc</B> (<I>indexName</I>, <I>procPtr</I>) + char *<I>indexName</I>; Blt_VectorIndexProc *<I>procPtr</I>; + + Description: + Registers a function to be called to retrieved the index + <I>indexName</I> from the vector's array variable. + + typedef double Blt_VectorIndexProc(Vector *vecPtr); + + The function will be passed a pointer to the vector. + + reset shortly. The vector is updated when <B>lt_ResetVector</B> 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; } + + +</PRE> +<H2>INCOMPATIBILITIES</H2><PRE> + 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 <B>x(10)</B> + set <B>x(9)</B> 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. + + +</PRE> +<H2>KEYWORDS</H2><PRE> + vector, graph, widget + + + +BLT BLT_VERSION blt::vector(n) +</PRE> +<HR> +<ADDRESS> +Man(1) output converted with +<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> +</ADDRESS> +</BODY> +</HTML> diff --git a/doc/vector.n b/doc/vector.n new file mode 100644 index 0000000..fa8bb7e --- /dev/null +++ b/doc/vector.n @@ -0,0 +1,1134 @@ +'\" +'\" Smithsonian Astrophysical Observatory, Cambridge, MA, USA +'\" This code has been modified under the terms listed below and is made +'\" available under the same terms. +'\" +'\" Copyright 1991-1997 by Lucent Technologies, Inc. +'\" +'\" Permission to use, copy, modify, and distribute this software and its +'\" documentation for any purpose and without fee is hereby granted, provided +'\" that the above copyright notice appear in all copies and that both that the +'\" copyright notice and warranty disclaimer appear in supporting documentation, +'\" and that the names of Lucent Technologies any of their entities not be used +'\" in advertising or publicity pertaining to distribution of the software +'\" without specific, written prior permission. +'\" +'\" Lucent Technologies disclaims all warranties with regard to this software, +'\" including all implied warranties of merchantability and fitness. In no event +'\" shall Lucent Technologies be liable for any special, indirect or +'\" consequential damages or any damages whatsoever resulting from loss of use, +'\" data or profits, whether in an action of contract, negligence or other +'\" tortuous action, arising out of or in connection with the use or performance +'\" of this software. +'\" +'\" Vector command created by George Howlett. +'\" +.TH blt::vector n BLT_VERSION BLT "BLT Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +\fBvector\fR \- Vector data type for Tcl +.SH SYNOPSIS +\fBblt::vector create \fIvecName \fR?\fIvecName\fR...? ?\fIswitches\fR? +.sp +\fBblt::vector destroy \fIvecName \fR?\fIvecName\fR...? +.sp +\fBblt::vector expr \fIexpression\fR +.sp +\fBblt::vector names \fR?\fIpattern\fR...? +.BE +.SH DESCRIPTION +The \fBvector\fR command creates an array of floating point +values. The vector's components can be manipulated in three ways: +through a Tcl array variable, a Tcl command, or the C API. +.SH INTRODUCTION +A vector is an ordered set of real numbers. The components of a +vector are indexed by integers. +.PP +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 analysis 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. +.PP +You could try to use Tcl's associative arrays as vectors. Tcl arrays +are easy to use. You can access individual elements randomly by +specifying the index, or the set the entire array by providing a list +of index and value pairs for each element. The disadvantages of +associative arrays as vectors lie in the fact they are implemented as +hash tables. +.TP 2 +\(bu +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 +values between two indices. Nor can you sort an array. +.TP 2 +\(bu +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. +.TP 2 +\(bu +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 element in the array. This makes it cumbersome to perform operations on +the array as a whole. +.PP +The \fBvector\fR command tries to overcome these disadvantages while +still retaining the ease of use of Tcl arrays. The \fBvector\fR +command creates both a new Tcl command and associate array which are +linked to the vector components. You can randomly access vector +components though the elements of array. Not have all indices are +generated for the array, so printing the array (using the \fBparray\fR +procedure) does not print out all the component values. You can use +the Tcl command to access the array as a whole. You can copy, append, +or sort vector using its command. If you need greater performance, or +customized behavior, you can write your own C code to manage vectors. +.SH EXAMPLE +You create vectors using the \fBvector\fR command and its \fBcreate\fR +operation. +.CS +# Create a new vector. +blt::vector create y(50) +.CE +This creates a new vector named \f(CWy\fR. It has fifty components, by +default, initialized to \f(CW0.0\fR. In addition, both a Tcl command +and array variable, both named \f(CWy\fR, are created. You can use +either the command or variable to query or modify components of the +vector. +.CS +# Set the first value. +set y(0) 9.25 +puts "y has [y length] components" +.CE +The array \f(CWy\fR 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 element of \f(CWy\fR. +.CS +# This is an error. The vector only has 50 components. +set y(50) 0.02 +.CE +You can also specify a range of indices using a colon (:) to separate +the first and last indices of the range. +.CS +# Set the first six components of y +set y(0:5) 25.2 +.CE +If you don't include an index, then it will default to the first +and/or last component of the vector. +.CS +# Print out all the components of y +puts "y = $y(:)" +.CE +There are special non-numeric indices. The index \f(CWend\fR, 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 \f(CW++end\fR can be +used to extend the vector by one component and initialize it to a specific +value. You can't read from the array using this index, though. +.CS +# Extend the vector by one component. +set y(++end) 0.02 +.CE +The other special indices are \f(CWmin\fR and \f(CWmax\fR. They return the +current smallest and largest components of the vector. +.CS +# Print the bounds of the vector +puts "min=$y(min) max=$y(max)" +.CE +To delete components from a vector, simply unset the corresponding +array element. In the following example, the first component of +\f(CWy\fR is deleted. All the remaining components of \f(CWy\fR will be +moved down by one index as the length of the vector is reduced by +one. +.CS +# Delete the first component +unset y(0) +puts "new first element is $y(0)" +.CE +The vector's Tcl command can also be used to query or set the vector. +.CS +# Create and set the components 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 } +.CE +Here we've created a vector \f(CWx\fR without a initial length specification. +In this case, the length is zero. The \fBset\fR operation resets the vector, +extending it and setting values for each new component. +.PP +There are several operations for vectors. The \fBrange\fR operation +lists the components of a vector between two indices. +.CS +# List the components +puts "x = [x range 0 end]" +.CE +You can search for a particular value using the \fBsearch\fR +operation. It returns a list of indices of the components with the +same value. If no component has the same value, it returns \f(CW""\fR. +.CS +# Find the index of the biggest component +set indices [x search $x(max)] +.CE +Other operations copy, append, or sort vectors. You can append +vectors or new values onto an existing vector with the \fBappend\fR +operation. +.CS +# Append assorted vectors and values to x +x append x2 x3 { 2.3 4.5 } x4 +.CE +The \fBsort\fR 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. +.CS +# Sort the data points +x sort y +.CE +The vector \f(CWx\fR is sorted while the components of \f(CWy\fR are +rearranged so that the original x,y coordinate pairs are retained. +.PP +The \fBexpr\fR operation lets you perform arithmetic on vectors. +The result is stored in the vector. +.CS +# Add the two vectors and a scalar +x expr { x + y } +x expr { x * 2 } +.CE +When a vector is modified, resized, or deleted, it may trigger +call-backs to notify the clients of the vector. For example, when a +vector used in the \fBgraph\fR widget is updated, the vector +automatically notifies the widget that it has changed. The graph can +then redrawn itself at the next idle point. By default, the +notification occurs when Tk is next idle. This way you can modify the +vector many times without incurring the penalty of the graph redrawing +itself for each change. You can change this behavior using the +\fBnotify\fR operation. +.CS +# Make vector x notify after every change +x notify always + ... +# Never notify +x notify never + ... +# Force notification now +x notify now +.CE +To delete a vector, use the \fBvector delete\fR command. +Both the vector and its corresponding Tcl command are destroyed. +.CS +# Remove vector x +blt::vector destroy x +.CE +.SH SYNTAX +Vectors are created using the \fBvector create\fR operation. +Th \fBcreate\fR operation can be invoked in one of three forms: +.TP +\fBblt::vector create \fIvecName\fR +This creates a new vector \fIvecName\fR which initially has no components. +.TP +\fBblt::vector create \fIvecName\fR(\fIsize\fR) +This second form creates a new vector which will contain \fIsize\fR +number of components. The components will be indexed starting from +zero (0). The default value for the components is \f(CW0.0\fR. +.TP +\fBblt::vector create \fIvecName\fR(\fIfirst\fR:\fIlast\fR) +The last form creates a new vector of indexed \fIfirst\fR through +\fIlast\fR. \fIFirst\fR and \fIlast\fR can be any integer value +so long as \fIfirst\fR is less than \fIlast\fR. +.PP +Vector names must start with a letter and consist of letters, digits, +or underscores. +.CS +# Error: must start with letter +blt::vector create 1abc +.CE +You can automatically generate vector names using the +"\f(CW#auto\fR" vector name. The \fBcreate\fR operation will generate a +unique vector name. +.CS +set vec [blt::vector create #auto] +puts "$vec has [$vec length] components" +.CE +.SS VECTOR INDICES +Vectors are indexed by integers. You can access the individual vector +components via its array variable or Tcl command. The string +representing the index can be an integer, a numeric expression, a +range, or a special keyword. +.PP +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 \fBoffset\fR operation to +change a vector's indices on-the-fly. +.CS +puts $vecName(0) +vecName offset -5 +puts $vecName(-5) +.CE +You can also use numeric expressions as indices. The result +of the expression must be an integer value. +.CS +set n 21 +set vecName($n+3) 50.2 +.CE +The following special non-numeric indices are available: \f(CWmin\fR, \f(CWmax\fR, \f(CWend\fR, and +\f(CW++end\fR. +.CS +puts "min = $vecName($min)" +set vecName(end) -1.2 +.CE +The indices \f(CWmin\fR and \f(CWmax\fR will return the minimum and maximum +values of the vector. The index \f(CWend\fR returns the value of the +last component in the vector. The index \f(CW++end\fR is used to append +new value onto the vector. It automatically extends the vector by +one component and sets its value. +.CS +# Append an new component to the end +set vecName(++end) 3.2 +.CE +A range of indices can be indicated by a colon (:). +.CS +# Set the first six components to 1.0 +set vecName(0:5) 1.0 +.CE +If no index is supplied the first or last component is assumed. +.CS +# Print the values of all the components +puts $vecName(:) +.CE +.SH VECTOR OPERATIONS +.TP +\fBblt::vector create \fIvecName\fR?(\fIsize\fR)?... \fR?\fIswitches\fR? +The \fBcreate\fR operation creates a new vector \fIvecName\fR. Both a +Tcl command and array variable \fIvecName\fR are also created. The +name \fIvecName\fR must be unique, so another Tcl command or array +variable can not already exist in that scope. You can access the +components of the vector using its variable. If you change a value in +the array, or unset an array element, the vector is updated to reflect +the changes. When the variable \fIvecName\fR is unset, the vector and +its Tcl command are also destroyed. +.sp +The vector has optional switches that affect how the vector is created. They +are as follows: +.RS +.TP +\fB\-variable \fIvarName\fR +Specifies the name of a Tcl variable to be mapped to the vector. If +the variable already exists, it is first deleted, then recreated. +If \fIvarName\fR is the empty string, then no variable will be mapped. +You can always map a variable back to the vector using the vector's +\fBvariable\fR operation. +.TP +\fB\-command \fIcmdName\fR +Maps a Tcl command to the vector. The vector can be accessed using +\fIcmdName\fR and one of the vector instance operations. +A Tcl command by that name cannot already exist. +If \fIcmdName\fR is the empty string, no command mapping +will be made. +.TP +\fB\-watchunset \fIboolean\fR +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 \fIboolean\fR to "true" to get the old behavior. +.RE +.TP +\fBblt::vector destroy \fIvecName\fR \fR?\fIvecName...\fR? +Deletes one or more vectors. Both the Tcl command and array variable +are removed also. +.TP +\fBblt::vector expr \fIexpression\fR +.RS +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 operand. 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 component, 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. +.sp +The valid operators are listed below, grouped in decreasing order +of precedence: +.TP 20 +\fB\-\0\0!\fR +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. +.TP 20 +\fB^\fR +Exponentiation. +.TP 20 +\fB*\0\0/\0\0%\fR +Multiply, divide, remainder. +.TP 20 +\fB+\0\0\-\fR +Add and subtract. +.TP 20 +\fB<<\0\0>>\fR +Left and right shift. Circularly shifts the values of the vector +(not implemented yet). +.TP 20 +\fB<\0\0>\0\0<=\0\0>=\fR +Boolean less, greater, less than or equal, and greater than or equal. +Each operator returns a vector of ones and zeros. If the condition is true, +1.0 is the component value, 0.0 otherwise. +.TP 20 +\fB==\0\0!=\fR +Boolean equal and not equal. +Each operator returns a vector of ones and zeros. If the condition is true, +1.0 is the component value, 0.0 otherwise. +.TP 20 +\fB|\fR +Bit-wise OR. (Not implemented). +.TP 20 +\fB&&\fR +Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. +.TP 20 +\fB||\fR +Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. +.TP 20 +\fIx\fB?\fIy\fB:\fIz\fR +If-then-else, as in C. (Not implemented yet). +.LP +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. +.sp +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. +.CS +.ta 2c 4c 6c +\fBacos\fR \fBcos\fR \fBhypot\fR \fBsinh\fR +\fBasin\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR +\fBatan\fR \fBexp\fR \fBlog10\fR \fBtan\fR +\fBceil\fR \fBfloor\fR \fBsin\fR \fBtanh\fR +.sp +.CE +Additional functions are: +.TP 1i +\fBabs\fR +Returns the absolute value of each component. +.TP 1i +\fBrandom\fR +Returns a vector of non-negative values uniformly distributed +between [0.0, 1.0) using \fIdrand48\fR. +The seed comes from the internal clock of the machine or may be +set manual with the srandom function. +.TP 1i +\fBround\fR +Rounds each component of the vector. +.TP 1i +\fBsrandom\fR +Initializes the random number generator using \fIsrand48\fR. +The high order 32-bits are set using the integral portion of the first +vector component. All other components are ignored. The low order 16-bits +are set to an arbitrary value. +.PP +The following functions return a single value. +.TP 1i +\fBadev\fR +Returns the average deviation (defined as the sum of the absolute values +of the differences between component and the mean, divided by the length +of the vector). +.TP 1i +\fBkurtosis\fR +Returns the degree of peakedness (fourth moment) of the vector. +.TP 1i +\fBlength\fR +Returns the number of components in the vector. +.TP 1i +\fBmax\fR +Returns the vector's maximum value. +.TP 1i +\fBmean\fR +Returns the mean value of the vector. +.TP 1i +\fBmedian\fR +Returns the median of the vector. +.TP 1i +\fBmin\fR +Returns the vector's minimum value. +.TP 1i +\fBq1\fR +Returns the first quartile of the vector. +.TP 1i +\fBq3\fR +Returns the third quartile of the vector. +.TP 1i +\fBprod\fR +Returns the product of the components. +.TP 1i +\fBsdev\fR +Returns the standard deviation (defined as the square root of the variance) +of the vector. +.TP 1i +\fBskew\fR +Returns the skewness (or third moment) of the vector. This characterizes +the degree of asymmetry of the vector about the mean. +.TP 1i +\fBsum\fR +Returns the sum of the components. +.TP 1i +\fBvar\fR +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. +.PP +The last set returns a vector of the same length as the argument. +.TP 1i +\fBnorm\fR +Scales the values of the vector to lie in the range [0.0..1.0]. +.TP 1i +\fBsort\fR +Returns the vector components sorted in ascending order. +.RE +.TP +\fBvector names \fR?\fIpattern\fR? +.SH INSTANCE OPERATIONS +You can also use the vector's Tcl command to query or modify it. The +general form is +.DS +\fIvecName \fIoperation\fR \fR?\fIarg\fR?... +.DE +Both \fIoperation\fR and its arguments determine the exact behavior of +the command. The operations available for vectors are listed below. +.TP +\fIvecName \fBappend\fR \fIitem\fR ?\fIitem\fR?... +Appends the component values from \fIitem\fR to \fIvecName\fR. +\fIItem\fR can be either the name of a vector or a list of numeric +values. +.TP +\fIvecName \fBbinread\fR \fIchannel\fR ?\fIlength\fR? ?\fIswitches\fR? +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 +\fB\-at\fR option), overwriting existing values. Data is read until EOF +is found on the channel or a specified number of values \fIlength\fR +are read (note that this is not necessarily the same as the number of +bytes). The following switches are supported: +.RS +.TP +\fB\-swap\fR +Swap bytes and words. The default endian is the host machine. +.TP +\fB\-at \fIindex\fR +New values will start at vector index \fIindex\fR. This will +overwrite any current values. +.TP +\fB\-format\fR \fIformat\fR +Specifies the format of the data. \fIFormat\fR can be one of the +following: "i1", "i2", "i4", "i8", "u1, "u2", "u4", "u8", "r4", +"r8", or "r16". The number indicates the number of bytes +required for each value. The letter indicates the type: "i" for signed, +"u" for unsigned, "r" or real. The default format is "r16". +.RE +.TP +\fIvecName \fBclear\fR +Clears the element indices from the array variable associated with +\fIvecName\fR. This doesn't affect the components of the vector. By +default, the number of entries in the Tcl array doesn't match the +number of components in the vector. This is because its too expensive +to maintain decimal strings for both the index and value for each +component. Instead, the index and value are saved only when you read +or write an element with a new index. This command removes the index +and value strings from the array. This is useful when the vector is +large. +.TP +\fIvecName \fBdelete\fR \fIindex\fR ?\fIindex\fR?... +Deletes the \fIindex\fRth component from the vector \fIvecName\fR. +\fIIndex\fR is the index of the element to be deleted. This is the +same as unsetting the array variable element \fIindex\fR. The vector +is compacted after all the indices have been deleted. +.TP +\fIvecName \fBdup\fR \fIdestName\fR +Copies \fIvecName\fR to \fIdestName\fR. \fIDestName\fR is the name of a +destination vector. If a vector \fIdestName\fR already exists, it is +overwritten with the components of \fIvecName\fR. Otherwise a +new vector is created. +.TP +\fIvecName \fBexpr\fR \fIexpression\fR +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 vectors. +.TP +\fIvecName \fBlength\fR ?\fInewSize\fR? +Queries or resets the number of components in \fIvecName\fR. +\fINewSize\fR is a number specifying the new size of the vector. If +\fInewSize\fR is smaller than the current size of \fIvecName\fR, +\fIvecName\fR is truncated. If \fInewSize\fR is greater, the vector +is extended and the new components are initialized to \f(CW0.0\fR. If +no \fInewSize\fR argument is present, the current length of the vector +is returned. +.TP +\fIvecName \fBmerge\fR \fIsrcName\fR ?\fIsrcName\fR?... +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. +.TP +\fIvecName \fBnotify\fR \fIkeyword\fR +Controls how vector clients are notified of changes to the vector. +The exact behavior is determined by \fIkeyword\fR. +.RS +.TP 0.75i +\f(CWalways\fR +Indicates that clients are to be notified immediately whenever the +vector is updated. +.TP +\f(CWnever\fR +Indicates that no clients are to be notified. +.TP +\f(CWwhenidle\fR +Indicates that clients are to be notified at the next idle point +whenever the vector is updated. +.TP +\f(CWnow\fR +If any client notifications is currently pending, they are notified +immediately. +.TP +\f(CWcancel\fR +Cancels pending notifications of clients using the vector. +.TP +\f(CWpending\fR +Returns \f(CW1\fR if a client notification is pending, and \f(CW0\fR otherwise. +.RE +.TP +\fIvecName \fBoffset\fR ?\fIvalue\fR? +Shifts the indices of the vector by the amount specified by \fIvalue\fR. +\fIValue\fR is an integer number. If no \fIvalue\fR argument is +given, the current offset is returned. +.TP +\fIvecName \fBpopulate\fR \fIdestName\fR ?\fIdensity\fR? +Creates a vector \fIdestName\fR which is a superset of \fIvecName\fR. +\fIDestName\fR will include all the components of \fIvecName\fR, in +addition the interval between each of the original components will +contain a \fIdensity\fR number of new components, whose values are +evenly distributed between the original components values. This is +useful for generating abscissas to be interpolated along a spline. +.TP +\fIvecName \fBrange\fR \fIfirstIndex\fR ?\fIlastIndex\fR?... +Returns a list of numeric values representing the vector components +between two indices. Both \fIfirstIndex\fR and \fIlastIndex\fR are +indices representing the range of components to be returned. If +\fIlastIndex\fR is less than \fIfirstIndex\fR, the components are +listed in reverse order. +.TP +\fIvecName \fBsearch\fR \fIvalue\fR ?\fIvalue\fR? +Searches for a value or range of values among the components of +\fIvecName\fR. If one \fIvalue\fR argument is given, a list of +indices of the components which equal \fIvalue\fR is returned. If a +second \fIvalue\fR is also provided, then the indices of all +components which lie within the range of the two values are returned. +If no components are found, then \f(CW""\fR is returned. +.TP +\fIvecName \fBset\fR \fIitem\fR +Resets the components of the vector to \fIitem\fR. \fIItem\fR can +be either a list of numeric expressions or another vector. +.TP +\fIvecName \fBseq\fR \fIstart\fR ?\fIfinish\fR? ?\fIstep\fR? +Generates a sequence of values starting with the value \fIstart\fR. +\fIFinish\fR indicates the terminating value of the sequence. +The vector is automatically resized to contain just the sequence. +If three arguments are present, \fIstep\fR designates the interval. +.sp +With only two arguments (no \fIfinish\fR argument), the sequence will +continue until the vector is filled. With one argument, the interval +defaults to 1.0. +.TP +\fIvecName \fBsort\fR ?\fB-reverse\fR? ?\fIargName\fR?... +Sorts the vector \fIvecName\fR in increasing order. If the +\fB-reverse\fR flag is present, the vector is sorted in decreasing +order. If other arguments \fIargName\fR are present, they are the +names of vectors which will be rearranged in the same manner as +\fIvecName\fR. Each vector must be the same length as \fIvecName\fR. +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. +.TP +\fIvecName \fBvariable\fR \fIvarName\fR +Maps a Tcl variable to the vector, creating another means for +accessing the vector. The variable \fIvarName\fR can't already +exist. This overrides any current variable mapping the vector +may have. +.RE +.SH C LANGUAGE API +You can create, modify, and destroy vectors from C code, using +library routines. +You need to include the header file \f(CWblt.h\fR. It contains the +definition of the structure \fBBlt_Vector\fR, which represents the +vector. It appears below. +.CS +\fRtypedef struct { + double *\fIvalueArr\fR; + int \fInumValues\fR; + int \fIarraySize\fR; + double \fImin\fR, \fImax\fR; +} \fBBlt_Vector\fR; +.CE +The field \fIvalueArr\fR points to memory holding the vector +components. The components are stored in a double precision array, +whose size size is represented by \fIarraySize\fR. \fINumValues\fR is +the length of vector. The size of the array is always equal to or +larger than the length of the vector. \fIMin\fR and \fImax\fR are +minimum and maximum component values. +.SH LIBRARY ROUTINES +The following routines are available from C to manage vectors. +Vectors are identified by the vector name. +.PP +\fBBlt_CreateVector\fR +.RS .25i +.TP 1i +Synopsis: +.CS +int \fBBlt_CreateVector\fR (\fIinterp\fR, \fIvecName\fR, \fIlength\fR, \fIvecPtrPtr\fR) +.RS 1.25i +Tcl_Interp *\fIinterp\fR; +char *\fIvecName\fR; +int \fIlength\fR; +Blt_Vector **\fIvecPtrPtr\fR; +.RE +.CE +.TP +Description: +Creates a new vector \fIvecName\fR\fR with a length of \fIlength\fR. +\fBBlt_CreateVector\fR creates both a new Tcl command and array +variable \fIvecName\fR. Neither a command nor variable named +\fIvecName\fR can already exist. A pointer to the vector is +placed into \fIvecPtrPtr\fR. +.TP +Results: +Returns \f(CWTCL_OK\fR if the vector is successfully created. If +\fIlength\fR is negative, a Tcl variable or command \fIvecName\fR +already exists, or memory cannot be allocated for the vector, then +\f(CWTCL_ERROR\fR is returned and \fIinterp->result\fR will contain an +error message. +.RE +.sp +.PP +\fBBlt_DeleteVectorByName\fR +.RS .25i +.TP 1i +Synopsis: +.CS +int \fBBlt_DeleteVectorByName\fR (\fIinterp\fR, \fIvecName\fR) +.RS 1.25i +Tcl_Interp *\fIinterp\fR; +char *\fIvecName\fR; +.RE +.CE +.TP 1i +Description: +Removes the vector \fIvecName\fR. \fIVecName\fR is the name of a vector +which must already exist. Both the Tcl command and array variable +\fIvecName\fR are destroyed. All clients of the vector will be notified +immediately that the vector has been destroyed. +.TP +Results: +Returns \f(CWTCL_OK\fR if the vector is successfully deleted. If +\fIvecName\fR is not the name a vector, then \f(CWTCL_ERROR\fR is returned +and \fIinterp->result\fR will contain an error message. +.RE +.sp +.PP +\fBBlt_DeleteVector\fR +.RS .25i +.TP 1i +Synopsis: +.CS +int \fBBlt_DeleteVector\fR (\fIvecPtr\fR) +.RS 1.25i +Blt_Vector *\fIvecPtr\fR; +.RE +.CE +.TP 1i +Description: +Removes the vector pointed to by \fIvecPtr\fR. \fIVecPtr\fR is a +pointer to a vector, typically set by \fBBlt_GetVector\fR or +\fBBlt_CreateVector\fR. 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. +.TP +Results: +Returns \f(CWTCL_OK\fR if the vector is successfully deleted. If +\fIvecName\fR is not the name a vector, then \f(CWTCL_ERROR\fR is returned +and \fIinterp->result\fR will contain an error message. +.RE +.sp +.PP +\fBBlt_GetVector\fR +.RS .25i +.TP 1i +Synopsis: +.CS +int \fBBlt_GetVector\fR (\fIinterp\fR, \fIvecName\fR, \fIvecPtrPtr\fR) +.RS 1.25i +Tcl_Interp *\fIinterp\fR; +char *\fIvecName\fR; +Blt_Vector **\fIvecPtrPtr\fR; +.RE +.CE +.TP 1i +Description: +Retrieves the vector \fIvecName\fR. \fIVecName\fR is the name of a +vector which must already exist. \fIVecPtrPtr\fR will point be set to +the address of the vector. +.TP +Results: +Returns \f(CWTCL_OK\fR if the vector is successfully retrieved. If +\fIvecName\fR is not the name of a vector, then \f(CWTCL_ERROR\fR is +returned and \fIinterp->result\fR will contain an error message. +.RE +.sp +.PP +\fBBlt_ResetVector\fR +.PP +.RS .25i +.TP 1i +Synopsis: +.CS +int \fBBlt_ResetVector\fR (\fIvecPtr\fR, \fIdataArr\fR, + \fInumValues\fR, \fIarraySize\fR, \fIfreeProc\fR) +.RS 1.25i +Blt_Vector *\fIvecPtr\fR; +double *\fIdataArr\fR; +int *\fInumValues\fR; +int *\fIarraySize\fR; +Tcl_FreeProc *\fIfreeProc\fR; +.RE +.CE +.TP +Description: +Resets the components of the vector pointed to by \fIvecPtr\fR. +Calling \fBBlt_ResetVector\fR will trigger the vector to dispatch +notifications to its clients. \fIDataArr\fR is the array of doubles +which represents the vector data. \fINumValues\fR is the number of +elements in the array. \fIArraySize\fR is the actual size of the array +(the array may be bigger than the number of values stored in +it). \fIFreeProc\fP indicates how the storage for the vector component +array (\fIdataArr\fR) was allocated. It is used to determine how to +reallocate memory when the vector is resized or destroyed. It must be +\f(CWTCL_DYNAMIC\fR, \f(CWTCL_STATIC\fR, \f(CWTCL_VOLATILE\fR, or a pointer +to a function to free the memory allocated for the vector array. If +\fIfreeProc\fR is \f(CWTCL_VOLATILE\fR, it indicates that \fIdataArr\fR +must be copied and saved. If \fIfreeProc\fR is \f(CWTCL_DYNAMIC\fR, it +indicates that \fIdataArr\fR was dynamically allocated and that Tcl +should free \fIdataArr\fR if necessary. \f(CWStatic\fR indicates that +nothing should be done to release storage for \fIdataArr\fR. +.TP +Results: +Returns \f(CWTCL_OK\fR if the vector is successfully resized. If +\fInewSize\fR is negative, a vector \fIvecName\fR does not exist, or +memory cannot be allocated for the vector, then \f(CWTCL_ERROR\fR is +returned and \fIinterp->result\fR will contain an error message. +.RE +.sp +.PP +\fBBlt_ResizeVector\fR +.RS .25i +.TP 1i +Synopsis: +.CS +int \fBBlt_ResizeVector\fR (\fIvecPtr\fR, \fInewSize\fR) +.RS 1.25i +Blt_Vector *\fIvecPtr\fR; +int \fInewSize\fR; +.RE +.CE +.TP +Description: +Resets the length of the vector pointed to by \fIvecPtr\fR to +\fInewSize\fR. If \fInewSize\fR is smaller than the current size of +the vector, it is truncated. If \fInewSize\fR is greater, the vector +is extended and the new components are initialized to \f(CW0.0\fR. +Calling \fBBlt_ResetVector\fR will trigger the vector to dispatch +notifications. +.TP +Results: +Returns \f(CWTCL_OK\fR if the vector is successfully resized. If +\fInewSize\fR is negative or memory can not be allocated for the vector, +then \f(CWTCL_ERROR\fR is returned and \fIinterp->result\fR will contain +an error message. +.sp +.PP +\fBBlt_VectorExists\fR +.RS .25i +.TP 1i +Synopsis: +.CS +int \fBBlt_VectorExists\fR (\fIinterp\fR, \fIvecName\fR) +.RS 1.25i +Tcl_Interp *\fIinterp\fR; +char *\fIvecName\fR; +.RE +.CE +.TP +Description: +Indicates if a vector named \fIvecName\fR exists in \fIinterp\fR. +.TP +Results: +Returns \f(CW1\fR if a vector \fIvecName\fR exists and \f(CW0\fR otherwise. +.RE +.sp +.PP +If your application needs to be notified when a vector changes, it can +allocate a unique \fIclient identifier\fR for itself. Using this +identifier, 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 +identifier for any vector. When the client application is done with +the vector, it should free the identifier. +.PP +The call-back routine must of the following type. +.CS +.RS +.sp +typedef void (\fBBlt_VectorChangedProc\fR) (Tcl_Interp *\fIinterp\fR, +.RS .25i +ClientData \fIclientData\fR, Blt_VectorNotify \fInotify\fR); +.RE +.sp +.RE +.CE +.fi +\fIClientData\fR is passed to this routine whenever it is called. You +can use this to pass information to the call-back. The \fInotify\fR +argument indicates whether the vector has been updated of destroyed. It +is an enumerated type. +.CS +.RS +.sp +typedef enum { + \f(CWBLT_VECTOR_NOTIFY_UPDATE\fR=1, + \f(CWBLT_VECTOR_NOTIFY_DESTROY\fR=2 +} \fBBlt_VectorNotify\fR; +.sp +.RE +.CE +.PP +\fBBlt_AllocVectorId\fR +.RS .25i +.TP 1i +Synopsis: +.CS +Blt_VectorId \fBBlt_AllocVectorId\fR (\fIinterp\fR, \fIvecName\fR) +.RS 1.25i +Tcl_Interp *\fIinterp\fR; +char *\fIvecName\fR; +.RE +.CE +.TP +Description: +Allocates an client identifier for with the vector \fIvecName\fR. +This identifier can be used to specify a call-back which is triggered +when the vector is updated or destroyed. +.TP +Results: +Returns a client identifier if successful. If \fIvecName\fR is not +the name of a vector, then \f(CWNULL\fR is returned and +\fIinterp->result\fR will contain an error message. +.RE +.sp +.PP +\fBBlt_GetVectorById\fR +.RS .25i +.TP 1i +Synopsis: +.CS +int \fBBlt_GetVector\fR (\fIinterp\fR, \fIclientId\fR, \fIvecPtrPtr\fR) +.RS 1.25i +Tcl_Interp *\fIinterp\fR; +Blt_VectorId \fIclientId\fR; +Blt_Vector **\fIvecPtrPtr\fR; +.RE +.CE +.TP 1i +Description: +Retrieves the vector used by \fIclientId\fR. \fIClientId\fR is a valid +vector client identifier allocated by \fBBlt_AllocVectorId\fR. +\fIVecPtrPtr\fR will point be set to the address of the vector. +.TP +Results: +Returns \f(CWTCL_OK\fR if the vector is successfully retrieved. +.RE +.sp +.PP +\fBBlt_SetVectorChangedProc\fR +.RS .25i +.TP 1i +Synopsis: +.CS +void \fBBlt_SetVectorChangedProc\fR (\fIclientId\fR, \fIproc\fR, \fIclientData\fR); +.RS 1.25i +Blt_VectorId \fIclientId\fR; +Blt_VectorChangedProc *\fIproc\fR; +ClientData *\fIclientData\fR; +.RE +.CE +.TP +Description: +Specifies a call-back routine to be called whenever the vector +associated with \fIclientId\fR is updated or deleted. \fIProc\fR is a +pointer to call-back routine and must be of the type +\fBBlt_VectorChangedProc\fR. \fIClientData\fR is a one-word value to +be passed to the routine when it is invoked. If \fIproc\fR is +\f(CWNULL\fR, then the client is not notified. +.TP +Results: +The designated call-back procedure will be invoked when the vector is +updated or destroyed. +.RE +.sp +.PP +\fBBlt_FreeVectorId\fR +.RS .25i +.TP 1i +Synopsis: +.CS +void \fBBlt_FreeVectorId\fR (\fIclientId\fR); +.RS 1.25i +Blt_VectorId \fIclientId\fR; +.RE +.CE +.TP +Description: +Frees the client identifier. Memory allocated for the identifier +is released. The client will no longer be notified when the +vector is modified. +.TP +Results: +The designated call-back procedure will be no longer be invoked when +the vector is updated or destroyed. +.RE +.sp +.PP +\fBBlt_NameOfVectorId\fR +.RS .25i +.TP 1i +Synopsis: +.CS +char *\fBBlt_NameOfVectorId\fR (\fIclientId\fR); +.RS 1.25i +Blt_VectorId \fIclientId\fR; +.RE +.CE +.TP +Description: +Retrieves the name of the vector associated with the client identifier +\fIclientId\fR. +.TP +Results: +Returns the name of the vector associated with \fIclientId\fR. If +\fIclientId\fR is not an identifier or the vector has been destroyed, +\f(CWNULL\fR is returned. +.RE +.sp +.PP +\fBBlt_InstallIndexProc\fR +.RS .25i +.TP 1i +Synopsis: +.CS +void \fBBlt_InstallIndexProc\fR (\fIindexName\fR, \fIprocPtr\fR) +.RS 1.25i +char *\fIindexName\fR; +Blt_VectorIndexProc *\fIprocPtr\fR; +.RE +.CE +.TP +Description: +Registers a function to be called to retrieved the index \fIindexName\fR +from the vector's array variable. +.sp +typedef double Blt_VectorIndexProc(Vector *vecPtr); +.sp +The function will be passed a pointer to the vector. The function must +return a double representing the value at the index. +.TP +Results: +The new index is installed into the vector. +.RE +.RE +.SH C API EXAMPLE +The following example opens a file of binary data and stores it in an +array of doubles. The array size is computed from the size of the +file. If the vector "data" exists, calling \fBBlt_VectorExists\fR, +\fBBlt_GetVector\fR is called to get the pointer to the vector. +Otherwise the routine \fBBlt_CreateVector\fR is called to create a new +vector and returns a pointer to it. Just like the Tcl interface, both +a new Tcl command and array variable are created when a new vector is +created. It doesn't make any difference what the initial size of the +vector is since it will be reset shortly. The vector is updated when +\fBlt_ResetVector\fR is called. Blt_ResetVector makes the changes +visible to the Tcl interface and other vector clients (such as a graph +widget). +.sp +.CS +#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 = (double *)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; +} +.CE +.SH "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 procedure returns. +.CS +proc doit {} { + # Temporary vector x + vector x(10) + set x(9) 2.0 + ... +} +.CE +.PP +This has changed. Variables are not automatically destroyed when +their variable is unset. You can restore the old behavior by +setting the "-watchunset" switch. +.CE +.SH KEYWORDS +vector, graph, widget |