Table of Contents
eps - Encapsulated PostScript canvas item.
canvas create eps x y ?option value ?...
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.
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.
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 .
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).
- 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.
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.
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.
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.
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" .
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
.
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.
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.
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
graph, widget
Table of Contents