#toc
Table of Contents
#toc0
Name
eps -  Encapsulated PostScript canvas item.
#toc1
Synopsis
canvas
create eps
x y
?
option value
?...
#toc2
Description
The
eps
canvas item lets you place
encapulated PostScript (EPS) on a canvas, controlling its size and placement.
The EPS item is displayed either as a solid rectangle or a preview image.
The preview image is designated in one of two ways: 1) the EPS file contains
an ASCII hexidecimal preview, or 2) a Tk photo image.  When the canvas generates
PostScript output, the EPS will be inserted with the proper translation
and scaling to match that of the EPS item. So can use the canvas widget
as a page layout tool.
#toc3
Example
Let's say you have for PostScript files of
four graphs which you want to tile two-by-two on a single page.  Maybe you'd
like to annotate the graphs by putting a caption at the bottom of each
graph.
Normally, you would have to resort to an external tool or write your
own PostScript program.  The
eps
canvas item lets you do this through Tk's
canvas widget.  An
eps
item displays an image (or rectangle) representing
the encapsulated PostScript file. It also scales and translates the EPS
file when the canvas is printed.
#toc4
Syntax
canvas
create eps
x y
?
option value
?...
The
eps
item creates a new canvas item.
Canvas
is the name of a
canvas
widget.
You must supply the X-Y coordinate of the new eps item.  How the coordinate
is exactly interpretered is  controlled by the
-anchor
option (see below).
Additional options may be specified on the command line to configure aspects
of the eps item such as its color, stipple, and font.  The following
option
and
value
pairs are valid.
-anchor
anchor
Tells how to position the EPS item
relative to its X-Y coordinate. The default is
center
.
-background
color
Sets
the background color of the EPS rectangle.
-borderwidth
pixels
Sets the width
of the 3-D border around the outside edge of the item.  The
-relief
option
determines if the border is to be drawn.  The default is
0
.
-file
fileName
Specifies the name of the EPS file.  The first line of an EPS file must
start with "%!PS" and contain a "EPS" version specification.  The other
requirement is that there be a "%%BoundingBox:" entry which contains four
integers representing the lower-left and upper-right coordinates of the area
bounding the EPS. The default is
""
.
-font
fontName
Specifies the font of
the title. The default is
*-Helvetica-Bold-R-Normal-*-18-180-*
.
-foreground
color
Specifies the foreground color of the EPS rectangle.  The option matters
only when the
-stipple
option is set. The default is
white
.
-height
pixels
Specifies the height EPS item.  If
pixels
is
0
, then the height is determined
from the PostScript "BoundingBox:" entry in the EPS file. The default is
0
.
-image
photo
Specifies the name of a Tk photo image to be displayed as
in the item as a preview image.  This option overrides any preview specification
found in the EPS file. The default is
""
.
-justify
justify
Specifies how the
title should be justified.  This matters only when the title contains more
than one line of text.
Justify
must be
left
,
right
, or
center
.  The default
is
center
.
-relief
relief
Specifies the 3-D effect for the EPS item.
Relief
specifies how the item should appear relative to canvas;  for example,
raised
means the item should appear to  protrude.  The default is
flat
.
-shadowcolor
color
Specifies the color of the drop shadow used for the title.  The option
with the
-shadowoffset
option control how the title's drop shadow appears.
The default is
grey
.
-shadowoffset
pixels
Specifies the offset of the drop
shadow from the title's text. If
pixels
is
0
, no shadow will be seen. The
default is
0
.
-showimage
boolean
Indicates whether to display the image preview
(if one exists),  or a simple rectangle.   The default is
yes
.
-stipple
bitmap
Specifies a bitmap to used to stipple the rectangle representing the EPS
item.  The default is
""
.
-title
string
Sets the title of the EPS item.  If
string
is
""
, then the title specified by the PostScript "Title:" entry
is used.  You can set the string a single space to display no title.  The
default is
""
.
-titleanchor
anchor
Tells how to position the title within
EPS item. The default is
n
.
-titlecolor
color
Specifies the color of the title.
The default is
white
.
-titlerotate
degrees
Sets the rotation of the title.
Degrees
is a real number representing the angle of rotation.   The title
is first rotated in space and then placed according to  the
-titleanchor
position.  The default rotation is
0.0
.
-width
pixels
Specifies the width EPS
item.  If
pixels
is
0
, then the width is determined from the PostScript
"BoundingBox:" entry in the EPS file. The default is
0
.
5i
.
#toc5
Example
The
graph
command creates a new graph.
# Create a new graph.  Plotting area is black.
graph .g -plotbackground black
A new Tcl command
.g
is also created.  This command can be used to query
and modify the graph.  For example, to change the title of the graph to
"My Plot", you use the new command and the graph's
configure
operation.
# Change the title.
.g configure -title "My Plot"
A graph has several components. To access a particular component you use
the component's name. For example, to add data elements, you use the new
command and the
element
component.
# Create a new element named "line1"
.g element create line1 \
-xdata { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 } \
-ydata { 26.18 50.46 72.85 93.31 111.86 128.47 143.14
155.85 166.60 175.38 }
The element's X and 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 graph.
vector xVec yVec
xVec set { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 }
yVec set { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85
166.60 175.38 }
.g element create line1 -xdata xVec -ydata yVec
The advantage of using vectors is that when you modify one, the graph is
automatically redrawn to display the new values.
# Change the X-Y coordinates of the first point.
set xVec(0) 0.18
set yVec(0) 25.18
An element named
line1
is now created in
.g
.  By default, the element's label
in the legend will be also
line1
. You can change the label, or specify no
legend entry, again using the element's
configure
operation.
# Don't display "line1" in the legend.
.g element configure line1 -label ""
You can configure more than just the element's label.  An element has many
attributes such as symbol type and size, dashed or solid lines, colors,
line width, etc.
.g element configure line1 -symbol square -color red \
-dashes { 2 4 2 } -linewidth 2 -pixels 2c
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
-mapx
and
-mapy
options.
# Map "line1" on the alternate Y-axis "y2".
.g element configure line1 -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
axis
component.
# Y-axis is log scale.
.g 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
-min
and
-max
configuration options.
.g axis configure x -min 1.0 -max 1.5
.g axis configure y -min 12.0 -max 55.15
To zoom interactively, you link the axis
configure
operations with some
user interaction (such as pressing the mouse button), using the
bind
command.
To convert between screen and graph coordinates, use the
invtransform
operation.
# Click the button to set a new minimum
bind .g <ButtonPress-1> {
%W axis configure x -min [%W axis invtransform x %x]
%W axis configure x -min [%W axis invtransform x %y]
}
By default, the limits of the axis are determined from data values. To reset
back to the default limits, set the
-min
and
-max
options to the empty value.
# Reset the axes to autoscale again.
.g axis configure x -min {} -max {}
.g axis configure y -min {} -max {}
By default, the legend is drawn in the right margin.  You can change this
or any legend configuration options using the
legend
component.
# Configure the legend font, color, and relief
.g legend configure -position left -relief raised \
-font fixed -fg blue
To prevent the legend from being displayed, turn on the
-hide
option.
# Don't display the legend.
.g legend configure -hide yes
The
graph
widget has simple drawing procedures called markers. They can
be used to highlight or annotate data in the graph. The types of markers
available are bitmaps, images, polygons, lines, or windows. Markers can
be used, for example, to mark or brush points.  In this example, is a text
marker that labels the data first point.  Markers are created using the
marker
component.
# Create a label for the first data point of "line1".
.g marker create text -name first_marker -coords { 0.2 26.18 } \
-text "start" -anchor se -xoffset -10 -yoffset -10
This creates a text marker named
first_marker
.  It will display the text
"start" near the coordinates of the first data point.  The
-anchor
,
-xoffset
,
and
-yoffset
options are used to display the marker above and to the left
of the data point, so that the data point isn't covered by the marker.  By
default, markers are drawn last, on top of data.  You can change this with
the
-under
option.
# Draw the label before elements are drawn.
.g marker configure first_marker -under yes
You can add cross hairs or grid lines using the
crosshairs
and
grid
components.
# Display both cross hairs and grid lines.
.g crosshairs configure -hide no -color red
.g grid configure -hide no -dashes { 2 2 }
Finally, to get hardcopy of the graph, use the
postscript
component.
# Print the graph into file "file.ps"
.g postscript output file.ps -maxpect yes -decorations no
This generates a file
file.ps
containing the encapsulated PostScript of
the graph.  The option
-maxpect
says to scale the plot to the size of the
page.  Turning off the
-decorations
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).
#toc6
Graph Operations
pathName
axis
operation
?
arg
?...
See the
AXIS COMPONENTS
section.
pathName
bar
elemName
?
option value
?...
Creates a new barchart element
elemName
.  It's an error if an element
elemName
already exists.   See the manual for
barchart
for details about what
option
and
value
pairs are valid.
pathName
cget
option
Returns the current value
of the configuration option given by
option
.
Option
may be any option described
below for the
configure
operation.
pathName
configure
?
option value
?...
Queries
or modifies the configuration options of the graph.  If
option
isn't specified,
a list describing the current options for
pathName
is returned.  If
option
is specified, but not
value
, then a list describing
option
is returned.
If one or more
option
and
value
pairs are specified, then for each pair,
the option
option
is set to
value
. The following options are valid.
-background
color
Sets the background color. This includes the margins and legend, but
not the plotting area.
-borderwidth
pixels
Sets the width of the 3-D border
around the outside edge of the widget.  The
-relief
option determines if
the border is to be drawn.  The default is
2
.
-bottommargin
pixels
Specifies
the size of the margin below the X-coordinate axis.  If
pixels
is
0
, the
size of the margin is selected automatically. The default is
0
.
-bufferelements
boolean
Indicates whether an internal pixmap to buffer the display of data
elements should be used.  If
boolean
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
SPEED TIPS
section. The default is
1
.
-cursor
cursor
Specifies the widget's cursor.  The default cursor is
crosshair
.
-font
fontName
Specifies the font of the graph title. The default is
*-Helvetica-Bold-R-Normal-*-18-180-*
.
-halo
pixels
Specifies a maximum distance to consider when searching for
the closest data point (see the element's
closest
operation below). Data
points further than
pixels
away are ignored.  The default is
0.5i
.
-height
pixels
Specifies the requested height of widget.  The default is
4i
.
-invertxy
boolean
Indicates whether the placement X-axis and Y-axis should be inverted.
If
boolean
is true, the X and Y axes are swapped.  The default is
0
.
-justify
justify
Specifies how the title should be justified.  This matters only
when the title contains more than one line of text.
Justify
must be
left
,
right
, or
center
.  The default is
center
.
-leftmargin
pixels
Sets the size
of the margin from the left edge of the window to  the Y-coordinate axis.
If
pixels
is
0
, the size is calculated automatically.  The default is
0
.
-plotbackground
color
Specifies the background color of the plotting area.
The default is
white
.
-plotborderwidth
pixels
Sets the width of the 3-D border
around the plotting area.  The
-plotrelief
option determines if a border
is drawn.  The default is
2
.
-plotpadx
pad
Sets the amount of padding to be
added to the left and right sides of the plotting area.
Pad
can be a list
of one or two screen distances.  If
pad
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
pad
is just one distance, both the left and right
sides are padded evenly.  The default is
8
.
-plotpady
pad
Sets the amount
of padding to be added to the top and bottom of the plotting area.
Pad
can be a list of one or two screen distances.  If
pad
has two elements,
the top of the plotting area is padded by the first distance and the bottom
by the second.  If
pad
is just one distance, both the top and bottom are
padded evenly.  The default is
8
.
-plotrelief
relief
Specifies the 3-D effect
for the plotting area.
Relief
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
.
-relief
relief
Specifies the 3-D effect
for the graph widget.
Relief
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
.
-rightmargin
pixels
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
pixels
is than 1, the margin size
is selected automatically.
-takefocus
focus
Provides information used when
moving the focus from window to window via keyboard traversal (e.g., Tab
and Shift-Tab).  If
focus
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
""
.
-tile
image
Specifies a tiled background for the widget.  If
image
isn't
""
, the background is tiled using
image
. Otherwise, the normal background
color is drawn (see the
-background
option).
Image
must be an image created
using the Tk
image
command.  The default is
""
.
-title
text
Sets the title
to
text
. If
text
is
""
, no title will be displayed.
-topmargin
pixels
Specifies
the size of the margin above the x2 axis.  If
pixels
is
0
, the margin size
is calculated automatically.
-width
pixels
Specifies the requested width
of the widget.  The default is
5i
.
pathName
crosshairs
operation
?
arg
?
See
the
CROSSHAIRS COMPONENT
section.
pathName
element
operation
?
arg
?...
See
the
ELEMENT COMPONENTS
section.
pathName
extents
item
Reports the size
of a particular items in the graph.
Item
must be either
leftmargin
,
rightmargin
,
topmargin
,
bottommargin
,
plotwidth
, or
plotheight
.
pathName
grid
operation
?
arg
?...
See the
GRID COMPONENT
section.
pathName
invtransform
winX winY
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 y graph coordinates.
pathName
inside
x y
Returns
1
is the designated screen coordinate (
x
and
y
) is inside the plotting
area and
0
otherwise.
pathName
legend
operation
?
arg
?...
See the
LEGEND COMPONENT
section.
pathName
line
operation arg
...
The operation is the same as
element
.
pathName
marker
operation
?
arg
?...
See the
MARKER COMPONENTS
section.
pathName
postscript
operation
?
arg
?...
See the
POSTSCRIPT COMPONENT
section.
pathName
snap
photoName
Takes a snapshot of the graph and stores the contents in
the photo image
photoName
.
PhotoName
is the name of a Tk photo image that
must already exist.
pathName
transform
x y
Performs a coordinate transformation,
mapping graph coordinates to window coordinates, using the standard X-axis
and Y-axis. Returns a list containing the X-Y screen coordinates.
pathName
xaxis
operation
?
arg
?...
pathName
x2axis
operation
?
arg
?...
pathName
yaxis
operation
?
arg
?...
pathName
y2axis
operation
?
arg
?...
See the
AXIS COMPONENTS
section.
#toc7
Graph Components
A graph is composed of several components: coordinate axes,
data elements, legend, grid, cross hairs, postscript, and annotation markers.
Instead of one big set of configuration options and operations, the graph
is partitioned, where each component has its own configuration options
and operations that specifically control that aspect or part of the graph.
#toc8
Axis Components
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 plotted.  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 "tempAxis"
.g axis create tempAxis
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 tempAxis data to this axis.
.g element create "e1" -xdata $x -ydata $y -mapy tempAxis
While you can create many axes, only four 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 bottom 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 components:
xaxis
,
yaxis
,
x2axis
, and
y2axis
.
The
use
operation designates the axis to be drawn in the corresponding
margin:
xaxis
in the bottom,
yaxis
in the left,
x2axis
in the top, and
y2axis
in the right.
# Display the axis tempAxis in the left margin.
.g yaxis use tempAxis
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.
pathName
axis
cget
axisName
option
Returns the current value of the option given by
option
for
axisName
.
Option
may be any option described below for the axis
configure
operation.
pathName
axis
configure
axisName
?
axisName
?... ?
option value
?...
Queries or modifies
the configuration options of
axisName
. Several axes can be changed.  If
option
isn't specified, a list describing all the current options for
axisName
is returned.  If
option
is specified, but not
value
, then a list describing
option
is returned.  If one or more
option
and
value
pairs are specified,
then for each pair, the axis option
option
is set to
value
.  The following
options are valid for axes.
-color
color
Sets the color of the axis and tick
labels. The default is
black
.
-command
prefix
Specifies a Tcl command to be
invoked when formatting the axis tick labels.
Prefix
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
prefix
to
""
.  The default
is
""
.
Please note that this procedure is invoked while the graph is redrawn.
You may query configuration options.  But do not them, because this can
have unexpected results.
-descending
boolean
Indicates whether the values
along the axis are monotonically increasing or decreasing.  If
boolean
is
true, the axis values will be decreasing.  The default is
0
.
-hide
boolean
Indicates whether the axis is displayed.
-justify
justify
Specifies how
the axis title should be justified.  This matters only when the axis title
contains more than one line of text.
Justify
must be
left
,
right
, or
center
.
The default is
center
.
-limits
formatStr
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.
FormatStr
is
a list of one or two format descriptions.  If one description is supplied,
both the minimum and maximum limits are formatted in the same way.  If two,
the first designates the format for the minimum limit, the second for the
maximum.  If
""
is given as either description, then  the that limit will
not be displayed.  The default is
""
.
-linewidth
pixels
Sets the width of
the axis and tick lines.  The default is
1
pixel.
-logscale
boolean
Indicates
whether the scale of the axis is logarithmic or linear.  If
boolean
is true,
the axis is logarithmic.  The default scale is linear.
-loose
boolean
Indicates
whether the limits of the axis should fit the data points tightly, at the
outermost data points, or loosely, at the outer tick intervals. This is
relevant only when the axis limit is automatically calculated. If
boolean
is true, the axis range is "loose". The default is
0
.
-majorticks
majorList
Specifies where to display major axis ticks.  You can use this option to
display ticks at non-uniform intervals.
MajorList
is a list of axis coordinates
designating the location of major ticks.  No minor ticks are drawn.  If
majorList
is
""
,  major ticks will be automatically computed. The default is
""
.
-max
value
Sets the maximum limit of
axisName
.  Any data point greater  than
value
is not displayed.  If
value
is
""
,  the maximum limit is calculated
using the largest data value. The default is
""
.
-min
value
Sets the minimum
limit of
axisName
. Any data point less than
value
is not displayed.  If
value
is
""
, the minimum limit is calculated using the smallest data value.
The default is
""
.
-minorticks
minorList
Specifies where to display minor
axis ticks.  You can use this option to display minor ticks at non-uniform
intervals.
MinorList
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
-majortick
option is also set.  If
minorList
is
""
, minor ticks will be automatically
computed. The default is
""
.
-rotate
theta
Specifies the how many degrees
to rotate the axis tick labels.
Theta
is a real value representing the number
of degrees to rotate the tick labels.  The default is
0.0
degrees.
-showticks
boolean
Indicates whether axis ticks should be drawn. If
boolean
is true,
ticks are drawn.  If false, only the axis line is drawn. The default is
1
.
-stepsize
value
Specifies the interval between major axis ticks.  If
value
isn't a valid interval (must be less than the axis range),  the request
is ignored and the step size is automatically calculated.
-subdivisions
number
Indicates how many minor axis ticks are to be drawn.  For example, if
number
is two, only one minor tick is drawn.  If
number
is one, no minor ticks
are displayed.  The default is
2
.
-tickfont
fontName
Specifies the font for
axis tick labels. The default is
*-Courier-Bold-R-Normal-*-100-*
.
-ticklength
pixels
Sets the length of major and minor ticks (minor ticks are half the length
of major ticks). If
pixels
is less than zero, the axis will be inverted
with ticks drawn pointing towards the plot.  The default is
0.1i
.
-title
text
Sets the title of the axis. If
text
is
""
, no axis title will be displayed.
-titlecolor
color
Sets the color of the axis title. The default is
black
.
-titlefont
fontName
Specifies the font for axis title. The default is
*-Helvetica-Bold-R-Normal-*-14-140-*
.
Axis configuration options may be also be set by the
option
command.  The
resource class is
Axis
.  The resource names are the names of the axes (such
as
x
or
x2
).
option add *Graph.Axis.Color  blue
option add *Graph.x.LogScale  true
option add *Graph.x2.LogScale false
pathName
axis
create
axisName
?
option value
?...
Creates a new axis by the
name
axisName
.  No axis by the same name can already exist.
Option
and
value
are described  in above in the axis
configure
operation.
pathName
axis
delete
?
axisName
?...
Deletes the named axes. An axis is not really deleted until it
is not longer in use, so it's safe to delete axes mapped to elements.
pathName
axis invtransform
axisName value
Performs the inverse transformation, changing
the screen coordinate
value
to a graph coordinate, mapping the value mapped
to
axisName
.  Returns the graph coordinate.
pathName
axis limits
axisName
Returns a list of the minimum and maximum limits for
axisName
.  The order
of the list is
min max
.
pathName
axis names
?
pattern
?...
Returns a list of
axes matching zero or more patterns.  If no
pattern
argument is give, the
names of all axes are returned.
pathName
axis transform
axisName value
Transforms
the coordinate
value
to a screen coordinate by mapping the it to
axisName
.
Returns the transformed screen coordinate.
Only four axes can be displayed
simultaneously.  By default, they are
x
,
y
,
x2
, and
y2
.  You can swap in
a different axis with
use
operation of the special axis components:
xaxis
,
x2axis
,
yaxis
, and
y2axis
.
.g create axis temp
.g create axis time
...
.g xaxis use temp
.g yaxis use time
Only the axes specified for use are displayed on the screen.
The
xaxis
,
x2axis
,
yaxis
, and
y2axis
components operate on an axis location rather
than a specific axis like the more general
axis
component does.  The
xaxis
component manages the X-axis located in the bottom margin (whatever axis
that happens to be).  Likewise,
yaxis
uses the Y-axis in the left margin,
x2axis
the top X-axis, and
y2axis
the right Y-axis.
They implicitly control
the axis that is currently using to that location.  By default,
xaxis
uses
the
x
axis,
yaxis
uses
y
,
x2axis
uses
x2
, and
y2axis
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
axis
component.  The
axis
argument must be
xaxis
,
x2axis
,
yaxis
, or
y2axis
.
pathName
axis
cget
option
pathName
axis
configure
?
option value
?...
pathName
axis
invtransform
value
pathName
axis
limits
pathName
axis
transform
value
pathName
axis
use
?
axisName
?
Designates the axis
axisName
is to be displayed at this location.
AxisName
can not be already in use at another location.   This command returns the
name of the axis currently using this location.
#toc9
Crosshairs Component
Cross
hairs consist of two intersecting lines (one vertical and one horizontal)
drawn completely across the plotting area.  They are used to position the
mouse in relation to the coordinate axes.  Cross hairs differ from line
markers in that they are implemented using XOR drawing primitives. This
means that they can be quickly drawn and erased without redrawing the entire
graph.
The following operations are available for cross hairs:
pathName
crosshairs cget
option
Returns the current value of the cross hairs configuration
option given by
option
.
Option
may be any option described below for the
cross hairs
configure
operation.
pathName
crosshairs configure
?
option value
?...
Queries or modifies the configuration options of the cross hairs.  If
option
isn't specified, a list describing all the current options for the
cross hairs is returned.  If
option
is specified, but not
value
, then a
list describing
option
is returned. If one or more
option
and
value
pairs
are specified, then for each pair, the cross hairs option
option
is set
to
value
. The following options are available for cross hairs.
-color
color
Sets the color of the cross hairs.  The default is
black
.
-dashes
dashList
Sets the dash style of the cross hairs.
DashList
is a list of up to 11 numbers
that alternately represent the lengths of the dashes and gaps on the cross
hair lines.  Each number must be between 1 and 255.  If
dashList
is
""
, the
cross hairs will be solid lines.
-hide
boolean
Indicates whether cross hairs
are drawn. If
boolean
is true, cross hairs are not drawn.  The default is
yes
.
-linewidth
pixels
Set the width of the cross hair lines.  The default
is
1
.
-position
pos
Specifies the screen position where the cross hairs
intersect.
Pos
must be in the form "
@x,y
", where
x
and
y
are the window
coordinates of the intersection.
Cross hairs configuration options may be
also be set by the
option
command.  The resource name and class are
crosshairs
and
Crosshairs
respectively.
option add *Graph.Crosshairs.LineWidth 2
option add *Graph.Crosshairs.Color     red
pathName
crosshairs off
Turns off the cross hairs.
pathName
crosshairs
on
Turns on the display of the cross hairs.
pathName
crosshairs toggle
Toggles the current state of the cross hairs, alternately mapping and unmapping
the cross hairs.
#toc10
Element Components
A data element represents a set of data.
It contains x and y vectors containing the coordinates of the data points.
Elements can be displayed with a symbol at each data point and lines connecting
the points.  Elements also control the appearance of the data, such as the
symbol type, line width, color etc.
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.
pathName
element activate
elemName
?
index
?...
Specifies the data points of element
elemName
to be drawn using
active foreground and background colors.
ElemName
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.
pathName
element cget
elemName
option
Returns the current value of the element configuration option given
by
option
.
Option
may be any of the options described below for the element
configure
operation.
pathName
element closest
x y
varName
?
option value
?...
?
elemName
?...
Finds the data point closest to the window coordinates
x
and
y
in the element
elemName
.
ElemName
is the name of an element, that must
not be hidden.  If no elements are specified, then all visible elements
are searched.  It returns via the array variable
varName
the name of the
closest element, the index of its closest point, and the graph coordinates
of the point. Returns
0
, if no data point within the threshold distance
can be found, otherwise
1
is returned.  The following
option
-
value
pairs
are available.
-halo
pixels
Specifies a threshold distance where selected
data points are ignored.
Pixels
is a valid screen distance, such as
2
or
1.2i
. If this option isn't specified, then it defaults to the value of the
graph's
-halo
option.
-interpolate
boolean
Indicates that both the data points
and interpolated points along the line segment formed should be considered.
If
boolean
is true, the closest line segment will be selected instead
of the closest point. If this option isn't specified,
boolean
defaults  to
0
.
pathName
element configure
elemName
?
elemName
... ?
option value
?...
Queries
or modifies the configuration options for elements.  Several elements can
be modified at the same time. If
option
isn't specified, a list describing
all the current options for
elemName
is returned.  If
option
is specified,
but not
value
, then a list describing the option
option
is returned.  If
one or more
option
and
value
pairs are specified, then for each pair, the
element option
option
is set to
value
.  The following options are valid
for elements.
-activepen
penName
Specifies pen to use to draw active element.
If
penName
is
""
, no active elements will be drawn.  The default is
activeLine
.
-color
color
Sets the color of the traces connecting the data points.
-dashes
dashList
Sets the dash style of element line.
DashList
is a list
of up to 11 numbers that alternately represent the lengths of the dashes
and gaps on the element line.  Each number must be between 1 and 255.  If
dashList
is
""
, the lines will be solid.
-data
coordList
Specifies the X-Y
coordinates of the data.
CoordList
is a list of numeric expressions representing
the X-Y coordinate pairs of each data point.
-fill
color
Sets the interior
color of symbols.  If
color
is
""
, then the interior of the symbol is transparent.
If
color
is
defcolor
, then the color will be the same as the
-color
option.
The default is
defcolor
.
-hide
boolean
Indicates whether the element is
displayed.  The default is
no
.
-label
text
Sets the element's label in the
legend.  If
text
is
""
, the element will have no entry in the legend. The
default label is the element's name.
-linewidth
pixels
Sets the width of
the connecting lines between data points.  If
pixels
is
0
, no connecting
lines will be drawn between symbols.  The default is
0
.
-mapx
xAxis
Selects
the X-axis to map the element's X-coordinates onto.
XAxis
must be the name
of an axis.  The default is
x
.
-mapy
yAxis
Selects the Y-axis to map the element's
Y-coordinates onto.
YAxis
must be the name of an axis. The default is
y
.
-offdash
color
Sets the color of the stripes when traces are dashed (see the
-dashes
option).  If
color
is
""
, then the "off" pixels will represent gaps instead
of stripes.  If
color
is
defcolor
, then the color will be the same as the
-color
option.  The default is
defcolor
.
-outline
color
Sets the color or
the outline around each symbol.  If
color
is
""
, then no outline is drawn.
If
color
is
defcolor
, then the color will be the same as the
-color
option.
The default is
defcolor
.
-outlinewidth
pixels
Sets the width of the outline
bordering each symbol.  If
pixels
is
0
, no outline will be drawn. The default
is
1
.
-pixels
pixels
Sets the size of symbols.  If
pixels
is
0
, no symbols
will be drawn.  The default is
0.125i
.
-scalesymbols
boolean
If
boolean
is
true, the size of the symbols drawn for
elemName
will change with scale
of the X-axis and Y-axis. At the time this option is set, the current ranges
of the axes are saved as the normalized scales (i.e scale factor is 1.0)
and the element is drawn at its designated size (see the
-pixels
option).
As the scale of the axes change, the symbol will be scaled according to
the smaller of the X-axis and Y-axis scales.  If
boolean
is false, the element's
symbols are drawn at the designated size, regardless of axis scales.  The
default is
0
.
-smooth
smooth
Specifies how connecting line segments are
drawn between data points.
Smooth
can be either
linear
,
step
,
natural
, or
quadratic
.  If
smooth
is
linear
, a single line segment is drawn, connecting
both data points. When
smooth
is
step
, two line segments are drawn. The first
is a horizontal line segment that steps the next X-coordinate.  The second
is a vertical line, moving to the next Y-coordinate.  Both
natural
and
quadratic
generate multiple segments between data points.  If
natural
, the segments
are generated using a cubic spline.  If
quadratic
, a quadratic spline is
used.  The default is
linear
.
-styles
styleList
Specifies what pen to use
based on the range of weights given.
StyleList
is a list of style specifications.
Each style specification, in turn, is a list consisting of a pen name,
and optionally a minimum and maximum range.  Data points whose weight (see
the
-weight
option) falls in this range, are drawn with this pen.  If no
range is specified it defaults to the index of the pen in the list.  Note
that this affects only symbol attributes. Line attributes, such as line
width, dashes, etc. are ignored.
-symbol
symbol
Specifies the symbol for
data points.
Symbol
can be either
square
,
circle
,
diamond
,
plus
,
cross
,
splus
,
scross
,
triangle
,
""
(where no symbol is drawn), or a bitmap.  Bitmaps
are specified as "
source
?
mask
?", where
source
is the name of the bitmap,
and
mask
is the bitmap's optional mask.  The default is
circle
.
-trace
direction
Indicates whether connecting lines between data points (whose X-coordinate
values are either increasing or decreasing) are drawn.
Direction
must
be
increasing
,
decreasing
, or
both
.  For example, if
direction
is
increasing
,
connecting lines will be drawn only between those data points where X-coordinate
values are monotonically increasing.  If
direction
is
both
, connecting lines
will be draw between all data points.  The default is
both
.
-weights
wVec
Specifies the weights of the individual data points.  This,  with the list
pen styles (see the
-styles
option), controls how data points are drawn.
WVec
is the name of a BLT vector or a list of numeric expressions representing
the weights for each data point.
-xdata
xVec
Specifies the X-coordinates
of the data.
XVec
is the name of a BLT vector or a list of numeric expressions.
-ydata
yVec
Specifies the Y-coordinates of the data.
YVec
is the name of
a BLT vector or a list of numeric expressions.
Element configuration options
may also be set by the
option
command.  The resource class is
Element
. The
resource name is the name of the element.
option add *Graph.Element.symbol line
option add *Graph.e1.symbol line
pathName
element create
elemName
?
option value
?...
Creates a new element
elemName
.
It's an error is an element
elemName
already exists.  If additional arguments
are present, they specify options valid for  the element
configure
operation.
pathName
element deactivate
elemName
?
elemName
?...
Deactivates all the elements
matching
pattern
. Elements whose names match any of the patterns given are
redrawn using their normal colors.
pathName
element delete
?
elemName
?...
Deletes
all the named elements.  The graph is automatically redrawn.
pathName
element
exists
elemName
Returns
1
if an element
elemName
currently exists and
0
otherwise.
pathName
element names
?
pattern
?...
Returns the elements matching
one or more pattern.  If no
pattern
is given, the names of all elements
is returned.
pathName
element show
?
nameList
?
Queries or modifies the
element display list.  The element display list designates the elements
drawn and in what order.
NameList
is a list of elements to be displayed
in the order they are named.  If there is no
nameList
argument, the current
display list is returned.
pathName
element type
elemName
Returns the type
of
elemName
.  If the element is a bar element, the commands returns the
string
"bar"
, otherwise it returns
"line"
.
#toc11
Grid Component
Grid lines extend
from the major and minor ticks of each axis horizontally or vertically
across the plotting area.  The following operations are available for grid
lines.
pathName
grid cget
option
Returns the current value of the grid line
configuration option given by
option
.
Option
may be any option described
below for the grid
configure
operation.
pathName
grid configure
?
option
value
?...
Queries or modifies the configuration options for grid lines.  If
option
isn't specified, a list describing all the current grid options for
pathName
is returned.  If
option
is specified, but not
value
, then a list
describing
option
is returned.  If one or more
option
and
value
pairs are
specified, then for each pair, the grid line option
option
is set to
value
.
The following options are valid for grid lines.
-color
color
Sets the color
of the grid lines.  The default is
black
.
-dashes
dashList
Sets the dash style
of the grid lines.
DashList
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
dashList
is
""
, the grid will be solid lines.
-hide
boolean
Indicates whether the grid should be drawn. If
boolean
is true,
grid lines are not shown. The default is
yes
.
-linewidth
pixels
Sets the width
of grid lines.  The default width is
1
.
-mapx
xAxis
Specifies the X-axis to
display grid lines.
XAxis
must be the name of an axis.  The default is
x
.
-mapy
yAxis
Specifies the Y-axis to display grid lines.
YAxis
must be the
name of an axis. The default is
y
.
-minor
boolean
Indicates whether the grid
lines should be drawn for minor ticks.  If
boolean
is true, the lines will
appear at minor tick intervals.  The default is
1
.
#toc12
Speed Tips
There may be
cases where the graph needs to be drawn and updated as quickly as possible.
If drawing speed becomes a big problem, here are a few tips to speed up
displays.
·
Try to minimize the number of data points.  The more data points
the looked at, the more work the graph must do.
·
If your data is generated
as floating point values, the time required to convert the data values
to and from ASCII strings can be significant, especially when there any
many data points.  You can avoid the redundant string-to-decimal conversions
using the C API to BLT vectors.
·
Data elements without symbols are drawn
faster than with symbols. Set the data element's
-symbol
option to
none
.  If
you need to draw symbols, try using the simple symbols such as
splus
and
scross
.
·
Don't stipple or dash the element.  Solid lines are much faster.
·
If
you update data elements frequently, try turning off the widget's
-bufferelements
option.  When the graph is first displayed, it draws data elements into
an internal pixmap.  The pixmap acts as a cache, so that when the graph
needs to be redrawn again, and the data elements or coordinate axes haven't
changed, the pixmap is simply copied to the screen.  This is especially
useful when you are using markers to highlight points and regions on the
graph.  But if the graph is updated frequently, changing either the element
data or coordinate axes, the buffering becomes redundant.
#toc13
Limitations
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 Reference Manual, page 568).  The work-around is to break
the polygon into separate pieces.
#toc14
Future Incompatibility
The
-mapped
options
are obsoleted and will be removed.  You can achieve the same results using
the
-hide
option instead.
# Works for now.
.g legend configure -mapped no
# Instead use this.
.g legend configure -hide yes
#toc15
Keywords
graph, widget
Table of Contents
#sect0
Name
#sect1
Synopsis
#sect2
Description
#sect3
Example
#sect4
Syntax
#sect5
Example
#sect6
Graph Operations
#sect7
Graph Components
#sect8
Axis Components
#sect9
Crosshairs Component
#sect10
Element Components
#sect11
Grid Component
#sect12
Speed Tips
#sect13
Limitations
#sect14
Future Incompatibility
#sect15
Keywords
