_________________________________________________________________
NAME
blt_graph - Create and manipulate graph widgets
SYNOPSIS
blt_graph pathName ?options?
STANDARD OPTIONS
background cursor foreground
borderWidth font relief
See the ``options'' manual entry for details on the standard
options.
WIDGET-SPECIFIC OPTIONS
bottomMargin leftMargin title
bufferElements plotBackground topMargin
halo plotBorderWidth width
height plotRelief
invertxy rightMargin
_________________________________________________________________
DESCRIPTION
The blt_graph command creates a new window (given by the
pathName argument) and makes it into an graph widget.
Additional options, described above, may be specified on the
command line or in the option database to configure aspects
of the graph such as its colors and font. The blt_graph
command returns its pathName argument. At the time this
command is invoked, there must not exist a window named
pathName, but pathName's parent must exist.
The blt_graph widget plots two-variable data in a window. It
has of several components; coordinate axes, crosshairs, a
legend, and a collection of elements and tags.
COORDINATE AXES
The graph widget has four axes, two standard (x and y) and
two alternate (x2 and y2). Graph elements and tags are
mapped onto one x-axis and y-axis (by default, they are
mapped onto the standard axes).
Each axis consists of the axis line and major and minor
ticks placed at set intervals. At major ticks, labels (text
strings) representing the coordinate value of the tick are
drawn. By default, the tick labels are simply numeric
strings. However, a Tcl procedure can be supplied to
individually format each tick label.
The scale of the axis is determined its minimum and maximum
limits. By default, each axis is auto-scaled using the data
limits. However either limit can be set to manually scale
the graph.
CROSSHAIRS
Crosshairs are a set of two lines (vertical and horizontal)
which intersect on the graph. They are implemented using
XOR drawing primitives, so they do not require the graph to
be redrawn when they are moved or redisplayed.
ELEMENTS
A graph element is a set of data points and configuration
options which determine how the data is displayed. Elements
are created by the element create widget command. The
configuration options may be specified as the element is
created or later by the element configure widget command.
There is an internal display list of element names which
controls the drawing order of the elements. By default,
elements are appended to the display list as they are
created. The element display list can be managed by the
element show command.
LEGEND
The legend consists of a list of entries, where each entry
is an element symbol and label. By default, the legend is
located in the right margin of the graph. However, the
legend may appear anywhere in the plotting area of the graph
by specifying its window coordinates.
TAGS
Tags are simple drawing procedures used to annotate or
highlight areas of the graph. A tag may be either a text
string, bitmap, line, window, or polygon. A tag may be
associated with a particular element, so that the tag is
displayed only if the element is displayed. Tags are the
first items drawn when the graph is displayed, so that
elements, symbols, legend, and axes always appear in front
of them.
Tags differ from elements in that they do not affect the
auto-scaling of coordinate axes. Furthermore, tags can have
elastic coordinates (specified by -Inf and Inf respectively)
which translate into the axis minimum or maximum limit. For
example, to place a tag so it always remains in the lower
left corner of the plot, use the coordinates -Inf,-Inf.
WIDGET COMMANDS
The blt_graph command creates a new Tcl command whose name
is pathName. This command may be used to invoke various
operations on the widget. It has the general form:
pathName option ?arg arg ...?
9 Option and the args determine the exact behavior of the
widgets:
pathName configure ?options...?
Queries or modifies the configuration options of the
widget. Valids options are described in
pathName crosshairs configure ?options...?
Queries or modifies the configuration options of the
crosshairs. This command is similar to the configure
command, except that it applies to the options of the
crosshairs, whereas configure applies to the options
for the graph as a whole. See for a description of
valid options.
pathName crosshairs toggle
Toggles the current state of the crosshairs, turning
them on or off. This command returns an empty string.
pathName element activate name ?index...?
Specifies which data points of element name are to be
drawn using active foreground and background colors.
Name is the name of the element and index is a number
representing the index of the data point. If no indices
are present then all data points become active. This
command returns the empty string.
pathName element append name coords
Appends pairs of x,y data points to element name.
coords is a list of numeric expressions (x,y graph
coordinates) representing data points. It returns the
empty string.
pathName element closest winX winY ?name...?
Finds the data point closest to the window coordinates
winX and winY in the element name. It returns a list
containing the name of the closest element, the index
of its closest point, and the graph x,y coordinates of
the point. If no data point within a threshold
distance can be found (see the -halo option), then the
empty list is returned. Name is the name of an
element, which must be mapped. If no elements are
specified, then all mapped elements are searched.
pathName element configure name ?options...?
This command is similar to the configure command,
except that it applies to the options of an individual
element, whereas configure applies to the options for
the graph as a whole. Options may have any of the
values accepted by the element create widget command.
See for a description of valid options.
Creates a new element name in the graph. Element names
must be unique, so name can not already exist in the
graph. If additional arguments are present, they
specify any of the element options (see ).
pathName element deactivate name ?name...?
Deactivate the named elements. The elements will be |
redrawn using their normal foreground and background |
colors. Name is the name of the element. This command |
returns the empty string.
pathName element delete ?name ...?
Deletes the element name from the graph. Returns the
empty string.
pathName element names
Returns a list of all elements. This differs from
element show in that it returns the names of all
elements, not just those in the element display list.
pathName element show ?names?
Queries or resets the element display list. The element
display list defines which elements are drawn and in
what order. Names is a list of the elements to be
displayed. If there is no names argument, the list of
elements currently being displayed is returned.
pathName invtransform winX winY
Performs an inverse coordinate transformation, mapping
x,y window coordinates to graph coordinates (using the
standard x and y axes). Returns a list of containing
the x and y graph coordinates.
pathName legend activate name...
Specifies that the legend entries of the named elements |
should be drawn with the active legend background and |
foreground colors. The entries may also be drawn with |
a different relief (using the -activerelief and |
-activeborderwidth options). Name is the name of an |
element in the graph.
pathName legend configure ?options...?
This command is similar to the configure command,
except that it applies to the options for the legend,
whereas configure applies to the options for the graph
as a whole. See for a description of valid options.
pathName legend deactivate name...
Specifies that the legend enties of the named elements |
should be drawn with the legend background and |
foreground colors. Name is the name of an element in |
pathName legend get string
Returns the name of the graph element at the current |
screen position in the legend. String must be in the |
form "@x,y", where x and y are the window coordinates. |
If the given screen coordinates do not lie over a |
legend entry, the empty string is returned.
pathName postscript ?fileName? ?options...?
Generates PostScript commands to print the graph. If no
fileName argument is present, the PostScript output is
returned. Otherwise, fileName is created and will
contain the PostScript output. In this case the empty
string is returned. If any option-value pairs are
present, they set configuration options controlling how
the PostScript is generated. See for a description of
valid options.
pathName psconfigure ?options...?
Queries or modifies the options of the postscript
command. See for a description of valid options.
pathName tag after tagId ?tagId?
Reorders the tag display list placing the first tag
specified after the second. If no second tagId
argument is specified, the tag is placed at the end of
the list. This command can be used to control how tags
are displayed since tags are drawn in the order of this
display list. The empty string is returned.
pathName tag before tagId ?tagId?
Reorders the tag display list placing the first tag
specified before the second. If no second tagId
argument is specified, the tag is placed at the
beginning of the list. This command can be used to
control how tags are displayed since tags are drawn in
the order of this display list. The empty string is
returned.
pathName tag configure tagId ?options...?
Queries or modifies the configuration options of the
particular tag. See for a description of valid
options.
pathName tag coords tagId ?coords?
Queries or resets the coordinates of the tag designated
by tagId. If coords is present, it is a list of
coordinate pairs representing the points of the tag.
This list is used to re-position the tag. If the
coords argument is not present, the current list of
coordinates for tagId is returned.
Creates a tag of the selected type. Type may be either
text, line, bitmap, polygon, or window. coords is a
list of coordinate pairs of points used to position the
tag. See for a description of valid options. This
command returns a unique tag identifier, which is used
as the tagId argument in other tag-related commands.
pathName tag delete tagId ?tagId..?
Deletes each of the specified tags. This command
returns the empty string.
pathName tag ids ?pattern?
Returns a list of IDs of tags created. If pattern is
supplied, only those tags whose IDs matching it will be
returned.
pathName tag type tagId
Returns the type of the tag given by tagId, such as
Line or Text. If tagId is not a valid a tag identifier,
the empty string is returned.
pathName transform x y
Transforms the graph coordinates into window
coordinates, by mapping the x and y values onto the
standard axes (x and y). Returns a list containing the
x and y window coordinates. Please note that graph
coordinates far outside of the axis range are not
guarenteed to be accurate.
pathName xaxis configure ?options...?
pathName yaxis configure ?options...?
pathName x2axis configure ?options...?
pathName y2axis configure ?options...?
Queries or modifies the configuration options of the
coordinate axis. See for a description of valid
options.
pathName xaxis limits
pathName yaxis limits
pathName x2axis limits
pathName y2axis limits
Returns a list of two graph coordinates representing
the minimum and maximum limits of the x-axis. The
format of the list returned is min max.
WIDGET OPTIONS
The following widget options are valid for the configure
command.
pathName configure ?option? ?value option value ...?
9 The configure command queries or modifies the configuration
options of the widget. If no option is specified, returns a
list describing all of the available options for pathName
(see Tk_ConfigureInfo for information on the format of this
list). If option is specified with no value, then the
command returns a list describing the one named option (this
list will be identical to the corresponding sublist of the
value returned if no option is specified). If one or more
option-value pairs are specified, then the command modifies
the given widget option(s) to have the given value(s); in
this case the command returns the empty string.
-bottommargin pixels
Specifies the size of the margin from the x-coordinate
axis to the bottom of the window. The x-axis title is
displayed in this margin. Pixels may be specified in
any of the forms described in Tk_GetPixels. If pixels
is less than one pixel, the the margin size is selected
automatically.
-bufferelements boolean
Specifies whether to use a pixmap to cache the display |
of elements. This is especially useful when there are |
many data points or the graph is redrawn frequently. |
Boolean is true by default.
-halo pixels
Specifies a threshold distance when searching for the
closest data point (see the element closest command).
Only data points within this distance are considered in
the search. If this option isn't specified, it
defaults to 0.5i.
-height pixels
Specifies a desired window height that the graph widget
should request from its geometry manager. The default
height is 400.
-invertxy boolean
Specifies that placement of the x and y axes should be |
inverted. If boolean is true, the x-axis is exchanged |
with the y-axis. By default boolean is false.
-leftmargin pixels
Sets the size of the margin from the left edge of the
window to the the y-coordinate axis. The y-axis title
-plotbackground color
Sets the background color of the plotting area.
-plotborderwidth pixels
Sets the width of the 3-D border to draw around the
outside of the plotting area (if such border is being
drawn; the plotrelief option determines this). By
default is the plot border width is 2.
-plotrelief string
Specifies the 3-D effect desired for the plotting area.
String must be in a form accepted by Tk_GetRelief. It
indicates 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. By
default, the plot relief is sunken.
-rightmargin pixels
Sets the size of marging from the plotting area to the
right edge of the window. By default, the legend is
displayed in this margin. If Ipixels is than 1, the
margin size is selected automatically.
-title string
Specifies the title of the graph. If string is the
empty string (the default), no title is displayed.
-topmargin pixels
Sets the size of the marging the top edge of the window
to the plotting area. The graph title is displayed in
this margin. If pixels is less than 1, the margin size
is selected automatically.
-width pixels
Specifies a desired window width that the graph widget
should request from its geometry manager. The default
width is 400.
AXIS OPTIONS
The following options are valid for the xaxis configure,
yaxis configure, x2axis configure, and the y2axis configure
commands.
pathName xaxis configure ?options...?
pathName yaxis configure ?options...?
pathName y2axis configure ?options...?
9 In addition, axis configuration options may be initialized
by the option command. The name fields in the blt_graph
option database are prefixed by x, y, x2, or y2 while the
class fields are prefixed by Axis. The following example
sets the color of all axes to blue and the x-axis scale to
logarithmic.
option add *Blt_graph.AxisColor blue
option add *Blt_graph.xLogscale true
9
-color color
Sets the color of the axis and its labels. This option
defaults to black.
-command prefix
Specifies a Tcl command to be invoked when formatting
the axis labels. Prefix is typically just the name of
a Tcl procedure, but the string may also contain extra
arguments for the procedure. When invoked, two
arguments (the path name of the graph widget and the
numeric value of the axis label) are appended to the
end of the command. The procedure value should be a
string representing the formatted label. If the value
is the empty string or if prefix is the empty string,
the default axis label is displayed. Please note that
this procedure is invoked during the display of the
graph. Resetting graph configurations within this
procedure can cause unexpected results.
-descending boolean
Specifies whether the values along the axis are |
increasing or decreasing. If boolean is true, the axis |
values will decrease. By default, the axis values |
increase.
-font fontName
Specifies the font for axis labels. If fontName isn't
specified then it defaults to *-Courier-Bold-R-Normal-
*-100-*.
-linewidth pixels
Sets the line width of the axis and its ticks. The
default line width is 0.
-logscale boolean
Sets the scale of the coordinate axis (either
logarithmically or linearly). If boolean is true, the
axis will be displayed in logarithmic scale. Boolean
-loose boolean
Indicates that when auto-scaling the axis, the axis
range should fit loosely around the data points at the
outer tick intervals. Otherwise the axis range fits
tightly at the limits of the data displayed. By
default, the range is tight.
-mapped boolean
Specifies if the axis should be displayed. By default,
the standard axes are displayed (x and y), but not the
alternate (x2 and y2).
-max value
Sets the maximum limit of the axis. Data points
exceeding this limit are clipped at this value. If
value is the empty string (the default), the axis is
auto-scaled whereby the maximum limit is determined
from the data points of the displayed elements.
-min value
Sets the minimum limit of the axis. Data points less
than this limit are clipped at this value. If value is
the empty string (the default), the axis is auto-scaled
whereby the minimum limit is determined from the data
points of the displayed elements.
-rotate theta
Specifies the rotation of the axis labels. Theta is a
real number representing the angle of rotation in
degrees. The default rotation is 0.0 degrees.
-showticks boolean
Indicates if axis ticks should be displayed. If boolean
is true (the default), ticks are displayed.
-stepsize value
Sets the step size between major axis ticks. Value
must be greater than zero and less than the axis range,
or the requested step size is ignored and the step size
is automatically calculated based upon the element data
points.
-subticks number
Sets the number of minor axis ticks to be displayed.
By default, the number of minor ticks is 5. If number
is zero, no subticks will be displayed.
-ticklength pixels
Sets the length of the ticks and subticks (subticks are |
-title string
Sets the title of the axis. If string is the empty
string, no axis title will be displayed.
CROSSHAIRS OPTIONS
The following options are valid for the crosshair configure
command.
pathName crosshairs configure ?options...?
9 In addition, crosshairs configuration options may be
initialized by the option command. The name fields in the
blt_graph option database are prefixed by by xhairs and
classfields are prefixed by Xhairs. The following example
sets the line width of the crosshairs to 2.
option add *Blt_graph.xhairsLinewidth 2
9
-color color
Sets the color of the crosshairs. If this option isn't
specified, then it defaults to black.
-dashes dashes
Sets the dash style of the crosshairs. dashes is the
number of alternatingly displayed pixels. If dashes is
0 (the default), the crosshairs will be drawn as a
solid line.
-linewidth pixels
Set the line width of crosshairs. The default line
width is 0.
-mapped boolean
Specifies if the crosshairs should be displayed. By
default, the crosshairs are not displayed.
-position string
Specifies the position of the crosshairs. String must
be in the format "@x,y", where x and y are window
coordinates.
ELEMENT OPTIONS
The following options are valid for the element create and
element configure commands. Name is the name of the element
to be configured.
Page 11 (printed 3/15/96)
initialized by the option command. The name fields in the
blt_graph option database are prefixed by elem. The
following example sets the symbol type of all elements to
line and the line width of all elements to 2.
option add *Blt_graph.elemSymbol line
option add *Blt_graph.LineWidth 2
9
-activebackground color
Like the -background option, but specifies the
background color to use when drawing data points which
are active (see the element activate command).
-activeforeground color
Like the -foreground option, but specifies the
foreground color to use when drawing data points which
are active (see the element activate command).
-activelinewidth pixels
Sets the width of the lines drawn when the element is |
active. If pixels is zero and the symbol is not line, |
no line will be drawn when the element is active. The |
default line width is 1.
-background color
If the symbol type is line, then color specifies the
background color for dashed lines. For non-line
symbols, color specifies the fill color for the symbol
(the foreground color is the outline). If this option
isn't specified then it defaults to white.
-dashes dashes
Sets the dash style for lines. dashes is the number of
alternatingly colored (foreground/background) pixels.
If dashes is 0 (the default), the line is drawn in a
solid fashion. This option only has effect only if the
symbol type is line or if the line width is greater
than zero.
-data values
Specifies the graph coordinates of the the data points
to be plotted. Values is a list of valid numeric
expressions. It this option isn't specified, it
defaults to the empty string.
-foreground color
Sets the foreground color of the element. If this
Page 12 (printed 3/15/96)
empty string, no legend entry will be displayed for the
element. By default, the label is the name of the
element.
-linewidth pixels
Sets the width of the lines drawn. For non-line
symbols, if pixels is greater than zero, a line is
drawn between the symbols. The default line width is
0.
-mapx type
Specifies which x-axis to map the element's x-
coordinates onto. Type must be either x, x2, or both.
The default axis is x.
-mapy type
Specifies which y-axis to map the element's y-
coordinates onto. Type must be either y, y2, or both.
The default axis is y.
-noretrace boolean
If boolean is true, data points where x-coordinate
values are not monotonically increasing (where the
current x-coordinate value is less than the previous)
indicate the start of a new line. In this case, no
connecting line segment will be drawn from the last to
the current point. If boolean is false, all points
will be connected by line segments, regardless of their
order. The default value is false.
-scale value
Specifies a scale factor for the size of the element's
symbol. The default scale factor is 1.0.
-symbol type
Type specifies the type of symbol to use for plotting
data points. Valid symbol types are line, square,
circle, diamond, plus, cross, splus, and scross. The
default symbol type is line.
-trace string
Indicates if to trace (draw lines) between data points |
where values are increasing or decreasing. String must |
be either increasing, decreasing, or both. For example, |
if string is increasing, data points where x-coordinate |
values are not monotonically increasing (where the |
current x-coordinate value is less than the previous) |
Page 13 (printed 3/15/96)
-xdata values
Specifies the x-coordinates of the data points to be
plotted. Values is a list of valid numeric expressions.
It this option isn't specified, it defaults to the
empty string.
-ydata values
Specifies the y-coordinates of the data points to be
plotted. Values is a valid list of numeric expressions.
It this option isn't specified, it defaults to the
empty string.
LEGEND OPTIONS
The following options are valid for the legend configure
command.
pathName legend configure ?options...?
9 In addition, legend configuration options may be initialized
by the option command. The name fields in the blt_graph
option database are prefixed by legend. The following
example initializes the legend foreground color to blue in
the option database.
option add *Blt_graph.legendForeground blue
9
-activebackground color
Sets the active background color of the legend. All |
legend entries marked as active (see legend activate |
command) are drawn with this background color.
-activeborderwidth pixels
Sets the width of the 3-D border to draw around the |
outside of the each active legend entry (if such border |
is being drawn; the -activerelief option determines |
this). By default is the active border width is 2.
-activeforeground color
Sets the active foreground color of the legend. All |
legend entries marked as active (see legend activate |
command) are drawn with this foreground color.
-activerelief string
Specifies the 3-D effect desired for active legend |
entries. String must be in a form accepted by |
Page 14 (printed 3/15/96)
-anchor anchorPos
Tells how to position the legend relative to the
positioning point for the legend; anchorPos may have
any of the forms accepted by Tk_GetAnchor. For
example, if anchorPos is center then the legend is
centered on the point; if anchorPos is n then the
legend will be drawn such that the top center point of
the rectangular region occupied by the legend will be
at the positioning point. This option defaults to
center.
-background color
Sets the background color of the legend. color must be |
a valid color, it can not be the empty string.
-borderwidth pixels
Sets the width of the 3-D border to draw around the
outside of the legend (if such border is being drawn;
the relief option determines this). By default is the
legend border width is 2.
-font fontName
FontName specifies a font to use when drawing the
labels of each element into the legend. If this option
isn't specified then it defaults to *-Helvetica-Bold-
R-Normal-*-120-*.
-foreground color
Sets the foreground color of the element labels in the
legend. If this option isn't specified, then it
defaults to black.
-ipadx pixels
Sets the internal padding to the width of the legend.
Padding will be added to both the left and right and
between the elements symbol and label. By default is
the legend border width is 2.
-ipady pixels
Sets the internal padding to the height of the legend.
Padding will be added to both the top and bottom and
between the elements labels. By default is the legend
border width is 2.
-mapped boolean
Page 15 (printed 3/15/96)
-pady pixels
Specifies extra padding on the top and bottom of the
legend. The default is 0.
-position string
Sets the positioning point of the legend in window
coordinates. This option in conjunction with the
-anchor option, determines where the legend is
positioned. The format of string is "@x,y", where x and
y are the window coordinate values. If string is the
empty string (the default), the legend will be
displayed in the right margin (which is automatically
extended to accommodate the legend).
-relief string
Specifies the 3-D effect desired for the legend.
String must be in a form accepted by Tk_GetRelief. It
indicates how the interior of the legend should appear
relative to the graph; for example, raised means the
legend should appear to protrude from the graph,
relative to the surface of the graph. By default, the
legend relief is sunken.
TAG OPTIONS
The following options are valid for the tag create and tag
configure commands. Tagid is the identifier returned by the
tag create command.
pathName tag create type ?coords? ?options...?
pathName tag configure tagId ?options...?
9 Tag configuration options may be initialized by the option
command. The name fields in the blt_graph option database
are prefixed by bmTag, textTag, lineTag, polyTag, or winTag
with respect to the tag type. Class fields are prefixed by
Tag. The following example sets the background color of all
tags to blue and the foreground color of all text tags to
white.
option add *Blt_graph.TagBackground blue
option add *Blt_graph.textTagForeground white
9 The description of tag options is broken into subsections
for each tag type.
Page 16 (printed 3/15/96)
expressions representing the graph coordinates of a point
used to position the text on the graph.
After the coordinate list there may be any number of
option-value pairs, each of which sets one of the
configuration options for the tag. These same option-value
pairs may be used in the tag configure command to change the
tag's configuration. The following options are supported
for text tags:
-anchor anchorPos
AnchorPos tells how to position the text relative to
the positioning point for the text; it may have any of
the forms accepted by Tk_GetAnchor. For example, if
anchorPos is center then the text is centered on the
point; if anchorPos 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 option defaults to center.
-background color
Sets the background color of the text string. If color
is the empty string, the background will be
transparent. If this option isn't specified then it
defaults to white.
-font fontName
Specifies the text font. If this option isn't
specified, it defaults *-Helvetica-Bold-R-Normal-*-
120-*.
-foreground color
Sets the foreground color of the text. If this option
isn't specified then it defaults to black.
-element name
Associates the tag with the element name. If name is
not the empty string (the default), the tag is
displayed only if name exists and is currently being
displayed (see element show).
-mapx type
Specifies which x-axis to map the tag's x-coordinates
onto. Type must be either x, x2, or both. The default
axis is x.
9 Page 17 (printed 3/15/96)
The tag is first rotated along its center and is then
displayed according to its anchor position. The default
rotation is 0.0 degrees.
-text string
Sets the text string. The exact way in which the text
string is displayed may be affected by other options
such as -anchor or -rotate. This option defaults to
the empty string.
-xoffset pixels
Specifies a x-coordinate offset (in window coordinates)
from the specified position.
-yoffset pixels
Specifies a y-coordinate offset (in window coordinates)
from the specified position.
LINE TAGS
A line tag displays one or more connected line segments on
the graph. Line tags are created with widget commands in
the form:
pathName tag create line ?coords? ?options...?
9 The argument coords specifies a list of numeric expressions
representing the graph coordinate pairs of the points
connecting the line.
After the coords there may be any number of option-value
pairs, each of which sets one of the configuration options
for the tag. These same option-value pairs may be used in
the tag configure command to change the tag's configuration.
The following options are supported for line tags:
-background color
Sets the background color of the line. The option is
affects the line color only when the -stipple option is
set. If this option isn't specified then it defaults to
white.
-dashes dashes
Sets the dash style of the line. Dashes is the number
of alternatingly displayed pixels. If dashes is 0 (the
9 Page 18 (printed 3/15/96)
Sets the foreground color. The default foreground
color is black.
-linewidth pixels
Sets the width of the lines. The default width is 0.
-mapx type
Specifies which x-axis to map the tag's x-coordinates
onto. Type must be either x, x2, or both. The default
axis is x.
-mapy type
Specifies which y-axis to map the tag's y-coordinates
onto. Type must be either y, y2, or both. The default
axis is y.
-stipple bitmap
Indicates that the line should be drawn with a stippled
pattern rather than solid; bitmap specifies the stipple
pattern to use, may be in any of the forms accepted by
Tk_GetBitmap. If bitmap is the empty string (the
default) then the line is drawn in a solid fashion.
-xoffset pixels
Specifies an offset in the x-coordinate direction (in
window coordinates) from the specified position. The
default offset is 0.
-yoffset pixels
Specifies an offset in the y-coordinate direction (in
window coordinates) from the specified position. The
default offset ifs 0.
BITMAP TAGS
A bitmap tag displays a bitmap on the graph. Bitmap tags
are created with widget commands in the form:
pathName tag create bitmap ?coords? ?options...?
9 The argument coords specifies a list containing the graph
coordinates of a point used to position the bitmap on the
display. After the coordinate list there may be any number
of option-value pairs, each of which sets one of the
9 Page 19 (printed 3/15/96)
point; if anchorPos is n then the bitmap will be drawn
such that the top center point of the rectangular
region occupied by the bitmap will be at the
positioning point. This option defaults to center.
-background color
Sets the background color of the bitmap. If color is
the empty string, the background color will be
transparent. The default background color is white.
-foreground color
Sets the foreground color of the bitmap. The default
foreground color is black.
-bitmap bitmap
Specifies the bitmap to be displayed. Bitmap may have
any of the forms accepted by Tk_GetBitmap. If bitmap
is the empty string (the default), the tag will not be
displayed.
-element name
Associates the tag with the element name. If name is
not the empty string (the default), the tag is
displayed only if name exists and is being plotted (see
element show).
-mapx type
Specifies which x-axis to map the tag's x-coordinates
onto. Type must be either x, x2, or both. The default
axis is x.
-mapy type
Specifies which y-axis to map the tag's y-coordinates
onto. Type must be either y, y2, or both. The default
axis is y.
-rotate theta
Sets the rotation of the bitmap. Theta is a real
number representing the angle of rotation in degrees.
The tag is first rotated and then placed according to
its anchor position. The default rotation is 0.0.
Page 20 (printed 3/15/96)
POLYGON TAGS
A polygon tag displays a closed region described as two or
more connected line segments on the graph. Polygon tags are
created with the widget command:
pathName tag create polygon ?coords? ?options...?
9 The argument coords specifies a list of numeric expressions
representing graph coordinates which describe the closed
polygon. It is assumed the first and last points are
connected.
After the coordinate list there may be any number of
option-value pairs, each of which sets one of the
configuration options for the tag. These same option-value
pairs may be used in the tag configure command to change the
tag's configuration. The following options are supported
for polygon tags:
-background color
Sets the background color of the polygon. The default
background color is white.
-dashes dashes
Sets the dash style of the outline around the polygon. |
Dashes is the number of alternatingly displayed pixels. |
If dashes is 0 (the default), the outline will be drawn |
as a solid line.
-element name
Associates the tag with the element name. If name is
not the empty string (the default), the tag is
displayed only if name exists and is currently being
displayed (see element show).
-foreground color
Sets the foreground color of the polygon. The default
foreground color is black.
-linewidth pixels
Sets the width of the outline of the polygon. If pixels |
is zero, no outline is drawn. The default width is 0.
9 Page 21 (printed 3/15/96)
blt_graph(1) UNIX System V blt_graph(1)
Indicates that the polygon should be drawn with a
stippled pattern rather than a solid color; bitmap
specifies the stipple pattern to use, in any of the
forms accepted by Tk_GetBitmap. If bitmap is the empty
string (the default), then the polygon is filled with a
solid (foreground) color.
-xoffset pixels
Specifies an x-coordinate offset (in window
coordinates) from the specified position. The default
offset is 0.
-yoffset pixels
Specifies a y-coordinate offset (in window coordinates)
from the specified position. The default is offset 0.
WINDOW TAGS
A window tag displays a particular window at a given
position on the graph. Window tags are created with the
widget command:
pathName tag create window ?coords? ?options...?
9 The argument coords specifies a list containing the graph
coordinates of a point used to position the window on the
display After coords, there may be any number of option-
value pairs, each of which sets one of the configuration
options for the tag. These same option-value pairs may be
used in the tag configure command to change the tag's
configuration. The following options are supported for
window tags:
-anchor anchorPos
AnchorPos tells how to position the window relative to
the positioning point for the window; it may have any
of the forms accepted by Tk_GetAnchor. For example, if
anchorPos is center then the window is centered on the
point; if anchorPos is n then the window will be
displayed such that the top center point of the
rectangular region occupied by the window will be at
the positioning point. This option defaults to center.
9 Page 22 (printed 3/15/96)
blt_graph(1) UNIX System V blt_graph(1)
-mapx type
Specifies which x-axis to map the tag's x-coordinates
onto. Type must be either x, x2, or both. The default
axis is x.
-mapy type
Specifies which y-axis to map the tag's y-coordinates
onto. Type must be either y, y2, or both. The default
axis is y.
-width pixels
Specifies the width to assign to the tag's window. If
this option isn't specified, or if it is specified as
the empty string, then the window is given whatever
width it requests internally.
-window pathName
Specifies the window to be managed by the graph. The
window specified by pathName must be a child of the
blt_graph widget.
-xoffset pixels
Specifies an x-coordinate offset (in window
coordinates) from the specified position. The default
offset is 0.
-yoffset pixels
Specifies a y-coordinate offset (in window coordinates)
from the specified position. The default offset is 0.
POSTSCRIPT OPTIONS
The following options are valid for configuring PostScript
output using either the postscript or the psconfigure
command.
pathName postscript ?fileName? options...?
pathName psconfigure ?options...?
99
Page 23 (printed 3/15/96)
blt_graph(1) UNIX System V blt_graph(1)
-colormode mode
Specifies how to output color information. Mode 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.
-fontmap varName
VarName must be the name of a global array variable
that specifies a font mapping from the X font name to
PostScript. Each element of varName must consist of a
Tcl list with one or two elements, which are the name
and point size of a PostScript font. When outputting
PostScript commands for a particular font, Tk checks to
see if varName contains an element with the same name
as the specified font. If there is such an element,
then the font information contained in that element is
used in the PostScript output. (If the point size is
omitted from the list, the point size of the X font is
used). Otherwise the X font is examined in an attempt
to guess what PostScript font to use. This works only
for fonts whose foundry property is Adobe (such as
Times, Helvetica, Courier, etc.). If all of this fails
then the font defaults to Helvetica-Bold.
-landscape boolean
If boolean is true, this specifies the printed area is
to be rotated 90 degrees. In non-rotated output the x
axis of the printed area runs along the short dimension
of the page (``portrait'' orientation); in rotated
output the x axis runs along the long dimension of the
page (``landscape'' orientation). Defaults to false.
-pageanchor anchor
Specifies which point of the printed area should be
appear over the positioning point on the page (which is
given by the -pagex and -pagey options). For example,
-pageanchor n means that the top center of the printed
Page 24 (printed 3/15/96)
blt_graph(1) UNIX System V blt_graph(1)
-pagewidth size
Specifies that the width of the graph drawn in
PostScript. The graph is not uniformly scaled since
this also scales the fonts. Size may be any value
accepted by Tk_GetPixels. The resulting pixel value is
then converted to postscript printer points. This
means that a width 6.5i will be properly converted to
6.5 inches. This options defaults to the width of the
graph window.
-pagex position
Specifies the x-coordinate of the page positioning
point. This (with the -pageanchor option) indicates
where the graph is placed on the PostScript page.
Position may be any value accepted by Tk_GetPixels. The
resulting pixel value is then converted to postscript
printer points. The default is 1i.
-pagey position
Specifies the y-coordinate of the page positioning
point. This (with the -pageanchor option) indicates
where the graph is placed on the PostScript page.
Position may be any value accepted by Tk_GetPixels. The
resulting pixel value is then converted to postscript
printer points. The default is 1i.
SETTING DATA FROM C
The data points of any element can be reset from a C routine
using the convenience function Blt_GraphElement. This can
be useful in situations where it is too expensive to
translate the data values from string representations.
Another possible use could be to read in special data file
formats.
int Blt_GraphElement(interp, pathName, elemName, numValues, valueArr)
Tcl_Interp *interp; /* Interpreter of the graph widget */
char *pathName; /* Path name of the graph widget */
char *elemName; /* Name of the element to reset */
int numValues; /* Number of values in array */
Page 25 (printed 3/15/96)
blt_graph(1) UNIX System V blt_graph(1)
>result" will contain an error message.
BINDINGS
There are no default bindings.
BUGS
Auto-scale routines do not use requested min/max limits as
boundaries when the axis is logarithmically scaled.
The needs to be a special mapping for undefined log scale
values (>= 0.0). Possibly set up a "red zone" of undefined
values which divides the positive and negative values.
The PostScript output generated for polygons with more than
1500 points may exceed the limits of some printers (See
PostScript Language Reference Manual, page 568). The work-
around is to break the polygon into separate pieces.
KEYWORDS
graph, widget
Page 26 (printed 3/15/96)