diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2019-08-04 17:06:59 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2019-08-04 17:06:59 (GMT) |
commit | 7c373035e82314e6e5b4390ef32f57cf891fcfcf (patch) | |
tree | 50bb9a8a6c4b1495e4eff46b860706670cf36d18 /doc/barchart.n | |
download | blt-7c373035e82314e6e5b4390ef32f57cf891fcfcf.zip blt-7c373035e82314e6e5b4390ef32f57cf891fcfcf.tar.gz blt-7c373035e82314e6e5b4390ef32f57cf891fcfcf.tar.bz2 |
Squashed 'tkblt/' content from commit 82a6d57b
git-subtree-dir: tkblt
git-subtree-split: 82a6d57b3b7afe7a5f33d954664adc43758de014
Diffstat (limited to 'doc/barchart.n')
-rw-r--r-- | doc/barchart.n | 2239 |
1 files changed, 2239 insertions, 0 deletions
diff --git a/doc/barchart.n b/doc/barchart.n new file mode 100644 index 0000000..7a9dac8 --- /dev/null +++ b/doc/barchart.n @@ -0,0 +1,2239 @@ +'\" +'\" Smithsonian Astrophysical Observatory, Cambridge, MA, USA +'\" This code has been modified under the terms listed below and is made +'\" available under the same terms. +'\" +'\" Copyright 1991-1998 by Bell Labs Innovations for Lucent Technologies. +'\" +'\" Permission to use, copy, modify, and distribute this software and its +'\" documentation for any purpose and without fee is hereby granted, provided +'\" that the above copyright notice appear in all copies and that both that the +'\" copyright notice and warranty disclaimer appear in supporting documentation, +'\" and that the names of Lucent Technologies any of their entities not be used +'\" in advertising or publicity pertaining to distribution of the software +'\" without specific, written prior permission. +'\" +'\" Lucent Technologies disclaims all warranties with regard to this software, +'\" including all implied warranties of merchantability and fitness. In no event +'\" shall Lucent Technologies be liable for any special, indirect or +'\" consequential damages or any damages whatsoever resulting from loss of use, +'\" data or profits, whether in an action of contract, negligence or other +'\" tortuous action, arising out of or in connection with the use or performance +'\" of this software. +'\" +'\" Barchart widget created by Sani Nassif and George Howlett. +'\" +.TH barchart n BLT_VERSION BLT "BLT Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +barchart \- Bar chart for plotting X-Y coordinate data. +.SH SYNOPSIS +\fBbarchart\fI \fIpathName \fR?\fIoption value\fR?... +.BE +.SH DESCRIPTION +The \fBbarchart\fR command creates a bar chart for plotting +two-dimensional data (X-Y coordinates). A bar chart is a graphic means +of comparing numbers by displaying bars of lengths proportional to the +y-coordinates of the points they represented. The bar chart has many +configurable components: coordinate axes, elements, legend, grid +lines, cross hairs, etc. They allow you to customize the look and +feel of the graph. +.SH INTRODUCTION +The \fBbarchart\fR command creates a new window for plotting +two-dimensional data (X-Y coordinates), using bars of +various lengths to represent the data points. The bars are drawn in a +rectangular area displayed in the center of the new window. This is the +\fIplotting area\fR. The coordinate axes are drawn in +the margins surrounding the plotting area. By default, the legend is +drawn in the right margin. The title is displayed in top margin. +.PP +A \fBbarchart\fR widget has several configurable components: +coordinate axes, data elements, legend, grid, cross hairs, pens, +postscript, and annotation markers. Each component can be queried or +modified. +.TP 1i +\f(CWaxis\fR + +Up to four coordinate axes (two X\-coordinate and two Y\-coordinate +axes) can be displayed, but you can create and use any number of +axes. Axes control what region of data is displayed and how the data +is scaled. Each axis consists of the axis line, title, major and minor +ticks, and tick labels. Tick labels display the value at each major +tick. +.TP 1i +\f(CWcrosshairs\fR +Cross hairs are used to position the mouse pointer relative to the X +and Y coordinate axes. Two perpendicular lines, intersecting at the +current location of the mouse, extend across the plotting area to the +coordinate axes. +.TP 1i +\f(CWelement\fR +An element represents a set of data to be plotted. It contains an x +and y vector of values representing the data points. Each +data point is displayed as a bar where the length of the bar is +proportional to the ordinate (Y-coordinate) of the data point. +The appearance of the bar, such as its color, stipple, or relief +is configurable. +.sp +A special case exists when two or more data points have the same +abscissa (X-coordinate). By default, the bars are overlayed, one on +top of the other. The bars are drawn in the order of the element +display list. But you can also configure the bars to be displayed in +two other ways. They may be displayed as a stack, where each bar +(with the same abscissa) is stacked on the previous. Or they can be +drawn side-by-side as thin bars. The width of each bar is a function +of the number of data points with the same abscissa. +.TP 1i +\f(CWgrid\fR +Extends the major and minor ticks of the X\-axis and/or Y\-axis across the +plotting area. +.TP 1i +\f(CWlegend\fR +The legend displays the name and symbol of each data element. +The legend can be drawn in any margin or in the plotting area. +.TP 1i +\f(CWmarker\fR +Markers are used annotate or highlight areas of the graph. For +example, you could use a text marker to label a particular data +point. Markers come in various forms: text strings, bitmaps, connected +line segments, images, polygons, or embedded widgets. +.TP 1i +\f(CWpen\fR +Pens define attributes for elements. Data elements use pens to +specify how they should be drawn. A data element may use many pens at +once. Here the particular pen used for a data point is determined +from each element's weight vector (see the element's \fB\-weight\fR +and \fB\-style\fR options). +.TP 1i +\f(CWpostscript\fR +The widget can generate encapsulated PostScript output. This component +has several options to configure how the PostScript is generated. +.SH SYNTAX +.DS +\fBbarchart \fIpathName \fR?\fIoption value\fR?... +.DE +The \fBbarchart\fR command creates a new window \fIpathName\fR and makes +it into a \fBbarchart\fR widget. At the time this command is invoked, there +must not exist a window named \fIpathName\fR, but \fIpathName\fR's +parent must exist. Additional options may be specified on the +command line or in the option database to configure aspects of the +graph such as its colors and font. See the \fBconfigure\fR operation +below for the exact details about what \fIoption\fR and \fIvalue\fR +pairs are valid. +.PP +If successful, \fBbarchart\fR returns the path name of the widget. It +also creates a new Tcl command by the same name. You can use this +command to invoke various operations that query or modify the graph. +The general form is: +.DS +\fIpathName \fIoperation\fR \fR?\fIarg\fR?... +.DE +Both \fIoperation\fR and its arguments determine the exact behavior of +the command. The operations available for the graph are described in +the +.SB "BARCHART OPERATIONS" +section. +.PP +The command can also be used to access components of the graph. +.DS +\fIpathName component operation\fR ?\fIarg\fR?... +.DE +The operation, now located after the name of the component, is the +function to be performed on that component. Each component has its own +set of operations that manipulate that component. They will be +described below in their own sections. +.SH EXAMPLE +The \fBbarchart\fR command creates a new bar chart. +.CS +# Create a new bar chart. Plotting area is black. +barchart .b -plotbackground black +.CE +A new Tcl command \f(CW.b\fR is created. This command can be used +to query and modify the bar chart. For +example, to change the title of the graph to "My Plot", you use the +new command and the \fBconfigure\fR operation. +.CS +# Change the title. +\&.b configure -title "My Plot" +.CE +To add data elements, you use the command and the \fBelement\fR component. +.CS +# Create a new element named "e1" +\&.b element create e1 \\ + -xdata { 1 2 3 4 5 6 7 8 9 10 } \\ + -ydata { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 + 155.85 166.60 175.38 } +.CE +The element's X-Y coordinates are specified using lists of +numbers. Alternately, BLT vectors could be used to hold the X-Y +coordinates. +.CS +# Create two vectors and add them to the barchart. +vector xVector yVector +xVector set { 1 2 3 4 5 6 7 8 9 10 } +yVector set { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85 + 166.60 175.38 } +\&n.b element create e1 -xdata xVector -ydata yVector +.CE +The advantage of using vectors is that when you modify one, the graph +is automatically redrawn to reflect the new values. +.CS +# Change the y coordinate of the first point. +set yVector(0) 25.18 +.CE +An element named \f(CWe1\fR is now created in \f(CW.b\fR. It +is automatically added to the display list of elements. You can +use this list to control in what order elements are displayed. +To query or reset the element display list, you use the element's +\fBshow\fR operation. +.CS +# Get the current display list +set elemList [.b element show] +# Remove the first element so it won't be displayed. +\&.b element show [lrange $elemList 0 end] +.CE +The element will be displayed by as many bars as there are data points +(in this case there are ten). The bars will be drawn centered at the +x-coordinate of the data point. All the bars will have the same +attributes (colors, stipple, etc). The width of each bar is by +default one unit. You can change this with using the \fB\-barwidth\fR +option. +.CS +# Change the scale of the x-coordinate data +xVector set { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 } +# Make sure we change the bar width too. +\&.b configure -barwidth 0.2 +.CE +The height of each bar is proportional to the ordinate (Y-coordinate) +of the data point. +.PP +If two or more data points have the same abscissa (X-coordinate +value), the bars representing those data points may be drawn in +various ways. +The default is to overlay the bars, one on top of the other. +The ordering is determined from the of element display list. If +the stacked mode is selected (using the \fB\-barmode\fR configuration +option), the bars are stacked, each bar above the previous. +.CS +# Display the elements as stacked. +\&.b configure -barmode stacked +.CE +If the aligned mode is selected, the bars having the same +x-coordinates are displayed side by side. The width of each bar is a +fraction of its normal width, based upon the number of bars with the +same x-coordinate. +.CS +# Display the elements side-by-side. +\&.b configure -barmode aligned +.CE +By default, the element's label in the legend will be also +\f(CWe1\fR. You can change the label, or specify no legend entry, +again using the element's \fBconfigure\fR operation. +.CS +# Don't display "e1" in the legend. +\&.b element configure e1 -label "" +.CE +You can configure more than just the element's label. An element has +many attributes such as stipple, foreground and background colors, +relief, etc. +.CS +\&.b element configure e1 -fg red -bg pink \\ + -stipple gray50 +.CE +Four coordinate axes are automatically created: \f(CWx\fR, \f(CWx2\fR, +\f(CWy\fR, and \f(CWy2\fR. And by default, elements are mapped onto the +axes \f(CWx\fR and \f(CWy\fR. This can be changed with the \fB\-mapx\fR +and \fB\-mapy\fR options. +.CS +# Map "e1" on the alternate y axis "y2". +\&.b element configure e1 -mapy y2 +.CE +Axes can be configured in many ways too. For example, you change the +scale of the Y\-axis from linear to log using the \fBaxis\fR component. +.CS +# Y-axis is log scale. +\&.b axis configure y -logscale yes +.CE +One important way axes are used is to zoom in on a particular data +region. Zooming is done by simply specifying new axis limits using +the \fB\-min\fR and \fB\-max\fR configuration options. +.CS +\&.b axis configure x \-min 1.0 \-max 1.5 +\&.b axis configure y \-min 12.0 \-max 55.15 +.CE +To zoom interactively, you link the\fBaxis configure\fR operations with +some user interaction (such as pressing the mouse button), using the +\fBbind\fR command. To convert between screen and graph coordinates, +use the \fBinvtransform\fR operation. +.CS +# Click the button to set a new minimum +bind .b <ButtonPress-1> { + %W axis configure x \-min [%W axis invtransform x %x] + %W axis configure x \-min [%W axis invtransform x %y] +} +.CE +By default, the limits of the axis are determined from data values. +To reset back to the default limits, set the \fB\-min\fR and +\fB\-max\fR options to the empty value. +.CS +# Reset the axes to autoscale again. +\&.b axis configure x \-min {} \-max {} +\&.b axis configure y \-min {} \-max {} +.CE +By default, the legend is drawn in the right margin. You can +change this or any legend configuration options using the +\fBlegend\fR component. +.CS +# Configure the legend font, color, and relief +\&.b legend configure -position left -relief raised \\ + -font fixed -fg blue +.CE +To prevent the legend from being displayed, turn on the \fB\-hide\fR +option. +.CS +# Don't display the legend. +\&.b legend configure \-hide yes\fR +.CE +The \fBbarchart\fR has simple drawing procedures called markers. They can be +used to highlight or annotate data in the graph. The types of markers +available are bitmaps, polygons, lines, or windows. Markers can be +used, for example, to mark or brush points. For example there may be +a line marker which indicates some low-water value. Markers are created +using the \fBmarker\fR operation. +.CS +# Create a line represent the low water mark at 10.0 +\&.b marker create line -name "low_water" \\ + -coords { -Inf 10.0 Inf 10.0 } \\ + -dashes { 2 4 2 } -fg red -bg blue +.CE +This creates a line marker named \f(CWlow_water\fR. It will display a +horizontal line stretching across the plotting area at the +y-coordinate 10.0. The coordinates "-Inf" and "Inf" indicate the +relative minimum and maximum of the axis (in this case the x-axis). By +default, markers are drawn last, on top of the bars. You can change this +with the \fB\-under\fR option. +.CS +# Draw the marker before elements are drawn. +\&.b marker configure low_water -under yes +.CE +You can add cross hairs or grid lines using the \fBcrosshairs\fR and +\fBgrid\fR components. +.CS +# Display both cross hairs and grid lines. +\&.b crosshairs configure -hide no -color red +\&.b grid configure -hide no -dashes { 2 2 } +.CE +Finally, to get hardcopy of the graph, use the \fBpostscript\fR +component. +.CS +# Print the bar chart into file "file.ps" +\&.b postscript output file.ps -maxpect yes -decorations no +.CE +This generates a file \f(CWfile.ps\fR containing the encapsulated +PostScript of the graph. The option \fB\-maxpect\fR says to scale the +plot to the size of the page. Turning off the \fB\-decorations\fR +option denotes that no borders or color backgrounds should be +drawn (i.e. the background of the margins, legend, and plotting +area will be white). +.SH SYNTAX +.DS +\fBbarchart \fIpathName \fR?\fIoption value\fR?... +.DE +The \fBbarchart\fR command creates a new window \fIpathName\fR and makes +it into a barchart widget. At the time this command is invoked, there +must not exist a window named \fIpathName\fR, but \fIpathName\fR's +parent must exist. Additional options may may be specified on the +command line or in the option database to configure aspects of the +bar chart such as its colors and font. See the \fBconfigure\fR operation +below for the exact details as to what \fIoption\fR and \fIvalue\fR +pairs are valid. +.PP +If successful, \fBbarchart\fR returns \fIpathName\fR. It also creates a +new Tcl command \fIpathName\fR. This command may be used to invoke +various operations to query or modify the bar chart. It has the general +form: +.DS +\fIpathName \fIoperation\fR \fR?\fIarg\fR?... +.DE +Both \fIoperation\fR and its arguments determine the exact behavior of +the command. The operations available for the bar chart are described in +the following section. +.SH "BARCHART OPERATIONS" +.TP +\fIpathName \fBbar \fIelemName \fR?\fIoption value\fR?... +Creates a new barchart element \fIelemName\fR. It's an +error if an element \fIelemName\fR already exists. +See the manual for \fBbarchart\fR for details about +what \fIoption\fR and \fIvalue\fR pairs are valid. +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given by +\fIoption\fR. \fIOption\fR may be any option described +below for the \fBconfigure\fR operation. +.TP +\fIpathName \fBconfigure \fR?\fIoption value\fR?... +Queries or modifies the configuration options of the graph. If +\fIoption\fR isn't specified, a list describing the current +options for \fIpathName\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the option \fIoption\fR is set to \fIvalue\fR. +The following options are valid. +.RS +.TP +\fB\-background \fIcolor\fR +Sets the background color. This includes the margins and +legend, but not the plotting area. +.TP +\fB\-barmode \fImode\fR +Indicates how related bar elements will be drawn. Related elements +have data points with the same abscissas (X-coordinates). \fIMode\fR +indicates how those segments should be drawn. \fIMode\fR can be +\f(CWinfront\fR, \f(CWaligned\fR, \f(CWoverlap\fR, or \f(CWstacked\fR. +The default mode is \f(CWinfront\fR. +.RS +.TP 1i +\f(CWinfront\fR +Each successive segment is drawn in front of the previous. +.TP 1i +\f(CWstacked\fR +Each successive segment is stacked vertically on top of the previous. +.TP 1i +\f(CWaligned\fR +Segments is displayed aligned from right-to-left. +.TP 1i +\f(CWoverlap\fR +Like \f(CWaligned\fR but segments slightly overlap each other. +.RE +.TP +\fB\-barwidth \fIvalue\fR +Specifies the width of the bars. This value can be overrided by the +individual elements using their \fB\-barwidth\fR configuration option. +\fIValue\fR is the width in terms of graph-coordinates. The +default width is \f(CW1.0\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the width of the 3\-D border around the outside edge of the widget. The +\fB\-relief\fR option determines if the border is to be drawn. The +default is \f(CW2\fR. +.TP +\fB\-bottommargin \fIpixels\fR +Specifies the size of the margin below the X\-coordinate axis. If +\fIpixels\fR is \f(CW0\fR, the size of the margin is selected automatically. +The default is \f(CW0\fR. +.TP +\fB\-bufferelements \fIboolean\fR +Indicates whether an internal pixmap to buffer the display of data +elements should be used. If \fIboolean\fR is true, data elements are +drawn to an internal pixmap. This option is especially useful when +the graph is redrawn frequently while the remains data unchanged (for +example, moving a marker across the plot). See the +.SB "SPEED TIPS" +section. +The default is \f(CW1\fR. +.TP +\fB\-cursor \fIcursor\fR +Specifies the widget's cursor. The default cursor is \f(CWcrosshair\fR. +.TP +\fB\-font \fIfontName\fR +Specifies the font of the graph title. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-18-180-*\fR. +.TP +\fB\-halo \fIpixels\fR +Specifies a maximum distance to consider when searching for the +closest data point (see the element's \fBclosest\fR operation below). +Data points further than \fIpixels\fR away are ignored. The default is +\f(CW0.5i\fR. +.TP +\fB\-height \fIpixels\fR +Specifies the requested height of widget. The default is +\f(CW4i\fR. +.TP +\fB\-invertxy \fIboolean\fR +Indicates whether the placement X\-axis and Y\-axis should be inverted. If +\fIboolean\fR is true, the X and Y axes are swapped. The default is +\f(CW0\fR. +.TP +\fB\-justify \fIjustify\fR +Specifies how the title should be justified. This matters only when +the title contains more than one line of text. \fIJustify\fR must be +\f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-leftmargin \fIpixels\fR +Sets the size of the margin from the left edge of the window to +the Y\-coordinate axis. If \fIpixels\fR is \f(CW0\fR, the size is +calculated automatically. The default is \f(CW0\fR. +.TP +\fB\-plotbackground \fIcolor\fR +Specifies the background color of the plotting area. The default is +\f(CWwhite\fR. +.TP +\fB\-plotborderwidth \fIpixels\fR +Sets the width of the 3-D border around the plotting area. The +\fB\-plotrelief\fR option determines if a border is drawn. The +default is \f(CW2\fR. +.TP +\fB\-plotpadx \fIpad\fR +Sets the amount of padding to be added to the left and right sides of +the plotting area. \fIPad\fR can be a list of one or two screen +distances. If \fIpad\fR has two elements, the left side of the +plotting area entry is padded by the first distance and the right side +by the second. If \fIpad\fR is just one distance, both the left and +right sides are padded evenly. The default is \f(CW8\fR. +.TP +\fB\-plotpady \fIpad\fR +Sets the amount of padding to be added to the top and bottom of the +plotting area. \fIPad\fR can be a list of one or two screen +distances. If \fIpad\fR has two elements, the top of the plotting +area is padded by the first distance and the bottom by the second. If +\fIpad\fR is just one distance, both the top and bottom are padded +evenly. The default is \f(CW8\fR. +.TP +\fB\-plotrelief \fIrelief\fR +Specifies the 3-D effect for the plotting area. \fIRelief\fR +specifies how the interior of the plotting area should appear relative +to rest of the graph; for example, \f(CWraised\fR means the plot should +appear to protrude from the graph, relative to the surface of the +graph. The default is \f(CWsunken\fR. +.TP +\fB\-relief \fIrelief\fR +Specifies the 3-D effect for the barchart widget. \fIRelief\fR +specifies how the graph should appear relative to widget it is packed +into; for example, \f(CWraised\fR means the graph should +appear to protrude. The default is \f(CWflat\fR. +.TP +\fB\-rightmargin \fIpixels\fR +Sets the size of margin from the plotting area to the right edge of +the window. By default, the legend is drawn in this margin. If +\fIpixels\fR is than 1, the margin size is selected automatically. +.TP +\fB\-takefocus\fR \fIfocus\fR +Provides information used when moving the focus from window to window +via keyboard traversal (e.g., Tab and Shift-Tab). If \fIfocus\fR is +\f(CW0\fR, this means that this window should be skipped entirely during +keyboard traversal. \f(CW1\fR means that the this window should always +receive the input focus. An empty value means that the traversal +scripts make the decision whether to focus on the window. +The default is \f(CW""\fR. +.TP +\fB\-tile \fIimage\fR +Specifies a tiled background for the widget. If \fIimage\fR isn't +\f(CW""\fR, the background is tiled using \fIimage\fR. +Otherwise, the normal background color is drawn (see the +\fB\-background\fR option). \fIImage\fR must be an image created +using the Tk \fBimage\fR command. The default is \f(CW""\fR. +.TP +\fB\-title \fItext\fR +Sets the title to \fItext\fR. If \fItext\fR is \f(CW""\fR, +no title will be displayed. +.TP +\fB\-topmargin \fIpixels\fR +Specifies the size of the margin above the x2 axis. If \fIpixels\fR +is \f(CW0\fR, the margin size is calculated automatically. +.TP +\fB\-width \fIpixels\fR +Specifies the requested width of the widget. The default is +\f(CW5i\fR. +.RE +.TP +\fIpathName \fBcrosshairs \fIoperation \fR?\fIarg\fR? +See the +.SB "CROSSHAIRS COMPONENT" +section. +.TP +\fIpathName \fBelement \fIoperation \fR?\fIarg\fR?... +See the +.SB "ELEMENT COMPONENTS" +section. +.TP +\fIpathName \fBextents \fIitem\fR +Returns the size of a particular item in the graph. \fIItem\fR must +be either \f(CWleftmargin\fR, \f(CWrightmargin\fR, \f(CWtopmargin\fR, +\f(CWbottommargin\fR, \f(CWplotwidth\fR, or \f(CWplotheight\fR. +.TP +\fIpathName \fBgrid \fIoperation \fR?\fIarg\fR?... +See the +.SB "GRID COMPONENT" +section. +.TP +\fIpathName \fBinvtransform \fIwinX winY\fR +Performs an inverse coordinate transformation, mapping window +coordinates back to graph-coordinates, using the standard X\-axis and Y\-axis. +Returns a list of containing the X-Y graph-coordinates. +.TP +\fIpathName \fBinside \fIx y\fR +Returns \f(CW1\fR is the designated screen-coordinate (\fIx\fR and \fIy\fR) +is inside the plotting area and \f(CW0\fR otherwise. +.TP +\fIpathName \fBlegend \fIoperation \fR?\fIarg\fR?... +See the +.SB "LEGEND COMPONENT" +section. +.TP +\fIpathName \fBline\fB operation arg\fR... +The operation is the same as \fBelement\fR. +.TP +\fIpathName \fBmarker \fIoperation \fR?\fIarg\fR?... +See the +.SB "MARKER COMPONENTS" +section. +.TP +\fIpathName\fR \fBmetafile\fR ?\fIfileName\fR? +\fIThis operation is for Window platforms only\fR. +Creates a Windows enhanced metafile of the barchart. +If present, \fIfileName\fR is the file name of the new metafile. +Otherwise, the metafile is automatically added to the clipboard. +.TP +\fIpathName \fBpostscript \fIoperation \fR?\fIarg\fR?... +See the +.SB "POSTSCRIPT COMPONENT" +section. +.TP +\fIpathName \fBsnap \fIphotoName\fR +Takes a snapshot of the graph and stores the contents in the photo +image \fIphotoName\fR. \fIPhotoName\fR is the name of a Tk photo +image that must already exist. +.TP +\fIpathName \fBtransform \fIx y\fR +Performs a coordinate transformation, mapping graph-coordinates to +window coordinates, using the standard X\-axis and Y\-axis. +Returns a list containing the X\-Y screen-coordinates. +.TP +\fIpathName \fBxaxis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fBx2axis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fByaxis \fIoperation\fR ?\fIarg\fR?... +.TP +\fIpathName \fBy2axis \fIoperation\fR ?\fIarg\fR?... +See the +.SB "AXIS COMPONENTS" +section. +.SH "BARCHART COMPONENTS" +A graph is composed of several components: coordinate axes, data +elements, legend, grid, cross hairs, postscript, and annotation +markers. Instead of one big set of configuration options and +operations, the graph is partitioned, where each component has its own +configuration options and operations that specifically control that +aspect or part of the graph. +.SS "AXIS COMPONENTS" +Four coordinate axes are automatically created: two X\-coordinate axes +(\f(CWx\fR and \f(CWx2\fR) and two Y\-coordinate axes (\f(CWy\fR, and +\f(CWy2\fR). By default, the axis \f(CWx\fR is located in the bottom +margin, \f(CWy\fR in the left margin, \f(CWx2\fR in the top margin, and +\f(CWy2\fR in the right margin. +.PP +An axis consists of the axis line, title, major and minor ticks, and +tick labels. Major ticks are drawn at uniform intervals along the +axis. Each tick is labeled with its coordinate value. Minor ticks +are drawn at uniform intervals within major ticks. +.PP +The range of the axis controls what region of data is plotted. +Data points outside the minimum and maximum limits of the axis are +not plotted. By default, the minimum and maximum limits are +determined from the data, but you can reset either limit. +.PP +You can create and use several axes. To create an axis, invoke +the axis component and its create operation. +.CS +# Create a new axis called "temperature" +\&.b axis create temperature +.CE +You map data elements to an axis using the element's \-mapy and \-mapx +configuration options. They specify the coordinate axes an element +is mapped onto. +.CS +# Now map the temperature data to this axis. +\&.b element create "temp" \-xdata $x \-ydata $tempData \\ + \-mapy temperature +.CE +While you can have many axes, only four axes can be displayed +simultaneously. They are drawn in each of the margins surrounding +the plotting area. The axes \f(CWx\fR and \f(CWy\fR are drawn in the +bottom and left margins. The axes \f(CWx2\fR and \f(CWy2\fR are drawn in +top and right margins. Only \f(CWx\fR and \f(CWy\fR are shown by +default. Note that the axes can have different scales. +.PP +To display a different axis, you invoke one of the following +components: \fBxaxis\fR, \fByaxis\fR, \fBx2axis\fR, and \fBy2axis\fR. +The \fBuse\fR operation designates the axis to be drawn in the +corresponding margin: \fBxaxis\fR in the bottom, \fByaxis\fR in the left, +\fBx2axis\fR in the top, and \fBy2axis\fR in the right. +.CS +# Display the axis temperature in the left margin. +\&.b yaxis use temperature +.CE +.PP +You can configure axes in many ways. The axis scale can be linear or +logarithmic. The values along the axis can either monotonically +increase or decrease. If you need custom tick labels, you can specify +a Tcl procedure to format the label any way you wish. You can +control how ticks are drawn, by changing the major tick interval +or the number of minor ticks. You can define non-uniform tick intervals, +such as for time-series plots. +.PP +.TP +\fIpathName \fBaxis \fBcget \fIaxisName \fIoption\fR +Returns the current value of the option given by \fIoption\fR for +\fIaxisName\fR. \fIOption\fR may be any option described below +for the axis \fBconfigure\fR operation. +.TP +\fIpathName \fBaxis \fBconfigure \fIaxisName \fR?\fIaxisName\fR?... ?\fIoption value\fR?... +Queries or modifies the configuration options of \fIaxisName\fR. +Several axes can be changed. If \fIoption\fR isn't specified, a list +describing all the current options for \fIaxisName\fR is returned. If +\fIoption\fR is specified, but not \fIvalue\fR, then a list describing +\fIoption\fR is returned. If one or more \fIoption\fR and \fIvalue\fR +pairs are specified, then for each pair, the axis option \fIoption\fR +is set to \fIvalue\fR. The following options are valid for axes. +.RS +.TP +\fB\-autorange \fIrange\fR +Sets the range of values for the axis to \fIrange\fR. The axis limits +are automatically reset to display the most recent data points in this range. +If \fIrange\fR is 0.0, the range is +determined from the limits of the data. If \fB\-min\fR or \fB-max\fR +are specified, they override this option. The default is \f(CW0.0\fR. +.TP +\fB\-color \fIcolor\fR +Sets the color of the axis and tick labels. +The default is \f(CWblack\fR. +.TP +\fB\-command \fIprefix\fR +Specifies a Tcl command to be invoked when formatting the axis tick +labels. \fIPrefix\fR is a string containing the name of a Tcl proc and +any extra arguments for the procedure. This command is invoked for each +major tick on the axis. Two additional arguments are passed to the +procedure: the pathname of the widget and the current the numeric +value of the tick. The procedure returns the formatted tick label. If +\f(CW""\fR is returned, no label will appear next to the tick. You can +get the standard tick labels again by setting \fIprefix\fR to +\f(CW""\fR. The default is \f(CW""\fR. +.sp 1 +Please note that this procedure is invoked while the bar chart is redrawn. +You may query the widget's configuration options. But do not reset +options, because this can have unexpected results. +.TP +\fB\-descending \fIboolean\fR +Indicates whether the values along the axis are monotonically increasing or +decreasing. If \fIboolean\fR is true, the axis values will be +decreasing. The default is \f(CW0\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the axis is displayed. +.TP +\fB\-justify \fIjustify\fR +Specifies how the axis title should be justified. This matters only +when the axis title contains more than one line of text. \fIJustify\fR +must be \f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-limits \fIformatStr\fR +Specifies a printf-like description to format the minimum and maximum +limits of the axis. The limits are displayed at the top/bottom or +left/right sides of the plotting area. \fIFormatStr\fR is a list of +one or two format descriptions. If one description is supplied, both +the minimum and maximum limits are formatted in the same way. If two, +the first designates the format for the minimum limit, the second for +the maximum. If \f(CW""\fR is given as either description, then +the that limit will not be displayed. The default is \f(CW""\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the axis and tick lines. The default is \f(CW1\fR +pixel. +.TP +\fB\-logscale \fIboolean\fR +Indicates whether the scale of the axis is logarithmic or linear. If +\fIboolean\fR is true, the axis is logarithmic. The default scale is +linear. +.TP +\fB\-loose \fIboolean\fR +Indicates whether the limits of the axis should fit the data points tightly, +at the outermost data points, or loosely, at the outer tick intervals. +This is relevant only when the axis limit is automatically calculated. +If \fIboolean\fR is true, the axis range is "loose". +The default is \f(CW0\fR. +.TP +\fB\-majorticks \fImajorList\fR +Specifies where to display major axis ticks. You can use this option +to display ticks at non-uniform intervals. \fIMajorList\fR is a list +of axis coordinates designating the location of major ticks. No +minor ticks are drawn. If \fImajorList\fR is \f(CW""\fR, +major ticks will be automatically computed. The default is \f(CW""\fR. +.TP +\fB\-max \fIvalue\fR +Sets the maximum limit of \fIaxisName\fR. Any data point greater +than \fIvalue\fR is not displayed. If \fIvalue\fR is \f(CW""\fR, +the maximum limit is calculated using the largest data value. +The default is \f(CW""\fR. +.TP +\fB\-min \fIvalue\fR +Sets the minimum limit of \fIaxisName\fR. Any data point less than +\fIvalue\fR is not displayed. If \fIvalue\fR is \f(CW""\fR, +the minimum limit is calculated using the smallest data value. +The default is \f(CW""\fR. +.TP +\fB\-minorticks \fIminorList\fR +Specifies where to display minor axis ticks. You can use this option +to display minor ticks at non-uniform intervals. \fIMinorList\fR is a +list of real values, ranging from 0.0 to 1.0, designating the placement of +a minor tick. No minor ticks are drawn if the \fB\-majortick\fR +option is also set. If \fIminorList\fR is \f(CW""\fR, minor ticks will +be automatically computed. The default is \f(CW""\fR. +.TP +\fB\-rotate \fItheta\fR +Specifies the how many degrees to rotate the axis tick labels. +\fITheta\fR is a real value representing the number of degrees +to rotate the tick labels. The default is \f(CW0.0\fR degrees. +.TP +\fB\-shiftby \fIvalue\fR +Specifies how much to automatically shift the range of the axis. +When the new data exceeds the current axis maximum, the maximum +is increased in increments of \fIvalue\fR. You can use this +option to prevent the axis limits from being recomputed +at each new time point. If \fIvalue\fR is 0.0, then no automatic +shifting is down. The default is \f(CW0.0\fR. +.TP +\fB\-showticks \fIboolean\fR +Indicates whether axis ticks should be drawn. If \fIboolean\fR is +true, ticks are drawn. If false, only the +axis line is drawn. The default is \f(CW1\fR. +.TP +\fB\-stepsize \fIvalue\fR +Specifies the interval between major axis ticks. If \fIvalue\fR isn't +a valid interval (must be less than the axis range), +the request is ignored and the step size is automatically calculated. +.TP +\fB\-subdivisions \fInumber\fR +Indicates how many minor axis ticks are +to be drawn. For example, if \fInumber\fR is two, only one minor +tick is drawn. If \fInumber\fR is one, no minor ticks are +displayed. The default is \f(CW2\fR. +.TP +\fB\-tickfont \fIfontName\fR +Specifies the font for axis tick labels. The default is +\f(CW*-Courier-Bold-R-Normal-*-100-*\fR. +.TP +\fB\-ticklength \fIpixels\fR +Sets the length of major and minor ticks (minor ticks are half the +length of major ticks). If \fIpixels\fR is less than zero, the axis +will be inverted with ticks drawn pointing towards the plot. The +default is \f(CW0.1i\fR. +.TP +\fB\-title \fItext\fR +Sets the title of the axis. If \fItext\fR is +\f(CW""\fR, no axis title will be displayed. +.TP +\fB\-titlecolor \fIcolor\fR +Sets the color of the axis title. The default is \f(CWblack\fR. +.TP +\fB\-titlefont \fIfontName\fR +Specifies the font for axis title. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-14-140-*\fR. +.PP +Axis configuration options may be also be set by the \fBoption\fR +command. The resource class is \f(CWAxis\fR. The resource names +are the names of the axes (such as \f(CWx\fR or \f(CWx2\fR). +.CS +option add *Barchart.Axis.Color blue +option add *Barchart.x.LogScale true +option add *Barchart.x2.LogScale false +.CE +.RE +.TP +\fIpathName \fBaxis \fBcreate \fIaxisName \fR?\fIoption value\fR?... +Creates a new axis by the name \fIaxisName\fR. No axis by the same +name can already exist. \fIOption\fR and \fIvalue\fR are described +in above in the axis \fBconfigure\fR operation. +.TP +\fIpathName \fBaxis \fBdelete \fR?\fIaxisName\fR?... +Deletes the named axes. An axis is not really +deleted until it is not longer in use, so it's safe to delete +axes mapped to elements. +.TP +\fIpathName \fBaxis invtransform \fIaxisName value\fR +Performs the inverse transformation, changing the screen-coordinate +\fIvalue\fR to a graph-coordinate, mapping the value mapped to +\fIaxisName\fR. Returns the graph-coordinate. +.TP +\fIpathName \fBaxis limits \fIaxisName\fR +Returns a list of the minimum and maximum limits for \fIaxisName\fR. The order +of the list is \f(CWmin max\fR. +.TP +\fIpathName \fBaxis names \fR?\fIpattern\fR?... +Returns a list of axes matching zero or more patterns. If no +\fIpattern\fR argument is give, the names of all axes are returned. +.TP +\fIpathName \fBaxis transform \fIaxisName value\fR +Transforms the coordinate \fIvalue\fR to a screen-coordinate by mapping +the it to \fIaxisName\fR. Returns the transformed screen-coordinate. +.PP +Only four axes can be displayed simultaneously. By default, they are +\f(CWx\fR, \f(CWy\fR, \f(CWx2\fR, and \f(CWy2\fR. You can swap in a different +axis with \fBuse\fR operation of the special axis components: +\fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, and \fBy2axis\fR. +.CS +\&.g create axis temp +\&.g create axis time +\&... +\&.g xaxis use temp +\&.g yaxis use time +.CE +Only the axes specified for use are displayed on the screen. +.PP +The \fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, and \fBy2axis\fR +components operate on an axis location rather than a specific axis +like the more general \fBaxis\fR component does. The \fBxaxis\fR +component manages the X-axis located in the bottom margin (whatever +axis that happens to be). Likewise, \fByaxis\fR uses the Y-axis in +the left margin, \fBx2axis\fR the top X-axis, and \fBy2axis\fR the +right Y-axis. +.PP +They implicitly control the axis that is currently using to that +location. By default, \fBxaxis\fR uses the \f(CWx\fR axis, \fByaxis\fR +uses \f(CWy\fR, \fBx2axis\fR uses \f(CWx2\fR, and \fBy2axis\fR uses +\f(CWy2\fR. These components can be more convenient to use than always +determining what axes are current being displayed by the graph. +.PP +The following operations are available for axes. They mirror exactly +the operations of the \fBaxis\fR component. The \fIaxis\fR argument +must be \fBxaxis\fR, \fBx2axis\fR, \fByaxis\fR, or \fBy2axis\fR. +.TP +\fIpathName \fIaxis \fBcget \fIoption\fR +.TP +\fIpathName \fIaxis \fBconfigure \fR?\fIoption value\fR?... +.TP +\fIpathName \fIaxis\fB invtransform \fIvalue\fR +.TP +\fIpathName \fIaxis \fBlimits\fR +.TP +\fIpathName \fIaxis\fB transform \fIvalue\fR +.TP +\fIpathName \fIaxis\fB use \fR?\fIaxisName\fR? +Designates the axis \fIaxisName\fR is to be displayed at this +location. \fIAxisName\fR can not be already in use at another location. +This command returns the name of the axis currently using this location. +.SS "CROSSHAIRS COMPONENT" +Cross hairs consist of two intersecting lines (one vertical and one horizontal) +drawn completely across the plotting area. They are used to position +the mouse in relation to the coordinate axes. Cross hairs differ from line +markers in that they are implemented using XOR drawing primitives. +This means that they can be quickly drawn and erased without redrawing +the entire widget. +.PP +The following operations are available for cross hairs: +.TP +\fIpathName \fBcrosshairs cget \fIoption\fR +Returns the current value of the cross hairs configuration option +given by \fIoption\fR. \fIOption\fR may be any option +described below for the cross hairs \fBconfigure\fR operation. +.TP +\fIpathName \fBcrosshairs configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options of the cross hairs. If +\fIoption\fR isn't specified, a list describing all the current +options for the cross hairs is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the cross hairs option \fIoption\fR is set to +\fIvalue\fR. +The following options are available for cross hairs. +.RS +.TP +\fB\-color \fIcolor\fR +Sets the color of the cross hairs. The default is \f(CWblack\fR. +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the cross hairs. \fIDashList\fR is a list of up +to 11 numbers that alternately represent the lengths of the dashes +and gaps on the cross hair lines. Each number must be between 1 and +255. If \fIdashList\fR is \f(CW""\fR, the cross hairs will be solid +lines. +.TP +\fB\-hide \fIboolean\fR +Indicates whether cross hairs are drawn. If \fIboolean\fR is true, +cross hairs are not drawn. The default is \f(CWyes\fR. +.TP +\fB\-linewidth \fIpixels\fR +Set the width of the cross hair lines. The default is \f(CW1\fR. +.TP +\fB\-position \fIpos\fR +Specifies the screen position where the cross hairs intersect. +\fIPos\fR must be in the form "\fI@x,y\fR", where \fIx\fR and \fIy\fR +are the window coordinates of the intersection. +.PP +Cross hairs configuration options may be also be set by the +\fBoption\fR command. The resource name and class are +\f(CWcrosshairs\fR and \f(CWCrosshairs\fR respectively. +.CS +option add *Barchart.Crosshairs.LineWidth 2 +option add *Barchart.Crosshairs.Color red +.CE +.RE +.TP +\fIpathName \fBcrosshairs off\fR +Turns off the cross hairs. +.TP +\fIpathName \fBcrosshairs on\fR +Turns on the display of the cross hairs. +.TP +\fIpathName \fBcrosshairs toggle\fR +Toggles the current state of the cross hairs, alternately mapping and +unmapping the cross hairs. +.SH "ELEMENTS" +A data element represents a set of data. It contains x and y vectors +which are the coordinates of the data points. Elements are displayed +as bars where the length of the bar is proportional to the ordinate of +the data point. Elements also control the appearance of the data, +such as the color, stipple, relief, etc. +.PP +When new data elements are created, they are automatically added to a +list of displayed elements. The display list controls what elements +are drawn and in what order. +.PP +The following operations are available for elements. +.TP +\fIpathName \fBelement activate \fIelemName \fR?\fIindex\fR?... +Specifies the data points of element \fIelemName\fR to be drawn +using active foreground and background colors. \fIElemName\fR is the +name of the element and \fIindex\fR is a number representing the index +of the data point. If no indices are present then all data points +become active. +.TP +\fIpathName \fBelement bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for an element with this +tag, \fIcommand\fR will be invoked. The syntax is similar to the +\fBbind\fR command except that it operates on graph elements, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBelement cget \fIelemName \fIoption\fR +Returns the current value of the element configuration option given by +\fIoption\fR. \fIOption\fR may be any of the options described below +for the element \fBconfigure\fR operation. +.TP +\fIpathName \fBelement closest \fIx y\fR ?\fIoption value\fR?... ?\fIelemName\fR?... +Finds the data point representing the bar closest to the window +coordinates \fIx\fR and \fIy\fR in the element \fIelemName\fR. +\fIElemName\fR is the name of an element, which must be currently displayed. +If no elements are specified, then all displayed elements are searched. It +returns a key-value list containing the name of the closest element, +the index of its closest point, and the graph-coordinates of the +point. If no data point within the threshold distance can be found, +\f(CW""\fR is returned. The following \fIoption\fR-\fIvalue\fR pairs +are available. +.RS +.TP +\fB\-halo \fIpixels\fR +Specifies a threshold distance where selected data points are ignored. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +If this option isn't specified, then it defaults to the value of the +\fBbarchart\fR's \fB\-halo\fR option. +.RE +.TP +\fIpathName \fBelement configure \fIelemName \fR?\fIelemName\fR... ?\fIoption value\fR?... +Queries or modifies the configuration options for elements. Several +elements can be modified at the same time. If \fIoption\fR isn't +specified, a list describing all the current options for +\fIelemName\fR is returned. If \fIoption\fR is specified, but not +\fIvalue\fR, then a list describing the option \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the element option \fIoption\fR is set +to \fIvalue\fR. The following options are valid for elements. +.RS +.TP +\fB\-activepen \fIpenName\fR +Specifies pen to use to draw active element. If \fIpenName\fR is +\f(CW""\fR, no active elements will be drawn. The default is +\f(CWactiveLine\fR. +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for the element. \fITagList\fR is a list +of binding tag names. The tags and their order will determine how +events for elements. Each tag in the list matching the current event +sequence will have its Tcl command executed. Implicitly the name of +the element is always the first tag in the list. The default value is +\f(CWall\fR. +.TP +\fB\-background \fIcolor\fR +Sets the the color of the border around each bar. The default is +\f(CWwhite\fR. +.TP +\fB\-barwidth \fIvalue\fR +Specifies the width the bars drawn for the element. \fIValue\fR is +the width in X-coordinates. If this option isn't +specified, the width of each bar is the value of the widget's +\fB\-barwidth\fR option. +.TP +\fB\-baseline \fIvalue\fR +Specifies the baseline of the bar segments. This affects how bars are +drawn since bars are drawn from their respective y-coordinate the +baseline. By default the baseline is \f(CW0.0\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the border width of the 3-D border drawn around the outside of +each bar. The \fB\-relief\fR option determines if such a border is +drawn. \fIPixels\fR must be a valid screen distance like \f(CW2\fR or +\f(CW0.25i\fR. The default is \f(CW2\fR. +.TP +\fB\-data \fIcoordList\fR +Specifies the X\-Y coordinates of the data. \fICoordList\fR is a +list of numeric expressions representing the X\-Y coordinate pairs +of each data point. +.TP +\fB\-foreground \fIcolor\fR +Sets the color of the interior of the bars. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the element is displayed. The default is \f(CWno\fR. +.TP +\fB\-label \fItext\fR +Sets the element's label in the legend. If \fItext\fR +is \f(CW""\fR, the element will have no entry in the legend. +The default label is the element's name. +.TP +\fB\-mapx \fIxAxis\fR +Selects the X\-axis to map the element's X\-coordinates onto. +\fIXAxis\fR must be the name of an axis. The default is \f(CWx\fR. +.TP +\fB\-mapy \fIyAxis\fR +Selects the Y\-axis to map the element's Y\-coordinates onto. +\fIYAxis\fR must be the name of an axis. The default is \f(CWy\fR. +.TP +\fB\-relief \fIstring\fR +Specifies the 3-D effect desired for bars. \fIRelief\fR indicates how +the interior of the bar should appear relative to the surface of the +chart; for example, \f(CWraised\fR means the bar should appear to +protrude from the surface of the plotting area. The default is +\f(CWraised\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies a stipple pattern with which to draw the bars. If +\fIbitmap\fR is \f(CW""\fR, then the bar is drawn in a solid fashion. +.TP +\fB\-xdata \fIxVector\fR +Specifies the x-coordinate vector of the data. +\fIXVector\fR is the name of a BLT vector or a +list of numeric expressions. +.TP +\fB\-ydata \fIyVector\fR +Specifies the y-coordinate vector of the data. +\fIYVector\fR is the name of a BLT vector or a list of +numeric expressions. +.PP +Element configuration options may also be set by the +\fBoption\fR command. The resource names in the option database +are prefixed by \f(CWelem\fR. +.CS +option add *Barchart.Element.background blue +.CE +.RE +.TP +\fIpathName \fBelement create \fIelemName\fR ?\fIoption value\fR?... +Creates a new element \fIelemName\fR. Element +names must be unique, so an element \fIelemName\fR may not already +exist. If additional arguments are present, they specify any of the +element options valid for element \fBconfigure\fR operation. +.TP +\fIpathName \fBelement deactivate \fIpattern\fR... +Deactivates all the elements matching \fIpattern\fR for the graph. +Elements whose names match any of the patterns given are redrawn +using their normal colors. +.TP +\fIpathName \fBelement delete\fR ?\fIpattern\fR?... +Deletes all the elements matching \fIpattern\fR for the graph. +Elements whose names match any of the patterns given are deleted. +The graph will be redrawn without the deleted elements. +.TP +\fIpathName \fBelement exists \fIelemName\fR +Returns \f(CW1\fR if an element \fIelemName\fR currently exists and +\f(CW0\fR otherwise. +.TP +\fIpathName \fBelement names \fR?\fIpattern\fR?... +Returns the elements matching one or more pattern. If no +\fIpattern\fR is given, the names of all elements is returned. +.TP +\fIpathName \fBelement show\fR ?\fInameList\fR? +Queries or modifies the element display list. The element display +list designates the elements drawn and in what +order. \fINameList\fR is a list of elements to be displayed in the +order they are named. If there is no \fInameList\fR argument, +the current display list is returned. +.TP +\fIpathName \fBelement type\fR \fIelemName\fR +Returns the type of \fIelemName\fR. +If the element is a bar element, the commands returns the string +\f(CW"bar"\fR, otherwise it returns \f(CW"line"\fR. +.CE +.SS "GRID COMPONENT" +Grid lines extend from the major and minor ticks of each axis +horizontally or vertically across the plotting area. The following +operations are available for grid lines. +.TP +\fIpathName \fBgrid cget \fIoption\fR +Returns the current value of the grid line configuration option given by +\fIoption\fR. \fIOption\fR may be any option described below +for the grid \fBconfigure\fR operation. +.TP +\fIpathName \fBgrid configure\fR ?\fIoption value\fR?... +Queries or modifies the configuration options for grid lines. If +\fIoption\fR isn't specified, a list describing all the current +grid options for \fIpathName\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the grid line option \fIoption\fR is set to +\fIvalue\fR. The following options are valid for grid lines. +.RS +.TP +\fB\-color \fIcolor\fR +Sets the color of the grid lines. The default is \f(CWblack\fR. +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the grid lines. \fIDashList\fR is a list of up +to 11 numbers that alternately represent the lengths of the dashes +and gaps on the grid lines. Each number must be between 1 and 255. +If \fIdashList\fR is \f(CW""\fR, the grid will be solid lines. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the grid should be drawn. If \fIboolean\fR +is true, grid lines are not shown. The default is \f(CWyes\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of grid lines. The default width is \f(CW1\fR. +.TP +\fB\-mapx \fIxAxis\fR +Specifies the X\-axis to display grid lines. \fIXAxis\fR +must be the name of an axis or \f(CW""\fR for no grid lines. +The default is \f(CW""\fR. +.TP +\fB\-mapy \fIyAxis\fR +Specifies the Y\-axis to display grid lines. \fIYAxis\fR +must be the name of an axis or \f(CW""\fR for no grid lines. +The default is \f(CWy\fR. +.TP +\fB\-minor \fIboolean\fR +Indicates whether the grid lines should be drawn for minor ticks. +If \fIboolean\fR is true, the lines will appear at +minor tick intervals. The default is \f(CW1\fR. +.PP +Grid configuration options may also be set by the +\fBoption\fR command. The resource name and class are \f(CWgrid\fR and +\f(CWGrid\fR respectively. +.CS +option add *Barchart.grid.LineWidth 2 +option add *Barchart.Grid.Color black +.CE +.RE +.TP +\fIpathName \fBgrid off\fR +Turns off the display the grid lines. +.TP +\fIpathName \fBgrid on\fR +Turns on the display the grid lines. +.TP +\fIpathName \fBgrid toggle\fR +Toggles the display of the grid. +.SS "LEGEND COMPONENT" +The legend displays a list of the data elements. Each entry consists +of the element's symbol and label. The legend can appear in any +margin (the default location is in the right margin). It +can also be positioned anywhere within the plotting area. +.PP +The following operations are valid for the legend. +.TP +\fIpathName \fBlegend activate \fIpattern\fR... +Selects legend entries to be drawn using the active legend colors and relief. +All entries whose element names match \fIpattern\fR are selected. To +be selected, the element name must match only one \fIpattern\fR. +.TP +\fIpathName \fBlegend bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for a legend entry with this +tag, \fIcommand\fR will be invoked. Implicitly the element names +in the entry are tags. The syntax is similar to the +\fBbind\fR command except that it operates on legend entries, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBlegend cget \fIoption\fR +Returns the current value of a legend configuration option. +\fIOption\fR may be any option described below in the +legend \fBconfigure\fR operation. +.TP +\fIpathName \fBlegend configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options for the legend. If +\fIoption\fR isn't specified, a list describing the current +legend options for \fIpathName\fR is returned. If \fIoption\fR is +specified, but not \fIvalue\fR, then a list describing \fIoption\fR is +returned. If one or more \fIoption\fR and \fIvalue\fR pairs are +specified, then for each pair, the legend option \fIoption\fR is set +to \fIvalue\fR. The following options are valid for the legend. +.RS +.TP +\fB\-activebackground \fIcolor\fR +Sets the background color for active legend entries. All legend +entries marked active (see the legend \fBactivate\fR operation) are +drawn using this background color. +.TP +\fB\-activeborderwidth \fIpixels\fR +Sets the width of the 3-D border around the outside edge of the active legend +entries. The default is \f(CW2\fR. +.TP +\fB\-activeforeground \fIcolor\fR +Sets the foreground color for active legend entries. All legend +entries marked as active (see the legend \fBactivate\fR operation) are +drawn using this foreground color. +.TP +\fB\-activerelief \fIrelief\fR +Specifies the 3-D effect desired for active legend entries. +\fIRelief\fR denotes how the interior of the entry should appear +relative to the legend; for example, \f(CWraised\fR means the entry +should appear to protrude from the legend, relative to the surface of +the legend. The default is \f(CWflat\fR. +.TP +\fB\-anchor \fIanchor\fR +Tells how to position the legend relative to the positioning point for +the legend. This is dependent on the value of the \fB\-position\fR +option. The default is \f(CWcenter\fR. +.RS +.TP 1.25i +\f(CWleft\fR or \f(CWright\fR +The anchor describes how to position the legend vertically. +.TP +\f(CWtop\fR or \f(CWbottom\fR +The anchor describes how to position the legend horizontally. +.TP +\f(CW@x,y\fR +The anchor specifies how to position the legend relative to the +positioning point. For example, if \fIanchor\fR is \f(CWcenter\fR then +the legend is centered on the point; if \fIanchor\fR is \f(CWn\fR then +the legend will be drawn such that the top center point of the +rectangular region occupied by the legend will be at the positioning +point. +.TP +\f(CWplotarea\fR +The anchor specifies how to position the legend relative to the +plotting area. For example, if \fIanchor\fR is \f(CWcenter\fR then the +legend is centered in the plotting area; if \fIanchor\fR is \f(CWne\fR +then the legend will be drawn such that occupies the upper right +corner of the plotting area. +.RE +.TP +\fB\-background \fIcolor\fR +Sets the background color of the legend. If \fIcolor\fR is \f(CW""\fR, +the legend background with be transparent. +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for legend entries. \fITagList\fR is a list +of binding tag names. The tags and their order will determine how +events for legend entries. Each tag in the list matching the current +event sequence will have its Tcl command executed. The default value +is \f(CWall\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the width of the 3-D border around the outside edge of the legend (if +such border is being drawn; the \fBrelief\fR option determines this). +The default is \f(CW2\fR pixels. +.TP +\fB\-font \fIfontName\fR +\fIFontName\fR specifies a font to use when drawing the labels of each +element into the legend. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-12-120-*\fR. +.TP +\fB\-foreground \fIcolor\fR +Sets the foreground color of the text drawn for the element's label. +The default is \f(CWblack\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the legend should be displayed. If \fIboolean\fR is +true, the legend will not be draw. The default is \f(CWno\fR. +.TP +\fB\-ipadx \fIpad\fR +Sets the amount of internal padding to be added to the width of each +legend entry. \fIPad\fR can be a list of one or two screen distances. If +\fIpad\fR has two elements, the left side of the legend entry is +padded by the first distance and the right side by the second. If +\fIpad\fR is just one distance, both the left and right sides are padded +evenly. The default is \f(CW2\fR. +.TP +\fB\-ipady \fIpad\fR +Sets an amount of internal padding to be added to the height of each +legend entry. \fIPad\fR can be a list of one or two screen distances. If +\fIpad\fR has two elements, the top of the entry is padded by the +first distance and the bottom by the second. If \fIpad\fR is just +one distance, both the top and bottom of the entry are padded evenly. +The default is \f(CW2\fR. +.TP +\fB\-padx \fIpad\fR +Sets the padding to the left and right exteriors of the legend. +\fIPad\fR can be a list of one or two screen distances. If \fIpad\fR +has two elements, the left side of the legend is padded by the first +distance and the right side by the second. If \fIpad\fR has just one +distance, both the left and right sides are padded evenly. The +default is \f(CW4\fR. +.TP +\fB\-pady \fIpad\fR +Sets the padding above and below the legend. \fIPad\fR can be a list +of one or two screen distances. If \fIpad\fR has two elements, the area above +the legend is padded by the first distance and the area below by the +second. If \fIpad\fR is just one distance, both the top and +bottom areas are padded evenly. The default is \f(CW0\fR. +.TP +\fB\-position \fIpos\fR +Specifies where the legend is drawn. The +\fB\-anchor\fR option also affects where the legend is positioned. If +\fIpos\fR is \f(CWleft\fR, \f(CWleft\fR, \f(CWtop\fR, or \f(CWbottom\fR, the +legend is drawn in the specified margin. If \fIpos\fR is +\f(CWplotarea\fR, then the legend is drawn inside the plotting area at a +particular anchor. If \fIpos\fR is in the form "\fI@x,y\fR", where +\fIx\fR and \fIy\fR are the window coordinates, the legend is drawn in +the plotting area at the specified coordinates. The default is +\f(CWright\fR. +.TP +\fB\-raised \fIboolean\fR +Indicates whether the legend is above or below the data elements. This +matters only if the legend is in the plotting area. If \fIboolean\fR +is true, the legend will be drawn on top of any elements that may +overlap it. The default is \f(CWno\fR. +.TP +\fB\-relief \fIrelief\fR +Specifies the 3-D effect for the border around the legend. +\fIRelief\fR specifies how the interior of the legend should appear +relative to the bar chart; for example, \f(CWraised\fR means the legend +should appear to protrude from the bar chart, relative to the surface of +the bar chart. The default is \f(CWsunken\fR. +.PP +Legend configuration options may also be set by the \fBoption\fR +command. The resource name and class are \f(CWlegend\fR and +\f(CWLegend\fR respectively. +.CS +option add *Barchart.legend.Foreground blue +option add *Barchart.Legend.Relief raised +.CE +.RE +.TP +\fIpathName \fBlegend deactivate \fIpattern\fR... +Selects legend entries to be drawn using the normal legend colors and +relief. All entries whose element names match \fIpattern\fR are +selected. To be selected, the element name must match only one +\fIpattern\fR. +.TP +\fIpathName \fBlegend get \fIpos\fR +Returns the name of the element whose entry is at the screen position +\fIpos\fR in the legend. \fIPos\fR must be in the form "\fI@x,y\fR", +where \fIx\fR and \fIy\fR are window coordinates. If the given +coordinates do not lie over a legend entry, \f(CW""\fR is returned. +.SS "PEN COMPONENTS" +Pens define attributes for elements. +Pens mirror the configuration options of data elements that pertain to +how symbols and lines are drawn. Data elements use pens to determine +how they are drawn. A data element may use several pens at once. In +this case, the pen used for a particular data point is determined from +each element's weight vector (see the element's \fB\-weight\fR and +\fB\-style\fR options). +.PP +One pen, called \f(CWactiveBar\fR, is automatically created. +It's used as the default active pen for elements. So you can change +the active attributes for all elements by simply reconfiguring this +pen. +.CS +\&.g pen configure "activeBar" -fg green -bg green4 +.CE +You can create and use several pens. To create a pen, invoke +the pen component and its create operation. +.CS +\&.g pen create myPen +.CE +You map pens to a data element using either the element's +\fB\-pen\fR or \fB\-activepen\fR options. +.CS +\&.g element create "e1" -xdata $x -ydata $tempData \\ + -pen myPen +.CE +An element can use several pens at once. This is done by specifying +the name of the pen in the element's style list (see the +\fB\-styles\fR option). +.CS +\&.g element configure "e1" -styles { myPen 2.0 3.0 } +.CE +This says that any data point with a weight between 2.0 and 3.0 +is to be drawn using the pen \f(CWmyPen\fR. All other points +are drawn with the element's default attributes. +.PP +The following operations are available for pen components. +.PP +.TP +\fIpathName \fBpen \fBcget \fIpenName \fIoption\fR +Returns the current value of the option given by \fIoption\fR for +\fIpenName\fR. \fIOption\fR may be any option described below +for the pen \fBconfigure\fR operation. +.TP +\fIpathName \fBpen \fBconfigure \fIpenName \fR?\fIpenName\fR... ?\fIoption value\fR?... +Queries or modifies the configuration options of +\fIpenName\fR. Several pens can be modified at once. If \fIoption\fR +isn't specified, a list describing the current options for +\fIpenName\fR is returned. If \fIoption\fR is specified, but not +\fIvalue\fR, then a list describing \fIoption\fR is returned. If one +or more \fIoption\fR and \fIvalue\fR pairs are specified, then for +each pair, the pen option \fIoption\fR is set to \fIvalue\fR. The +following options are valid for pens. +.RS +.TP +\fB\-background \fIcolor\fR +Sets the the color of the border around each bar. The default is +\f(CWwhite\fR. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the border width of the 3-D border drawn around the outside of +each bar. The \fB\-relief\fR option determines if such a border is +drawn. \fIPixels\fR must be a valid screen distance like \f(CW2\fR or +\f(CW0.25i\fR. The default is \f(CW2\fR. +.TP +\fB\-foreground \fIcolor\fR +Sets the color of the interior of the bars. +.TP +\fB\-relief \fIstring\fR +Specifies the 3-D effect desired for bars. \fIRelief\fR indicates how +the interior of the bar should appear relative to the surface of the +chart; for example, \f(CWraised\fR means the bar should appear to +protrude from the bar chart, relative to the surface of the plotting +area. The default is \f(CWraised\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies a stipple pattern with which to draw the bars. If +\fIbitmap\fR is \f(CW""\fR, then the bar is drawn in a solid fashion. +.TP +\fB\-type \fIelemType\fR +Specifies the type of element the pen is to be used with. +This option should only be employed when creating the pen. This +is for those that wish to mix different types of elements (bars and +lines) on the same graph. The default type is "bar". +.PP +Pen configuration options may be also be set by the \fBoption\fR +command. The resource class is \f(CWPen\fR. The resource names +are the names of the pens. +.CS +option add *Barchart.Pen.Foreground blue +option add *Barchart.activeBar.foreground green +.CE +.RE +.TP +\fIpathName \fBpen \fBcreate \fIpenName \fR?\fIoption value\fR?... +Creates a new pen by the name \fIpenName\fR. No pen by the same +name can already exist. \fIOption\fR and \fIvalue\fR are described +in above in the pen \fBconfigure\fR operation. +.TP +\fIpathName \fBpen \fBdelete \fR?\fIpenName\fR?... +Deletes the named pens. A pen is not really +deleted until it is not longer in use, so it's safe to delete +pens mapped to elements. +.TP +\fIpathName \fBpen names \fR?\fIpattern\fR?... +Returns a list of pens matching zero or more patterns. If no +\fIpattern\fR argument is give, the names of all pens are returned. +.SS "POSTSCRIPT COMPONENT" +The barchart can generate encapsulated PostScript output. There +are several configuration options you can specify to control how the +plot will be generated. You can change the page dimensions and +borders. The plot itself can be scaled, centered, or rotated to +landscape. The PostScript output can be written directly to a file or +returned through the interpreter. +.PP +The following postscript operations are available. +.TP +\fIpathName \fBpostscript cget \fIoption\fR +Returns the current value of the postscript option given by +\fIoption\fR. \fIOption\fR may be any option described +below for the postscript \fBconfigure\fR operation. +.TP +\fIpathName \fBpostscript configure \fR?\fIoption value\fR?... +Queries or modifies the configuration options for PostScript +generation. If \fIoption\fR isn't specified, a list describing +the current postscript options for \fIpathName\fR is returned. If +\fIoption\fR is specified, but not \fIvalue\fR, then a list describing +\fIoption\fR is returned. If one or more \fIoption\fR and \fIvalue\fR +pairs are specified, then for each pair, the postscript option +\fIoption\fR is set to \fIvalue\fR. The following postscript options +are available. +.RS +.TP +\fB\-center \fIboolean\fR +Indicates whether the plot should be centered on the PostScript page. If +\fIboolean\fR is false, the plot will be placed in the upper left +corner of the page. The default is \f(CW1\fR. +.TP +\fB\-colormap \fIvarName\fR +\fIVarName\fR must be the name of a global array variable that +specifies a color mapping from the X color name to PostScript. Each +element of \fIvarName\fR must consist of PostScript code to set a +particular color value (e.g. ``\f(CW1.0 1.0 0.0 setrgbcolor\fR''). When +generating color information in PostScript, the array variable \fIvarName\fR +is checked if an element of the name as the color exists. If so, it uses +its value as the PostScript +command to set the color. If this option hasn't been specified, or if +there isn't an entry in \fIvarName\fR for a given color, then it uses +the red, green, and blue intensities from the X color. +.TP +\fB\-colormode \fImode\fR +Specifies how to output color information. \fIMode\fR must be either +\f(CWcolor\fR (for full color output), \f(CWgray\fR (convert all colors to +their gray-scale equivalents) or \f(CWmono\fR (convert foreground colors +to black and background colors to white). The default mode is +\f(CWcolor\fR. +.TP +\fB\-fontmap \fIvarName\fR +\fIVarName\fR must be the name of a global array variable that +specifies a font mapping from the X font name to PostScript. Each +element of \fIvarName\fR must consist of a Tcl list with one or two +elements; the name and point size of a PostScript font. +When outputting PostScript commands for a particular font, the array +variable \fIvarName\fR is checked to see if an element by the +specified font exists. If there is such an element, then the font +information contained in that element is used in the PostScript +output. (If the point size is omitted from the list, the point size +of the X font is used). Otherwise the X font is examined in an +attempt to guess what PostScript font to use. This works only for +fonts whose foundry property is \fIAdobe\fR (such as Times, Helvetica, +Courier, etc.). If all of this fails then the font defaults to +\f(CWHelvetica-Bold\fR. +.TP +\fB\-decorations \fIboolean\fR +Indicates whether PostScript commands to generate color backgrounds and 3-D +borders will be output. If \fIboolean\fR is false, the graph will +background will be white and no 3-D borders will be generated. The +default is \f(CW1\fR. +.TP +\fB\-height \fIpixels\fR +Sets the height of the plot. This lets you print the bar chart with a +height different from the one drawn on the screen. If +\fIpixels\fR is 0, the height is the same as the widget's height. +The default is \f(CW0\fR. +.TP +\fB\-landscape \fIboolean\fR +If \fIboolean\fR is true, this specifies the printed area is to be +rotated 90 degrees. In non-rotated output the X\-axis of the printed +area runs along the short dimension of the page (``portrait'' +orientation); in rotated output the X\-axis runs along the long +dimension of the page (``landscape'' orientation). Defaults to +\f(CW0\fR. +.TP +\fB\-maxpect \fIboolean\fR +Indicates to scale the plot so that it fills the PostScript page. +The aspect ratio of the barchart is still retained. The default is +\f(CW0\fR. +.TP +\fB\-padx \fIpad\fR +Sets the horizontal padding for the left and right page borders. The +borders are exterior to the plot. \fIPad\fR can be a list of one or +two screen distances. If \fIpad\fR has two elements, the left border is padded +by the first distance and the right border by the second. If +\fIpad\fR has just one distance, both the left and right borders are +padded evenly. The default is \f(CW1i\fR. +.TP +\fB\-pady \fIpad\fR +Sets the vertical padding for the top and bottom page borders. The +borders are exterior to the plot. \fIPad\fR can be a list of one or +two screen distances. If \fIpad\fR has two elements, the top border is padded +by the first distance and the bottom border by the second. If +\fIpad\fR has just one distance, both the top and bottom borders are +padded evenly. The default is \f(CW1i\fR. +.TP +\fB\-paperheight \fIpixels\fR +Sets the height of the postscript page. This can be used to select +between different page sizes (letter, A4, etc). The default height is +\f(CW11.0i\fR. +.TP +\fB\-paperwidth \fIpixels\fR +Sets the width of the postscript page. This can be used to select +between different page sizes (letter, A4, etc). The default width is +\f(CW8.5i\fR. +.TP +\fB\-width \fIpixels\fR +Sets the width of the plot. This lets you generate a plot +of a width different from that of the widget. If \fIpixels\fR +is 0, the width is the same as the widget's width. The default is +\f(CW0\fR. +.PP +Postscript configuration options may be also be set by the +\fBoption\fR command. The resource name and class are +\f(CWpostscript\fR and \f(CWPostscript\fR respectively. +.CS +option add *Barchart.postscript.Decorations false +option add *Barchart.Postscript.Landscape true +.CE +.RE +.TP +\fIpathName \fBpostscript output \fR?\fIfileName\fR? ?\fIoption value\fR?... +Outputs a file of encapsulated PostScript. If a +\fIfileName\fR argument isn't present, the command returns the +PostScript. If any \fIoption-value\fR pairs are present, they set +configuration options controlling how the PostScript is generated. +\fIOption\fR and \fIvalue\fR can be anything accepted by the +postscript \fBconfigure\fR operation above. +.SS "MARKER COMPONENTS" +Markers are simple drawing procedures used to annotate or highlight +areas of the graph. Markers have various types: text strings, +bitmaps, images, connected lines, windows, or polygons. They can be +associated with a particular element, so that when the element is +hidden or un-hidden, so is the marker. By default, markers are the +last items drawn, so that data elements will appear in +behind them. You can change this by configuring the \fB\-under\fR +option. +.PP +Markers, in contrast to elements, don't affect the scaling of the +coordinate axes. They can also have \fIelastic\fR coordinates +(specified by \f(CW-Inf\fR and \f(CWInf\fR respectively) that translate +into the minimum or maximum limit of the axis. For example, you can +place a marker so it always remains in the lower left corner of the +plotting area, by using the coordinates \f(CW-Inf\fR,\f(CW-Inf\fR. +.PP +The following operations are available for markers. +.TP +\fIpathName \fBmarker after \fImarkerId\fR ?\fIafterId\fR? +Changes the order of the markers, drawing the first +marker after the second. If no second \fIafterId\fR argument is +specified, the marker is placed at the end of the display list. This +command can be used to control how markers are displayed since markers +are drawn in the order of this display list. +.TP +\fIpathName \fBmarker before \fImarkerId\fR ?\fIbeforeId\fR? +Changes the order of the markers, drawing the first +marker before the second. If no second \fIbeforeId\fR argument is +specified, the marker is placed at the beginning of the display list. +This command can be used to control how markers are displayed since +markers are drawn in the order of this display list. +.TP +\fIpathName \fBmarker bind \fItagName\fR ?\fIsequence\fR? ?\fIcommand\fR? +Associates \fIcommand\fR with \fItagName\fR such that whenever the +event sequence given by \fIsequence\fR occurs for a marker with this +tag, \fIcommand\fR will be invoked. The syntax is similar to the +\fBbind\fR command except that it operates on graph markers, rather +than widgets. See the \fBbind\fR manual entry for +complete details on \fIsequence\fR and the substitutions performed on +\fIcommand\fR before invoking it. +.sp +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR. +If the first character of \fIcommand\fR is \f(CW+\fR then \fIcommand\fR +augments an existing binding rather than replacing it. +If no \fIcommand\fR argument is provided then the command currently +associated with \fItagName\fR and \fIsequence\fR (it's an error occurs +if there's no such binding) is returned. If both \fIcommand\fR and +\fIsequence\fR are missing then a list of all the event sequences for +which bindings have been defined for \fItagName\fR. +.TP +\fIpathName \fBmarker cget \fIoption\fR +Returns the current value of the marker configuration option given by +\fIoption\fR. \fIOption\fR may be any option described +below in the \fBconfigure\fR operation. +.TP +\fIpathName \fBmarker configure \fImarkerId\fR ?\fIoption value\fR?... +Queries or modifies the configuration options for markers. If +\fIoption\fR isn't specified, a list describing the current +options for \fImarkerId\fR is returned. If \fIoption\fR is specified, +but not \fIvalue\fR, then a list describing \fIoption\fR is returned. +If one or more \fIoption\fR and \fIvalue\fR pairs are specified, then +for each pair, the marker option \fIoption\fR is set to \fIvalue\fR. +.sp +The following options are valid for all markers. +Each type of marker also has its own type-specific options. +They are described in the sections below. +.RS +.TP +\fB\-bindtags \fItagList\fR +Specifies the binding tags for the marker. \fITagList\fR is a list +of binding tag names. The tags and their order will determine how +events for markers are handled. Each tag in the list matching the +current event sequence will have its Tcl command executed. Implicitly +the name of the marker is always the first tag in the list. +The default value is \f(CWall\fR. +.TP +\fB\-coords \fIcoordList\fR +Specifies the coordinates of the marker. \fICoordList\fR is +a list of graph-coordinates. The number of coordinates required +is dependent on the type of marker. Text, image, and window markers +need only two coordinates (an X\-Y coordinate). Bitmap markers +can take either two or four coordinates (if four, they represent the +corners of the bitmap). Line markers +need at least four coordinates, polygons at least six. +If \fIcoordList\fR is \f(CW""\fR, the marker will not be displayed. +The default is \f(CW""\fR. +.TP +\fB\-element \fIelemName\fR +Links the marker with the element \fIelemName\fR. The marker is +drawn only if the element is also currently displayed (see the +element's \fBshow\fR operation). If \fIelemName\fR is \f(CW""\fR, the +marker is always drawn. The default is \f(CW""\fR. +.TP +\fB\-hide \fIboolean\fR +Indicates whether the marker is drawn. If \fIboolean\fR is true, +the marker is not drawn. The default is \f(CWno\fR. +.TP +\fB\-mapx \fIxAxis\fR +Specifies the X\-axis to map the marker's X\-coordinates onto. +\fIXAxis\fR must the name of an axis. The default is \f(CWx\fR. +.TP +\fB\-mapy \fIyAxis\fR +Specifies the Y\-axis to map the marker's Y\-coordinates onto. +\fIYAxis\fR must the name of an axis. The default is \f(CWy\fR. +.TP +\fB\-name \fImarkerId\fR +Changes the identifier for the marker. The identifier \fImarkerId\fR +can not already be used by another marker. If this option +isn't specified, the marker's name is uniquely generated. +.TP +\fB\-under \fIboolean\fR +Indicates whether the marker is drawn below/above data +elements. If \fIboolean\fR is true, the marker is be drawn +underneath the data elements. Otherwise, the marker is +drawn on top of the element. The default is \f(CW0\fR. +.TP +\fB\-xoffset \fIpixels\fR +Specifies a screen distance to offset the marker horizontally. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +The default is \f(CW0\fR. +.TP +\fB\-yoffset \fIpixels\fR +Specifies a screen distance to offset the markers vertically. +\fIPixels\fR is a valid screen distance, such as \f(CW2\fR or \f(CW1.2i\fR. +The default is \f(CW0\fR. +.PP +Marker configuration options may also be set by the \fBoption\fR command. +The resource class is either \f(CWBitmapMarker\fR, \f(CWImageMarker\fR, +\f(CWLineMarker\fR, \f(CWPolygonMarker\fR, \f(CWTextMarker\fR, or \f(CWWindowMarker\fR, +depending on the type of marker. The resource name is the name of the +marker. +.CS +option add *Barchart.TextMarker.Foreground white +option add *Barchart.BitmapMarker.Foreground white +option add *Barchart.m1.Background blue +.CE +.RE +.TP +\fIpathName \fBmarker create \fItype\fR ?\fIoption value\fR?... +Creates a marker of the selected type. \fIType\fR may be either +\f(CWtext\fR, \f(CWline\fR, \f(CWbitmap\fR, \f(CWimage\fR, \f(CWpolygon\fR, or +\f(CWwindow\fR. This command returns the marker identifier, +used as the \fImarkerId\fR argument in the other marker-related +commands. If the \fB\-name\fR option is used, this overrides the +normal marker identifier. If the name provided is already used for +another marker, the new marker will replace the old. +.TP +\fIpathName \fBmarker delete\fR ?\fIname\fR?... +Removes one of more markers. The graph will automatically be redrawn +without the marker.\fR. +.TP +\fIpathName \fBmarker exists \fImarkerId\fR +Returns \f(CW1\fR if the marker \fImarkerId\fR exists and \f(CW0\fR +otherwise. +.TP +\fIpathName \fBmarker names\fR ?\fIpattern\fR? +Returns the names of all the markers that currently exist. If +\fIpattern\fR is supplied, only those markers whose names match it +will be returned. +.TP +\fIpathName \fBmarker type \fImarkerId\fR +Returns the type of the marker given by \fImarkerId\fR, such as +\f(CWline\fR or \f(CWtext\fR. If \fImarkerId\fR is not a valid a marker +identifier, \f(CW""\fR is returned. +.SS "BITMAP MARKERS" +A bitmap marker displays a bitmap. The size of the +bitmap is controlled by the number of coordinates specified. If two +coordinates, they specify the position of the top-left corner of the +bitmap. The bitmap retains its normal width and height. If four +coordinates, the first and second pairs of coordinates represent the +corners of the bitmap. The bitmap will be stretched or reduced as +necessary to fit into the bounding rectangle. +.PP +Bitmap markers are created with the marker's \fBcreate\fR operation in +the form: +.DS +\fIpathName \fBmarker create bitmap \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR pairs, each +sets a configuration options for the marker. These +same \fIoption\fR\-\fIvalue\fR pairs may be used with the marker's +\fBconfigure\fR operation. +.PP +The following options are specific to bitmap markers: +.TP +\fB\-background \fIcolor\fR +Same as the \fB\-fill\fR option. +.TP +\fB\-bitmap \fIbitmap\fR +Specifies the bitmap to be displayed. If \fIbitmap\fR is \f(CW""\fR, +the marker will not be displayed. The default is \f(CW""\fR. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the bitmap. If \fIcolor\fR is the empty +string, no background will be transparent. The default background color is +\f(CW""\fR. +.TP +\fB\-foreground \fIcolor\fR +Same as the \fB\-outline\fR option. +.TP +\fB\-mask \fImask\fR +Specifies a mask for the bitmap to be displayed. This mask is a bitmap +itself, denoting the pixels that are transparent. If \fImask\fR is +\f(CW""\fR, all pixels of the bitmap will be drawn. The default is +\f(CW""\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the foreground color of the bitmap. The default value is \f(CWblack\fR. +.TP +\fB\-rotate \fItheta\fR +Sets the rotation of the bitmap. \fITheta\fR is a real number +representing the angle of rotation in degrees. The marker is first +rotated and then placed according to its anchor position. The default +rotation is \f(CW0.0\fR. +.SS "IMAGE MARKERS" +A image marker displays an image. Image markers are +created with the marker's \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create image \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR operation. +.PP +The following options are specific to image markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the image relative to the +positioning point for the image. For example, if \fIanchor\fR +is \f(CWcenter\fR then the image is centered on the point; if +\fIanchor\fR is \f(CWn\fR then the image will be drawn such that +the top center point of the rectangular region occupied by the +image will be at the positioning point. +This option defaults to \f(CWcenter\fR. +.TP +\fB\-image \fIimage\fR +Specifies the image to be drawn. +If \fIimage\fR is \f(CW""\fR, the marker will not be +drawn. The default is \f(CW""\fR. +.SS "LINE MARKERS" +A line marker displays one or more connected line segments. +Line markers are created with marker's \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create line \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR operation. +.PP +The following options are specific to line markers: +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the line. \fIDashList\fR is a list of up to 11 +numbers that alternately represent the lengths of the dashes and gaps +on the line. Each number must be between 1 and 255. If +\fIdashList\fR is \f(CW""\fR, the marker line will be solid. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the line. This color is used with +striped lines (see the \fB\-dashes\fR option). If \fIcolor\fR is +the empty string, no background color is drawn (the line will be +dashed, not striped). The default background color is \f(CW""\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the lines. +The default width is \f(CW0\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the foreground color of the line. The default value is \f(CWblack\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies a stipple pattern used to draw the line, rather than +a solid line. +\fIBitmap\fR specifies a bitmap to use as the stipple +pattern. If \fIbitmap\fR is \f(CW""\fR, then the +line is drawn in a solid fashion. The default is \f(CW""\fR. +.SS "POLYGON MARKERS" +A polygon marker displays a closed region described as two or more +connected line segments. It is assumed the first and +last points are connected. Polygon markers are created using the +marker \fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create polygon \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the \fBmarker configure\fR command to change the marker's +configuration. +The following options are supported for polygon markers: +.TP +\fB\-dashes \fIdashList\fR +Sets the dash style of the outline of the polygon. \fIDashList\fR is a +list of up to 11 numbers that alternately represent the lengths of +the dashes and gaps on the outline. Each number must be between 1 and +255. If \fIdashList\fR is \f(CW""\fR, the outline will be a solid line. +.TP +\fB\-fill \fIcolor\fR +Sets the fill color of the polygon. If \fIcolor\fR is \f(CW""\fR, then +the interior of the polygon is transparent. +The default is \f(CWwhite\fR. +.TP +\fB\-linewidth \fIpixels\fR +Sets the width of the outline of the polygon. If \fIpixels\fR is zero, +no outline is drawn. The default is \f(CW0\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the color of the outline of the polygon. If the polygon is +stippled (see the \fB\-stipple\fR option), then this represents the +foreground color of the stipple. The default is \f(CWblack\fR. +.TP +\fB\-stipple \fIbitmap\fR +Specifies that the polygon should be drawn with a stippled pattern +rather than a solid color. \fIBitmap\fR specifies a bitmap to use as +the stipple pattern. If \fIbitmap\fR is \f(CW""\fR, then the polygon is +filled with a solid color (if the \fB\-fill\fR option is set). The +default is \f(CW""\fR. +.SS "TEXT MARKERS" +A text marker displays a string of characters on one or more lines of +text. Embedded newlines cause line breaks. They may be used to +annotate regions of the graph. Text markers are created with the +\fBcreate\fR operation in the form: +.DS +\fIpathName \fBmarker create text \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR pairs, +each sets a configuration option for the text marker. +These same \fIoption\fR\-\fIvalue\fR pairs may be used with the +marker's \fBconfigure\fR operation. +.PP +The following options are specific to text markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the text relative to the +positioning point for the text. For example, if \fIanchor\fR is +\f(CWcenter\fR then the text is centered on the point; if +\fIanchor\fR is \f(CWn\fR then the text will be drawn such that the +top center point of the rectangular region occupied by the text will +be at the positioning point. This default is \f(CWcenter\fR. +.TP +\fB\-background \fIcolor\fR +Same as the \fB\-fill\fR option. +.TP +\fB\-font \fIfontName\fR +Specifies the font of the text. The default is +\f(CW*-Helvetica-Bold-R-Normal-*-120-*\fR. +.TP +\fB\-fill \fIcolor\fR +Sets the background color of the text. If \fIcolor\fR is the empty +string, no background will be transparent. The default background color is +\f(CW""\fR. +.TP +\fB\-foreground \fIcolor\fR +Same as the \fB\-outline\fR option. +.TP +\fB\-justify \fIjustify\fR +Specifies how the text should be justified. This matters only when +the marker contains more than one line of text. \fIJustify\fR must be +\f(CWleft\fR, \f(CWright\fR, or \f(CWcenter\fR. The default is +\f(CWcenter\fR. +.TP +\fB\-outline \fIcolor\fR +Sets the color of the text. The default value is \f(CWblack\fR. +.TP +\fB\-padx \fIpad\fR +Sets the padding to the left and right exteriors of the text. +\fIPad\fR can be a list of one or two screen distances. If \fIpad\fR +has two elements, the left side of the text is padded by the first +distance and the right side by the second. If \fIpad\fR has just one +distance, both the left and right sides are padded evenly. The +default is \f(CW4\fR. +.TP +\fB\-pady \fIpad\fR +Sets the padding above and below the text. \fIPad\fR can be a list of +one or two screen distances. If \fIpad\fR has two elements, the area above the +text is padded by the first distance and the area below by the second. +If \fIpad\fR is just one distance, both the top and bottom areas +are padded evenly. The default is \f(CW4\fR. +.TP +\fB\-rotate \fItheta\fR +Specifies the number of degrees to rotate the text. \fITheta\fR is a +real number representing the angle of rotation. The marker is first +rotated along its center and is then drawn according to its anchor +position. The default is \f(CW0.0\fR. +.TP +\fB\-text \fItext\fR +Specifies the text of the marker. The exact way the text is +displayed may be affected by other options such as \fB\-anchor\fR or +\fB\-rotate\fR. +.SS "WINDOW MARKERS" +A window marker displays a widget at a given position. +Window markers are created with the marker's \fBcreate\fR operation in +the form: +.DS +\fIpathName \fBmarker create window \fR?\fIoption value\fR?... +.DE +There may be many \fIoption\fR-\fIvalue\fR +pairs, each sets a configuration option +for the marker. These same \fIoption\fR\-\fIvalue\fR pairs may be +used with the marker's \fBconfigure\fR command. +.PP +The following options are specific to window markers: +.TP +\fB\-anchor \fIanchor\fR +\fIAnchor\fR tells how to position the widget relative to the +positioning point for the widget. For example, if \fIanchor\fR is +\f(CWcenter\fR then the widget is centered on the point; if \fIanchor\fR +is \f(CWn\fR then the widget will be displayed such that the top center +point of the rectangular region occupied by the widget will be at the +positioning point. This option defaults to \f(CWcenter\fR. +.TP +\fB\-height \fIpixels\fR +Specifies the height to assign to the marker's window. If this option +isn't specified, or if it is specified as \f(CW""\fR, then the window is +given whatever height the widget requests internally. +.TP +\fB\-width \fIpixels\fR +Specifies the width to assign to the marker's window. If this option +isn't specified, or if it is specified as \f(CW""\fR, then the window is +given whatever width the widget requests internally. +.TP +\fB\-window \fIpathName\fR +Specifies the widget to be managed by the barchart. \fIPathName\fR must +be a child of the \fBbarchart\fR widget. +.SH "GRAPH COMPONENT BINDINGS" +Specific barchart components, such as elements, markers and legend +entries, can have a command trigger when event occurs in them, much +like canvas items in Tk's canvas widget. Not all event sequences are +valid. The only binding events that may be specified are those +related to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, +\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR). +.PP +Only one element or marker can be picked during an event. This means, +that if the mouse is directly over both an element and a marker, only +the uppermost component is selected. This isn't true for legend entries. +Both a legend entry and an element (or marker) binding commands +will be invoked if both items are picked. +.PP +It is possible for multiple bindings to match a particular event. +This could occur, for example, if one binding is associated with the +element name and another is associated with one of the element's tags +(see the \fB\-bindtags\fR option). When this occurs, all of the +matching bindings are invoked. A binding associated with the element +name is invoked first, followed by one binding for each of the element's +bindtags. If there are multiple matching bindings for a single tag, +then only the most specific binding is invoked. A continue command +in a binding script terminates that script, and a break command +terminates that script and skips any remaining scripts for the event, +just as for the bind command. +.PP +The \fB\-bindtags\fR option for these components controls addition +tag names which can be matched. Implicitly elements and markers +always have tags matching their names. Setting the value of +the \fB\-bindtags\fR option doesn't change this. +.SH "C LANGUAGE API" +You can manipulate data elements from the C language. There +may be situations where it is too expensive to translate the data +values from ASCII strings. Or you might want to read data in a +special file format. +.PP +Data can manipulated from the C language using BLT vectors. +You specify the X-Y data coordinates of an element as vectors and +manipulate the vector from C. The barchart will be redrawn automatically +after the vectors are updated. +.PP +From Tcl, create the vectors and configure the element to use them. +.CS +vector X Y +\&.g element configure line1 -xdata X -ydata Y +.CE +To set data points from C, you pass the values as arrays of doubles +using the \fBBlt_ResetVector\fR call. The vector is reset with the +new data and at the next idle point (when Tk re-enters its event +loop), the graph will be redrawn automatically. +.CS +#include <tcl.h> +#include <blt.h> + +register int i; +Blt_Vector *xVec, *yVec; +double x[50], y[50]; + +/* Get the BLT vectors "X" and "Y" (created above from Tcl) */ +if ((Blt_GetVector(interp, "X", 50, &xVec) != TCL_OK) || + (Blt_GetVector(interp, "Y", 50, &yVec) != TCL_OK)) { + return TCL_ERROR; +} + +for (i = 0; i < 50; i++) { + x[i] = i * 0.02; + y[i] = sin(x[i]); +} + +/* Put the data into BLT vectors */ +if ((Blt_ResetVector(xVec, x, 50, 50, TCL_VOLATILE) != TCL_OK) || + (Blt_ResetVector(yVec, y, 50, 50, TCL_VOLATILE) != TCL_OK)) { + return TCL_ERROR; +} +.CE +See the \fBvector\fR manual page for more details. +.SH SPEED TIPS +There may be cases where the bar chart needs to be drawn and updated as +quickly as possible. If drawing speed becomes a big +problem, here are a few tips to speed up displays. +.TP 2 +\(bu +Try to minimize the number of data points. The more data points +looked at, the more work the bar chart must do. +.TP 2 +\(bu +If your data is generated as floating point values, the time required +to convert the data values to and from ASCII strings can be +significant, especially when there any many data points. You can +avoid the redundant string-to-decimal conversions using the C API to +BLT vectors. +.TP 2 +\(bu +Don't stipple or dash the element. Solid bars are much faster. +.TP 2 +\(bu +If you update data elements frequently, try turning off the +widget's \fB\-bufferelements\fR option. When the bar chart is first +displayed, it draws data elements into an internal pixmap. The pixmap +acts as a cache, so that when the bar chart needs to be redrawn again, and +the data elements or coordinate axes haven't changed, the pixmap is +simply copied to the screen. This is especially useful when you are +using markers to highlight points and regions on the bar chart. But if +the bar chart is updated frequently, changing either the element data or +coordinate axes, the buffering becomes redundant. +.SH LIMITATIONS +Auto-scale routines do not use requested min/max limits +as boundaries when the axis is logarithmically scaled. +.PP +The PostScript output generated for polygons with more than 1500 +points may exceed the limits of some printers (See PostScript Language +Reference Manual, page 568). The work-around is to break the polygon +into separate pieces. +.SH KEYWORDS +bar chart, widget |