tkxgraph - Draw a graph using Tcl/Tk 8

tkxgraph -- -f file [-f file] [options]

The tkxgraph program draws a graph using Tcl/Tk 8.0 given data read from data files. It can display up to 64 independent data sets using different colors and/or line styles for each set. It annotates the graph with a title, axis labels, grid lines or tick marks, grid labels, and a legend. There are options to control the appearance of most components of the graph. tkxgraph starts a wish (and console on pc's). A Tcl/Tk extension (tkxg) is used to create a persistent graph data structure.

The input format is similar to graph(1G) but differs slightly. The data consists of a number of data sets. Data sets are separated by a blank line. A new data set is also assumed at the start of each input file. A data set consists of an ordered list of points of the form "{directive} X Y". The directive is either "draw" or "move" and can be omitted. If the directive is "draw", a line will be drawn between the previous point and the current point (if a line graph is chosen). Specifying a "move" directive tells tkxgraph not to draw a line between the points. If the directive is omitted, "draw" is assumed for all points in a data set except the first point where "move" is assumed. The "move" directive is used most often to allow discontinuous data in a data set. The name of a data set can be specified by enclosing the name in double quotes on a line by itself in the body of the data set. The trailing double quote is optional. Overall graphing options for the graph can be specified in data files by writing lines of the form "<option>: <value>". The option names are the same as those used for specifying X resources (see below). The option and value must be separated by at bleast one space. An example input file with three data sets is shown below. Note that set three is not named, set two has discontinuous data, and the title of the graph is specified near the top of the file.

TitleText: Sample Data
0.5 7.8
1.0 6.2
"set one
1.5 8.9

"set two"
-3.4 1.4e-3
-2.0 1.9e-2
move -1.0 2.0e-2
-0.65 2.2e-4

2.2 12.8
2.4 -3.3
2.6 -32.2
2.8 -10.3

After tkxgraph has read the data, it will create a new window to graphically display the data. The interface used to specify the size and location of this window depends on the window manager currently in use. Refer to the reference manual of the window manager for details.

Once the window has been opened, all of the data sets will be displayed graphically (subject to the options explained below) with a legend in the upper right corner of the screen. To zoom in on a portion of the graph, depress a mouse button in the window and sweep out a region. (This feature is supported in C, but not in the current Tcl bindings in tkxg.tcl). tkxgraph will then open a new window looking at just that portion of the graph. tkxgraph also presents three control menus in the upper left corner of each window: File, Execute, and View. Windows are closed by selecting Exit from the File button. The File Print button causes a dialog to appear asking about hardcopy (printout) options. These options are described below (none reimplemented yet). (The
.ISave "postscript"
button uses the tk canvas PostScript generation feature and prompts the user for the name of an output file.)

• Output Device
  Specifies the type of the output device (e.g. "HPGL", "Postscript", etc). An output device is chosen by depressing the mouse inside its name. The default values of other fields will change when you select a different output device.
• Disposition
  Specifies whether the output should go directly to a device or to a file. Again, the default values of other fields will change when you select a different disposition.
• File or Device Name
  If the disposition is "To Device", this field specifies the device name. A device name is the same as the name given for the -P command of lpr(1). If the disposition is "To File", this field specifies the name of the output file.
• Maximum Dimension
  This specifies the maximum size of the plot on the hardcopy device in centimeters. tkxgraph takes in account the aspect ratio of the plot on the screen and will scale the plot so that the longer side of the plot is no more than the value of this parameter. If the device supports it, the plot may also be rotated on the page based on the value of the maximum dimension.
• Include in Document
  If selected, this option causes tkxgraph to produce harcopy output that is suitable for inclusion in other larger documents. As an example, when this option is selected the Postscript output produced by tkxgraph will have a bounding box suitable for use with psfig.
• Title Font Family
  This field specifies the name of a font to use when drawing the graph title. Suitable defaults are initially chosen for any given hardcopy device. The value of this field is hardware specific -- refer to the device reference manual for details.
• Title Font Size
  This field specifies the desired size of the title fonts in points (1/72 of an inch). If the device supports scalable fonts, the font will be scaled to this size.
• Axis Font Family and Axis Font Size
  These fields are like Title Font Family and Title Font Size except they specify values for the font tkxgraph uses to draw axis labels, and legend descriptions.
• Control Buttons
  After specifing the parameters for the plot, the "Ok" button causes tkxgraph to produce a hardcopy. Pressing the "Cancel" button will abort the hardcopy operation. Depressing the About button causes Xgraph to display a window containing the version of the program and an electronic mailing address for the author for comments and suggestions.

tkxgraph accepts a large number of options most of which can be specified either on the command line or in the data files themselves. The .Xdefaults/.Xresources file is no longer supported. A list of these options is given below. The command line option is specified first with its data file name (if any) in parentheses afterward. Additional options or more standard tk-like names for options are also given in parentheses afterward. The format of the option in the data file is "option: value" where the option name is one specified below.

• =WxH+X+Y (Geometry, -geometry WxH+X+Y)
  Specifies the initial size and location of the tkxgraph window. -<digit> <name> (SeriesName<digit>, -serieslegend <digit> <name>) These options specify the data set name for the corresponding data set. The digit should be in the range '0' to '63'. This name will be used in the legend.
• -bar (BarGraph, -bargraph <0,1>)
  Specifies that vertical bars should be drawn from the data points to a base point which can be specified with -brb. Usually, the -nl flag is used with this option. The point itself is located at the center of the bar.
• -bb (BoundBox, -boundingbox <0,1>)
  Draw a bounding box around the data region. This is very useful if you prefer to see tick marks rather than grid lines (see -tk).
• -bd <color> (Border, -bordercolor <color>)
  This specifies the border color of the tkxgraph window. This may not affect the window on some platforms.
• -bg <color> (Background)
  Background color of the tkxgraph window. Ignored by tkxgraph, as the graph is not directly tied to one canvas by the C implementation. The Tcl implementation needs a color switch for controlling the canvas being plotted.
• -brb <base> (BarBase, -barbase <double base>)
  This specifies the base for a bar graph. By default, the base is zero. The value can be any real number.
• -brw <width> (BarWidth, -barwidth <width>)
  This specifies the width of bars in a bar graph. The amount is specified in the user's units. By default, a bar one pixel wide is drawn.
• -bw <size> (BorderSize, -borderwidth <size>)
  Border width (in pixels) of the tkxgraph window.
• -db (Debug)
  Causes tkxgraph to print out the values of all known configuration info from the C perspective, which may not be consistent with Tcl.
• -fg <color> (Foreground, -foreground <color>)
  Foreground color. This color is used to draw all text and the normal grid lines in the window.
• -gw (GridSize, -gridsize <width>)
  Width, in pixels, of normal grid lines.
• -gs (GridStyle. -gridstyle <binary string>)
  Line style pattern of normal grid lines. Tk does not support linestyles very well, and tkxgraph does not use the dash patch to tk.
• -lf <fontname> (LabelFont, -labelfont <fontname>)
  Label font. All axis labels and grid labels are drawn using this font. A font name may be specified in any form acceptable to tk. (e.g."-*-courier-bold-r-normal-*-140-*") or in an abbreviated form: {Times 12 bold}. The default for this parameter is "helvetica 12" or system, depending on the platform.
• -lnx (LogX, -logx <0,1>)
  Specifies a logarithmic X axis. Grid labels represent powers of ten.
• -lny (LogY, -logy <0,1>)
  Specifies a logarithmic Y axis. Grid labels represent powers of ten.
• -lw width (LineWidth, -linewidth <width>)
  Specifies the width of the data lines in pixels. The default is zero. -serieswidth <digit> <width> overrides the -lw option.
• -lx <xl,xh> (XLowLimit,XHighLimit, -xlow <xl>,-xhigh <xh>)
  This option limits the range of the X axis to the specified interval. This (along with -ly) can be used to "zoom in" on a particularly interesting portion of a larger graph.
• -ly <yl,yh> (YLowLimit,YHighLimit, -ylow <yl>,-yhigh <yh>)
  This option limits the range of the Y axis to the specified interval.
• -m (Markers, -seriesmarker <digit> <bitmapname>)
  Mark each data point with a distinctive marker. There are eight distinctive markers used by tkxgraph. These markers are assigned uniquely to each different line style on black and white machines and varies with each color on color machines. The seriesmarker option overrides the default. tkxg_dot and pixel are also defined bitmaps.
• -M (StyleMarkers)
  Similar to -m but markers are assigned uniquely to each eight consecutive data sets (this corresponds to each different line style on color machines). This option, like markers, is fully configurable interactively per series.
• -nl (NoLines, -nolines <0,1>)
  Turn off drawing lines. When used with -m, -M, -p, or -P this can be used to produce scatter plots. When used with -bar, it can be used to produce standard bar graphs.
• -nx (NegateX, -negatex <0,1>)
  Flips the sign of the numbers printed along the X axis. Does not affect the data, however.
• -ny (NegateY, -negatey <0,1>)
  Flips the sign of the numbers printed along the Y axis. Does not affect the data, however.
• -p (PixelMarkers)
  Marks each data point with a small marker (pixel sized). This is usually used with the -nl option for scatter plots.
• -P (LargePixels)
  Similar to -p but marks each pixel with a large dot.
• -rv (ReverseVideo)
  Reverse video. On black and white displays, this will invert the foreground and background colors. The behaviour on color displays is undefined. The behavior of rv under tkxgraph is very ill-defined. wysiwyg.
• -t <string> (TitleText, -title <string>)
  Title of the plot. This string is centered at the top of the graph.
• -tf <fontname> (TitleFont, -titlefont <fontname>)
  Title font. This is the name of the font to use for the graph title. A font name may be specified exactly (e.g. "9x15" or "-*-courier-bold-r-normal-*-140-*") or in any tk abbreviated form. The default for this parameter is "helvetica 18" or "system".
• -tk (Ticks, -ticks <0,1>)
  This option causes tkxgraph to draw tick marks rather than full grid lines. The -bb option is also useful when viewing graphs with tick marks only.
• -x <unitname> (XUnitText, -xtitle <unitname>)
  This is the unit name for the X axis. Its default is "X".
• -y <unitname> (YUnitText, -ytitle <unitname>)
  This is the unit name for the Y axis. Its default is "Y".
• -zg <color> (ZeroColor, -zerocolor <color>)
  This is the color used to draw the zero grid line.
• -zw <width> (ZeroWidth, -zerowidth <width>)
  This is the width of the zero grid line in pixels.

Some options can only be specified in the X defaults file or in the data files. These options are described below:

• <digit>.Color (-seriescolor <digit> <color>)
  Specifies the color for a data set. Eight independent colors can be specified as N.Color, 64 using -seriescolor. Thus, the digit should be between '0' and '7' ('63'). If there are more than eight data sets, the colors will repeat but with a new line style (see below). -seriescolor overrides N.Color.
• <digit>.Style (-seriesstipple <digit> <bitmapname>)
  Specifies the line style for a data set. A string of ones and zeros specifies the pattern used for the line style. Eight independent line styles can be specified. Thus, the digit should be between '0' and '7' (63). If there are more than eight data sets, these styles will be reused. On color workstations, one line style is used for each of eight colors. Thus, 64 unique data sets can be displayed. -seriesstipple overrides N.Style, and linestyles are morphed crudely to bitmaps when specified with N.style, with potential loss of horizontal or near horizontal lines.
• Device
  The default output form presented in the hardcopy dialog (i.e. "Postscript", "HPGL", etc). tkxgraph silently ignores this option.
• Disposition
  The default setting of whether output goes directly to a device or to a file. This must be one of the strings "To File" or "To Device". tkxgraph silently ignores this option.
• FileOrDev
  The default file name or device string in the hardcopy dialog. tkxgraph silently ignores this option.
• ZeroWidth (-zerowidth <width>)
  Width, in pixels, of the zero grid line.
• ZeroStyle (-zerostipple <bitmapname>)
  Line style pattern of the zero grid line.

David Harrison University of California and Ben Allan Carnegie Mellon University

Now accepts input files with one value per line (X-coordinate is no longer required; if none is given integers from 0-n will be used).

New options -nx, -ny allow changing the signs on axes, which is useful for plots with origin desired at the upper left.

The interface is now interactively fully configurable and the rendering engine is user modifiable. The restriction of graph that axes once defined as logarithmic are always logarithmic is no longer imposed. The complete set of configuration parameters is accessible through the View menu. The bulk of the rendering engine is implemented in Tcl procedures so that associations between the xgraph data object and a canvas can be manipulated and the full power of canvas tags may be exploited.

A call to tkxg returns the name of an xgraph created from the input files specified to the command. The xgraph name returned is a Tcl command that can respond to the messages: destroy, configure, cget, plot, and resource. The first such return is always xgraph0, and the trailing digit increases with successive calls. tkxgraph aims to be maximally compatible with the old xgraph, and this causes some inconsistencies in the handling of the old Xresources and the new tk-like switches.

• xgraph0 cget <option>
  Returns the value for any of the tk-like configuration parameters.
• xgraph0 configure <option>
  Returns the complete list of tk-like configurations. Not completely tk class compatible, however.
• xgraph0 configure <option>
  Returns the tuple for any of the tk-like configuration parameters except the -series(marker/stipple/width/color/legend).
• xgraph0 destroy
  Destroys the associated C data structures and undefines the command xgraph0.
• xgraph0 plot
  Invokes the tkxgraph rendering engine, which generates calls to Tkxg_cseg, Tkxg_seg, Tkxg_dot, and Tkxg_text. These are Tcl functions defined in tkxg.tcl which can be customized to other applications. The rendering engine emits, along with graphic specification data, class numbers which indicate which series, axis, or other major plot component the graphic elements are grouped with.
• xgraph0 resource <name>
  Returns the record for Xresource like data with name. If name is not in the database, code may exit.
• xgraph0 resource
  Dumps the complete contents, including internal variables, of the xgraph database to the stdout file.

- Based on Tcl/Tk 8.0b1, which is buggy.
- Zooming in on graphs doesn't work yet.
- There is no way to produce hardcopy without running tkxgraph interactively.
- There is no way to produce hardcopy except saving to a file.
- The maintainer is ballan@cs.cmu.edu.

Last Modified: 03:22pm EDT, September 30, 1997