diff options
Diffstat (limited to 'tkblt/doc')
| -rw-r--r-- | tkblt/doc/BLT.html | 74 | ||||
| -rw-r--r-- | tkblt/doc/BLT.n | 76 | ||||
| -rw-r--r-- | tkblt/doc/barchart.html | 1640 | ||||
| -rw-r--r-- | tkblt/doc/barchart.n | 2239 | ||||
| -rw-r--r-- | tkblt/doc/graph.html | 1759 | ||||
| -rw-r--r-- | tkblt/doc/graph.n | 2408 | ||||
| -rw-r--r-- | tkblt/doc/vector.html | 704 | ||||
| -rw-r--r-- | tkblt/doc/vector.n | 1134 |
8 files changed, 0 insertions, 10034 deletions
diff --git a/tkblt/doc/BLT.html b/tkblt/doc/BLT.html deleted file mode 100644 index 55e4e38..0000000 --- a/tkblt/doc/BLT.html +++ /dev/null @@ -1,74 +0,0 @@ -<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/tkblt/doc/BLT.n b/tkblt/doc/BLT.n deleted file mode 100644 index 6f63aa8..0000000 --- a/tkblt/doc/BLT.n +++ /dev/null @@ -1,76 +0,0 @@ -'\" -'\" 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/tkblt/doc/barchart.html b/tkblt/doc/barchart.html deleted file mode 100644 index 7f04d25..0000000 --- a/tkblt/doc/barchart.html +++ /dev/null @@ -1,1640 +0,0 @@ -<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/tkblt/doc/barchart.n b/tkblt/doc/barchart.n deleted file mode 100644 index 7a9dac8..0000000 --- a/tkblt/doc/barchart.n +++ /dev/null @@ -1,2239 +0,0 @@ -'\" -'\" 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/tkblt/doc/graph.html b/tkblt/doc/graph.html deleted file mode 100644 index 70f1e6f..0000000 --- a/tkblt/doc/graph.html +++ /dev/null @@ -1,1759 +0,0 @@ -<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/tkblt/doc/graph.n b/tkblt/doc/graph.n deleted file mode 100644 index fbbbb9b..0000000 --- a/tkblt/doc/graph.n +++ /dev/null @@ -1,2408 +0,0 @@ -'\" -'\" 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/tkblt/doc/vector.html b/tkblt/doc/vector.html deleted file mode 100644 index ef097c6..0000000 --- a/tkblt/doc/vector.html +++ /dev/null @@ -1,704 +0,0 @@ -<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/tkblt/doc/vector.n b/tkblt/doc/vector.n deleted file mode 100644 index fa8bb7e..0000000 --- a/tkblt/doc/vector.n +++ /dev/null @@ -1,1134 +0,0 @@ -'\" -'\" 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 |