Plotchart(n)                       Plotchart                      Plotchart(n)



______________________________________________________________________________

NAME
       Plotchart - Simple plotting and charting package

SYNOPSIS
       package require Tcl  ?8.4?

       package require Tk  ?8.4?

       package require Plotchart  ?1.6?

       ::Plotchart::createXYPlot w xaxis yaxis

       ::Plotchart::createStripchart w xaxis yaxis

       ::Plotchart::createTXPlot w timeaxis xaxis

       ::Plotchart::createXLogYPlot w xaxis yaxis

       ::Plotchart::createPolarPlot w radius_data

       ::Plotchart::createIsometricPlot w xaxis yaxis stepsize

       ::Plotchart::createHistogram w xaxis yaxis

       ::Plotchart::create3DPlot w xaxis yaxis zaxis

       ::Plotchart::createPiechart w

       ::Plotchart::createRadialchart w names scale style

       ::Plotchart::createBarchart w xlabels yaxis noseries

       ::Plotchart::createHorizontalBarchart w ylabels xaxis noseries

       ::Plotchart::create3DBarchart w yaxis nobars

       ::Plotchart::create3DRibbonChart w names yaxis zaxis

       ::Plotchart::createBoxplot w xaxis ylabels

       ::Plotchart::createTimechart w time_begin time_end args

       ::Plotchart::createGanttchart w time_begin time_end args

       ::Plotchart::createRightAxis w yaxis

       $anyplot title text

       $anyplot saveplot filename args

       $anyplot xtext text

       $anyplot ytext text

       $anyplot xconfig -option value ...

       $anyplot yconfig -option value ...

       $anyplot background part colour_or_image dir

       $anyplot xticklines colour

       $anyplot yticklines colour

       $anyplot legendconfig -option value ...

       $anyplot legend series text

       $anyplot balloon x y text dir

       $anyplot balloonconfig args

       $xyplot plot series xcrd ycrd

       $xyplot trend series xcrd ycrd

       $xyplot rchart series xcrd ycrd

       $xyplot interval series xcrd ymin ymax ?ycentr?

       $xyplot box-and-whiskers series xcrd ycrd

       $xyplot vector series xcrd ycrd ucmp vcmp

       $xyplot vectorconfig series -option value ...

       $xyplot dot series xcrd ycrd value

       $xyplot dotconfig series -option value ...

       $xyplot contourlines xcrd ycrd values ?classes?

       $xyplot contourfill xcrd ycrd values ?classes?

       $xyplot contourbox xcrd ycrd values ?classes?

       $xyplot colorMap colours

       $xyplot grid xcrd ycrd

       $polarplot plot series radius angle

       $plot3d plotfunc function

       $plot3d plotfuncont function contours

       $plot3d gridsize nxcells nycells

       $plot3d plotdata data

       $plot3d colours fill border

       $xyplot dataconfig series -option value ...

       $pie plot data

       $pie colours colour1 colour2 ...

       $radial plot data colour thickness

       $pie colours colour1 colour2 ...

       $barchart plot series ydata colour

       $barchart plot series xdata colour

       $barchart plot label yvalue colour

       $barchart config -option value ...

       $ribbon line xypairs colour

       $ribbon area xypairs colour

       $boxplot plot label values

       $timechart period text time_begin time_end colour

       $timechart milestone text time colour

       $timechart vertline text time

       $timechart hscroll scrollbar

       $timechart vscroll scrollbar

       $ganttchart task text time_begin time_end completed

       $ganttchart milestone text time colour

       $ganttchart vertline text time

       $ganttchart connect from to

       $ganttchart summary text args

       $ganttchart color keyword newcolor

       $ganttchart font keyword newfont

       $ganttchart hscroll scrollbar

       $ganttchart vscroll scrollbar

       $isoplot plot rectangle x1 y1 x2 y2 colour

       $isoplot plot filled-rectangle x1 y1 x2 y2 colour

       $isoplot plot circle xc yc radius colour

       $isoplot plot filled-circle xc yc radius colour

       ::Plotchart::viewPort w pxmin pymin pxmax pymax

       ::Plotchart::worldCoordinates w xmin ymin xmax ymax

       ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax

       ::Plotchart::coordsToPixel w x y

       ::Plotchart::coords3DToPixel w x y z

       ::Plotchart::polarCoordinates w radmax

       ::Plotchart::polarToPixel w rad phi

       ::Plotchart::pixelToCoords w x y

       ::Plotchart::pixelToIndex w x y

       ::Plotchart::determineScale xmin xmax inverted

       ::Plotchart::plotconfig charttype component property value

       ::Plotchart::plotpack w dir args

_________________________________________________________________

DESCRIPTION
       Plotchart is a Tcl-only package that focuses on the easy creation of
       xy-plots, barcharts and other common types of graphical presentations.
       The emphasis is on ease of use, rather than flexibility. The procedures
       that create a plot use the entire canvas window, making the layout of
       the plot completely automatic.

       This results in the creation of an xy-plot in, say, ten lines of code:

                  package require Plotchart

                  canvas .c -background white -width 400 -height 200
                  pack   .c -fill both

                  #
                  # Create the plot with its x- and y-axes
                  #
                  set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

                  foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {
                      $s plot series1 $x $y
                  }

                  $s title "Data series"


       A drawback of the package might be that it does not do any data
       management. So if the canvas that holds the plot is to be resized, the
       whole plot must be redrawn.  The advantage, though, is that it offers a
       number of plot and chart types:

       o      XY-plots like the one shown above with any number of data
              series.

       o      Stripcharts, a kind of XY-plots where the horizontal axis is
              adjusted automatically. The result is a kind of sliding window
              on the data series.

       o      Polar plots, where the coordinates are polar instead of
              cartesian.

       o      Histograms, for plotting statistical information.

       o      Isometric plots, where the scale of the coordinates in the two
              directions is always the same, i.e. a circle in world
              coordinates appears as a circle on the screen.

              You can zoom in and out, as well as pan with these plots (Note:
              this works best if no axes are drawn, the zooming and panning
              routines do not distinguish the axes), using the mouse buttons
              with the control key and the arrow keys with the control key.

       o      Piecharts, with automatic scaling to indicate the proportions.

       o      Barcharts, with either vertical or horizontal bars, stacked bars
              or bars side by side.

       o      Timecharts, where bars indicate a time period and milestones or
              other important moments in time are represented by triangles.

       o      3D plots (both for displaying surfaces and 3D bars)

       With version 1.5 a new command has been introduced: plotconfig, which
       can be used to configure the plot options for particular types of plots
       and charts (cf. CONFIGURATION OPTIONS)

PLOT CREATION COMMANDS
       You create the plot or chart with one single command and then fill the
       plot with data:

       ::Plotchart::createXYPlot w xaxis yaxis
              Create a new xy-plot (configuration type: xyplot).

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list xaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the x-axis, in this order.  For an inverted axis,
                     where the maximum appears on the left-hand side, use:
                     maximum, minimum and a negative stepsize.

              list yaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis, in this order.  For an inverted axis,
                     where the maximum appears at the bottom, use: maximum,
                     minimum and a negative stepsize.


       ::Plotchart::createStripchart w xaxis yaxis
              Create a new strip chart (configuration type: stripchart). The
              only difference to a regular XY plot is that the x-axis will be
              automatically adjusted when the x-coordinate of a new point
              exceeds the maximum.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list xaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the x-axis, in this order.  Note that an inverted x-
                     axis is not supported for this type of plot.

              list yaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis, in this order.  For an inverted axis,
                     where the maximum appears at the bottom, use: maximum,
                     minimum and a negative stepsize.


       ::Plotchart::createTXPlot w timeaxis xaxis
              Create a new time-x-plot (configuration type: txplot). The
              horizontal axis represents the date/time of the data and the
              vertical axis the values themselves.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list timeaxis (in)
                     A 3-element list containing the minimum and maximum
                     date/time to be shown and the stepsize (in days) for the
                     time-axis, in this order.  Note that an inverted time-
                     axis is not supported.

              list xaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the vertical axis, in this order.  For an inverted
                     axis, where the maximum appears at the bottom, use:
                     maximum, minimum and a negative stepsize.


       ::Plotchart::createXLogYPlot w xaxis yaxis
              Create a new xy-plot where the y-axis has a logarithmic scale
              (configuration type: xlogyplot).

              The data should be given as for a linear scale, as the
              logarithmic transformation is taken of internally.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list xaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the x-axis, in this order.  For an inverted axis,
                     where the maximum appears on the left-hand side, use:
                     maximum, minimum and a negative stepsize.

              list yaxis (in)
                     A 2-element list containing minimum and maximum for the
                     y-axis, in this order.  Note that an inverted logarithmic
                     axis is not supported.


       ::Plotchart::createPolarPlot w radius_data
              Create a new polar plot (configuration type: polarplot).

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list radius_data (in)
                     A 2-element list containing maximum radius and stepsize
                     for the radial axis, in this order.


       ::Plotchart::createIsometricPlot w xaxis yaxis stepsize
              Create a new isometric plot, where the vertical and the
              horizontal coordinates are scaled so that a circle will truly
              appear as a circle (configuration type: isometric).

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list xaxis (in)
                     A 2-element list containing minimum, and maximum for the
                     x-axis, in this order.

              list yaxis (in)
                     A 2-element list containing minimum, and maximum for the
                     y-axis, in this order.

              float|noaxes stepsize (in)
                     Either the stepsize used by both axes or the keyword
                     noaxes to signal the plot that it should use the full
                     area of the widget, to not draw any of the axes.


       ::Plotchart::createHistogram w xaxis yaxis
              Create a new histogram (configuration type: histogram).

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list xaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the x-axis, in this order.

              list yaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis, in this order.


       ::Plotchart::create3DPlot w xaxis yaxis zaxis
              Create a new 3D plot.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list xaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the x-axis, in this order.

              list yaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis, in this order.

              list zaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the z-axis, in this order.


       ::Plotchart::createPiechart w
              Create a new piechart (configuration type: piechart).

              widget w (in)
                     Name of the existing canvas widget to hold the plot.


       ::Plotchart::createRadialchart w names scale style
              Create a new radial chart (the data are drawn as a line
              connecting the spokes of the diagram) (configuration type:
              radialchart).

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list names (in)
                     Names for the spokes.

              float scale (in)
                     Scale value to determine the position of the data along
                     the spokes.

              float style (in)
                     Style of the chart (optional). One of:

                     o      lines - the default: draw the data as independent
                            polylines.

                     o      cumulative - draw the data as polylines where the
                            data are accumulated.

                     o      filled - draw the data as filled polygons where
                            the data are accumulated


       ::Plotchart::createBarchart w xlabels yaxis noseries
              Create a new barchart with vertical bars (configuration type:
              vertbars). The horizontal axis will display the labels contained
              in the argument xlabels. The number of series given by noseries
              determines both the width of the bars, and the way the series
              will be drawn.

              If the keyword stacked was specified the series will be drawn
              stacked on top of each other. Otherwise each series that is
              drawn will be drawn shifted to the right.

              The number of series determines the width of the bars, so that
              there is space of that number of bars. If you use a floating-
              point number, like 2.2, instead of an integer, like 2, a small
              gap between the sets of bars will be drawn - the width depends
              on the fractional part.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list xlabels (in)
                     List of labels for the x-axis. Its length also determines
                     the number of bars that will be plotted per series.

              list yaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis, in this order.

              int|stacked noseries (in)
                     The number of data series that will be plotted. This has
                     to be an integer number greater than zero (if stacked is
                     not used).


       ::Plotchart::createHorizontalBarchart w ylabels xaxis noseries
              Create a new barchart with horizontal bars (configuration type:
              horizbars). The vertical axis will display the labels contained
              in the argument ylabels. The number of series given by noseries
              determines both the width of the bars, and the way the series
              will be drawn.

              If the keyword stacked was specified the series will be drawn
              stacked from left to right. Otherwise each series that is drawn
              will be drawn shifted upward.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list ylabels (in)
                     List of labels for the y-axis. Its length also determines
                     the number of bars that will be plotted per series.

              list xaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the x-axis, in this order.

              int|stacked noseries (in)
                     The number of data series that will be plotted. This has
                     to be an integer number greater than zero (if stacked is
                     not used).


       ::Plotchart::create3DBarchart w yaxis nobars
              Create a new barchart with 3D vertical bars (configuration type:
              3dbars). The horizontal axis will display the labels per bar.
              The number of bars given by nobars determines the position and
              the width of the bars. The colours can be varied per bar. (This
              type of chart was inspired by the Wiki page on 3D bars by
              Richard Suchenwirth.)

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list yaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis, in this order.

              int nobars (in)
                     The number of bars that will be plotted.


       ::Plotchart::create3DRibbonChart w names yaxis zaxis
              Create a new "ribbon chart" (configuration type: 3dribbon). This
              is a chart where the data series are represented as ribbons in a
              three-dimensional axis system. Along the x-axis (which is "into"
              the screen) the names are plotted, each representing a single
              series. The first plot command draws the furthest series, the
              second draws the series in front of that and so on.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              widget w (in)
                     Names of the series, plotted as labels along the x-axis

              list yaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis (drawn horizontally!), in this order.

              list zaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the z-axis (drawn vertically), in this order.

              int nobars (in)
                     The number of bars that will be plotted.


       ::Plotchart::createBoxplot w xaxis ylabels
              Create a new boxplot with horizontal boxes (box-and-whiskers).
              The y-axis is drawn with labels. The boxes are drawn based on
              the raw data (see the plot subcommand for this type of plot).

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list xaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis, in this order.

              list ylabels (in)
                     List of labels for the y-axis. Its length also determines
                     the number of boxes that can be plotted. The labels are
                     also used in the plot subcommand.


       ::Plotchart::createTimechart w time_begin time_end args
              Create a new timechart (configuration type: timechart).  The
              time axis (= x-axis) goes from time_begin to time_end, and the
              vertical spacing is determined by the number of items to plot.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              string time_begin (in)
                     The start time given in a form that is recognised by the
                     clock scan command (e.g. "1 january 2004").

              string time_end (in)
                     The end time given in a form that is recognised by the
                     clock scan command (e.g. "1 january 2004").

              arguments args (in)
                     The remaining arguments can be:

                     o      The expected/maximum number of items. This
                            determines the vertical spacing. (If given, it
                            must be the first argument after "time_end"

                     o      The keyword -barheight and the number of pixels
                            per bar. This is an alternative method to
                            determine the vertical spacing.

                     o      The keyword -ylabelwidth and the number of pixels
                            to reserve for the labels at the y-axis.

       ::Plotchart::createGanttchart w time_begin time_end args
              Create a new Gantt chart (configuration type: ganttchart).  The
              time axis (= x-axis) goes from time_begin to time_end, and the
              vertical spacing is determined by the number of items to plot.
              Via the specific commands you can then add tasks and connections
              between the tasks.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              string time_begin (in)
                     The start time given in a form that is recognised by the
                     clock scan command (e.g. "1 january 2004").

              string time_end (in)
                     The end time given in a form that is recognised by the
                     clock scan command (e.g. "1 january 2004").

              arguments args (in)
                     The remaining arguments can be:

                     o      The expected/maximum number of items. This
                            determines the vertical spacing. (If given this
                            way, it must be the first argument after
                            "time_end")

                     o      The expected/maximum width of the descriptive text
                            (roughly in characters, for the actual space
                            reserved for the text, it is assumed that a
                            character is about ten pixels wide). Defaults to
                            20. (If given this way, it must be the second
                            argument after "time_end").

                     o      The keyword -barheight and the number of pixels
                            per bar. This is an alternative method to
                            determine the vertical spacing.

                     o      The keyword -ylabelwidth and the number of pixels
                            to reserve for the labels at the y-axis.

       ::Plotchart::createRightAxis w yaxis
              Create a plot command that will use a right axis instead of the
              left axis (configuration type: inherited from the existing
              plot). The widget (w) must already contain an ordinary plot, as
              the horizontal axis and other properties are reused. To plot
              data using the right axis, use this new command, to plot data
              using the left axis, use the original plot command.

              widget w (in)
                     Name of the existing canvas widget to hold the plot.

              list yaxis (in)
                     A 3-element list containing minimum, maximum and stepsize
                     for the y-axis, in this order.


PLOT METHODS
       Each of the creation commands explained in the last section returns the
       name of a new object command that can be used to manipulate the plot or
       chart. The subcommands available to a chart command depend on the type
       of the chart.

       General subcommands for all types of charts. $anyplot is the command
       returned by the creation command:

       $anyplot title text
              Specify the title of the whole chart.

              string text (in)
                     The text of the title to be drawn.


       $anyplot saveplot filename args
              Draws the plot into a file, using PostScript.

              string filename (in)
                     Contain the path name of the file to write the plot to.

              list args (in)
                     Optionally you can specify the option -format "some
                     picture format" to store the plot in a different file
                     than a PostScript file. This, however, relies on the Img
                     package to do the actual job.

                     Note: Because the window holding the plot must be fully
                     visible before Img can successfully grab it, it is raised
                     first.  On some systems, for instance Linux with KDE,
                     raising a window is not done automatically, but instead
                     you need to click on the window in the task bar. Similar
                     things happen on Windows XP.

                     There seems to be something wrong under some
                     circumstances, so instead of waiting for the visibility
                     of the window, the procedure simply waits two seconds. It
                     is not ideal, but it seems to work better.


       $anyplot xtext text
              Specify the title of the (horizontal) x-axis, for those plots
              that have a straight x-axis.

              string text (in)
                     The text of the x-axis label to be drawn.


       $anyplot ytext text
              Specify the title of the (horizontal) y-axis, for those plots
              that have a straight y-axis.

              string text (in)
                     The text of the y-axis label to be drawn.


       $anyplot xconfig -option value ...
              Set one or more configuration parameters for the x-axis.  The
              following options are supported:

              format fmt
                     The format for the numbers along the axis.

              ticklength length
                     The length of the tickmarks (in pixels).

              ticklines boolean
                     Whether to draw ticklines (true) or not (false).

              scale scale_data
                     New scale data for the axis, i.e. a 3-element list
                     containing minimum, maximum and stepsize for the axis, in
                     this order.

                     Beware: Setting this option will clear all data from the
                     plot.


       $anyplot yconfig -option value ...
              Set one or more configuration parameters for the y-axis. This
              method accepts the same options and values as the method
              xconfig.

       $anyplot background part colour_or_image dir
              Set the background of a part of the plot

              string part
                     Which part of the plot: "axes" for the axes area and
                     "plot" for the inner part. The interpretation depends on
                     the type of plot. Two further possibilities are:

                     o      image, in which case a predefined image is loaded
                            into the background of the plot.

                     o      gradient, in which case the background is coloured
                            in different shades of the given colour. The "dir"
                            argument specifies the direction in which the
                            colour gets whiter.

              string colour_or_image
                     Colour for that part or the name of the image if "part"
                     is "image"

              string dir
                     The direction of the gradient. One of: top-down, bottom-
                     up, left-right or right-left.


       $anyplot xticklines colour
              Draw vertical ticklines at each tick location

              string colour
                     Colour of the lines. Specifying an empty colour ("")
                     removes them again.  Defaults to "black"


       $anyplot yticklines colour
              Draw horizontal ticklines at each tick location

              string colour
                     Colour of the lines. Specifying an empty colour ("")
                     removes them again Defaults to "black"


       $anyplot legendconfig -option value ...
              Set one or more options for the legend. The legend is drawn as a
              rectangle with text and graphics inside.

              background colour
                     Set the colour of the background (the default colour is
                     white).  Set to the empty string for a transparant
                     legend.

              border colour
                     Set the colour of the border (the default colour is
                     white). Set to the empty string if you do not want a
                     border.

              canvas c
                     Draw the legend in a different canvas widget. This gives
                     you the freedom to position the legend outside the actual
                     plot.

              position corner
                     Set the position of the legend. May be one of: top-left,
                     top-right, bottom-left or bottom-right. (Default value is
                     top-right.)


       $anyplot legend series text
              Add an entry to the legend. The series determines which
              graphical symbol is to be used. (As a side effect the legend is
              actually drawn.)

              string series
                     Name of the data series. This determines the colour of
                     the line and the symbol (if any) that will be drawn.

              string text
                     Text to be drawn next to the line/symbol.


       $anyplot balloon x y text dir
              Add balloon text to the plot (except for 3D plots). The arrow
              will point to the given x- and y-coordinates. For xy-graphs and
              such, the coordinates are directly related to the axes; for
              vertical barcharts the x-coordinate is measured as the number of
              bars minus 1 and similar for horizontal barcharts.

              float x
                     X-coordinate of the point that the arrow of the balloon
                     will point to.

              float y
                     Y-coordinate of the point that the arrow of the balloon
                     will point to.

              string text
                     Text to be drawn in the balloon.

              string dir
                     Direction of the arrow, one of: north, north-east, east,
                     south-east, south, south-west, west or north-west.


       $anyplot balloonconfig args
              Configure the balloon text for the plot. The new settings will
              be used for the next balloon text.

              font fontname
                     Font to be used for the text

              justify left|center|right
                     Way to justify multiline text

              textcolour colour
                     Colour for the text (synonym: textcolor)

              background colour
                     Background colour for the balloon

              outline colour
                     Colour of the outline of the balloon

              margin value
                     Margin around the text (in pixels)

              rimwidth value
                     Width of the outline of the balloon (in pixels)

              arrowsize value
                     Length factor for the arrow (in pixels)


       Note: The commands xconfig and yconfig are currently implemented only
       for XY-plots and only the option -format has any effect.

       For xy plots, stripcharts, histograms and time-x-plots:

       $xyplot plot series xcrd ycrd
              Add a data point to the plot.

              string series (in)
                     Name of the data series the new point belongs to.

              float xcrd (in)
                     X-coordinate of the new point. (For time-x plots this
                     must be valid date/time that can be read with the clock
                     scan command).

              float ycrd (in)
                     Y-coordinate of the new point.

       Note on histograms:

       For histograms the x-coordinate that is given is interpreted to be the
       x-coordinate of the right side of the bar. The first bar starts at the
       y-axis on the left. To completely fill the range of the x-axis, you
       should draw a bar at the maximum x-coordinate.

       For xy plots:

       $xyplot trend series xcrd ycrd
              Draw or update a trend line using the data given sofar.

              string series (in)
                     Name of the data series the trend line belongs to.

              float xcrd (in)
                     X-coordinate of the new data point

              float ycrd (in)
                     Y-coordinate of the new data point

       $xyplot rchart series xcrd ycrd
              Draw data in the same way as the plot method, but with two lines
              added that indicate the expected range (+/- 3*standard
              deviation) of the data.

              string series (in)
                     Name of the data series the data point belongs to.

              float xcrd (in)
                     X-coordinate of the new data point

              float ycrd (in)
                     Y-coordinate of the new data point

       $xyplot interval series xcrd ymin ymax ?ycentr?
              Add a vertical error interval to the plot. The interval is drawn
              from ymin to ymax. If the ycentr argument is given, a symbol is
              drawn at that position.

              string series (in)
                     Name of the data series the interval belongs to.

              float xcrd (in)
                     X-coordinate of the interval

              float ymin (in)
                     Minimum y-coordinate of the interval.

              float ymax (in)
                     Maximum y-coordinate of the interval.

              float ycentr (in)
                     Y-coordinate to draw the symbol at (optional)

       $xyplot box-and-whiskers series xcrd ycrd
              Draw a box and whiskers in the plot. If the argument xcrd is a
              list of several values and the argument ycrd is a single value,
              a horizontal box is drawn with the quartiles determined from the
              list of values contained in xcrd.

              If, instead, the argument ycrd contains a list of several values
              and the argument xcrd a single value, then a vertical box is
              drawn and the quartiles are determined from ycrd. (There must be
              exactly one list of several values. Otherwise an error is
              reported.)

              The option -boxwidth (default: 10 pixels) determines the width
              (or height) of the box.

              string series (in)
                     Name of the data series the box-and-whiskers belongs to.

              float xcrd (in)
                     X-coordinate of the box or a list of values.

              float ymin (in)
                     Y-coordinate of the box or a list of values.

       $xyplot vector series xcrd ycrd ucmp vcmp
              Draw a vector in the plot. The vector can be given as either
              cartesian coordinates or as length/angle, where the angle is in
              degrees and is interpreted according to the mathematical
              convention or the nautical.  (See the vectorconfig subcommand)

              string series (in)
                     Name of the series the vector belongs to. Determines the
                     appearance and interpretation.

              float xcrd (in)
                     X-coordinate of the point where the arrow appears

              float ycrd (in)
                     Y-coordinate of the point where the arrow appears

              float ucmp (in)
                     X-component or the length of the vector

              float ycentr (in)
                     Y-component or the angle of the vector

       $xyplot vectorconfig series -option value ...
              ] Set the vector drawing options for a particular series

              string series (in)
                     Name of the series the vector belongs to.

              The options can be one of the following:

              colour The colour of the arrow (default: black; synonym: color)

              scale value
                     The scale factor used to convert the length of the arrow
                     into a number of pixels (default: 1.0)

              centred onoff
                     Logical value indicating that the xy-coordinates are to
                     be used as the start of the arrow or as the centre
                     (default: 0; synonym: centered)

              type keyword
                     Interpretation of the vector components. Can be
                     "cartesian" (default), in which case the x- and y-
                     components are expected, "polar" (the angle 0 coincides
                     with the positive x-axis, 90 coincides with the positive
                     y-axis) or "nautical" (0 is "north" and 90 is "east").


       $xyplot dot series xcrd ycrd value
              Draw a dot in the plot. The size and colour is determined by the
              value and by the options set for the series it belongs to.  (See
              the dotconfig subcommand)

              string series (in)
                     Name of the series the dot belongs to. Determines size
                     and colour

              float xcrd (in)
                     X-coordinate of the point where the arrow appears

              float ycrd (in)
                     Y-coordinate of the point where the arrow appears

              float value (in)
                     Value determining size and colour

       $xyplot dotconfig series -option value ...
              ] Set the dot drawing options for a particular series

              string series (in)
                     Name of the series the dot belongs to.

              The options can be one of the following:

              colour The colour of the dot if no scaling is used or the value
                     exceeds the last limit of the classes.

              scale value
                     The scale factor used to convert the value into the
                     radius of the dot in pixels (default: 1.0)

              radius value
                     The default radius of the dots, used if there is no
                     scaling by value (in pixels; default: 3)

              scalebyvalue onoff
                     Determines whether the dots all have the same size or a
                     size depending on the given value (default: on).

              outline onoff
                     Draw a black circle around the dot or not (default: on)

              classes list
                     Set the limits and the corresponding colours. For
                     instance:


                         $xyplot series1 -classes {0 blue 1 green} -colour red


                     will cause a blue dot to be drawn for values smaller than
                     0, a green dot for values larger/equal 0 but lower than 1
                     and a red dot for values larger/equal 1.

                     If there is no list of classes for the particular series,
                     the dots are scaled by the value.

                     You can combine the colouring by value and the scaling by
                     value by setting a list of classes and setting the
                     scalebyvalue option on.


       $xyplot contourlines xcrd ycrd values ?classes?
              Draw contour lines for the values given on the grid. The grid is
              defined by the xcrd and ycrd arguments (they give the x- and y-
              coordinates of the grid cell corners). The values are given at
              these corners. The classes determine which contour lines are
              drawn. If a value on one of the corners is missing, the contour
              lines in that cell will not be drawn.

              list xcrd (in)
                     List of lists, each value is an x-coordinate for a grid
                     cell corner

              list ycrd (in)
                     List of lists, each value is an y-coordinate for a grid
                     cell corner

              list values (in)
                     List of lists, each value is the value at a grid cell
                     corner

              list classes (in)
                     List of class values or a list of lists of two elements
                     (each inner list the class value and the colour to be
                     used). If empty or missing, the classes are determined
                     automatically.

                     Note: The class values must enclose the whole range of
                     values.


       $xyplot contourfill xcrd ycrd values ?classes?
              Draw filled contours for the values given on the grid. (The use
              of this method is identical to the "contourlines" method).

       $xyplot contourbox xcrd ycrd values ?classes?
              Draw the cells as filled quadrangles. The colour is determined
              from the average of the values on all four corners.

       $xyplot colorMap colours
              Set the colours to be used with the contour methods. The
              argument is either a predefined colourmap (grey/gray, jet, hot
              or cool) or a list of colours. When selecting the colours for
              actually drawing the contours, the given colours will be
              interpolated (based on the HLS scheme).

              list colours (in)
                     List of colour names or colour values or one of the
                     predefined maps:

                     o      grey or gray: gray colours from dark to light

                     o      jet: rainbow colours

                     o      hot: colours from yellow via red to darkred

                     o      cool: colours from cyan via blue to magenta

       $xyplot grid xcrd ycrd
              Draw the grid cells as lines connecting the (valid) grid points.

              list xcrd (in)
                     List of lists, each value is an x-coordinate for a grid
                     cell corner

              list ycrd (in)
                     List of lists, each value is an y-coordinate for a grid
                     cell corner

       For polar plots:

       $polarplot plot series radius angle
              Add a data point to the polar plot.

              string series (in)
                     Name of the data series the new point belongs to.

              float radius (in)
                     Radial coordinate of the new point.

              float angle (in)
                     Angular coordinate of the new point (in degrees).

       For 3D plots:

       $plot3d plotfunc function
              Plot a function defined over two variables x and y.  The
              resolution is determined by the set grid sizes (see the method
              gridsize for more information).

              string function (in)
                     Name of the procedure that calculates the z-value for the
                     given x and y coordinates. The procedure has to accept
                     two float arguments (x is first argument, y is second)
                     and return a floating-point value.


       $plot3d plotfuncont function contours
              Plot a function defined over two variables x and y using the
              contour levels in contours to colour the surface.  The
              resolution is determined by the set grid sizes (see the method
              gridsize for more information).

              string function (in)
                     Name of the procedure that calculates the z-value for the
                     given x and y coordinates. The procedure has to accept
                     two float arguments (x is first argument, y is second)
                     and return a floating-point value.

              list contours (in)
                     List of values in ascending order that represent the
                     contour levels (the boundaries between the colours in the
                     contour map).


       $plot3d gridsize nxcells nycells
              Set the grid size in the two directions. Together they determine
              how many polygons will be drawn for a function plot.

              int nxcells (in)
                     Number of grid cells in x direction. Has to be an integer
                     number greater than zero.

              int nycells (in)
                     Number of grid cells in y direction. Has to be an integer
                     number greater than zero.


       $plot3d plotdata data
              Plot a matrix of data.

              list data (in)
                     The data to be plotted. The data has to be provided as a
                     nested list with 2 levels. The outer list contains rows,
                     drawn in y-direction, and each row is a list whose
                     elements are drawn in x-direction, for the columns.
                     Example:



                         set data {
                         {1.0 2.0 3.0}
                         {4.0 5.0 6.0}
                         }



       $plot3d colours fill border
              Configure the colours to use for polygon borders and inner area.

              color fill (in)
                     The colour to use for filling the polygons.

              color border (in)
                     The colour to use for the border of the polygons.

       For xy plots, stripcharts and polar plots:

       $xyplot dataconfig series -option value ...
              Set the value for one or more options regarding the drawing of
              data of a specific series.

              string series (in)
                     Name of the data series whose configuration we are
                     changing.

       The following options are allowed:

              colour c

              color c
                     The colour to be used when drawing the data series.

              type enum
                     The drawing mode chosen for the series.  This can be one
                     of line, symbol, or both.

              symbol enum
                     What kind of symbol to draw. The value of this option is
                     ignored when the drawing mode line was chosen. This can
                     be one of plus, cross, circle, up (triangle pointing up),
                     down (triangle pointing down), dot (filled circle),
                     upfilled or downfilled (filled triangles).

              filled enum
                     Whether to fill the area above or below the data line or
                     not. Can be one of: no, up or down (SPECIAL EFFECTS)

              fillcolour colour
                     Colour to use when filling the area associated with the
                     data line.

       For piecharts:

       $pie plot data
              Fill a piechart.

              list data (in)
                     A list of pairs (labels and values). The values determine
                     the relative size of the circle segments. The labels are
                     drawn beside the circle.

       $pie colours colour1 colour2 ...
              Set the colours to be used.

              color colour1 (in)
                     The first colour.

              color colour2 (in)
                     The second colour, and so on.

       For radial charts:

       $radial plot data colour thickness
              Draw a new line in the radial chart

              list data (in)
                     A list of data (one for each spoke). The values determine
                     the distance from the centre of the line connecting the
                     spokes.

              color colour (in)
                     The colour for the line.

              int thickness (in)
                     An optional argument for the thickness of the line.

       $pie colours colour1 colour2 ...
              Set the colours to be used.

              color colour1 (in)
                     The first colour.

              color colour2 (in)
                     The second colour, and so on.

       For vertical barcharts:

       $barchart plot series ydata colour
              Add a data series to a barchart.

              string series (in)
                     Name of the series the values belong to.

              list ydata (in)
                     A list of values, one for each x-axis label.

              color colour (in)
                     The colour of the bars.

       For horizontal barcharts:

       $barchart plot series xdata colour
              Add a data series to a barchart.

              string series (in)
                     Name of the series the values belong to.

              list xdata (in)
                     A list of values, one for each y-axis label.

              color colour (in)
                     The colour of the bars.

       For 3D barcharts:

       $barchart plot label yvalue colour
              Add the next bar to the barchart.

              string label (in)
                     The label to be shown below the column.

              float yvalue (in)
                     The value that determines the height of the column

              color colour (in)
                     The colour of the column.

       $barchart config -option value ...
              Set one or more configuration parameters. The following options
              are supported:

              usebackground boolean
                     Whether to draw walls to the left and to the back of the
                     columns or not

              useticklines boolean
                     Whether to draw ticklines on the walls or not

              showvalues boolean
                     Whether to show the values or not

              labelfont newfont
                     Name of the font to use for labels

              labelcolour colour
                     Colour for the labels

              valuefont newfont
                     Name of the font to use for the values

              valuecolour colour
                     Colour for the values

       For 3D ribbon charts:

       $ribbon line xypairs colour
              Plot the given xy-pairs as a ribbon in the chart

              list xypairs (in)
                     The pairs of x/y values to be drawn (the series is drawn
                     as a whole)

              color colour (in)
                     The colour of the ribbon.

       $ribbon area xypairs colour
              Plot the given xy-pairs as a ribbon with a filled area in front.
              The effect is that of a box with the data as its upper surface.

              list xypairs (in)
                     The pairs of x/y values to be drawn (the series is drawn
                     as a whole)

              color colour (in)
                     The colour of the ribbon/area.

       For boxplots:

       $boxplot plot label values
              Add a box-and-whisker to the plot.

              string label (in)
                     The label along the y-axis to which the data belong

              list values (in)
                     List of raw values, the extent of the box and the
                     whiskers will be determined from this list.

       For timecharts:

       $timechart period text time_begin time_end colour
              Add a time period to the chart.

              string text (in)
                     The text describing the period.

              string time_begin (in)
                     Start time of the period.

              string time_end (in)
                     Stop time of the period.

              color colour (in)
                     The colour of the bar (defaults to black).


       $timechart milestone text time colour
              Add a milestone (represented as an point-down triangle) to the
              chart.

              string text (in)
                     The text describing the milestone.

              string time (in)
                     Time at which the milestone must be positioned.

              color colour (in)
                     The colour of the triangle (defaults to black).


       $timechart vertline text time
              Add a vertical line (to indicate the start of the month for
              instance) to the chart.

              string text (in)
                     The text appearing at the top (an abbreviation of the
                     date/time for instance).

              string time (in)
                     Time at which the line must be positioned.

       $timechart hscroll scrollbar
              Connect a horizontal scrollbar to the chart. See also the
              section on scrolling.

              widget scrollbar (in)
                     The horizontal scrollbar that is to be connected to the
                     chart

       $timechart vscroll scrollbar
              Connect a vertical scrollbar to the chart. See also the section
              on scrolling.

              widget scrollbar (in)
                     The vertical scrollbar that is to be connected to the
                     chart

       For Gantt charts:

       $ganttchart task text time_begin time_end completed
              Add a task with its period and level of completion to the chart.
              Returns a list of canvas items that can be used for further
              manipulations, like connecting two tasks.

              string text (in)
                     The text describing the task.

              string time_begin (in)
                     Start time of the task.

              string time_end (in)
                     Stop time of the task.

              float completed (in)
                     The percentage of the task that is completed.


       $ganttchart milestone text time colour
              Add a milestone (represented as an point-down triangle) to the
              chart.

              string text (in)
                     The text describing the milestone.

              string time (in)
                     Time at which the milestone must be positioned.

              color colour (in)
                     The colour of the triangle (defaults to black).


       $ganttchart vertline text time
              Add a vertical line (to indicate the start of the month for
              instance) to the chart.

              string text (in)
                     The text appearing at the top (an abbreviation of the
                     date/time for instance).

              string time (in)
                     Time at which the line must be positioned.


       $ganttchart connect from to
              Add an arrow that connects the from task with the to task.

              list from (in)
                     The list of items returned by the "task" command that
                     represents the task from which the arrow starts.

              string text (in)
                     The text summarising the tasks

              list args (in)
                     One or more tasks (the lists returned by the "task"
                     command). They are shifted down to make room for the
                     summary.

              list to (in)
                     The list of items returned by the "task" command that
                     represents the task at which the arrow ends.


       $ganttchart summary text args
              Add a summary item that spans all the tasks listed. The
              graphical representation is a thick bar running from the
              leftmost task to the rightmost.

              Use this command before connecting the tasks, as the arrow would
              not be shifted down!

              string text (in)
                     The text summarising the tasks

              list args (in)
                     One or more tasks (the lists returned by the "task"
                     command). They are shifted down to make room for the
                     summary.


       $ganttchart color keyword newcolor
              Set the colour of a part of the Gantt chart. These colours hold
              for all items of that type.

              string keyword (in)
                     The keyword indicates which part of the Gantt chart to
                     change:

                     o      description - the colour of the descriptive text

                     o      completed - the colour of the filled bar
                            representing the completed part of a task

                     o      left - the colour for the part that is not yet
                            completed

                     o      odd - the background colour for the odd entries

                     o      even - the background colour for the even entries

                     o      summary - the colour for the summary text

                     o      summarybar - the colour for the bar for a summary

              string newcolor (in)
                     The new colour for the chosen items.


       $ganttchart font keyword newfont
              Set the font of a part of the Gantt chart. These fonts hold for
              all items of that type.

              string keyword (in)
                     The keyword indicates which part of the Gantt chart to
                     change:

                     o      description - the font used for descriptive text

                     o      summary - the font used for summaries

                     o      scale - the font used for the time scale

              string newfont (in)
                     The new font for the chosen items.

       $ganttchart hscroll scrollbar
              Connect a horizontal scrollbar to the chart. See also the
              section on scrolling.

              widget scrollbar (in)
                     The horizontal scrollbar that is to be connected to the
                     chart

       $ganttchart vscroll scrollbar
              Connect a vertical scrollbar to the chart. See also the section
              on scrolling.

              widget scrollbar (in)
                     The vertical scrollbar that is to be connected to the
                     chart

       For isometric plots (to be extended):

       $isoplot plot rectangle x1 y1 x2 y2 colour
              Plot the outlines of a rectangle.

              float x1 (in)
                     Minimum x coordinate of the rectangle to be drawn.

              float y1 (in)
                     Minimum y coordinate of the rectangle.

              float x2 (in)
                     Maximum x coordinate of the rectangle to be drawn.

              float y2 (in)
                     Maximum y coordinate of the rectangle.

              color colour (in)
                     The colour of the rectangle.


       $isoplot plot filled-rectangle x1 y1 x2 y2 colour
              Plot a rectangle filled with the given colour.

              float x1 (in)
                     Minimum x coordinate of the rectangle to be drawn.

              float y1 (in)
                     Minimum y coordinate of the rectangle.

              float x2 (in)
                     Maximum x coordinate of the rectangle to be drawn.

              float y2 (in)
                     Maximum y coordinate of the rectangle.

              color colour (in)
                     The colour of the rectangle.


       $isoplot plot circle xc yc radius colour
              Plot the outline of a circle.

              float xc (in)
                     X coordinate of the circle's centre.

              float yc (in)
                     Y coordinate of the circle's centre.

              color colour (in)
                     The colour of the circle.


       $isoplot plot filled-circle xc yc radius colour
              Plot a circle filled with the given colour.

              float xc (in)
                     X coordinate of the circle's centre.

              float yc (in)
                     Y coordinate of the circle's centre.

              color colour (in)
                     The colour of the circle.

       There are a number of public procedures that may be useful in specific
       situations: Pro memorie.

COORDINATE TRANSFORMATIONS
       Besides the commands that deal with the plots and charts directly,
       there are a number of commands that can be used to convert world
       coordinates to pixels and vice versa.  These include:

       ::Plotchart::viewPort w pxmin pymin pxmax pymax
              Set the viewport for window w. Should be used in cooperation
              with ::Plotchart::worldCoordinates.

              widget w (in)
                     Name of the window (canvas widget) in question.

              float pxmin (in)
                     Left-most pixel coordinate.

              float pymin (in)
                     Top-most pixel coordinate (remember: the vertical pixel
                     coordinate starts with 0 at the top!).

              float pxmax (in)
                     Right-most pixel coordinate.

              float pymax (in)
                     Bottom-most pixel coordinate.


       ::Plotchart::worldCoordinates w xmin ymin xmax ymax
              Set the extreme world coordinates for window w. The world
              coordinates need not be in ascending order (i.e. xmin can be
              larger than xmax, so that a reversal of the x-axis is achieved).

              widget w (in)
                     Name of the window (canvas widget) in question.

              float xmin (in)
                     X-coordinate to be mapped to left side of viewport.

              float ymin (in)
                     Y-coordinate to be mapped to bottom of viewport.

              float xmax (in)
                     X-coordinate to be mapped to right side of viewport.

              float ymax (in)
                     Y-coordinate to be mapped to top side of viewport.


       ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
              Set the extreme three-dimensional world coordinates for window
              w. The world coordinates need not be in ascending order (i.e.
              xmin can be larger than xmax, so that a reversal of the x-axis
              is achieved).

              widget w (in)
                     Name of the window (canvas widget) in question.

              float xmin (in)
                     X-coordinate to be mapped to front side of the 3D
                     viewport.

              float ymin (in)
                     Y-coordinate to be mapped to left side of the viewport.

              float zmin (in)
                     Z-coordinate to be mapped to bottom of viewport.

              float xmax (in)
                     X-coordinate to be mapped to back side of viewport.

              float ymax (in)
                     Y-coordinate to be mapped to right side of viewport.

              float zmax (in)
                     Z-coordinate to be mapped to top side of viewport.


       ::Plotchart::coordsToPixel w x y
              Return a list of pixel coordinates valid for the given window.

              widget w (in)
                     Name of the window (canvas widget) in question.

              float x (in)
                     X-coordinate to be mapped.

              float y (in)
                     Y-coordinate to be mapped.


       ::Plotchart::coords3DToPixel w x y z
              Return a list of pixel coordinates valid for the given window.

              widget w (in)
                     Name of the window (canvas widget) in question.

              float x (in)
                     X-coordinate to be mapped.

              float y (in)
                     Y-coordinate to be mapped.

              float y (in)
                     Z-coordinate to be mapped.


       ::Plotchart::polarCoordinates w radmax
              Set the extreme polar coordinates for window w. The angle always
              runs from 0 to 360 degrees and the radius starts at 0. Hence you
              only need to give the maximum radius.  Note: If the viewport is
              not square, this procedure will not adjust the extremes, so that
              would result in an elliptical plot. The creation routine for a
              polar plot always determines a square viewport.

              widget w (in)
                     Name of the window (canvas widget) in question.

              float radmax (in)
                     Maximum radius.


       ::Plotchart::polarToPixel w rad phi
              Wrapper for a call to ::Plotchart::coordsToPixel, which assumes
              the world coordinates and viewport are set appropriately.
              Converts polar coordinates to pixel coordinates.  Note: To be
              useful it should be accompanied by a matching
              ::Plotchart::worldCoordinates procedure. This is automatically
              taken care of in the creation routine for polar plots.

              widget w (in)
                     Name of the window (canvas widget) in question.

              float rad (in)
                     Radius of the point.

              float phi (in)
                     Angle to the positive x-axis.


       ::Plotchart::pixelToCoords w x y
              Return a list of world coordinates valid for the given window.

              widget w (in)
                     Name of the window (canvas widget) in question.

              float x (in)
                     X-pixel to be mapped.

              float y (in)
                     Y-pixel to be mapped.

       ::Plotchart::pixelToIndex w x y
              Return the index of the pie segment containing the pixel
              coordinates (x,y)

              widget w (in)
                     Name of the window (canvas widget) in question, holding a
                     piechart.

              float x (in)
                     X-pixel to be mapped.

              float y (in)
                     Y-pixel to be mapped.

       Furthermore there is a routine to determine "pretty" numbers for use
       with an axis:

       ::Plotchart::determineScale xmin xmax inverted
              Determine "pretty" numbers from the given range and return a
              list containing the minimum, maximum and stepsize that can be
              used for a (linear) axis.

              float xmin (in)
                     Rough minimum value for the scaling

              float xmax (in)
                     Rough maximum value for the scaling.

              boolean inverted (in)
                     Optional argument: if 1, then the returned list produces
                     an inverted axis. Defaults to 0 (the axis will be from
                     minimum to maximum)

MISSING VALUES
       Often data that need to be plotted contain gaps - in a series of
       measurement data, they can occur because the equipment failed, a sample
       was not collected correctly or for many other reasons. The Plotchart
       handles these gaps by assuming that one or both coordinates of such
       data points are an empty string:


                  #
                  # Create the plot with its x- and y-axes
                  #
                  set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

                  foreach {x y} {0.0 32.0 10.0 {} 25.0 60.0 78.0 11.0 } {
                      $s plot series1 $x $y
                  }

       The effect varies according to the type of plot:

       o      For xy-plots, radial plots and strip charts the missing data
              point causes a gap in the line through the points.

       o      For barchats, missing values are treated as if a value of zero
              was given.

       o      For time charts and Gantt charts missing values cause errors -
              there is no use for them there.

OTHER OUTPUT FORMATS
       Besides output to the canvas on screen, the module is capable, via
       canvas postscript, of producing PostScript files. One may wonder
       whether it is possible to extend this set of output formats and the
       answer is "yes". This section tries to sum up the aspects of using this
       module for another sort of output.

       One way you can create output files in a different format, is by
       examining the contents of the canvas after everything has been drawn
       and render that contents in the right form. This is probably the
       easiest way, as it involves nothing more than the re-creation of all
       the elements in the plot that are already there.

       The drawback of that method is that you need to have a display, which
       is not always the case if you run a CGI server or something like that.

       An alternative is to emulate the canvas command. For this to work, you
       need to know which canvas subcommands are used and what for. Obviously,
       the create subcommand is used to create the lines, texts and other
       items. But also the raise and lower subcommands are used, because with
       these the module can influence the drawing order - important to
       simulate a clipping rectangle around the axes. (The routine DrawMask is
       responsible for this - if the output format supports proper clipping
       areas, then a redefinition of this routine might just solve this).

       Furthermore, the module uses the cget subcommand to find out the sizes
       of the canvas. A more mundane aspect of this is that the module
       currently assumes that the text is 14 pixels high and that 80 pixels in
       width suffice for the axis' labels. No "hook" is provided to customise
       this.

       In summary:

       o      Emulate the create subcommand to create all the items in the
              correct format

       o      Emulate the cget subcommand for the options -width and -height
              to allow the correct calculation of the rectangle's position and
              size

       o      Solve the problem of raising and lowering the items so that they
              are properly clipped, for instance by redefining the routine
              DrawMask.

       o      Take care of the currently fixed text size properties

SPECIAL EFFECTS
       As an example of some special effects you can achieve, here is the code
       for a plot where the area below the data line varies in colour:


              canvas .c  -background white -width 400 -height 200
              pack .c -fill both

              set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

              $s background gradient green top-down

              $s dataconfig series1 -filled up -fillcolour white

              $s plot series1  0.0 20.0
              $s plot series1 10.0 20.0
              $s plot series1 30.0 50.0
              $s plot series1 35.0 45.0
              $s plot series1 45.0 25.0
              $s plot series1 75.0 55.0
              $s plot series1 100.0 55.0

              $s plaintext 30.0 60.0 "Peak" south

       The trick is to fill the background with a colour that changes from
       green at the top to white at the bottom. Then the area above the data
       line is filled with a white polygon. Thus the green shading varies with
       the height of the line.

ROOM FOR IMPROVEMENT
       In this version there are a lot of things that still need to be
       implemented:

       o      More robust handling of incorrect calls (right now the
              procedures may fail when called incorrectly):

              o      The axis drawing routines can not handle inverse axes
                     right now.

              o      If the user provides an invalid date/time string, the
                     routines simply throw an error.

RESIZING
       Plotchart has not been designed to create plots and charts that keep
       track of the data that are put in. This means that if an application
       needs to allow the user to resize the window holding the plot or chart,
       it must take care to redraw the complete plot.

       The code below is a simple example of how to do that:


              package require Plotchart

              grid [canvas .c -background white] -sticky news
              grid columnconfigure . 0 -weight 1
              grid rowconfigure . 0 -weight 1

              bind .c <Configure> {doResize}

              proc doPlot {} {
                  #
                  # Clean up the contents (see also the note below!)
                  #
                  .c delete all

                  #
                  # (Re)draw the bar chart
                  #
                  set p [::Plotchart::createBarchart .c {x y z} {0 100 10} 3]
                  $p plot R {10 30 40} red
                  $p plot G {30 40 60} green
              }

              proc doResize {} {
                  global redo

                  #
                  # To avoid redrawing the plot many times during resizing,
                  # cancel the callback, until the last one is left.
                  #
                  if { [info exists redo] } {
                      after cancel $redo
                  }

                  set redo [after 50 doPlot]
              }
       Please note: The code above will work fine for barcharts and many other
       types of plots, but as Plotchart keeps some private information for xy
       plots, more is needed in these cases. This actually requires a command
       "destroyPlot" to take care of such details. A next version of Plotchart
       will have that.

ZOOMING IN
       As the Plotchart package does not keep track of the data itself,
       rescaling an existing plot - for instance when zooming in - would have
       to be done by redefining the plot and redrawing the data. However, the
       canvas widget offers a way out by scaling and moving items, so that
       zooming in becomes a bit simpler.

       Whether zooming is indeed useful, depends on the type of plot.
       Currently it is defined for XY-plots only. The method is called
       "rescale" and simply redraws the axes and scales and moves the data
       items so that they conform to the new axes. The drawback is that any
       symbols are scaled by the same amount. The rescale method works best
       for plots that only have lines, not symbols.

       The method works very simply:


                 $p rescale {newxmin newxmax newxstep} {newymin newymax newystep}


CONFIGURATION OPTIONS
       The command plotconfig can be used to set all manner of options. The
       syntax is:

       ::Plotchart::plotconfig charttype component property value
              Set a new value for the property of a component in a particular
              chart or plot type or query its current value. Each argument is
              optional.

              string charttype (in)
                     The type of chart or plot (see the configuration type
                     that is mentioned for each create command). If not given
                     or empty, a list of chart types is returned. If it is
                     given, the properties for that particular type are used.

              string component (in)
                     The component of the plot/chart: leftaxis, rightaxis,
                     background, margin and so on. If not given or empty, a
                     list of components is returned. If it is given, the
                     properties for that particular component will be set for
                     that particular type of chart.

              string property (in)
                     The property of the component of the plot/chart:
                     textcolor, thickness of the axis line, etc. If not given
                     or empty, a list of properties is returned. If it is
                     given, that particular property for that particular
                     component will be set for that particular type of chart.

              string value (in)
                     The new value for the property. If empty, the current
                     value is returned.  If the value is "default", the
                     default value will be restored.

                     Note, that in some cases an empty value is useful. Use
                     "none" in this case - it can be useful for colours and
                     for formats.

       Below is a more detailed list of the components and properties:

       o      Axes come in a wide variety:

              o      leftaxis, rightaxis, topaxis, bottomaxis for the plots
                     with a rectangular shape.

              o      xaxis, yaxis and zaxis are used for the 3D plots

              o      axis, this represents the radial and tangential axes of a
                     polar plot

              All axes have the following properties:

              o      color - the colour of the line and the tickmarks

              o      thickness - the width of the line of the axis itself, not
                     the tickmarks

              o      ticklength - the length of the tickmarks in pixels. A
                     positive value is outward, a negative value is inward.

              o      font - the font for the labels and the text at the axis

              o      format - the format for rendering the (numerical) labels.
                     For the time axis it is the format for a date and time.

              o      textcolor - the colour for the labels and the text.

       o      The margin is important for the layout. Currently only the
              rectangular plots allow the margins to be set: left, right, top
              and bottom.  The values are in pixels.

       o      The text component is meant for any text appearing via the
              plaintext subcommand. The properties are: textcolor, font and
              anchor (positioning of the text relative to the given
              coordinates).

       o      The background has two properties: outercolor, the colour
              outside of the actual plot, and innercolor, the colour inside
              the plot. (Note: only "outercolor" has now been implemented).

       o      The legend has three properties: background, border and
              position.  See the legend subcommand for the meaning.

       See the examples in plotdemos7.tcl for it use.

SCROLLING FOR TIMECHARTS AND GANTT CHARTS
       For two types of plots automatic scrolling management has been
       implemented: timecharts and Gantt charts. The subcommands hscroll and
       vscroll associate (existing) scrollbars to the plot, in much the same
       way as for text and canvas widgets.

       Once the association is made, the scrollbars are automatically updated
       if:

       o      You add an item with a period wider than the current one.

       o      You add a vertical line for a time beyond the current bounds.

       o      You add an extra item beyond the number that was used to create
              the chart.

       For instance:


              package require Plotchart

              canvas .c -width 400 -height 200
              scrollbar .y -orient vertical
              scrollbar .x -orient horizontal

              grid .c .y -sticky news
              grid .x    -sticky news

              source plotchart.tcl

              set s [::Plotchart::createTimechart .c "1 january 2004"  "31 december 2004" 4]

              $s period "Spring" "1 march 2004" "1 june 2004" green
              $s period "Summer" "1 june 2004" "1 september 2004" yellow
              $s vertline "1 jan" "1 january 2004"
              $s vertline "1 apr" "1 april 2004"
              $s vertline "1 jul" "1 july 2004"
              $s vertline "1 oct" "1 october 2004"
              $s vertline "1 jan" "1 january 2005"
              $s vertline "1 apr" "1 april 2005"
              $s vertline "1 jul" "1 july 2005"
              $s milestone "Longest day" "21 july 2004"
              $s milestone "Longest day 2" "21 july 2004"
              $s milestone "Longest day 3" "21 july 2004"
              $s milestone "Longest day 4" "21 july 2004"
              $s milestone "Longest day 5" "21 july 2004"
              $s milestone "Longest day 6" "21 july 2004"
              $s title "Seasons (northern hemisphere)"

              $s vscroll .y
              $s hscroll .x

       The original extent of the chart is from 1 january 2004 to 31 december
       2004. But because of the addition of vertical lines in 2005 and more
       items than was specified at the creation of the chart, both the
       horizontal and the vertical scrollbar will be enabled.

ARRANGING MULTIPLE PLOTS IN A CANVAS
       The command plotpack allows you to copy the contents of a plot into
       another canvas widget. This canvas widget does not act as a composite
       plot, but it can be saved as a PostScript file for instance: Note: the
       command simply takes a snapshot of the plots/charts as they are at that
       moment.

       ::Plotchart::plotpack w dir args
              Copy the contents of the plots/charts into another widget, in a
              manner similar to the pack geometry manager.

              widget w (in)
                     The name of the canvas widget to copy the plots/charts
                     into

              string dir (in)
                     The direction of the arrangement - top, left, bottom or
                     right

              list args (in)
                     List of plots/charts to be copied.

       For example:


                  set p1 [createXYPlot ...]
                  set p2 [createBarchart ...]

                  ... fill the plots ...

                  toplevel .t
                  pack [canvas .t.c2 -width ...]

                  #
                  # Copy the two plots above each other in the new canvas
                  #
                  plotpack .t.c2 top $p1 $p2


NOTES ON TAGS
       P.M.

TODO - SOME PRIVATE NOTES
       I have the following wishlist:

       o      Isometric plots - allow new items to be implemented easily.

       o      A general 3D viewer - emphasis on geometry, not a ray-tracer.

       o      Several improvements for boxplots:

              o      Height of the box scales with the logarithm of the number
                     of points

              o      Marker line to indicate a "current" value

              o      Box drawn from quantiles

KEYWORDS
       3D bars, 3D surfaces, bar charts, charts, coordinate transformations,
       coordinates, graphical presentation, isometric plots, pie charts,
       plotting, polar plots, strip charts, time charts, xy-plots

COPYRIGHT
       Copyright (c) 2007 Arjen Markus <arjenmarkus@users.sourceforge.net>




plotchart                             1.6                         Plotchart(n)
