Table of Contents



NAME

padgraph - Create and manipulate a 2D plot of data

SYNOPSIS

padgraph pathName ?options ?

STANDARD OPTIONS

-xscrollcommand -yscrollcommand

See the options manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS

Command-Line Name:    -bottomborder
Database Name:    bottomBorder
Database Class:    BottomBorder

The width of the bottom border of the graph, default 50.

Command-Line Name:    -dataheight
Database Name:    dataHeight
Database Class:    DataHeight

Specifies the desired height of the data portion of the graph in
pixels. If this option is not supplied, a default is calculated from the window height and the border heights of the graph.

Command-Line Name:    -datarange
Database Name:    dataRange
Database Class:    DataRange

The limits of the data being displayed in the graph as a list of {xmin
ymin xmax ymax}. This would normally be calculated automatically from the data being displayed in the graph, however, any values supplied here will become the fixed limits of the displayed portion of the graph. Note that the portion of the data actually displayed at any time is controlled by the scrollRegion option.

Command-Line Name:    -datawidth
Database Name:    dataWidth
Database Class:    DataWidth

Specifies the desired width of the data portion of the graph in
pixels. If this option is not supplied, a default is calculated from the window width and the border widths of the graph.    

Command-Line Name:    -height
Database Name:    height
Database Class:    Height

Specifies a desired window height that the padgraph widget should request from
its geometry manager. The value should be in pixels.

Command-Line Name:    -image
Database Name:    image
Database Class:    Image

Specifies an image to use as the backdrop for the graph. Specifying an
image forces the NoZoom option on and sets the DataWidth and DataHeight options to be no larger than the image. The intention is that the image corresponds to a display of data and so you would normally use the DataRange option to fix the limits of the data to those of the image.

Command-Line Name:    -leftborder
Database Name:    leftBorder
Database Class:    LeftBorder

The width of the left border of the graph, default 50.

Command-Line Name:    -nozoom
Database Name:    noZoom
Database Class:    NoZoom

Disable zooming for the graph.

Command-Line Name:    -preservexscale
Database Name:    preserveXScale
Database Class:    preserveXScale

If this option is supplied, the display scale for the x-axis will
remain constant when the window is resized resulting in more or less data being displayed. The default behaviour is to modify the display scale so as to display the same range of data on the graph.

Command-Line Name:    -preserveyscale
Database Name:    preserveYScale
Database Class:    preserveYScale

If this option is supplied, the display scale for the y-axis will
remain constant when the window is resized resulting in more or less data being displayed. The default behaviour is to modify the display scale so as to display the same range of data on the graph.

Command-Line Name:    -rightborder
Database Name:    rightBorder
Database Class:    RightBorder

The width of the right border of the graph, default 50.

Command-Line Name:    -scrollregion
Database Name:    scrollRegion
Database Class:    ScrollRegion

Specifies a list with four graph coordinates {xmin ymin xmax ymax}
which are the limits of the data to be displayed on the graph.

Command-Line Name:    -textoffset
Database Name:    textOffset
Database Class:    TextOffset

The offset between an axis and the axis tick labels, default 5.

Command-Line Name:    -ticklength
Database Name:    tickLength
Database Class:    TickLength

The length of an axis tickmark, default 5.

Command-Line Name:    -topborder
Database Name:    topBorder
Database Class:    TopBorder

The width of the top border of the graph, default 20.

Command-Line Name:    -title
Database Name:    title
Database Class:    Title

A main title for the graph. The title is displayed at the center of the
graph in the top border.

Command-Line Name:    -width
Database Name:    width
Database Class:    width

Specifies a desired window width that the canvas widget should request from
its geometry manager. The value should be in pixels.

Command-Line Name:    -xcursor
Database Name:    xCursor
Database Class:    XCursor

Enable a vertical cursor on the graph.

Command-Line Name:    -xlabel
Database Name:    xlabel
Database Class:    Xlabel

A label for the x-axis. The label is displayed below the tick labels
for the x-axis.

Command-Line Name:    -xscrollincrement
Database Name:    xScrollIncrement
Database Class:    ScrollIncrement

Specifies an increment for horizontal scrolling, in any of the usual forms
permitted for screen distances. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the canvas x coordinate at the left edge of the window is always an even multiple of xScrollIncrement ; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be xScrollIncrement . If the value of this option is less than or equal to zero, then vertical scrolling is unconstrained.

Command-Line Name:    -ycursor
Database Name:    yCursor
Database Class:    YCursor

Enable a horizontal cursor on the graph.

Command-Line Name:    -ylabel
Database Name:    ylabel
Database Class:    Ylabel

A label for the y-axis. The label is displayed to the left of the tick labels
for the y-axis. The text is shown stacked one letter above the other rather than being rotated.

Command-Line Name:    -yscrollincrement
Database Name:    yScrollIncrement
Database Class:    ScrollIncrement

Specifies an increment for vertical scrolling, in any of the usual forms
permitted for screen distances. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the canvas y coordinate at the top edge of the window is always an even multiple of yScrollIncrement ; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be yScrollIncrement . If the value of this option is less than or equal to zero, then vertical scrolling is unconstrained.

INTRODUCTION

The padgraph command creates a new window (given by the pathName argument) and makes it into a padgraph widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the padgraph such as its scrolling behaviour and axis labels. The padgraph 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.

WIDGET COMMAND

The padgraph 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 following general form:

pathName option ?arg arg ... ?

Option and the arg s determine the exact behavior of the command. The following widget commands are possible for padgraph widgets:

pathName adddata coords ?-points ? ?-lines ? ?-color colour ? ?-mask vector ?
Add a dataset to the graph. Coords is a list of coordinates of the form {x1 y1 x2 y2 ... xn yn} and is added to the graph as a new dataset. The dataset is rendered on the graph using points if the -points is specified, with lines if the -lines is specified or with both if both are given. The -color option defines the colour of the line/points. If the -mask option is specified vector should be a vector of boolean values corresponding to the x/y pairs in coords ; only those points for which the mask vector is true will be rendered on the graph -- currently masking is only implemented for datasets rendered as points.

pathName bbox
Returns a list with four elements giving an approximate bounding box for the data currently displayed on the graph (corresponding to the current scrollRegion . The list has the form ``x1 y1 x2 y2 '' such that the drawn areas of all the named elements are within the region bounded by x1 on the left, x2 on the right, y1 on the top, and y2 on the bottom.

pathName cget option
Returns the current value of the configuration option given by option . Option may have any of the values accepted by the padgraph command.

pathName configure ?option ? ?value ? ?option value ... ?
Query or modify 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 an empty string. Option may have any of the values accepted by the padgraph command.

pathName cursors screenx screeny
This command is intended to be used as a binding on mouse motion for the padgraph widget. Cursors are drawn at the screen position specified if they have been enabled via the -xcursor or -ycursor options. This binding is made internally by default if either x or y cursors are enabled but may be overriden to provide different behaviour.

pathName marker ?-noflush? type coords colour q ?tag ?

pathName marker ?-noflush ? move coords ?tag ?

pathName marker ?-noflush ? delete ?tag ?
These commands deal with markers on the graph. The first form creates a marker on the graph of the specified type: one of vline for a vertical line or hline for a horizontal line. Coords is a list of the coordinates for the marker, in both of the current markers this is just a single floating point number giving the x or y coordinate of the marker. Colour is the colour of the line and the optional tag is a unique name for the marker which can be used to move it at a later time. The second form moves an existing marker, as specified by its tag, to the new coordinates. The third form deletes an existing marker. Normally the graph will be redrawn after the marker is created, moved or deleted; if the -noflush flag is specified, no redraw is done, this is useful if a number of changes are being made at one time as many redraws can take a long time.

pathName redraw
Forces a redraw of the graph.

pathName xtograph screenx
Given a window x-coordinate in the padgraph screenx , this command returns the graph x-coordinate that is displayed at that location.

pathName xtopad graphX
Given a graph x-coordinate graphX this command returns the pad x-coordinate corresponding to that data value.

pathName ytograph screeny
Given a window y-coordinate in the padgraph screeny this command returns the graph y-coordinate that is displayed at that location.

pathName ytopad graphY
Given a graph y-coordinate graphX this command returns the pad y-coordinate corresponding to that data value. Note that pad coordinates have the origin at the bottom left of the window.

pathName ytoxwin graphY
Given a graph y-coordinate graphX this command returns the window y-coordinate corresponding to that data value. Note how this command differs from ytopad in that it returns the raw window coordinate with the origin at the upper left.

pathName zoomx x1 x2
Zoom in the X direction so that the new axis limits are x1 and x2 .

C API

Data can be added to a padgraph widget directly from C code using the padgraph_adddata function which is analogous to the adddata command above:

#include <padgraph.h>

int padgraph_adddata ( graph, data, n, mask, lines, points, colorname )

A pointer to an padgraph widget.
An array of points. padgraph_point is just a pair of doubles.
The number of points in data .
The mask vector, must have the same length as data.
1 for lines, 0 for no lines.
1 for points, 0 for no points.
The colour of the line/points.

See the file pgtest.c in the padgraph distribution for an example of the C API usage.

CREDITS

The padgraph widget uses the pad widget from Steve Bellenot (bellenot@math.fsu.edu ) to render its graphs. Some code (for axis tick labels) and ideas have been taken from the graph widget in the BLT extensions to Tcl/Tk. Code for scrolling the graph is based on that for the Tk canvas widget.

KEYWORDS

padgraph, widget

Table of Contents