diff options
Diffstat (limited to 'tkblt/doc/barchart.html')
| -rw-r--r-- | tkblt/doc/barchart.html | 1640 |
1 files changed, 0 insertions, 1640 deletions
diff --git a/tkblt/doc/barchart.html b/tkblt/doc/barchart.html deleted file mode 100644 index 7f04d25..0000000 --- a/tkblt/doc/barchart.html +++ /dev/null @@ -1,1640 +0,0 @@ -<HTML> -<BODY> -<PRE> -<!-- Manpage converted by man2html 3.0.1 --> - -</PRE> -<H2>SYNOPSIS</H2><PRE> - <B>barchart</B> <I>pathName</I> ?<I>option</I> <I>value</I>?... - - -</PRE> -<H2>DESCRIPTION</H2><PRE> - The <B>barchart</B> command creates a bar chart for plotting two-dimensional - data (X-Y coordinates). A bar chart is a graphic means of comparing - numbers by displaying bars of lengths proportional to the y-coordinates - of the points they represented. The bar chart has many configurable - components: coordinate axes, elements, legend, grid lines, cross hairs, - etc. They allow you to customize the look and feel of the graph. - - -</PRE> -<H2>INTRODUCTION</H2><PRE> - The <B>barchart</B> command creates a new window for plotting two-dimensional - data (X-Y coordinates), using bars of various lengths to represent the - data points. The bars are drawn in a rectangular area displayed in the - center of the new window. This is the <I>plotting</I> <I>area</I>. The coordinate - axes are drawn in the margins surrounding the plotting area. By - default, the legend is drawn in the right margin. The title is dis- - played in top margin. - - A <B>barchart</B> widget has several configurable components: coordinate axes, - data elements, legend, grid, cross hairs, pens, postscript, and annota- - tion markers. Each component can be queried or modified. - - axis Up to four coordinate axes (two X-coordinate and two Y-coor- - dinate axes) can be displayed, but you can create and use any - number of axes. Axes control what region of data is displayed - and how the data is scaled. Each axis consists of the axis - line, title, major and minor ticks, and tick labels. Tick - labels display the value at each major tick. - - crosshairs - Cross hairs are used to position the mouse pointer relative - to the X and Y coordinate axes. Two perpendicular lines, - intersecting at the current location of the mouse, extend - across the plotting area to the coordinate axes. - - element An element represents a set of data to be plotted. It con- - tains an x and y vector of values representing the data - points. Each data point is displayed as a bar where the - length of the bar is proportional to the ordinate (Y-coordi- - nate) of the data point. The appearance of the bar, such as - its color, stipple, or relief is configurable. - - A special case exists when two or more data points have the - same abscissa (X-coordinate). By default, the bars are over- - layed, one on top of the other. The bars are drawn in the - order of the element display list. But you can also config- - ure the bars to be displayed in two other ways. They may be - displayed as a stack, where each bar (with the same abscissa) - is stacked on the previous. Or they can be drawn side-by- - side as thin bars. The width of each bar is a function of - - pen Pens define attributes for elements. Data elements use pens - to specify how they should be drawn. A data element may use - many pens at once. Here the particular pen used for a data - point is determined from each element's weight vector (see - the element's <B>-weight</B> and <B>-style</B> options). - - postscript - The widget can generate encapsulated PostScript output. This - component has several options to configure how the PostScript - is generated. - - -</PRE> -<H2>SYNTAX</H2><PRE> - <B>barchart</B> <I>pathName</I> ?<I>option</I> <I>value</I>?... The <B>barchart</B> command creates a new - window <I>pathName</I> and makes it into a <B>barchart</B> widget. At the time this - command is invoked, there must not exist a window named <I>pathName</I>, but - <I>pathName</I>'s parent must exist. Additional options may be specified on - the command line or in the option database to configure aspects of the - graph such as its colors and font. See the <B>configure</B> operation below - for the exact details about what <I>option</I> and <I>value</I> pairs are valid. - - If successful, <B>barchart</B> returns the path name of the widget. It also - creates a new Tcl command by the same name. You can use this command - to invoke various operations that query or modify the graph. The gen- - eral form is: <I>pathName</I> <I>operation</I> ?<I>arg</I>?... Both <I>operation</I> and its argu- - ments determine the exact behavior of the command. The operations - available for the graph are described in the <B>BARCHART</B> <B>OPERATIONS</B> sec- - tion. - - The command can also be used to access components of the graph. <I>path-</I> - <I>Name</I> <I>component</I> <I>operation</I> ?<I>arg</I>?... The operation, now located after the - name of the component, is the function to be performed on that compo- - nent. Each component has its own set of operations that manipulate that - component. They will be described below in their own sections. - - -</PRE> -<H2>EXAMPLE</H2><PRE> - The <B>barchart</B> command creates a new bar chart. # Create a new bar - chart. Plotting area is black. barchart .b -plotbackground black A - new Tcl command .b is created. This command can be used to query and - modify the bar chart. For example, to change the title of the graph to - "My Plot", you use the new command and the <B>configure</B> operation. # - Change the title. .b configure -title "My Plot" To add data elements, - you use the command and the <B>element</B> component. # Create a new element - named "e1" .b element create e1 \ -xdata { 1 2 3 4 5 6 7 8 9 10 } - \ -ydata { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 - 155.85 166.60 175.38 } The element's X-Y coordinates are - specified using lists of numbers. Alternately, BLT vectors could be - used to hold the X-Y coordinates. # Create two vectors and add them to - the barchart. vector xVector yVector xVector set { 1 2 3 4 5 6 7 8 9 - 10 } yVector set { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85 - 166.60 175.38 } n.b element create e1 -xdata xVector -ydata yVec- - tor The advantage of using vectors is that when you modify one, the - sure we change the bar width too. .b configure -barwidth 0.2 The - height of each bar is proportional to the ordinate (Y-coordinate) of - the data point. - - If two or more data points have the same abscissa (X-coordinate value), - the bars representing those data points may be drawn in various ways. - The default is to overlay the bars, one on top of the other. The - ordering is determined from the of element display list. If the - stacked mode is selected (using the <B>-barmode</B> configuration option), the - bars are stacked, each bar above the previous. # Display the elements - as stacked. .b configure -barmode stacked If the aligned mode is - selected, the bars having the same x-coordinates are displayed side by - side. The width of each bar is a fraction of its normal width, based - upon the number of bars with the same x-coordinate. # Display the ele- - ments side-by-side. .b configure -barmode aligned By default, the ele- - ment's label in the legend will be also e1. You can change the label, - or specify no legend entry, again using the element's <B>configure</B> opera- - tion. # Don't display "e1" in the legend. .b element configure e1 - -label "" You can configure more than just the element's label. An - element has many attributes such as stipple, foreground and background - colors, relief, etc. .b element configure e1 -fg red -bg pink \ - -stipple gray50 Four coordinate axes are automatically created: x, - x2, y, and y2. And by default, elements are mapped onto the axes x and - y. This can be changed with the <B>-mapx</B> and <B>-mapy</B> options. # Map "e1" - on the alternate y axis "y2". .b element configure e1 -mapy y2 Axes - can be configured in many ways too. For example, you change the scale - of the Y-axis from linear to log using the <B>axis</B> component. # Y-axis is - log scale. .b axis configure y -logscale yes One important way axes - are used is to zoom in on a particular data region. Zooming is done by - simply specifying new axis limits using the <B>-min</B> and <B>-max</B> configuration - options. .b axis configure x -min 1.0 -max 1.5 .b axis configure y - -min 12.0 -max 55.15 To zoom interactively, you link the<B>axis</B> <B>configure</B> - operations with some user interaction (such as pressing the mouse but- - ton), using the <B>bind</B> command. To convert between screen and graph - coordinates, use the <B>invtransform</B> operation. # Click the button to set - a new minimum bind .b <ButtonPress-1> { - %W axis configure x -min [%W axis invtransform x %x] - %W axis configure x -min [%W axis invtransform x %y] } By default, - the limits of the axis are determined from data values. To reset back - to the default limits, set the <B>-min</B> and <B>-max</B> options to the empty - value. # Reset the axes to autoscale again. .b axis configure x -min - {} -max {} .b axis configure y -min {} -max {} By default, the legend - is drawn in the right margin. You can change this or any legend con- - figuration options using the <B>legend</B> component. # Configure the legend - font, color, and relief .b legend configure -position left -relief - raised \ -font fixed -fg blue To prevent the legend from being - displayed, turn on the <B>-hide</B> option. # Don't display the legend. .b - legend configure -hide yes The <B>barchart</B> has simple drawing procedures - called markers. They can be used to highlight or annotate data in the - graph. The types of markers available are bitmaps, polygons, lines, or - windows. Markers can be used, for example, to mark or brush points. - For example there may be a line marker which indicates some low-water - chart into file "file.ps" .b postscript output file.ps -maxpect yes - -decorations no This generates a file file.ps containing the encapsu- - lated PostScript of the graph. The option <B>-maxpect</B> says to scale the - plot to the size of the page. Turning off the <B>-decorations</B> option - denotes that no borders or color backgrounds should be drawn (i.e. the - background of the margins, legend, and plotting area will be white). - - -</PRE> -<H2>SYNTAX</H2><PRE> - <B>barchart</B> <I>pathName</I> ?<I>option</I> <I>value</I>?... The <B>barchart</B> command creates a new - window <I>pathName</I> and makes it into a barchart widget. At the time this - command is invoked, there must not exist a window named <I>pathName</I>, but - <I>pathName</I>'s parent must exist. Additional options may may be specified - on the command line or in the option database to configure aspects of - the bar chart such as its colors and font. See the <B>configure</B> operation - below for the exact details as to what <I>option</I> and <I>value</I> pairs are - valid. - - If successful, <B>barchart</B> returns <I>pathName</I>. It also creates a new Tcl - command <I>pathName</I>. This command may be used to invoke various opera- - tions to query or modify the bar chart. It has the general form: <I>path-</I> - <I>Name</I> <I>operation</I> ?<I>arg</I>?... Both <I>operation</I> and its arguments determine the - exact behavior of the command. The operations available for the bar - chart are described in the following section. - - -</PRE> -<H2>BARCHART OPERATIONS</H2><PRE> - <I>pathName</I> <B>bar</B> <I>elemName</I> ?<I>option</I> <I>value</I>?... - Creates a new barchart element <I>elemName</I>. It's an error if an - element <I>elemName</I> already exists. See the manual for <B>barchart</B> - for details about what <I>option</I> and <I>value</I> pairs are valid. - - <I>pathName</I> <B>cget</B> <I>option</I> - Returns the current value of the configuration option given by - <I>option</I>. <I>Option</I> may be any option described below for the <B>con-</B> - <B>figure</B> operation. - - <I>pathName</I> <B>configure</B> ?<I>option</I> <I>value</I>?... - Queries or modifies the configuration options of the graph. If - <I>option</I> isn't specified, a list describing the current options - for <I>pathName</I> is returned. If <I>option</I> is specified, but not - <I>value</I>, then a list describing <I>option</I> is returned. If one or - more <I>option</I> and <I>value</I> pairs are specified, then for each pair, - the option <I>option</I> is set to <I>value</I>. The following options are - valid. - - <B>-background</B> <I>color</I> - Sets the background color. This includes the margins and - legend, but not the plotting area. - - <B>-barmode</B> <I>mode</I> - Indicates how related bar elements will be drawn. - Related elements have data points with the same abscissas - (X-coordinates). <I>Mode</I> indicates how those segments should - - <B>-barwidth</B> <I>value</I> - Specifies the width of the bars. This value can be over- - rided by the individual elements using their <B>-barwidth</B> - configuration option. <I>Value</I> is the width in terms of - graph-coordinates. The default width is 1.0. - - <B>-borderwidth</B> <I>pixels</I> - Sets the width of the 3-D border around the outside edge - of the widget. The <B>-relief</B> option determines if the bor- - der is to be drawn. The default is 2. - - <B>-bottommargin</B> <I>pixels</I> - Specifies the size of the margin below the X-coordinate - axis. If <I>pixels</I> is 0, the size of the margin is selected - automatically. The default is 0. - - <B>-bufferelements</B> <I>boolean</I> - Indicates whether an internal pixmap to buffer the dis- - play of data elements should be used. If <I>boolean</I> is - true, data elements are drawn to an internal pixmap. - This option is especially useful when the graph is - redrawn frequently while the remains data unchanged (for - example, moving a marker across the plot). See the <B>SPEED</B> - <B>TIPS</B> section. The default is 1. - - <B>-cursor</B> <I>cursor</I> - Specifies the widget's cursor. The default cursor is - crosshair. - - <B>-font</B> <I>fontName</I> - Specifies the font of the graph title. The default is - *-Helvetica-Bold-R-Normal-*-18-180-*. - - <B>-halo</B> <I>pixels</I> - Specifies a maximum distance to consider when searching - for the closest data point (see the element's <B>closest</B> - operation below). Data points further than <I>pixels</I> away - are ignored. The default is 0.5i. - - <B>-height</B> <I>pixels</I> - Specifies the requested height of widget. The default is - 4i. - - <B>-invertxy</B> <I>boolean</I> - Indicates whether the placement X-axis and Y-axis should - be inverted. If <I>boolean</I> is true, the X and Y axes are - swapped. The default is 0. - - <B>-justify</B> <I>justify</I> - Specifies how the title should be justified. This mat- - ters only when the title contains more than one line of - area. The <B>-plotrelief</B> option determines if a border is - drawn. The default is 2. - - <B>-plotpadx</B> <I>pad</I> - Sets the amount of padding to be added to the left and - right sides of the plotting area. <I>Pad</I> can be a list of - one or two screen distances. If <I>pad</I> has two elements, - the left side of the plotting area entry is padded by the - first distance and the right side by the second. If <I>pad</I> - is just one distance, both the left and right sides are - padded evenly. The default is 8. - - <B>-plotpady</B> <I>pad</I> - Sets the amount of padding to be added to the top and - bottom of the plotting area. <I>Pad</I> can be a list of one or - two screen distances. If <I>pad</I> has two elements, the top - of the plotting area is padded by the first distance and - the bottom by the second. If <I>pad</I> is just one distance, - both the top and bottom are padded evenly. The default - is 8. - - <B>-plotrelief</B> <I>relief</I> - Specifies the 3-D effect for the plotting area. <I>Relief</I> - specifies how the interior of the plotting area should - appear relative to rest of the graph; for example, raised - means the plot should appear to protrude from the graph, - relative to the surface of the graph. The default is - sunken. - - <B>-relief</B> <I>relief</I> - Specifies the 3-D effect for the barchart widget. <I>Relief</I> - specifies how the graph should appear relative to widget - it is packed into; for example, raised means the graph - should appear to protrude. The default is flat. - - <B>-rightmargin</B> <I>pixels</I> - Sets the size of margin from the plotting area to the - right edge of the window. By default, the legend is - drawn in this margin. If <I>pixels</I> is than 1, the margin - size is selected automatically. - - <B>-takefocus</B> <I>focus</I> - Provides information used when moving the focus from win- - dow to window via keyboard traversal (e.g., Tab and - Shift-Tab). If <I>focus</I> is 0, this means that this window - should be skipped entirely during keyboard traversal. 1 - means that the this window should always receive the - input focus. An empty value means that the traversal - scripts make the decision whether to focus on the window. - The default is "". - - <B>-tile</B> <I>image</I> - <B>-width</B> <I>pixels</I> - Specifies the requested width of the widget. The default - is 5i. - - <I>pathName</I> <B>crosshairs</B> <I>operation</I> ?<I>arg</I>? - See the <B>CROSSHAIRS</B> <B>COMPONENT</B> section. - - <I>pathName</I> <B>element</B> <I>operation</I> ?<I>arg</I>?... - See the <B>ELEMENT</B> <B>COMPONENTS</B> section. - - <I>pathName</I> <B>extents</B> <I>item</I> - Returns the size of a particular item in the graph. <I>Item</I> must - be either leftmargin, rightmargin, topmargin, bottommargin, - plotwidth, or plotheight. - - <I>pathName</I> <B>grid</B> <I>operation</I> ?<I>arg</I>?... - See the <B>GRID</B> <B>COMPONENT</B> section. - - <I>pathName</I> <B>invtransform</B> <I>winX</I> <I>winY</I> - Performs an inverse coordinate transformation, mapping window - coordinates back to graph-coordinates, using the standard X-axis - and Y-axis. Returns a list of containing the X-Y graph-coordi- - nates. - - <I>pathName</I> <B>inside</B> <I>x</I> <I>y</I> - Returns 1 is the designated screen-coordinate (<I>x</I> and <I>y</I>) is - inside the plotting area and 0 otherwise. - - <I>pathName</I> <B>legend</B> <I>operation</I> ?<I>arg</I>?... - See the <B>LEGEND</B> <B>COMPONENT</B> section. - - <I>pathName</I> <B>line</B> <B>operation</B> <B>arg</B>... - The operation is the same as <B>element</B>. - - <I>pathName</I> <B>marker</B> <I>operation</I> ?<I>arg</I>?... - See the <B>MARKER</B> <B>COMPONENTS</B> section. - - <I>pathName</I> <B>metafile</B> ?<I>fileName</I>? - <I>This</I> <I>operation</I> <I>is</I> <I>for</I> <I>Window</I> <I>platforms</I> <I>only</I>. Creates a Windows - enhanced metafile of the barchart. If present, <I>fileName</I> is the - file name of the new metafile. Otherwise, the metafile is auto- - matically added to the clipboard. - - <I>pathName</I> <B>postscript</B> <I>operation</I> ?<I>arg</I>?... - See the <B>POSTSCRIPT</B> <B>COMPONENT</B> section. - - <I>pathName</I> <B>snap</B> <I>photoName</I> - Takes a snapshot of the graph and stores the contents in the - photo image <I>photoName</I>. <I>PhotoName</I> is the name of a Tk photo - image that must already exist. - - <I>pathName</I> <B>transform</B> <I>x</I> <I>y</I> - A graph is composed of several components: coordinate axes, data ele- - ments, legend, grid, cross hairs, postscript, and annotation markers. - Instead of one big set of configuration options and operations, the - graph is partitioned, where each component has its own configuration - options and operations that specifically control that aspect or part of - the graph. - - <B>AXIS</B> <B>COMPONENTS</B> - Four coordinate axes are automatically created: two X-coordinate axes - (x and x2) and two Y-coordinate axes (y, and y2). By default, the axis - x is located in the bottom margin, y in the left margin, x2 in the top - margin, and y2 in the right margin. - - An axis consists of the axis line, title, major and minor ticks, and - tick labels. Major ticks are drawn at uniform intervals along the - axis. Each tick is labeled with its coordinate value. Minor ticks are - drawn at uniform intervals within major ticks. - - The range of the axis controls what region of data is plotted. Data - points outside the minimum and maximum limits of the axis are not plot- - ted. By default, the minimum and maximum limits are determined from - the data, but you can reset either limit. - - You can create and use several axes. To create an axis, invoke the axis - component and its create operation. # Create a new axis called "tem- - perature" .b axis create temperature You map data elements to an axis - using the element's -mapy and -mapx configuration options. They specify - the coordinate axes an element is mapped onto. # Now map the tempera- - ture data to this axis. .b element create "temp" -xdata $x -ydata - $tempData \ - -mapy temperature While you can have many axes, only four axes can - be displayed simultaneously. They are drawn in each of the margins - surrounding the plotting area. The axes x and y are drawn in the bot- - tom and left margins. The axes x2 and y2 are drawn in top and right - margins. Only x and y are shown by default. Note that the axes can - have different scales. - - To display a different axis, you invoke one of the following compo- - nents: <B>xaxis</B>, <B>yaxis</B>, <B>x2axis</B>, and <B>y2axis</B>. The <B>use</B> operation designates - the axis to be drawn in the corresponding margin: <B>xaxis</B> in the bottom, - <B>yaxis</B> in the left, <B>x2axis</B> in the top, and <B>y2axis</B> in the right. # Dis- - play the axis temperature in the left margin. .b yaxis use temperature - - You can configure axes in many ways. The axis scale can be linear or - logarithmic. The values along the axis can either monotonically - increase or decrease. If you need custom tick labels, you can specify - a Tcl procedure to format the label any way you wish. You can control - how ticks are drawn, by changing the major tick interval or the number - of minor ticks. You can define non-uniform tick intervals, such as for - time-series plots. - - - <B>-autorange</B> <I>range</I> - Sets the range of values for the axis to <I>range</I>. The axis - limits are automatically reset to display the most recent - data points in this range. If <I>range</I> is 0.0, the range is - determined from the limits of the data. If <B>-min</B> or <B>-max</B> - are specified, they override this option. The default is - 0.0. - - <B>-color</B> <I>color</I> - Sets the color of the axis and tick labels. The default - is black. - - <B>-command</B> <I>prefix</I> - Specifies a Tcl command to be invoked when formatting the - axis tick labels. <I>Prefix</I> is a string containing the name - of a Tcl proc and any extra arguments for the procedure. - This command is invoked for each major tick on the axis. - Two additional arguments are passed to the procedure: the - pathname of the widget and the current the numeric value - of the tick. The procedure returns the formatted tick - label. If "" is returned, no label will appear next to - the tick. You can get the standard tick labels again by - setting <I>prefix</I> to "". The default is "". - - Please note that this procedure is invoked while the bar - chart is redrawn. You may query the widget's configura- - tion options. But do not reset options, because this can - have unexpected results. - - <B>-descending</B> <I>boolean</I> - Indicates whether the values along the axis are monotoni- - cally increasing or decreasing. If <I>boolean</I> is true, the - axis values will be decreasing. The default is 0. - - <B>-hide</B> <I>boolean</I> - Indicates whether the axis is displayed. - - <B>-justify</B> <I>justify</I> - Specifies how the axis title should be justified. This - matters only when the axis title contains more than one - line of text. <I>Justify</I> must be left, right, or center. - The default is center. - - <B>-limits</B> <I>formatStr</I> - Specifies a printf-like description to format the minimum - and maximum limits of the axis. The limits are displayed - at the top/bottom or left/right sides of the plotting - area. <I>FormatStr</I> is a list of one or two format descrip- - tions. If one description is supplied, both the minimum - and maximum limits are formatted in the same way. If - two, the first designates the format for the minimum - limit, the second for the maximum. If "" is given as - data points tightly, at the outermost data points, or - loosely, at the outer tick intervals. This is relevant - only when the axis limit is automatically calculated. If - <I>boolean</I> is true, the axis range is "loose". The default - is 0. - - <B>-majorticks</B> <I>majorList</I> - Specifies where to display major axis ticks. You can use - this option to display ticks at non-uniform intervals. - <I>MajorList</I> is a list of axis coordinates designating the - location of major ticks. No minor ticks are drawn. If - <I>majorList</I> is "", major ticks will be automatically com- - puted. The default is "". - - <B>-max</B> <I>value</I> - Sets the maximum limit of <I>axisName</I>. Any data point - greater than <I>value</I> is not displayed. If <I>value</I> is "", the - maximum limit is calculated using the largest data value. - The default is "". - - <B>-min</B> <I>value</I> - Sets the minimum limit of <I>axisName</I>. Any data point less - than <I>value</I> is not displayed. If <I>value</I> is "", the minimum - limit is calculated using the smallest data value. The - default is "". - - <B>-minorticks</B> <I>minorList</I> - Specifies where to display minor axis ticks. You can use - this option to display minor ticks at non-uniform inter- - vals. <I>MinorList</I> is a list of real values, ranging from - 0.0 to 1.0, designating the placement of a minor tick. - No minor ticks are drawn if the <B>-majortick</B> option is also - set. If <I>minorList</I> is "", minor ticks will be automati- - cally computed. The default is "". - - <B>-rotate</B> <I>theta</I> - Specifies the how many degrees to rotate the axis tick - labels. <I>Theta</I> is a real value representing the number of - degrees to rotate the tick labels. The default is 0.0 - degrees. - - <B>-shiftby</B> <I>value</I> - Specifies how much to automatically shift the range of - the axis. When the new data exceeds the current axis - maximum, the maximum is increased in increments of <I>value</I>. - You can use this option to prevent the axis limits from - being recomputed at each new time point. If <I>value</I> is 0.0, - then no automatic shifting is down. The default is 0.0. - - <B>-showticks</B> <I>boolean</I> - Indicates whether axis ticks should be drawn. If <I>boolean</I> - is true, ticks are drawn. If false, only the axis line - - <B>-tickfont</B> <I>fontName</I> - Specifies the font for axis tick labels. The default is - *-Courier-Bold-R-Normal-*-100-*. - - <B>-ticklength</B> <I>pixels</I> - Sets the length of major and minor ticks (minor ticks are - half the length of major ticks). If <I>pixels</I> is less than - zero, the axis will be inverted with ticks drawn pointing - towards the plot. The default is 0.1i. - - <B>-title</B> <I>text</I> - Sets the title of the axis. If <I>text</I> is "", no axis title - will be displayed. - - <B>-titlecolor</B> <I>color</I> - Sets the color of the axis title. The default is black. - - <B>-titlefont</B> <I>fontName</I> - Specifies the font for axis title. The default is *-Hel- - vetica-Bold-R-Normal-*-14-140-*. - - Axis configuration options may be also be set by the <B>option</B> com- - mand. The resource class is Axis. The resource names are the - names of the axes (such as x or x2). option add *Bar- - chart.Axis.Color blue option add *Barchart.x.LogScale true - option add *Barchart.x2.LogScale false - - <I>pathName</I> <B>axis</B> <B>create</B> <I>axisName</I> ?<I>option</I> <I>value</I>?... - Creates a new axis by the name <I>axisName</I>. No axis by the same - name can already exist. <I>Option</I> and <I>value</I> are described in above - in the axis <B>configure</B> operation. - - <I>pathName</I> <B>axis</B> <B>delete</B> ?<I>axisName</I>?... - Deletes the named axes. An axis is not really deleted until it - is not longer in use, so it's safe to delete axes mapped to ele- - ments. - - <I>pathName</I> <B>axis</B> <B>invtransform</B> <I>axisName</I> <I>value</I> - Performs the inverse transformation, changing the screen-coordi- - nate <I>value</I> to a graph-coordinate, mapping the value mapped to - <I>axisName</I>. Returns the graph-coordinate. - - <I>pathName</I> <B>axis</B> <B>limits</B> <I>axisName</I> - Returns a list of the minimum and maximum limits for <I>axisName</I>. - The order of the list is min max. - - <I>pathName</I> <B>axis</B> <B>names</B> ?<I>pattern</I>?... - Returns a list of axes matching zero or more patterns. If no - <I>pattern</I> argument is give, the names of all axes are returned. - - <I>pathName</I> <B>axis</B> <B>transform</B> <I>axisName</I> <I>value</I> - Transforms the coordinate <I>value</I> to a screen-coordinate by map- - - right Y-axis. - - They implicitly control the axis that is currently using to that loca- - tion. By default, <B>xaxis</B> uses the x axis, <B>yaxis</B> uses y, <B>x2axis</B> uses x2, - and <B>y2axis</B> uses y2. These components can be more convenient to use - than always determining what axes are current being displayed by the - graph. - - The following operations are available for axes. They mirror exactly - the operations of the <B>axis</B> component. The <I>axis</I> argument must be <B>xaxis</B>, - <B>x2axis</B>, <B>yaxis</B>, or <B>y2axis</B>. - - <I>pathName</I> <I>axis</I> <B>cget</B> <I>option</I> - - <I>pathName</I> <I>axis</I> <B>configure</B> ?<I>option</I> <I>value</I>?... - - <I>pathName</I> <I>axis</I> <B>invtransform</B> <I>value</I> - - <I>pathName</I> <I>axis</I> <B>limits</B> - - <I>pathName</I> <I>axis</I> <B>transform</B> <I>value</I> - - <I>pathName</I> <I>axis</I> <B>use</B> ?<I>axisName</I>? - Designates the axis <I>axisName</I> is to be displayed at this loca- - tion. <I>AxisName</I> can not be already in use at another location. - This command returns the name of the axis currently using this - location. - - <B>CROSSHAIRS</B> <B>COMPONENT</B> - Cross hairs consist of two intersecting lines (one vertical and one - horizontal) drawn completely across the plotting area. They are used - to position the mouse in relation to the coordinate axes. Cross hairs - differ from line markers in that they are implemented using XOR drawing - primitives. This means that they can be quickly drawn and erased with- - out redrawing the entire widget. - - The following operations are available for cross hairs: - - <I>pathName</I> <B>crosshairs</B> <B>cget</B> <I>option</I> - Returns the current value of the cross hairs configuration - option given by <I>option</I>. <I>Option</I> may be any option described - below for the cross hairs <B>configure</B> operation. - - <I>pathName</I> <B>crosshairs</B> <B>configure</B> ?<I>option</I> <I>value</I>?... - Queries or modifies the configuration options of the cross - hairs. If <I>option</I> isn't specified, a list describing all the - current options for the cross hairs is returned. If <I>option</I> is - specified, but not <I>value</I>, then a list describing <I>option</I> is - returned. If one or more <I>option</I> and <I>value</I> pairs are specified, - then for each pair, the cross hairs option <I>option</I> is set to - <I>value</I>. The following options are available for cross hairs. - - <B>-linewidth</B> <I>pixels</I> - Set the width of the cross hair lines. The default is 1. - - <B>-position</B> <I>pos</I> - Specifies the screen position where the cross hairs - intersect. <I>Pos</I> must be in the form "<I>@x,y</I>", where <I>x</I> and <I>y</I> - are the window coordinates of the intersection. - - Cross hairs configuration options may be also be set by the - <B>option</B> command. The resource name and class are crosshairs and - Crosshairs respectively. option add *Bar- - chart.Crosshairs.LineWidth 2 option add *Bar- - chart.Crosshairs.Color red - - <I>pathName</I> <B>crosshairs</B> <B>off</B> - Turns off the cross hairs. - - <I>pathName</I> <B>crosshairs</B> <B>on</B> - Turns on the display of the cross hairs. - - <I>pathName</I> <B>crosshairs</B> <B>toggle</B> - Toggles the current state of the cross hairs, alternately map- - ping and unmapping the cross hairs. - - -</PRE> -<H2>ELEMENTS</H2><PRE> - A data element represents a set of data. It contains x and y vectors - which are the coordinates of the data points. Elements are displayed - as bars where the length of the bar is proportional to the ordinate of - the data point. Elements also control the appearance of the data, such - as the color, stipple, relief, etc. - - When new data elements are created, they are automatically added to a - list of displayed elements. The display list controls what elements - are drawn and in what order. - - The following operations are available for elements. - - <I>pathName</I> <B>element</B> <B>activate</B> <I>elemName</I> ?<I>index</I>?... - Specifies the data points of element <I>elemName</I> to be drawn using - active foreground and background colors. <I>ElemName</I> is the name - of the element and <I>index</I> is a number representing the index of - the data point. If no indices are present then all data points - become active. - - <I>pathName</I> <B>element</B> <B>bind</B> <I>tagName</I> ?<I>sequence</I>? ?<I>command</I>? - Associates <I>command</I> with <I>tagName</I> such that whenever the event - sequence given by <I>sequence</I> occurs for an element with this tag, - <I>command</I> will be invoked. The syntax is similar to the <B>bind</B> com- - mand except that it operates on graph elements, rather than wid- - gets. See the <B>bind</B> manual entry for complete details on <I>sequence</I> - and the substitutions performed on <I>command</I> before invoking it. - - - <I>pathName</I> <B>element</B> <B>closest</B> <I>x</I> <I>y</I> ?<I>option</I> <I>value</I>?... ?<I>elemName</I>?... - Finds the data point representing the bar closest to the window - coordinates <I>x</I> and <I>y</I> in the element <I>elemName</I>. <I>ElemName</I> is the - name of an element, which must be currently displayed. If no - elements are specified, then all displayed elements are - searched. It returns a key-value list containing the name of - the closest element, the index of its closest point, and the - graph-coordinates of the point. If no data point within the - threshold distance can be found, "" is returned. The following - <I>option</I>-<I>value</I> pairs are available. - - <B>-halo</B> <I>pixels</I> - Specifies a threshold distance where selected data points - are ignored. <I>Pixels</I> is a valid screen distance, such as - 2 or 1.2i. If this option isn't specified, then it - defaults to the value of the <B>barchart</B>'s <B>-halo</B> option. - - <I>pathName</I> <B>element</B> <B>configure</B> <I>elemName</I> ?<I>elemName</I>... ?<I>option</I> <I>value</I>?... - Queries or modifies the configuration options for elements. - Several elements can be modified at the same time. If <I>option</I> - isn't specified, a list describing all the current options for - <I>elemName</I> is returned. If <I>option</I> is specified, but not <I>value</I>, - then a list describing the option <I>option</I> is returned. If one or - more <I>option</I> and <I>value</I> pairs are specified, then for each pair, - the element option <I>option</I> is set to <I>value</I>. The following - options are valid for elements. - - <B>-activepen</B> <I>penName</I> - Specifies pen to use to draw active element. If <I>penName</I> - is "", no active elements will be drawn. The default is - activeLine. - - <B>-bindtags</B> <I>tagList</I> - Specifies the binding tags for the element. <I>TagList</I> is a - list of binding tag names. The tags and their order will - determine how events for elements. Each tag in the list - matching the current event sequence will have its Tcl - command executed. Implicitly the name of the element is - always the first tag in the list. The default value is - all. - - <B>-background</B> <I>color</I> - Sets the the color of the border around each bar. The - default is white. - - <B>-barwidth</B> <I>value</I> - Specifies the width the bars drawn for the element. - <I>Value</I> is the width in X-coordinates. If this option - isn't specified, the width of each bar is the value of - the widget's <B>-barwidth</B> option. - - a list of numeric expressions representing the X-Y coor- - dinate pairs of each data point. - - <B>-foreground</B> <I>color</I> - Sets the color of the interior of the bars. - - <B>-hide</B> <I>boolean</I> - Indicates whether the element is displayed. The default - is no. - - <B>-label</B> <I>text</I> - Sets the element's label in the legend. If <I>text</I> is "", - the element will have no entry in the legend. The - default label is the element's name. - - <B>-mapx</B> <I>xAxis</I> - Selects the X-axis to map the element's X-coordinates - onto. <I>XAxis</I> must be the name of an axis. The default is - x. - - <B>-mapy</B> <I>yAxis</I> - Selects the Y-axis to map the element's Y-coordinates - onto. <I>YAxis</I> must be the name of an axis. The default is - y. - - <B>-relief</B> <I>string</I> - Specifies the 3-D effect desired for bars. <I>Relief</I> indi- - cates how the interior of the bar should appear relative - to the surface of the chart; for example, raised means - the bar should appear to protrude from the surface of the - plotting area. The default is raised. - - <B>-stipple</B> <I>bitmap</I> - Specifies a stipple pattern with which to draw the bars. - If <I>bitmap</I> is "", then the bar is drawn in a solid fash- - ion. - - <B>-xdata</B> <I>xVector</I> - Specifies the x-coordinate vector of the data. <I>XVector</I> - is the name of a BLT vector or a list of numeric expres- - sions. - - <B>-ydata</B> <I>yVector</I> - Specifies the y-coordinate vector of the data. <I>YVector</I> - is the name of a BLT vector or a list of numeric expres- - sions. - - Element configuration options may also be set by the <B>option</B> com- - mand. The resource names in the option database are prefixed - by elem. option add *Barchart.Element.background blue - - <I>pathName</I> <B>element</B> <B>create</B> <I>elemName</I> ?<I>option</I> <I>value</I>?... - - <I>pathName</I> <B>element</B> <B>exists</B> <I>elemName</I> - Returns 1 if an element <I>elemName</I> currently exists and 0 other- - wise. - - <I>pathName</I> <B>element</B> <B>names</B> ?<I>pattern</I>?... - Returns the elements matching one or more pattern. If no <I>pat-</I> - <I>tern</I> is given, the names of all elements is returned. - - <I>pathName</I> <B>element</B> <B>show</B> ?<I>nameList</I>? - Queries or modifies the element display list. The element dis- - play list designates the elements drawn and in what order. - <I>NameList</I> is a list of elements to be displayed in the order they - are named. If there is no <I>nameList</I> argument, the current dis- - play list is returned. - - <I>pathName</I> <B>element</B> <B>type</B> <I>elemName</I> - Returns the type of <I>elemName</I>. If the element is a bar element, - the commands returns the string "bar", otherwise it returns - "line". - - <B>GRID</B> <B>COMPONENT</B> - Grid lines extend from the major and minor ticks of each axis horizon- - tally or vertically across the plotting area. The following operations - are available for grid lines. - - <I>pathName</I> <B>grid</B> <B>cget</B> <I>option</I> - Returns the current value of the grid line configuration option - given by <I>option</I>. <I>Option</I> may be any option described below for - the grid <B>configure</B> operation. - - <I>pathName</I> <B>grid</B> <B>configure</B> ?<I>option</I> <I>value</I>?... - Queries or modifies the configuration options for grid lines. - If <I>option</I> isn't specified, a list describing all the current - grid options for <I>pathName</I> is returned. If <I>option</I> is specified, - but not <I>value</I>, then a list describing <I>option</I> is returned. If - one or more <I>option</I> and <I>value</I> pairs are specified, then for each - pair, the grid line option <I>option</I> is set to <I>value</I>. The follow- - ing options are valid for grid lines. - - <B>-color</B> <I>color</I> - Sets the color of the grid lines. The default is black. - - <B>-dashes</B> <I>dashList</I> - Sets the dash style of the grid lines. <I>DashList</I> is a list - of up to 11 numbers that alternately represent the - lengths of the dashes and gaps on the grid lines. Each - number must be between 1 and 255. If <I>dashList</I> is "", the - grid will be solid lines. - - <B>-hide</B> <I>boolean</I> - Indicates whether the grid should be drawn. If <I>boolean</I> is - - <B>-minor</B> <I>boolean</I> - Indicates whether the grid lines should be drawn for - minor ticks. If <I>boolean</I> is true, the lines will appear - at minor tick intervals. The default is 1. - - Grid configuration options may also be set by the <B>option</B> com- - mand. The resource name and class are grid and Grid respec- - tively. option add *Barchart.grid.LineWidth 2 option add *Bar- - chart.Grid.Color black - - <I>pathName</I> <B>grid</B> <B>off</B> - Turns off the display the grid lines. - - <I>pathName</I> <B>grid</B> <B>on</B> - Turns on the display the grid lines. - - <I>pathName</I> <B>grid</B> <B>toggle</B> - Toggles the display of the grid. - - <B>LEGEND</B> <B>COMPONENT</B> - The legend displays a list of the data elements. Each entry consists - of the element's symbol and label. The legend can appear in any margin - (the default location is in the right margin). It can also be posi- - tioned anywhere within the plotting area. - - The following operations are valid for the legend. - - <I>pathName</I> <B>legend</B> <B>activate</B> <I>pattern</I>... - Selects legend entries to be drawn using the active legend col- - ors and relief. All entries whose element names match <I>pattern</I> - are selected. To be selected, the element name must match only - one <I>pattern</I>. - - <I>pathName</I> <B>legend</B> <B>bind</B> <I>tagName</I> ?<I>sequence</I>? ?<I>command</I>? - Associates <I>command</I> with <I>tagName</I> such that whenever the event - sequence given by <I>sequence</I> occurs for a legend entry with this - tag, <I>command</I> will be invoked. Implicitly the element names in - the entry are tags. The syntax is similar to the <B>bind</B> command - except that it operates on legend entries, rather than widgets. - See the <B>bind</B> manual entry for complete details on <I>sequence</I> and - the substitutions performed on <I>command</I> before invoking it. - - If all arguments are specified then a new binding is created, - replacing any existing binding for the same <I>sequence</I> and <I>tag-</I> - <I>Name</I>. If the first character of <I>command</I> is + then <I>command</I> aug- - ments an existing binding rather than replacing it. If no <I>com-</I> - <I>mand</I> argument is provided then the command currently associated - with <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no - such binding) is returned. If both <I>command</I> and <I>sequence</I> are - missing then a list of all the event sequences for which bind- - ings have been defined for <I>tagName</I>. - - <B>-activebackground</B> <I>color</I> - Sets the background color for active legend entries. All - legend entries marked active (see the legend <B>activate</B> - operation) are drawn using this background color. - - <B>-activeborderwidth</B> <I>pixels</I> - Sets the width of the 3-D border around the outside edge - of the active legend entries. The default is 2. - - <B>-activeforeground</B> <I>color</I> - Sets the foreground color for active legend entries. All - legend entries marked as active (see the legend <B>activate</B> - operation) are drawn using this foreground color. - - <B>-activerelief</B> <I>relief</I> - Specifies the 3-D effect desired for active legend - entries. <I>Relief</I> denotes how the interior of the entry - should appear relative to the legend; for example, raised - means the entry should appear to protrude from the leg- - end, relative to the surface of the legend. The default - is flat. - - <B>-anchor</B> <I>anchor</I> - Tells how to position the legend relative to the posi- - tioning point for the legend. This is dependent on the - value of the <B>-position</B> option. The default is center. - - left or right - The anchor describes how to position the leg- - end vertically. - - top or bottom - The anchor describes how to position the leg- - end horizontally. - - @x,y The anchor specifies how to position the leg- - end relative to the positioning point. For - example, if <I>anchor</I> is center then the legend - is centered on the point; if <I>anchor</I> is n then - the legend will be drawn such that the top - center point of the rectangular region occu- - pied by the legend will be at the positioning - point. - - plotarea The anchor specifies how to position the leg- - end relative to the plotting area. For exam- - ple, if <I>anchor</I> is center then the legend is - centered in the plotting area; if <I>anchor</I> is - ne then the legend will be drawn such that - occupies the upper right corner of the plot- - ting area. - - of the legend (if such border is being drawn; the <B>relief</B> - option determines this). The default is 2 pixels. - - <B>-font</B> <I>fontName</I> - <I>FontName</I> specifies a font to use when drawing the labels - of each element into the legend. The default is *-Hel- - vetica-Bold-R-Normal-*-12-120-*. - - <B>-foreground</B> <I>color</I> - Sets the foreground color of the text drawn for the ele- - ment's label. The default is black. - - <B>-hide</B> <I>boolean</I> - Indicates whether the legend should be displayed. If - <I>boolean</I> is true, the legend will not be draw. The - default is no. - - <B>-ipadx</B> <I>pad</I> - Sets the amount of internal padding to be added to the - width of each legend entry. <I>Pad</I> can be a list of one or - two screen distances. If <I>pad</I> has two elements, the left - side of the legend entry is padded by the first distance - and the right side by the second. If <I>pad</I> is just one - distance, both the left and right sides are padded - evenly. The default is 2. - - <B>-ipady</B> <I>pad</I> - Sets an amount of internal padding to be added to the - height of each legend entry. <I>Pad</I> can be a list of one or - two screen distances. If <I>pad</I> has two elements, the top - of the entry is padded by the first distance and the bot- - tom by the second. If <I>pad</I> is just one distance, both the - top and bottom of the entry are padded evenly. The - default is 2. - - <B>-padx</B> <I>pad</I> - Sets the padding to the left and right exteriors of the - legend. <I>Pad</I> can be a list of one or two screen dis- - tances. If <I>pad</I> has two elements, the left side of the - legend is padded by the first distance and the right side - by the second. If <I>pad</I> has just one distance, both the - left and right sides are padded evenly. The default is - 4. - - <B>-pady</B> <I>pad</I> - Sets the padding above and below the legend. <I>Pad</I> can be - a list of one or two screen distances. If <I>pad</I> has two - elements, the area above the legend is padded by the - first distance and the area below by the second. If <I>pad</I> - is just one distance, both the top and bottom areas are - padded evenly. The default is 0. - - drawn on top of any elements that may overlap it. The - default is no. - - <B>-relief</B> <I>relief</I> - Specifies the 3-D effect for the border around the leg- - end. <I>Relief</I> specifies how the interior of the legend - should appear relative to the bar chart; for example, - raised means the legend should appear to protrude from - the bar chart, relative to the surface of the bar chart. - The default is sunken. - - Legend configuration options may also be set by the <B>option</B> com- - mand. The resource name and class are legend and Legend respec- - tively. option add *Barchart.legend.Foreground blue option add - *Barchart.Legend.Relief raised - - <I>pathName</I> <B>legend</B> <B>deactivate</B> <I>pattern</I>... - Selects legend entries to be drawn using the normal legend col- - ors and relief. All entries whose element names match <I>pattern</I> - are selected. To be selected, the element name must match only - one <I>pattern</I>. - - <I>pathName</I> <B>legend</B> <B>get</B> <I>pos</I> - Returns the name of the element whose entry is at the screen - position <I>pos</I> in the legend. <I>Pos</I> must be in the form "<I>@x,y</I>", - where <I>x</I> and <I>y</I> are window coordinates. If the given coordinates - do not lie over a legend entry, "" is returned. - - <B>PEN</B> <B>COMPONENTS</B> - Pens define attributes for elements. Pens mirror the configuration - options of data elements that pertain to how symbols and lines are - drawn. Data elements use pens to determine how they are drawn. A data - element may use several pens at once. In this case, the pen used for a - particular data point is determined from each element's weight vector - (see the element's <B>-weight</B> and <B>-style</B> options). - - One pen, called activeBar, is automatically created. It's used as the - default active pen for elements. So you can change the active - attributes for all elements by simply reconfiguring this pen. .g pen - configure "activeBar" -fg green -bg green4 You can create and use sev- - eral pens. To create a pen, invoke the pen component and its create - operation. .g pen create myPen You map pens to a data element using - either the element's <B>-pen</B> or <B>-activepen</B> options. .g element create - "e1" -xdata $x -ydata $tempData \ - -pen myPen An element can use several pens at once. This is done by - specifying the name of the pen in the element's style list (see the - <B>-styles</B> option). .g element configure "e1" -styles { myPen 2.0 3.0 } - This says that any data point with a weight between 2.0 and 3.0 is to - be drawn using the pen myPen. All other points are drawn with the ele- - ment's default attributes. - - The following operations are available for pen components. - <I>value</I>. The following options are valid for pens. - - <B>-background</B> <I>color</I> - Sets the the color of the border around each bar. The - default is white. - - <B>-borderwidth</B> <I>pixels</I> - Sets the border width of the 3-D border drawn around the - outside of each bar. The <B>-relief</B> option determines if - such a border is drawn. <I>Pixels</I> must be a valid screen - distance like 2 or 0.25i. The default is 2. - - <B>-foreground</B> <I>color</I> - Sets the color of the interior of the bars. - - <B>-relief</B> <I>string</I> - Specifies the 3-D effect desired for bars. <I>Relief</I> indi- - cates how the interior of the bar should appear relative - to the surface of the chart; for example, raised means - the bar should appear to protrude from the bar chart, - relative to the surface of the plotting area. The - default is raised. - - <B>-stipple</B> <I>bitmap</I> - Specifies a stipple pattern with which to draw the bars. - If <I>bitmap</I> is "", then the bar is drawn in a solid fash- - ion. - - <B>-type</B> <I>elemType</I> - Specifies the type of element the pen is to be used with. - This option should only be employed when creating the - pen. This is for those that wish to mix different types - of elements (bars and lines) on the same graph. The - default type is "bar". - - Pen configuration options may be also be set by the <B>option</B> com- - mand. The resource class is Pen. The resource names are the - names of the pens. option add *Barchart.Pen.Foreground - blue option add *Barchart.activeBar.foreground green - - <I>pathName</I> <B>pen</B> <B>create</B> <I>penName</I> ?<I>option</I> <I>value</I>?... - Creates a new pen by the name <I>penName</I>. No pen by the same name - can already exist. <I>Option</I> and <I>value</I> are described in above in - the pen <B>configure</B> operation. - - <I>pathName</I> <B>pen</B> <B>delete</B> ?<I>penName</I>?... - Deletes the named pens. A pen is not really deleted until it is - not longer in use, so it's safe to delete pens mapped to ele- - ments. - - <I>pathName</I> <B>pen</B> <B>names</B> ?<I>pattern</I>?... - Returns a list of pens matching zero or more patterns. If no - <I>option</I>. <I>Option</I> may be any option described below for the post- - script <B>configure</B> operation. - - <I>pathName</I> <B>postscript</B> <B>configure</B> ?<I>option</I> <I>value</I>?... - Queries or modifies the configuration options for PostScript - generation. If <I>option</I> isn't specified, a list describing the - current postscript options for <I>pathName</I> is returned. If <I>option</I> - is specified, but not <I>value</I>, then a list describing <I>option</I> is - returned. If one or more <I>option</I> and <I>value</I> pairs are specified, - then for each pair, the postscript option <I>option</I> is set to - <I>value</I>. The following postscript options are available. - - <B>-center</B> <I>boolean</I> - Indicates whether the plot should be centered on the - PostScript page. If <I>boolean</I> is false, the plot will be - placed in the upper left corner of the page. The default - is 1. - - <B>-colormap</B> <I>varName</I> - <I>VarName</I> must be the name of a global array variable that - specifies a color mapping from the X color name to Post- - Script. Each element of <I>varName</I> must consist of Post- - Script code to set a particular color value (e.g. ``1.0 - 1.0 0.0 setrgbcolor''). When generating color informa- - tion in PostScript, the array variable <I>varName</I> is checked - if an element of the name as the color exists. If so, it - uses its value as the PostScript command to set the - color. If this option hasn't been specified, or if there - isn't an entry in <I>varName</I> for a given color, then it uses - the red, green, and blue intensities from the X color. - - <B>-colormode</B> <I>mode</I> - Specifies how to output color information. <I>Mode</I> must be - either color (for full color output), gray (convert all - colors to their gray-scale equivalents) or mono (convert - foreground colors to black and background colors to - white). The default mode is color. - - <B>-fontmap</B> <I>varName</I> - <I>VarName</I> must be the name of a global array variable that - specifies a font mapping from the X font name to Post- - Script. Each element of <I>varName</I> must consist of a Tcl - list with one or two elements; the name and point size of - a PostScript font. When outputting PostScript commands - for a particular font, the array variable <I>varName</I> is - checked to see if an element by the specified font - exists. If there is such an element, then the font - information contained in that element is used in the - PostScript output. (If the point size is omitted from - the list, the point size of the X font is used). Other- - wise the X font is examined in an attempt to guess what - PostScript font to use. This works only for fonts whose - widget's height. The default is 0. - - <B>-landscape</B> <I>boolean</I> - If <I>boolean</I> is true, this specifies the printed area is to - be rotated 90 degrees. In non-rotated output the X-axis - of the printed area runs along the short dimension of the - page (``portrait'' orientation); in rotated output the - X-axis runs along the long dimension of the page (``land- - scape'' orientation). Defaults to 0. - - <B>-maxpect</B> <I>boolean</I> - Indicates to scale the plot so that it fills the Post- - Script page. The aspect ratio of the barchart is still - retained. The default is 0. - - <B>-padx</B> <I>pad</I> - Sets the horizontal padding for the left and right page - borders. The borders are exterior to the plot. <I>Pad</I> can - be a list of one or two screen distances. If <I>pad</I> has two - elements, the left border is padded by the first distance - and the right border by the second. If <I>pad</I> has just one - distance, both the left and right borders are padded - evenly. The default is 1i. - - <B>-pady</B> <I>pad</I> - Sets the vertical padding for the top and bottom page - borders. The borders are exterior to the plot. <I>Pad</I> can - be a list of one or two screen distances. If <I>pad</I> has two - elements, the top border is padded by the first distance - and the bottom border by the second. If <I>pad</I> has just one - distance, both the top and bottom borders are padded - evenly. The default is 1i. - - <B>-paperheight</B> <I>pixels</I> - Sets the height of the postscript page. This can be used - to select between different page sizes (letter, A4, etc). - The default height is 11.0i. - - <B>-paperwidth</B> <I>pixels</I> - Sets the width of the postscript page. This can be used - to select between different page sizes (letter, A4, etc). - The default width is 8.5i. - - <B>-width</B> <I>pixels</I> - Sets the width of the plot. This lets you generate a - plot of a width different from that of the widget. If - <I>pixels</I> is 0, the width is the same as the widget's width. - The default is 0. - - Postscript configuration options may be also be set by the - <B>option</B> command. The resource name and class are postscript and - Postscript respectively. option add *Barchart.postscript.Deco- - - with a particular element, so that when the element is hidden or un- - hidden, so is the marker. By default, markers are the last items - drawn, so that data elements will appear in behind them. You can - change this by configuring the <B>-under</B> option. - - Markers, in contrast to elements, don't affect the scaling of the coor- - dinate axes. They can also have <I>elastic</I> coordinates (specified by -Inf - and Inf respectively) that translate into the minimum or maximum limit - of the axis. For example, you can place a marker so it always remains - in the lower left corner of the plotting area, by using the coordinates - -Inf,-Inf. - - The following operations are available for markers. - - <I>pathName</I> <B>marker</B> <B>after</B> <I>markerId</I> ?<I>afterId</I>? - Changes the order of the markers, drawing the first marker after - the second. If no second <I>afterId</I> argument is specified, the - marker is placed at the end of the display list. This command - can be used to control how markers are displayed since markers - are drawn in the order of this display list. - - <I>pathName</I> <B>marker</B> <B>before</B> <I>markerId</I> ?<I>beforeId</I>? - Changes the order of the markers, drawing the first marker - before the second. If no second <I>beforeId</I> argument is specified, - the marker is placed at the beginning of the display list. This - command can be used to control how markers are displayed since - markers are drawn in the order of this display list. - - <I>pathName</I> <B>marker</B> <B>bind</B> <I>tagName</I> ?<I>sequence</I>? ?<I>command</I>? - Associates <I>command</I> with <I>tagName</I> such that whenever the event - sequence given by <I>sequence</I> occurs for a marker with this tag, - <I>command</I> will be invoked. The syntax is similar to the <B>bind</B> com- - mand except that it operates on graph markers, rather than wid- - gets. See the <B>bind</B> manual entry for complete details on <I>sequence</I> - and the substitutions performed on <I>command</I> before invoking it. - - If all arguments are specified then a new binding is created, - replacing any existing binding for the same <I>sequence</I> and <I>tag-</I> - <I>Name</I>. If the first character of <I>command</I> is + then <I>command</I> aug- - ments an existing binding rather than replacing it. If no <I>com-</I> - <I>mand</I> argument is provided then the command currently associated - with <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no - such binding) is returned. If both <I>command</I> and <I>sequence</I> are - missing then a list of all the event sequences for which bind- - ings have been defined for <I>tagName</I>. - - <I>pathName</I> <B>marker</B> <B>cget</B> <I>option</I> - Returns the current value of the marker configuration option - given by <I>option</I>. <I>Option</I> may be any option described below in - the <B>configure</B> operation. - - <I>pathName</I> <B>marker</B> <B>configure</B> <I>markerId</I> ?<I>option</I> <I>value</I>?... - determine how events for markers are handled. Each tag - in the list matching the current event sequence will have - its Tcl command executed. Implicitly the name of the - marker is always the first tag in the list. The default - value is all. - - <B>-coords</B> <I>coordList</I> - Specifies the coordinates of the marker. <I>CoordList</I> is a - list of graph-coordinates. The number of coordinates - required is dependent on the type of marker. Text, - image, and window markers need only two coordinates (an - X-Y coordinate). Bitmap markers can take either two or - four coordinates (if four, they represent the corners of - the bitmap). Line markers need at least four coordinates, - polygons at least six. If <I>coordList</I> is "", the marker - will not be displayed. The default is "". - - <B>-element</B> <I>elemName</I> - Links the marker with the element <I>elemName</I>. The marker - is drawn only if the element is also currently displayed - (see the element's <B>show</B> operation). If <I>elemName</I> is "", - the marker is always drawn. The default is "". - - <B>-hide</B> <I>boolean</I> - Indicates whether the marker is drawn. If <I>boolean</I> is - true, the marker is not drawn. The default is no. - - <B>-mapx</B> <I>xAxis</I> - Specifies the X-axis to map the marker's X-coordinates - onto. <I>XAxis</I> must the name of an axis. The default is x. - - <B>-mapy</B> <I>yAxis</I> - Specifies the Y-axis to map the marker's Y-coordinates - onto. <I>YAxis</I> must the name of an axis. The default is y. - - <B>-name</B> <I>markerId</I> - Changes the identifier for the marker. The identifier - <I>markerId</I> can not already be used by another marker. If - this option isn't specified, the marker's name is - uniquely generated. - - <B>-under</B> <I>boolean</I> - Indicates whether the marker is drawn below/above data - elements. If <I>boolean</I> is true, the marker is be drawn - underneath the data elements. Otherwise, the marker is - drawn on top of the element. The default is 0. - - <B>-xoffset</B> <I>pixels</I> - Specifies a screen distance to offset the marker horizon- - tally. <I>Pixels</I> is a valid screen distance, such as 2 or - 1.2i. The default is 0. - - Creates a marker of the selected type. <I>Type</I> may be either text, - line, bitmap, image, polygon, or window. This command returns - the marker identifier, used as the <I>markerId</I> argument in the - other marker-related commands. If the <B>-name</B> option is used, - this overrides the normal marker identifier. If the name pro- - vided is already used for another marker, the new marker will - replace the old. - - <I>pathName</I> <B>marker</B> <B>delete</B> ?<I>name</I>?... - Removes one of more markers. The graph will automatically be - redrawn without the marker.. - - <I>pathName</I> <B>marker</B> <B>exists</B> <I>markerId</I> - Returns 1 if the marker <I>markerId</I> exists and 0 otherwise. - - <I>pathName</I> <B>marker</B> <B>names</B> ?<I>pattern</I>? - Returns the names of all the markers that currently exist. If - <I>pattern</I> is supplied, only those markers whose names match it - will be returned. - - <I>pathName</I> <B>marker</B> <B>type</B> <I>markerId</I> - Returns the type of the marker given by <I>markerId</I>, such as line - or text. If <I>markerId</I> is not a valid a marker identifier, "" is - returned. - - <B>BITMAP</B> <B>MARKERS</B> - A bitmap marker displays a bitmap. The size of the bitmap is con- - trolled by the number of coordinates specified. If two coordinates, - they specify the position of the top-left corner of the bitmap. The - bitmap retains its normal width and height. If four coordinates, the - first and second pairs of coordinates represent the corners of the bit- - map. The bitmap will be stretched or reduced as necessary to fit into - the bounding rectangle. - - Bitmap markers are created with the marker's <B>create</B> operation in the - form: <I>pathName</I> <B>marker</B> <B>create</B> <B>bitmap</B> ?<I>option</I> <I>value</I>?... There may be - many <I>option</I>-<I>value</I> pairs, each sets a configuration options for the - marker. These same <I>option</I>-<I>value</I> pairs may be used with the marker's - <B>configure</B> operation. - - The following options are specific to bitmap markers: - - <B>-background</B> <I>color</I> - Same as the <B>-fill</B> option. - - <B>-bitmap</B> <I>bitmap</I> - Specifies the bitmap to be displayed. If <I>bitmap</I> is "", the - marker will not be displayed. The default is "". - - <B>-fill</B> <I>color</I> - Sets the background color of the bitmap. If <I>color</I> is the empty - string, no background will be transparent. The default back- - - <B>-rotate</B> <I>theta</I> - Sets the rotation of the bitmap. <I>Theta</I> is a real number repre- - senting the angle of rotation in degrees. The marker is first - rotated and then placed according to its anchor position. The - default rotation is 0.0. - - <B>IMAGE</B> <B>MARKERS</B> - A image marker displays an image. Image markers are created with the - marker's <B>create</B> operation in the form: <I>pathName</I> <B>marker</B> <B>create</B> <B>image</B> - ?<I>option</I> <I>value</I>?... There may be many <I>option</I>-<I>value</I> pairs, each sets a - configuration option for the marker. These same <I>option</I>-<I>value</I> pairs may - be used with the marker's <B>configure</B> operation. - - The following options are specific to image markers: - - <B>-anchor</B> <I>anchor</I> - <I>Anchor</I> tells how to position the image relative to the position- - ing point for the image. For example, if <I>anchor</I> is center then - the image is centered on the point; if <I>anchor</I> is n then the - image will be drawn such that the top center point of the rect- - angular region occupied by the image will be at the positioning - point. This option defaults to center. - - <B>-image</B> <I>image</I> - Specifies the image to be drawn. If <I>image</I> is "", the marker - will not be drawn. The default is "". - - <B>LINE</B> <B>MARKERS</B> - A line marker displays one or more connected line segments. Line mark- - ers are created with marker's <B>create</B> operation in the form: <I>pathName</I> - <B>marker</B> <B>create</B> <B>line</B> ?<I>option</I> <I>value</I>?... There may be many <I>option</I>-<I>value</I> - pairs, each sets a configuration option for the marker. These same - <I>option</I>-<I>value</I> pairs may be used with the marker's <B>configure</B> operation. - - The following options are specific to line markers: - - <B>-dashes</B> <I>dashList</I> - Sets the dash style of the line. <I>DashList</I> is a list of up to 11 - numbers that alternately represent the lengths of the dashes and - gaps on the line. Each number must be between 1 and 255. If - <I>dashList</I> is "", the marker line will be solid. - - <B>-fill</B> <I>color</I> - Sets the background color of the line. This color is used with - striped lines (see the <B>-dashes</B> option). If <I>color</I> is the empty - string, no background color is drawn (the line will be dashed, - not striped). The default background color is "". - - <B>-linewidth</B> <I>pixels</I> - Sets the width of the lines. The default width is 0. - - in the form: <I>pathName</I> <B>marker</B> <B>create</B> <B>polygon</B> ?<I>option</I> <I>value</I>?... There - may be many <I>option</I>-<I>value</I> pairs, each sets a configuration option for - the marker. These same <I>option</I>-<I>value</I> pairs may be used with the <B>marker</B> - <B>configure</B> command to change the marker's configuration. The following - options are supported for polygon markers: - - <B>-dashes</B> <I>dashList</I> - Sets the dash style of the outline of the polygon. <I>DashList</I> is a - list of up to 11 numbers that alternately represent the lengths - of the dashes and gaps on the outline. Each number must be - between 1 and 255. If <I>dashList</I> is "", the outline will be a - solid line. - - <B>-fill</B> <I>color</I> - Sets the fill color of the polygon. If <I>color</I> is "", then the - interior of the polygon is transparent. The default is white. - - <B>-linewidth</B> <I>pixels</I> - Sets the width of the outline of the polygon. If <I>pixels</I> is zero, - no outline is drawn. The default is 0. - - <B>-outline</B> <I>color</I> - Sets the color of the outline of the polygon. If the polygon is - stippled (see the <B>-stipple</B> option), then this represents the - foreground color of the stipple. The default is black. - - <B>-stipple</B> <I>bitmap</I> - Specifies that the polygon should be drawn with a stippled pat- - tern rather than a solid color. <I>Bitmap</I> specifies a bitmap to use - as the stipple pattern. If <I>bitmap</I> is "", then the polygon is - filled with a solid color (if the <B>-fill</B> option is set). The - default is "". - - <B>TEXT</B> <B>MARKERS</B> - A text marker displays a string of characters on one or more lines of - text. Embedded newlines cause line breaks. They may be used to anno- - tate regions of the graph. Text markers are created with the <B>create</B> - operation in the form: <I>pathName</I> <B>marker</B> <B>create</B> <B>text</B> ?<I>option</I> <I>value</I>?... - There may be many <I>option</I>-<I>value</I> pairs, each sets a configuration option - for the text marker. These same <I>option</I>-<I>value</I> pairs may be used with - the marker's <B>configure</B> operation. - - The following options are specific to text markers: - - <B>-anchor</B> <I>anchor</I> - <I>Anchor</I> tells how to position the text relative to the position- - ing point for the text. For example, if <I>anchor</I> is center then - the text is centered on the point; if <I>anchor</I> is n then the text - will be drawn such that the top center point of the rectangular - region occupied by the text will be at the positioning point. - This default is center. - - - <B>-justify</B> <I>justify</I> - Specifies how the text should be justified. This matters only - when the marker contains more than one line of text. <I>Justify</I> - must be left, right, or center. The default is center. - - <B>-outline</B> <I>color</I> - Sets the color of the text. The default value is black. - - <B>-padx</B> <I>pad</I> - Sets the padding to the left and right exteriors of the text. - <I>Pad</I> can be a list of one or two screen distances. If <I>pad</I> has - two elements, the left side of the text is padded by the first - distance and the right side by the second. If <I>pad</I> has just one - distance, both the left and right sides are padded evenly. The - default is 4. - - <B>-pady</B> <I>pad</I> - Sets the padding above and below the text. <I>Pad</I> can be a list of - one or two screen distances. If <I>pad</I> has two elements, the area - above the text is padded by the first distance and the area - below by the second. If <I>pad</I> is just one distance, both the top - and bottom areas are padded evenly. The default is 4. - - <B>-rotate</B> <I>theta</I> - Specifies the number of degrees to rotate the text. <I>Theta</I> is a - real number representing the angle of rotation. The marker is - first rotated along its center and is then drawn according to - its anchor position. The default is 0.0. - - <B>-text</B> <I>text</I> - Specifies the text of the marker. The exact way the text is - displayed may be affected by other options such as <B>-anchor</B> or - <B>-rotate</B>. - - <B>WINDOW</B> <B>MARKERS</B> - A window marker displays a widget at a given position. Window markers - are created with the marker's <B>create</B> operation in the form: <I>pathName</I> - <B>marker</B> <B>create</B> <B>window</B> ?<I>option</I> <I>value</I>?... There may be many <I>option</I>-<I>value</I> - pairs, each sets a configuration option for the marker. These same - <I>option</I>-<I>value</I> pairs may be used with the marker's <B>configure</B> command. - - The following options are specific to window markers: - - <B>-anchor</B> <I>anchor</I> - <I>Anchor</I> tells how to position the widget relative to the posi- - tioning point for the widget. For example, if <I>anchor</I> is center - then the widget is centered on the point; if <I>anchor</I> is n then - the widget will be displayed such that the top center point of - the rectangular region occupied by the widget will be at the - positioning point. This option defaults to center. - - -</PRE> -<H2>GRAPH COMPONENT BINDINGS</H2><PRE> - Specific barchart components, such as elements, markers and legend - entries, can have a command trigger when event occurs in them, much - like canvas items in Tk's canvas widget. Not all event sequences are - valid. The only binding events that may be specified are those related - to the mouse and keyboard (such as <B>Enter</B>, <B>Leave</B>, <B>ButtonPress</B>, <B>Motion</B>, - and <B>KeyPress</B>). - - Only one element or marker can be picked during an event. This means, - that if the mouse is directly over both an element and a marker, only - the uppermost component is selected. This isn't true for legend - entries. Both a legend entry and an element (or marker) binding com- - mands will be invoked if both items are picked. - - It is possible for multiple bindings to match a particular event. This - could occur, for example, if one binding is associated with the element - name and another is associated with one of the element's tags (see the - <B>-bindtags</B> option). When this occurs, all of the matching bindings are - invoked. A binding associated with the element name is invoked first, - followed by one binding for each of the element's bindtags. If there - are multiple matching bindings for a single tag, then only the most - specific binding is invoked. A continue command in a binding script - terminates that script, and a break command terminates that script and - skips any remaining scripts for the event, just as for the bind com- - mand. - - The <B>-bindtags</B> option for these components controls addition tag names - which can be matched. Implicitly elements and markers always have tags - matching their names. Setting the value of the <B>-bindtags</B> option - doesn't change this. - - -</PRE> -<H2>C LANGUAGE API</H2><PRE> - You can manipulate data elements from the C language. There may be - situations where it is too expensive to translate the data values from - ASCII strings. Or you might want to read data in a special file for- - mat. - - Data can manipulated from the C language using BLT vectors. You spec- - ify the X-Y data coordinates of an element as vectors and manipulate - the vector from C. The barchart will be redrawn automatically after - the vectors are updated. - - From Tcl, create the vectors and configure the element to use them. - vector X Y .g element configure line1 -xdata X -ydata Y To set data - points from C, you pass the values as arrays of doubles using the - <B>Blt_ResetVector</B> call. The vector is reset with the new data and at the - next idle point (when Tk re-enters its event loop), the graph will be - redrawn automatically. #include <tcl.h> #include <blt.h> - - register int i; Blt_Vector *xVec, *yVec; double x[50], y[50]; - - /* Get the BLT vectors "X" and "Y" (created above from Tcl) */ if - There may be cases where the bar chart needs to be drawn and updated as - quickly as possible. If drawing speed becomes a big problem, here are - a few tips to speed up displays. - - <B>o</B> Try to minimize the number of data points. The more data points - looked at, the more work the bar chart must do. - - <B>o</B> If your data is generated as floating point values, the time required - to convert the data values to and from ASCII strings can be signifi- - cant, especially when there any many data points. You can avoid the - redundant string-to-decimal conversions using the C API to BLT vec- - tors. - - <B>o</B> Don't stipple or dash the element. Solid bars are much faster. - - <B>o</B> If you update data elements frequently, try turning off the widget's - <B>-bufferelements</B> option. When the bar chart is first displayed, it - draws data elements into an internal pixmap. The pixmap acts as a - cache, so that when the bar chart needs to be redrawn again, and the - data elements or coordinate axes haven't changed, the pixmap is sim- - ply copied to the screen. This is especially useful when you are - using markers to highlight points and regions on the bar chart. But - if the bar chart is updated frequently, changing either the element - data or coordinate axes, the buffering becomes redundant. - - -</PRE> -<H2>LIMITATIONS</H2><PRE> - Auto-scale routines do not use requested min/max limits as boundaries - when the axis is logarithmically scaled. - - The PostScript output generated for polygons with more than 1500 points - may exceed the limits of some printers (See PostScript Language Refer- - ence Manual, page 568). The work-around is to break the polygon into - separate pieces. - - -</PRE> -<H2>KEYWORDS</H2><PRE> - bar chart, widget - - - -BLT BLT_VERSION barchart(n) -</PRE> -<HR> -<ADDRESS> -Man(1) output converted with -<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> -</ADDRESS> -</BODY> -</HTML> |