'\"
'\" Generated from file './modules/plotchart/plotchart.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2007 Arjen Markus <arjenmarkus@users.sourceforge.net>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "Plotchart" 3tk 1.6 plotchart "Plotchart"
.BS
.SH NAME
Plotchart \- Simple plotting and charting package
.SH SYNOPSIS
package require \fBTcl  ?8.4?\fR
.sp
package require \fBTk  ?8.4?\fR
.sp
package require \fBPlotchart  ?1.6?\fR
.sp
\fB::Plotchart::createXYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
.sp
\fB::Plotchart::createStripchart\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
.sp
\fB::Plotchart::createTXPlot\fR \fIw\fR \fItimeaxis\fR \fIxaxis\fR
.sp
\fB::Plotchart::createXLogYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
.sp
\fB::Plotchart::createPolarPlot\fR \fIw\fR \fIradius_data\fR
.sp
\fB::Plotchart::createIsometricPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIstepsize\fR
.sp
\fB::Plotchart::createHistogram\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
.sp
\fB::Plotchart::create3DPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIzaxis\fR
.sp
\fB::Plotchart::createPiechart\fR \fIw\fR
.sp
\fB::Plotchart::createRadialchart\fR \fIw\fR \fInames\fR \fIscale\fR \fIstyle\fR
.sp
\fB::Plotchart::createBarchart\fR \fIw\fR \fIxlabels\fR \fIyaxis\fR \fInoseries\fR
.sp
\fB::Plotchart::createHorizontalBarchart\fR \fIw\fR \fIylabels\fR \fIxaxis\fR \fInoseries\fR
.sp
\fB::Plotchart::create3DBarchart\fR \fIw\fR \fIyaxis\fR \fInobars\fR
.sp
\fB::Plotchart::create3DRibbonChart\fR \fIw\fR \fInames\fR \fIyaxis\fR \fIzaxis\fR
.sp
\fB::Plotchart::createBoxplot\fR \fIw\fR \fIxaxis\fR \fIylabels\fR
.sp
\fB::Plotchart::createTimechart\fR \fIw\fR \fItime_begin\fR \fItime_end\fR \fIargs\fR
.sp
\fB::Plotchart::createGanttchart\fR \fIw\fR \fItime_begin\fR \fItime_end\fR \fIargs\fR
.sp
\fB::Plotchart::createRightAxis\fR \fIw\fR \fIyaxis\fR
.sp
\fB$anyplot\fR title \fItext\fR
.sp
\fB$anyplot\fR saveplot \fIfilename\fR \fIargs\fR
.sp
\fB$anyplot\fR xtext \fItext\fR
.sp
\fB$anyplot\fR ytext \fItext\fR
.sp
\fB$anyplot\fR xconfig \fB-option\fR \fIvalue\fR ...
.sp
\fB$anyplot\fR yconfig \fB-option\fR \fIvalue\fR ...
.sp
\fB$anyplot\fR background \fIpart\fR \fIcolour_or_image\fR \fIdir\fR
.sp
\fB$anyplot\fR xticklines \fIcolour\fR
.sp
\fB$anyplot\fR yticklines \fIcolour\fR
.sp
\fB$anyplot\fR legendconfig \fB-option\fR \fIvalue\fR ...
.sp
\fB$anyplot\fR legend \fIseries\fR \fItext\fR
.sp
\fB$anyplot\fR balloon \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
.sp
\fB$anyplot\fR balloonconfig \fIargs\fR
.sp
\fB$xyplot\fR plot \fIseries\fR \fIxcrd\fR \fIycrd\fR
.sp
\fB$xyplot\fR trend \fIseries\fR \fIxcrd\fR \fIycrd\fR
.sp
\fB$xyplot\fR rchart \fIseries\fR \fIxcrd\fR \fIycrd\fR
.sp
\fB$xyplot\fR interval \fIseries\fR \fIxcrd\fR \fIymin\fR \fIymax\fR ?ycentr?
.sp
\fB$xyplot\fR box-and-whiskers \fIseries\fR \fIxcrd\fR \fIycrd\fR
.sp
\fB$xyplot\fR vector \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIucmp\fR \fIvcmp\fR
.sp
\fB$xyplot\fR vectorconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
.sp
\fB$xyplot\fR dot \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIvalue\fR
.sp
\fB$xyplot\fR dotconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
.sp
\fB$xyplot\fR contourlines \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
.sp
\fB$xyplot\fR contourfill \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
.sp
\fB$xyplot\fR contourbox \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
.sp
\fB$xyplot\fR colorMap \fIcolours\fR
.sp
\fB$xyplot\fR grid \fIxcrd\fR \fIycrd\fR
.sp
\fB$polarplot\fR plot \fIseries\fR \fIradius\fR \fIangle\fR
.sp
\fB$plot3d\fR plotfunc \fIfunction\fR
.sp
\fB$plot3d\fR plotfuncont \fIfunction\fR \fIcontours\fR
.sp
\fB$plot3d\fR gridsize \fInxcells\fR \fInycells\fR
.sp
\fB$plot3d\fR plotdata \fIdata\fR
.sp
\fB$plot3d\fR colours \fIfill\fR \fIborder\fR
.sp
\fB$xyplot\fR dataconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
.sp
\fB$pie\fR plot \fIdata\fR
.sp
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR ...
.sp
\fB$radial\fR plot \fIdata\fR \fIcolour\fR \fIthickness\fR
.sp
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR ...
.sp
\fB$barchart\fR plot \fIseries\fR \fIydata\fR \fIcolour\fR
.sp
\fB$barchart\fR plot \fIseries\fR \fIxdata\fR \fIcolour\fR
.sp
\fB$barchart\fR plot \fIlabel\fR \fIyvalue\fR \fIcolour\fR
.sp
\fB$barchart\fR config \fB-option\fR \fIvalue\fR ...
.sp
\fB$ribbon\fR line \fIxypairs\fR \fIcolour\fR
.sp
\fB$ribbon\fR area \fIxypairs\fR \fIcolour\fR
.sp
\fB$boxplot\fR plot \fIlabel\fR \fIvalues\fR
.sp
\fB$timechart\fR period \fItext\fR \fItime_begin\fR \fItime_end\fR \fIcolour\fR
.sp
\fB$timechart\fR milestone \fItext\fR \fItime\fR \fIcolour\fR
.sp
\fB$timechart\fR vertline \fItext\fR \fItime\fR
.sp
\fB$timechart\fR hscroll \fIscrollbar\fR
.sp
\fB$timechart\fR vscroll \fIscrollbar\fR
.sp
\fB$ganttchart\fR task \fItext\fR \fItime_begin\fR \fItime_end\fR \fIcompleted\fR
.sp
\fB$ganttchart\fR milestone \fItext\fR \fItime\fR \fIcolour\fR
.sp
\fB$ganttchart\fR vertline \fItext\fR \fItime\fR
.sp
\fB$ganttchart\fR connect \fIfrom\fR \fIto\fR
.sp
\fB$ganttchart\fR summary \fItext\fR \fIargs\fR
.sp
\fB$ganttchart\fR color \fIkeyword\fR \fInewcolor\fR
.sp
\fB$ganttchart\fR font \fIkeyword\fR \fInewfont\fR
.sp
\fB$ganttchart\fR hscroll \fIscrollbar\fR
.sp
\fB$ganttchart\fR vscroll \fIscrollbar\fR
.sp
\fB$isoplot\fR plot rectangle \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR \fIcolour\fR
.sp
\fB$isoplot\fR plot filled-rectangle \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR \fIcolour\fR
.sp
\fB$isoplot\fR plot circle \fIxc\fR \fIyc\fR \fIradius\fR \fIcolour\fR
.sp
\fB$isoplot\fR plot filled-circle \fIxc\fR \fIyc\fR \fIradius\fR \fIcolour\fR
.sp
\fB::Plotchart::viewPort\fR \fIw\fR \fIpxmin\fR \fIpymin\fR \fIpxmax\fR \fIpymax\fR
.sp
\fB::Plotchart::worldCoordinates\fR \fIw\fR \fIxmin\fR \fIymin\fR \fIxmax\fR \fIymax\fR
.sp
\fB::Plotchart::world3DCoordinates\fR \fIw\fR \fIxmin\fR \fIymin\fR \fIzmin\fR \fIxmax\fR \fIymax\fR \fIzmax\fR
.sp
\fB::Plotchart::coordsToPixel\fR \fIw\fR \fIx\fR \fIy\fR
.sp
\fB::Plotchart::coords3DToPixel\fR \fIw\fR \fIx\fR \fIy\fR \fIz\fR
.sp
\fB::Plotchart::polarCoordinates\fR \fIw\fR \fIradmax\fR
.sp
\fB::Plotchart::polarToPixel\fR \fIw\fR \fIrad\fR \fIphi\fR
.sp
\fB::Plotchart::pixelToCoords\fR \fIw\fR \fIx\fR \fIy\fR
.sp
\fB::Plotchart::pixelToIndex\fR \fIw\fR \fIx\fR \fIy\fR
.sp
\fB::Plotchart::determineScale\fR \fIxmin\fR \fIxmax\fR \fIinverted\fR
.sp
\fB::Plotchart::plotconfig\fR \fIcharttype\fR \fIcomponent\fR \fIproperty\fR \fIvalue\fR
.sp
\fB::Plotchart::plotpack\fR \fIw\fR \fIdir\fR \fIargs\fR
.sp
.BE
.SH DESCRIPTION
.PP
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.
.PP
This results in the creation of an xy-plot in, say, ten lines of code:
.PP
.CS


    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"

.CE
.PP
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:
.IP \(bu
XY-plots like the one shown above with any number of data series.
.IP \(bu
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.
.IP \(bu
Polar plots, where the coordinates are polar instead of cartesian.
.IP \(bu
Histograms, for plotting statistical information.
.IP \(bu
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.
.sp
You can zoom in and out, as well as pan with these plots (\fINote:\fR
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.
.IP \(bu
Piecharts, with automatic scaling to indicate the proportions.
.IP \(bu
Barcharts, with either vertical or horizontal bars, stacked bars or
bars side by side.
.IP \(bu
Timecharts, where bars indicate a time period and milestones or other
important moments in time are represented by triangles.
.IP \(bu
3D plots (both for displaying surfaces and 3D bars)
.PP
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. \fBCONFIGURATION OPTIONS\fR)
.SH "PLOT CREATION COMMANDS"
You create the plot or chart with one single command and then fill the
plot with data:
.TP
\fB::Plotchart::createXYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new xy-plot (configuration type: xyplot).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (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 \fInegative\fR stepsize.
.TP
list \fIyaxis\fR (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 \fInegative\fR stepsize.
.RE
.sp
.TP
\fB::Plotchart::createStripchart\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
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.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
Note that an inverted x-axis is \fInot\fR supported for this type of plot.
.TP
list \fIyaxis\fR (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 \fInegative\fR stepsize.
.RE
.sp
.TP
\fB::Plotchart::createTXPlot\fR \fIw\fR \fItimeaxis\fR \fIxaxis\fR
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.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fItimeaxis\fR (in)
A 3-element list containing the minimum and maximum date/time to be
shown and the stepsize (\fIin days\fR) for the time-axis, in this order.
Note that an inverted time-axis is \fInot\fR supported.
.TP
list \fIxaxis\fR (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 \fInegative\fR stepsize.
.RE
.sp
.TP
\fB::Plotchart::createXLogYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new xy-plot where the y-axis has a logarithmic scale (configuration type: xlogyplot).
.sp
The data should be given as for a linear scale, as the logarithmic transformation
is taken of internally.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (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 \fInegative\fR stepsize.
.TP
list \fIyaxis\fR (in)
A 2-element list containing minimum and maximum for the y-axis, in this order.
Note that an inverted logarithmic axis is \fInot\fR supported.
.RE
.sp
.TP
\fB::Plotchart::createPolarPlot\fR \fIw\fR \fIradius_data\fR
Create a new polar plot (configuration type: polarplot).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIradius_data\fR (in)
A 2-element list containing maximum radius and stepsize for the radial
axis, in this order.
.RE
.sp
.TP
\fB::Plotchart::createIsometricPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIstepsize\fR
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).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 2-element list containing minimum, and maximum for the x-axis, in this order.
.TP
list \fIyaxis\fR (in)
A 2-element list containing minimum, and maximum for the y-axis, in this order.
.TP
float|\fBnoaxes\fR \fIstepsize\fR (in)
Either the stepsize used by both axes or the keyword \fBnoaxes\fR to
signal the plot that it should use the full area of the widget, to not
draw any of the axes.
.RE
.sp
.TP
\fB::Plotchart::createHistogram\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new histogram (configuration type: histogram).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.RE
.sp
.TP
\fB::Plotchart::create3DPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIzaxis\fR
Create a new 3D plot.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.TP
list \fIzaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order.
.RE
.sp
.TP
\fB::Plotchart::createPiechart\fR \fIw\fR
Create a new piechart (configuration type: piechart).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.RE
.sp
.TP
\fB::Plotchart::createRadialchart\fR \fIw\fR \fInames\fR \fIscale\fR \fIstyle\fR
Create a new radial chart (the data are drawn as a line connecting the
spokes of the diagram) (configuration type: radialchart).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fInames\fR (in)
Names for the spokes.
.TP
float \fIscale\fR (in)
Scale value to determine the position of the data along the spokes.
.TP
float \fIstyle\fR (in)
Style of the chart (optional). One of:
.RS
.IP \(bu
\fIlines\fR - the default: draw the data as independent polylines.
.IP \(bu
\fIcumulative\fR - draw the data as polylines where the data are
accumulated.
.IP \(bu
\fIfilled\fR - draw the data as filled polygons where the data are
accumulated
.RE
.RE
.sp
.TP
\fB::Plotchart::createBarchart\fR \fIw\fR \fIxlabels\fR \fIyaxis\fR \fInoseries\fR
Create a new barchart with vertical bars (configuration type: vertbars). The horizontal axis will
display the labels contained in the argument \fIxlabels\fR. The number
of series given by \fInoseries\fR determines both the width of the
bars, and the way the series will be drawn.
.sp
If the keyword \fBstacked\fR 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.
.sp
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.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxlabels\fR (in)
List of labels for the x-axis. Its length also determines the number of
bars that will be plotted per series.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.TP
int|\fBstacked\fR \fInoseries\fR (in)
The number of data series that will be plotted. This has to be an
integer number greater than zero (if \fBstacked\fR is not used).
.RE
.sp
.TP
\fB::Plotchart::createHorizontalBarchart\fR \fIw\fR \fIylabels\fR \fIxaxis\fR \fInoseries\fR
Create a new barchart with horizontal bars (configuration type: horizbars). The vertical axis will
display the labels contained in the argument \fIylabels\fR. The number
of series given by \fInoseries\fR determines both the width of the
bars, and the way the series will be drawn.
.sp
If the keyword \fBstacked\fR was specified the series will be drawn
stacked from left to right. Otherwise each series that is drawn will
be drawn shifted upward.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIylabels\fR (in)
List of labels for the y-axis. Its length also determines the number of
bars that will be plotted per series.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
.TP
int|\fBstacked\fR \fInoseries\fR (in)
The number of data series that will be plotted. This has to be an
integer number greater than zero (if \fBstacked\fR is not used).
.RE
.sp
.TP
\fB::Plotchart::create3DBarchart\fR \fIw\fR \fIyaxis\fR \fInobars\fR
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 \fInobars\fR
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.)
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.TP
int \fInobars\fR (in)
The number of bars that will be plotted.
.RE
.sp
.TP
\fB::Plotchart::create3DRibbonChart\fR \fIw\fR \fInames\fR \fIyaxis\fR \fIzaxis\fR
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.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
widget \fIw\fR (in)
Names of the series, plotted as labels along the x-axis
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis
(drawn horizontally!), in this order.
.TP
list \fIzaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis
(drawn vertically), in this order.
.TP
int \fInobars\fR (in)
The number of bars that will be plotted.
.RE
.sp
.TP
\fB::Plotchart::createBoxplot\fR \fIw\fR \fIxaxis\fR \fIylabels\fR
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).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.TP
list \fIylabels\fR (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.
.RE
.sp
.TP
\fB::Plotchart::createTimechart\fR \fIw\fR \fItime_begin\fR \fItime_end\fR \fIargs\fR
Create a new timechart (configuration type: timechart).
The time axis (= x-axis) goes from \fItime_begin\fR to \fItime_end\fR,
and the vertical spacing is determined by the number of items to plot.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
string \fItime_begin\fR (in)
The start time given in a form that is recognised by the \fBclock scan\fR
command (e.g. "1 january 2004").
.TP
string \fItime_end\fR (in)
The end time given in a form that is recognised by the \fBclock scan\fR
command (e.g. "1 january 2004").
.TP
arguments \fIargs\fR (in)
The remaining arguments can be:
.RS
.IP \(bu
The expected/maximum number of items. This determines the vertical
spacing. (If given, it must be the first argument after "time_end"
.IP \(bu
The keyword -barheight and the number of pixels per bar. This is an
alternative method to determine the vertical spacing.
.IP \(bu
The keyword -ylabelwidth and the number of pixels to reserve for the
labels at the y-axis.
.RE
.RE
.TP
\fB::Plotchart::createGanttchart\fR \fIw\fR \fItime_begin\fR \fItime_end\fR \fIargs\fR
Create a new Gantt chart (configuration type: ganttchart).
The time axis (= x-axis) goes from \fItime_begin\fR to \fItime_end\fR,
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.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
string \fItime_begin\fR (in)
The start time given in a form that is recognised by the \fBclock scan\fR
command (e.g. "1 january 2004").
.TP
string \fItime_end\fR (in)
The end time given in a form that is recognised by the \fBclock scan\fR
command (e.g. "1 january 2004").
.TP
arguments \fIargs\fR (in)
The remaining arguments can be:
.RS
.IP \(bu
The expected/maximum number of items. This determines the vertical
spacing. (If given this way, it must be the first argument after "time_end")
.IP \(bu
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").
.IP \(bu
The keyword -barheight and the number of pixels per bar. This is an
alternative method to determine the vertical spacing.
.IP \(bu
The keyword -ylabelwidth and the number of pixels to reserve for the
labels at the y-axis.
.RE
.RE
.TP
\fB::Plotchart::createRightAxis\fR \fIw\fR \fIyaxis\fR
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 \fIleft\fR
axis, use the original plot command.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.RE
.sp
.PP
.SH "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.
.PP
General subcommands for all types of charts. $anyplot is the command
returned by the creation command:
.TP
\fB$anyplot\fR title \fItext\fR
Specify the title of the whole chart.
.RS
.TP
string \fItext\fR (in)
The text of the title to be drawn.
.RE
.sp
.TP
\fB$anyplot\fR saveplot \fIfilename\fR \fIargs\fR
Draws the plot into a file, using PostScript.
.RS
.TP
string \fIfilename\fR (in)
Contain the path name of the file to write the plot to.
.TP
list \fIargs\fR (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.
.sp
\fINote:\fR
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.
.sp
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.
.RE
.sp
.TP
\fB$anyplot\fR xtext \fItext\fR
Specify the title of the (horizontal) x-axis, for those plots that have
a straight x-axis.
.RS
.TP
string \fItext\fR (in)
The text of the x-axis label to be drawn.
.RE
.sp
.TP
\fB$anyplot\fR ytext \fItext\fR
Specify the title of the (horizontal) y-axis, for those plots that have
a straight y-axis.
.RS
.TP
string \fItext\fR (in)
The text of the y-axis label to be drawn.
.RE
.sp
.TP
\fB$anyplot\fR xconfig \fB-option\fR \fIvalue\fR ...
Set one or more configuration parameters for the x-axis.
The following options are supported:
.RS
.TP
\fBformat\fR fmt
The format for the numbers along the axis.
.TP
\fBticklength\fR length
The length of the tickmarks (in pixels).
.TP
\fBticklines\fR boolean
Whether to draw ticklines (\fBtrue\fR) or not (\fBfalse\fR).
.TP
\fBscale\fR 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.
.sp
\fIBeware:\fR Setting this option will clear all data from the plot.
.RE
.sp
.TP
\fB$anyplot\fR yconfig \fB-option\fR \fIvalue\fR ...
Set one or more configuration parameters for the y-axis. This method
accepts the same options and values as the method \fBxconfig\fR.
.TP
\fB$anyplot\fR background \fIpart\fR \fIcolour_or_image\fR \fIdir\fR
Set the background of a part of the plot
.RS
.TP
string \fIpart\fR
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:
.RS
.IP \(bu
\fIimage\fR, in which case a predefined image is loaded
into the background of the plot.
.IP \(bu
\fIgradient\fR, 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.
.RE
.TP
string \fIcolour_or_image\fR
Colour for that part or the name of the image if "part" is "image"
.TP
string \fIdir\fR
The direction of the gradient. One of: top-down, bottom-up, left-right
or right-left.
.RE
.sp
.TP
\fB$anyplot\fR xticklines \fIcolour\fR
Draw vertical ticklines at each tick location
.RS
.TP
string \fIcolour\fR
Colour of the lines. Specifying an empty colour ("") removes them again.
Defaults to "black"
.RE
.sp
.TP
\fB$anyplot\fR yticklines \fIcolour\fR
Draw horizontal ticklines at each tick location
.RS
.TP
string \fIcolour\fR
Colour of the lines. Specifying an empty colour ("") removes them again
Defaults to "black"
.RE
.sp
.TP
\fB$anyplot\fR legendconfig \fB-option\fR \fIvalue\fR ...
Set one or more options for the legend. The legend is drawn as a
rectangle with text and graphics inside.
.RS
.TP
\fBbackground\fR colour
Set the colour of the background (the default colour is white).
Set to the empty string for a transparant legend.
.TP
\fBborder\fR colour
Set the colour of the border (the default colour is white). Set to the
empty string if you do not want a border.
.TP
\fBcanvas\fR c
Draw the legend in a different canvas widget. This gives you the freedom
to position the legend outside the actual plot.
.TP
\fBposition\fR 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.)
.RE
.sp
.TP
\fB$anyplot\fR legend \fIseries\fR \fItext\fR
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.)
.RS
.TP
string \fIseries\fR
Name of the data series. This determines the colour of the line and the
symbol (if any) that will be drawn.
.TP
string \fItext\fR
Text to be drawn next to the line/symbol.
.RE
.sp
.TP
\fB$anyplot\fR balloon \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
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.
.RS
.TP
float \fIx\fR
X-coordinate of the point that the arrow of the balloon will point to.
.TP
float \fIy\fR
Y-coordinate of the point that the arrow of the balloon will point to.
.TP
string \fItext\fR
Text to be drawn in the balloon.
.TP
string \fIdir\fR
Direction of the arrow, one of: north, north-east, east, south-east,
south, south-west, west or north-west.
.RE
.sp
.TP
\fB$anyplot\fR balloonconfig \fIargs\fR
Configure the balloon text for the plot. The new settings will be used
for the next balloon text.
.RS
.TP
\fBfont\fR fontname
Font to be used for the text
.TP
\fBjustify\fR left|center|right
Way to justify multiline text
.TP
\fBtextcolour\fR colour
Colour for the text (synonym: textcolor)
.TP
\fBbackground\fR colour
Background colour for the balloon
.TP
\fBoutline\fR colour
Colour of the outline of the balloon
.TP
\fBmargin\fR value
Margin around the text (in pixels)
.TP
\fBrimwidth\fR value
Width of the outline of the balloon (in pixels)
.TP
\fBarrowsize\fR value
Length factor for the arrow (in pixels)
.RE
.sp
.PP
.PP
\fINote:\fR The commands \fBxconfig\fR and \fByconfig\fR are
currently implemented only for XY-plots
and only the option \fB-format\fR has any effect.
.PP
For \fIxy plots\fR, \fIstripcharts\fR, \fIhistograms\fR and
\fItime-x-plots\fR:
.TP
\fB$xyplot\fR plot \fIseries\fR \fIxcrd\fR \fIycrd\fR
Add a data point to the plot.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the new point belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new point. (For time-x plots this must be valid
date/time that can be read with the \fIclock scan\fR command).
.TP
float \fIycrd\fR (in)
Y-coordinate of the new point.
.RE
.PP
.PP
\fINote on histograms:\fR
.PP
For histograms the x-coordinate that is given is interpreted to be
the x-coordinate of the \fIright\fR 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.
.PP
For \fIxy plots\fR:
.TP
\fB$xyplot\fR trend \fIseries\fR \fIxcrd\fR \fIycrd\fR
Draw or update a trend line using the data given sofar.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the trend line belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new data point
.TP
float \fIycrd\fR (in)
Y-coordinate of the new data point
.RE
.TP
\fB$xyplot\fR rchart \fIseries\fR \fIxcrd\fR \fIycrd\fR
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.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the data point belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new data point
.TP
float \fIycrd\fR (in)
Y-coordinate of the new data point
.RE
.TP
\fB$xyplot\fR interval \fIseries\fR \fIxcrd\fR \fIymin\fR \fIymax\fR ?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.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the interval belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the interval
.TP
float \fIymin\fR (in)
Minimum y-coordinate of the interval.
.TP
float \fIymax\fR (in)
Maximum y-coordinate of the interval.
.TP
float \fIycentr\fR (in)
Y-coordinate to draw the symbol at (optional)
.RE
.TP
\fB$xyplot\fR box-and-whiskers \fIseries\fR \fIxcrd\fR \fIycrd\fR
Draw a box and whiskers in the plot. If the argument \fIxcrd\fR is a
list of
several values and the argument \fIycrd\fR is a single value, a
horizontal
box is drawn with the quartiles determined from the list of values
contained in \fIxcrd\fR.
.sp
If, instead, the argument \fIycrd\fR contains a list of several values
and the argument \fIxcrd\fR a single value, then a vertical box is
drawn and the quartiles are determined from \fIycrd\fR. (There must be
exactly one list of several values. Otherwise an error is reported.)
.sp
The option -boxwidth (default: 10 pixels) determines the width (or
height) of the box.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the box-and-whiskers belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the box or a list of values.
.TP
float \fIymin\fR (in)
Y-coordinate of the box or a list of values.
.RE
.TP
\fB$xyplot\fR vector \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIucmp\fR \fIvcmp\fR
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)
.RS
.TP
string \fIseries\fR (in)
Name of the series the vector belongs to. Determines the appearance and
interpretation.
.TP
float \fIxcrd\fR (in)
X-coordinate of the point where the arrow appears
.TP
float \fIycrd\fR (in)
Y-coordinate of the point where the arrow appears
.TP
float \fIucmp\fR (in)
X-component or the length of the vector
.TP
float \fIycentr\fR (in)
Y-component or the angle of the vector
.RE
.TP
\fB$xyplot\fR vectorconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
]
Set the vector drawing options for a particular series
.RS
.TP
string \fIseries\fR (in)
Name of the series the vector belongs to.
.RE
.IP
The options can be one of the following:
.RS
.TP
\fBcolour\fR
The colour of the arrow (default: black; synonym: color)
.TP
\fBscale\fR value
The scale factor used to convert the length of the
arrow into a number of pixels (default: 1.0)
.TP
\fBcentred\fR 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)
.TP
\fBtype\fR 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").
.RE
.sp
.TP
\fB$xyplot\fR dot \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIvalue\fR
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)
.RS
.TP
string \fIseries\fR (in)
Name of the series the dot belongs to. Determines size and colour
.TP
float \fIxcrd\fR (in)
X-coordinate of the point where the arrow appears
.TP
float \fIycrd\fR (in)
Y-coordinate of the point where the arrow appears
.TP
float \fIvalue\fR (in)
Value determining size and colour
.RE
.TP
\fB$xyplot\fR dotconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
]
Set the dot drawing options for a particular series
.RS
.TP
string \fIseries\fR (in)
Name of the series the dot belongs to.
.RE
.IP
The options can be one of the following:
.RS
.TP
\fBcolour\fR
The colour of the dot if no scaling is used or the value exceeds the
last limit of the classes.
.TP
\fBscale\fR value
The scale factor used to convert the value into the radius of the dot
in pixels (default: 1.0)
.TP
\fBradius\fR value
The default radius of the dots, used if there is no scaling by value
(in pixels; default: 3)
.TP
\fBscalebyvalue\fR onoff
Determines whether the dots all have the same size or a size depending
on the given value (default: on).
.TP
\fBoutline\fR onoff
Draw a black circle around the dot or not (default: on)
.TP
\fBclasses\fR list
Set the limits and the corresponding colours. For instance:
.CS


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

.CE
.IP
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.
.sp
If there is no list of classes for the particular series, the dots are
scaled by the value.
.sp
You can combine the colouring by value and the scaling by value by
setting a list of classes and setting the \fIscalebyvalue\fR option on.
.RE
.sp
.TP
\fB$xyplot\fR contourlines \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?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.
.RS
.TP
list \fIxcrd\fR (in)
List of lists, each value is an x-coordinate for a grid cell corner
.TP
list \fIycrd\fR (in)
List of lists, each value is an y-coordinate for a grid cell corner
.TP
list \fIvalues\fR (in)
List of lists, each value is the value at a grid cell corner
.TP
list \fIclasses\fR (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.
.sp
\fINote:\fR The class values must enclose the whole range of values.
.sp
.RE
.TP
\fB$xyplot\fR contourfill \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
Draw filled contours for the values given on the grid. (The use of this
method is identical to the "contourlines" method).
.TP
\fB$xyplot\fR contourbox \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
Draw the cells as filled quadrangles. The colour is determined from
the average of the values on all four corners.
.TP
\fB$xyplot\fR colorMap \fIcolours\fR
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).
.RS
.TP
list \fIcolours\fR (in)
List of colour names or colour values or one of the predefined maps:
.RS
.IP \(bu
grey or gray: gray colours from dark to light
.IP \(bu
jet: rainbow colours
.IP \(bu
hot: colours from yellow via red to darkred
.IP \(bu
cool: colours from cyan via blue to magenta
.RE
.RE
.TP
\fB$xyplot\fR grid \fIxcrd\fR \fIycrd\fR
Draw the grid cells as lines connecting the (valid) grid points.
.RS
.TP
list \fIxcrd\fR (in)
List of lists, each value is an x-coordinate for a grid cell corner
.TP
list \fIycrd\fR (in)
List of lists, each value is an y-coordinate for a grid cell corner
.RE
.PP
.PP
For \fIpolar plots\fR:
.TP
\fB$polarplot\fR plot \fIseries\fR \fIradius\fR \fIangle\fR
Add a data point to the polar plot.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the new point belongs to.
.TP
float \fIradius\fR (in)
Radial coordinate of the new point.
.TP
float \fIangle\fR (in)
Angular coordinate of the new point (in degrees).
.RE
.PP
.PP
For \fI3D plots\fR:
.TP
\fB$plot3d\fR plotfunc \fIfunction\fR
Plot a function defined over two variables \fBx\fR and \fBy\fR.
The resolution is determined by the set grid sizes (see the method
\fBgridsize\fR for more information).
.RS
.TP
string \fIfunction\fR (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.
.RE
.sp
.TP
\fB$plot3d\fR plotfuncont \fIfunction\fR \fIcontours\fR
Plot a function defined over two variables \fBx\fR and \fBy\fR using
the contour levels in \fBcontours\fR to colour the surface.
The resolution is determined by the set grid sizes (see the method
\fBgridsize\fR for more information).
.RS
.TP
string \fIfunction\fR (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.
.TP
list \fIcontours\fR (in)
List of values in ascending order that represent the contour levels
(the boundaries between the colours in the contour map).
.RE
.sp
.TP
\fB$plot3d\fR gridsize \fInxcells\fR \fInycells\fR
Set the grid size in the two directions. Together they determine how
many polygons will be drawn for a function plot.
.RS
.TP
int \fInxcells\fR (in)
Number of grid cells in x direction. Has to be an integer number
greater than zero.
.TP
int \fInycells\fR (in)
Number of grid cells in y direction. Has to be an integer number
greater than zero.
.RE
.sp
.TP
\fB$plot3d\fR plotdata \fIdata\fR
Plot a matrix of data.
.RS
.TP
list \fIdata\fR (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:
.sp
.CS


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

.CE
.RE
.sp
.TP
\fB$plot3d\fR colours \fIfill\fR \fIborder\fR
Configure the colours to use for polygon borders and inner area.
.RS
.TP
color \fIfill\fR (in)
The colour to use for filling the polygons.
.TP
color \fIborder\fR (in)
The colour to use for the border of the polygons.
.RE
.PP
.PP
For \fIxy plots\fR, \fIstripcharts\fR and \fIpolar plots\fR:
.TP
\fB$xyplot\fR dataconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
Set the value for one or more options regarding the drawing of data of
a specific series.
.RS
.TP
string \fIseries\fR (in)
Name of the data series whose configuration we are changing.
.RE
.sp
The following options are allowed:
.RS
.TP
\fBcolour\fR c
.TP
\fBcolor\fR c
The colour to be used when drawing the data series.
.TP
\fBtype\fR enum
The drawing mode chosen for the series.
This can be one of \fBline\fR, \fBsymbol\fR, or \fBboth\fR.
.TP
\fBsymbol\fR enum
What kind of symbol to draw. The value of this option is ignored when
the drawing mode \fBline\fR was chosen. This can be one of
\fBplus\fR, \fBcross\fR, \fBcircle\fR, \fBup\fR (triangle
pointing up), \fBdown\fR (triangle pointing down), \fBdot\fR
(filled circle), \fBupfilled\fR or \fBdownfilled\fR (filled
triangles).
.TP
\fBfilled\fR enum
Whether to fill the area above or below the data line or not. Can be one
of: \fBno\fR, \fBup\fR or \fBdown\fR (\fBSPECIAL EFFECTS\fR)
.TP
\fBfillcolour\fR colour
Colour to use when filling the area associated with the data line.
.RE
.PP
.PP
For \fIpiecharts\fR:
.TP
\fB$pie\fR plot \fIdata\fR
Fill a piechart.
.RS
.TP
list \fIdata\fR (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.
.RE
.TP
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR ...
Set the colours to be used.
.RS
.TP
color \fIcolour1\fR (in)
The first colour.
.TP
color \fIcolour2\fR (in)
The second colour, and so on.
.RE
.PP
.PP
For \fIradial charts\fR:
.TP
\fB$radial\fR plot \fIdata\fR \fIcolour\fR \fIthickness\fR
Draw a new line in the radial chart
.RS
.TP
list \fIdata\fR (in)
A list of data (one for each spoke). The values determine the distance
from the centre of the line connecting the spokes.
.TP
color \fIcolour\fR (in)
The colour for the line.
.TP
int \fIthickness\fR (in)
An optional argument for the thickness of the line.
.RE
.TP
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR ...
Set the colours to be used.
.RS
.TP
color \fIcolour1\fR (in)
The first colour.
.TP
color \fIcolour2\fR (in)
The second colour, and so on.
.RE
.PP
.PP
For \fIvertical barcharts\fR:
.TP
\fB$barchart\fR plot \fIseries\fR \fIydata\fR \fIcolour\fR
Add a data series to a barchart.
.RS
.TP
string \fIseries\fR (in)
Name of the series the values belong to.
.TP
list \fIydata\fR (in)
A list of values, one for each x-axis label.
.TP
color \fIcolour\fR (in)
The colour of the bars.
.RE
.PP
.PP
For \fIhorizontal barcharts\fR:
.TP
\fB$barchart\fR plot \fIseries\fR \fIxdata\fR \fIcolour\fR
Add a data series to a barchart.
.RS
.TP
string \fIseries\fR (in)
Name of the series the values belong to.
.TP
list \fIxdata\fR (in)
A list of values, one for each y-axis label.
.TP
color \fIcolour\fR (in)
The colour of the bars.
.RE
.PP
.PP
For \fI3D barcharts\fR:
.TP
\fB$barchart\fR plot \fIlabel\fR \fIyvalue\fR \fIcolour\fR
Add the next bar to the barchart.
.RS
.TP
string \fIlabel\fR (in)
The label to be shown below the column.
.TP
float \fIyvalue\fR (in)
The value that determines the height of the column
.TP
color \fIcolour\fR (in)
The colour of the column.
.RE
.TP
\fB$barchart\fR config \fB-option\fR \fIvalue\fR ...
Set one or more configuration parameters. The following options are
supported:
.RS
.TP
\fBusebackground\fR boolean
Whether to draw walls to the left and to the back of the columns or not
.TP
\fBuseticklines\fR boolean
Whether to draw ticklines on the walls or not
.TP
\fBshowvalues\fR boolean
Whether to show the values or not
.TP
\fBlabelfont\fR newfont
Name of the font to use for labels
.TP
\fBlabelcolour\fR colour
Colour for the labels
.TP
\fBvaluefont\fR newfont
Name of the font to use for the values
.TP
\fBvaluecolour\fR colour
Colour for the values
.RE
.PP
.PP
For \fI3D ribbon charts\fR:
.TP
\fB$ribbon\fR line \fIxypairs\fR \fIcolour\fR
Plot the given xy-pairs as a ribbon in the chart
.RS
.TP
list \fIxypairs\fR (in)
The pairs of x/y values to be drawn (the series is drawn as a whole)
.TP
color \fIcolour\fR (in)
The colour of the ribbon.
.RE
.TP
\fB$ribbon\fR area \fIxypairs\fR \fIcolour\fR
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.
.RS
.TP
list \fIxypairs\fR (in)
The pairs of x/y values to be drawn (the series is drawn as a whole)
.TP
color \fIcolour\fR (in)
The colour of the ribbon/area.
.RE
.PP
For \fIboxplots\fR:
.TP
\fB$boxplot\fR plot \fIlabel\fR \fIvalues\fR
Add a box-and-whisker to the plot.
.RS
.TP
string \fIlabel\fR (in)
The label along the y-axis to which the data belong
.TP
list \fIvalues\fR (in)
List of raw values, the extent of the box and the whiskers will be
determined from this list.
.RE
.PP
For \fItimecharts\fR:
.TP
\fB$timechart\fR period \fItext\fR \fItime_begin\fR \fItime_end\fR \fIcolour\fR
Add a time period to the chart.
.RS
.TP
string \fItext\fR (in)
The text describing the period.
.TP
string \fItime_begin\fR (in)
Start time of the period.
.TP
string \fItime_end\fR (in)
Stop time of the period.
.TP
color \fIcolour\fR (in)
The colour of the bar (defaults to black).
.RE
.sp
.TP
\fB$timechart\fR milestone \fItext\fR \fItime\fR \fIcolour\fR
Add a \fImilestone\fR (represented as an point-down triangle) to the
chart.
.RS
.TP
string \fItext\fR (in)
The text describing the milestone.
.TP
string \fItime\fR (in)
Time at which the milestone must be positioned.
.TP
color \fIcolour\fR (in)
The colour of the triangle (defaults to black).
.RE
.sp
.TP
\fB$timechart\fR vertline \fItext\fR \fItime\fR
Add a vertical line (to indicate the start of the month for instance)
to the chart.
.RS
.TP
string \fItext\fR (in)
The text appearing at the top (an abbreviation of the
date/time for instance).
.TP
string \fItime\fR (in)
Time at which the line must be positioned.
.RE
.TP
\fB$timechart\fR hscroll \fIscrollbar\fR
Connect a horizontal scrollbar to the chart. See also the section on
scrolling.
.RS
.TP
widget \fIscrollbar\fR (in)
The horizontal scrollbar that is to be connected to the chart
.RE
.TP
\fB$timechart\fR vscroll \fIscrollbar\fR
Connect a vertical scrollbar to the chart. See also the section on
scrolling.
.RS
.TP
widget \fIscrollbar\fR (in)
The vertical scrollbar that is to be connected to the chart
.RE
.PP
.PP
For \fIGantt charts\fR:
.TP
\fB$ganttchart\fR task \fItext\fR \fItime_begin\fR \fItime_end\fR \fIcompleted\fR
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.
.RS
.TP
string \fItext\fR (in)
The text describing the task.
.TP
string \fItime_begin\fR (in)
Start time of the task.
.TP
string \fItime_end\fR (in)
Stop time of the task.
.TP
float \fIcompleted\fR (in)
The percentage of the task that is completed.
.RE
.sp
.TP
\fB$ganttchart\fR milestone \fItext\fR \fItime\fR \fIcolour\fR
Add a \fImilestone\fR (represented as an point-down triangle) to the
chart.
.RS
.TP
string \fItext\fR (in)
The text describing the milestone.
.TP
string \fItime\fR (in)
Time at which the milestone must be positioned.
.TP
color \fIcolour\fR (in)
The colour of the triangle (defaults to black).
.RE
.sp
.TP
\fB$ganttchart\fR vertline \fItext\fR \fItime\fR
Add a vertical line (to indicate the start of the month for instance)
to the chart.
.RS
.TP
string \fItext\fR (in)
The text appearing at the top (an abbreviation of the
date/time for instance).
.TP
string \fItime\fR (in)
Time at which the line must be positioned.
.RE
.sp
.TP
\fB$ganttchart\fR connect \fIfrom\fR \fIto\fR
Add an arrow that connects the \fIfrom\fR task with the \fIto\fR task.
.RS
.TP
list \fIfrom\fR (in)
The list of items returned by the "task" command that represents the
task from which the arrow starts.
.TP
string \fItext\fR (in)
The text summarising the tasks
.TP
list \fIargs\fR (in)
One or more tasks (the lists returned by the "task" command). They are
shifted down to make room for the summary.
.TP
list \fIto\fR (in)
The list of items returned by the "task" command that represents the
task at which the arrow ends.
.RE
.sp
.TP
\fB$ganttchart\fR summary \fItext\fR \fIargs\fR
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.
.sp
Use this command before connecting the tasks, as the arrow would not be
shifted down!
.RS
.TP
string \fItext\fR (in)
The text summarising the tasks
.TP
list \fIargs\fR (in)
One or more tasks (the lists returned by the "task" command). They are
shifted down to make room for the summary.
.RE
.sp
.TP
\fB$ganttchart\fR color \fIkeyword\fR \fInewcolor\fR
Set the colour of a part of the Gantt chart. These colours hold for all
items of that type.
.RS
.TP
string \fIkeyword\fR (in)
The keyword indicates which part of the Gantt chart to change:
.RS
.IP \(bu
description - the colour of the descriptive text
.IP \(bu
completed - the colour of the filled bar representing the completed part
of a task
.IP \(bu
left - the colour for the part that is not yet completed
.IP \(bu
odd - the background colour for the odd entries
.IP \(bu
even - the background colour for the even entries
.IP \(bu
summary - the colour for the summary text
.IP \(bu
summarybar - the colour for the bar for a summary
.RE
.TP
string \fInewcolor\fR (in)
The new colour for the chosen items.
.RE
.sp
.TP
\fB$ganttchart\fR font \fIkeyword\fR \fInewfont\fR
Set the font of a part of the Gantt chart. These fonts hold for all
items of that type.
.RS
.TP
string \fIkeyword\fR (in)
The keyword indicates which part of the Gantt chart to change:
.RS
.IP \(bu
description - the font used for descriptive text
.IP \(bu
summary - the font used for summaries
.IP \(bu
scale - the font used for the time scale
.RE
.TP
string \fInewfont\fR (in)
The new font for the chosen items.
.RE
.TP
\fB$ganttchart\fR hscroll \fIscrollbar\fR
Connect a horizontal scrollbar to the chart. See also the section on
scrolling.
.RS
.TP
widget \fIscrollbar\fR (in)
The horizontal scrollbar that is to be connected to the chart
.RE
.TP
\fB$ganttchart\fR vscroll \fIscrollbar\fR
Connect a vertical scrollbar to the chart. See also the section on
scrolling.
.RS
.TP
widget \fIscrollbar\fR (in)
The vertical scrollbar that is to be connected to the chart
.RE
.PP
.PP
For \fIisometric plots\fR (to be extended):
.TP
\fB$isoplot\fR plot rectangle \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR \fIcolour\fR
Plot the outlines of a rectangle.
.RS
.TP
float \fIx1\fR (in)
Minimum x coordinate of the rectangle to be drawn.
.TP
float \fIy1\fR (in)
Minimum y coordinate of the rectangle.
.TP
float \fIx2\fR (in)
Maximum x coordinate of the rectangle to be drawn.
.TP
float \fIy2\fR (in)
Maximum y coordinate of the rectangle.
.TP
color \fIcolour\fR (in)
The colour of the rectangle.
.RE
.sp
.TP
\fB$isoplot\fR plot filled-rectangle \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR \fIcolour\fR
Plot a rectangle filled with the given colour.
.RS
.TP
float \fIx1\fR (in)
Minimum x coordinate of the rectangle to be drawn.
.TP
float \fIy1\fR (in)
Minimum y coordinate of the rectangle.
.TP
float \fIx2\fR (in)
Maximum x coordinate of the rectangle to be drawn.
.TP
float \fIy2\fR (in)
Maximum y coordinate of the rectangle.
.TP
color \fIcolour\fR (in)
The colour of the rectangle.
.RE
.sp
.TP
\fB$isoplot\fR plot circle \fIxc\fR \fIyc\fR \fIradius\fR \fIcolour\fR
Plot the outline of a circle.
.RS
.TP
float \fIxc\fR (in)
X coordinate of the circle's centre.
.TP
float \fIyc\fR (in)
Y coordinate of the circle's centre.
.TP
color \fIcolour\fR (in)
The colour of the circle.
.RE
.sp
.TP
\fB$isoplot\fR plot filled-circle \fIxc\fR \fIyc\fR \fIradius\fR \fIcolour\fR
Plot a circle filled with the given colour.
.RS
.TP
float \fIxc\fR (in)
X coordinate of the circle's centre.
.TP
float \fIyc\fR (in)
Y coordinate of the circle's centre.
.TP
color \fIcolour\fR (in)
The colour of the circle.
.RE
.PP
.PP
There are a number of public procedures that may be useful in specific
situations: \fIPro memorie\fR.
.SH "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:
.TP
\fB::Plotchart::viewPort\fR \fIw\fR \fIpxmin\fR \fIpymin\fR \fIpxmax\fR \fIpymax\fR
Set the viewport for window \fIw\fR. Should be used in cooperation
with \fB::Plotchart::worldCoordinates\fR.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIpxmin\fR (in)
Left-most pixel coordinate.
.TP
float \fIpymin\fR (in)
Top-most pixel coordinate (remember: the vertical pixel coordinate
starts with 0 at the top!).
.TP
float \fIpxmax\fR (in)
Right-most pixel coordinate.
.TP
float \fIpymax\fR (in)
Bottom-most pixel coordinate.
.RE
.sp
.TP
\fB::Plotchart::worldCoordinates\fR \fIw\fR \fIxmin\fR \fIymin\fR \fIxmax\fR \fIymax\fR
Set the extreme world coordinates for window \fIw\fR. 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).
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIxmin\fR (in)
X-coordinate to be mapped to left side of viewport.
.TP
float \fIymin\fR (in)
Y-coordinate to be mapped to bottom of viewport.
.TP
float \fIxmax\fR (in)
X-coordinate to be mapped to right side of viewport.
.TP
float \fIymax\fR (in)
Y-coordinate to be mapped to top side of viewport.
.RE
.sp
.TP
\fB::Plotchart::world3DCoordinates\fR \fIw\fR \fIxmin\fR \fIymin\fR \fIzmin\fR \fIxmax\fR \fIymax\fR \fIzmax\fR
Set the extreme three-dimensional world coordinates for window
\fIw\fR. 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).
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIxmin\fR (in)
X-coordinate to be mapped to front side of the 3D viewport.
.TP
float \fIymin\fR (in)
Y-coordinate to be mapped to left side of the viewport.
.TP
float \fIzmin\fR (in)
Z-coordinate to be mapped to bottom of viewport.
.TP
float \fIxmax\fR (in)
X-coordinate to be mapped to back side of viewport.
.TP
float \fIymax\fR (in)
Y-coordinate to be mapped to right side of viewport.
.TP
float \fIzmax\fR (in)
Z-coordinate to be mapped to top side of viewport.
.RE
.sp
.TP
\fB::Plotchart::coordsToPixel\fR \fIw\fR \fIx\fR \fIy\fR
Return a list of pixel coordinates valid for the given window.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIx\fR (in)
X-coordinate to be mapped.
.TP
float \fIy\fR (in)
Y-coordinate to be mapped.
.RE
.sp
.TP
\fB::Plotchart::coords3DToPixel\fR \fIw\fR \fIx\fR \fIy\fR \fIz\fR
Return a list of pixel coordinates valid for the given window.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIx\fR (in)
X-coordinate to be mapped.
.TP
float \fIy\fR (in)
Y-coordinate to be mapped.
.TP
float \fIy\fR (in)
Z-coordinate to be mapped.
.RE
.sp
.TP
\fB::Plotchart::polarCoordinates\fR \fIw\fR \fIradmax\fR
Set the extreme polar coordinates for window \fIw\fR. The angle always
runs from 0 to 360 degrees and the radius starts at 0. Hence you only
need to give the maximum radius.
\fINote:\fR 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.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIradmax\fR (in)
Maximum radius.
.RE
.sp
.TP
\fB::Plotchart::polarToPixel\fR \fIw\fR \fIrad\fR \fIphi\fR
Wrapper for a call to \fB::Plotchart::coordsToPixel\fR, which assumes
the world coordinates and viewport are set appropriately. Converts
polar coordinates to pixel coordinates.
\fINote:\fR To be useful it should be accompanied by a matching
\fB::Plotchart::worldCoordinates\fR procedure. This is automatically
taken care of in the creation routine for polar plots.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIrad\fR (in)
Radius of the point.
.TP
float \fIphi\fR (in)
Angle to the positive x-axis.
.RE
.sp
.TP
\fB::Plotchart::pixelToCoords\fR \fIw\fR \fIx\fR \fIy\fR
Return a list of world coordinates valid for the given window.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIx\fR (in)
X-pixel to be mapped.
.TP
float \fIy\fR (in)
Y-pixel to be mapped.
.RE
.TP
\fB::Plotchart::pixelToIndex\fR \fIw\fR \fIx\fR \fIy\fR
Return the index of the pie segment containing the pixel coordinates
(x,y)
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question, holding a piechart.
.TP
float \fIx\fR (in)
X-pixel to be mapped.
.TP
float \fIy\fR (in)
Y-pixel to be mapped.
.RE
.PP
.PP
Furthermore there is a routine to determine "pretty" numbers for use
with an axis:
.TP
\fB::Plotchart::determineScale\fR \fIxmin\fR \fIxmax\fR \fIinverted\fR
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.
.RS
.TP
float \fIxmin\fR (in)
Rough minimum value for the scaling
.TP
float \fIxmax\fR (in)
Rough maximum value for the scaling.
.TP
boolean \fIinverted\fR (in)
Optional argument: if 1, then the returned list produces an
inverted axis. Defaults to 0 (the axis will be from minimum to maximum)
.RE
.PP
.SH "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
\fIPlotchart\fR handles these gaps by assuming that one or both
coordinates of such data points are an empty string:
.CS


    #
    # 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
    }

.CE
The effect varies according to the type of plot:
.IP \(bu
For xy-plots, radial plots and strip charts the missing data point
causes a gap in the line through the points.
.IP \(bu
For barchats, missing values are treated as if a value of zero was
given.
.IP \(bu
For time charts and Gantt charts missing values cause errors - there is
no use for them there.
.PP
.SH "OTHER OUTPUT FORMATS"
Besides output to the canvas on screen, the module is capable, via
\fBcanvas postscript\fR, 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.
.PP
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.
.PP
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.
.PP
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 \fIcreate\fR subcommand is used to create the lines, texts and
other items. But also the \fIraise\fR and \fIlower\fR 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).
.PP
Furthermore, the module uses the \fIcget\fR 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.
.PP
In summary:
.IP \(bu
Emulate the \fIcreate\fR subcommand to create all the items in the
correct format
.IP \(bu
Emulate the \fIcget\fR subcommand for the options -width and -height to
allow the correct calculation of the rectangle's position and size
.IP \(bu
Solve the problem of \fIraising\fR and \fIlowering\fR the items so
that they are properly clipped, for instance by redefining the
routine DrawMask.
.IP \(bu
Take care of the currently fixed text size properties
.PP
.SH "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:
.CS


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

.CE
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.
.SH "ROOM FOR IMPROVEMENT"
In this version there are a lot of things that still need to
be implemented:
.IP \(bu
More robust handling of incorrect calls (right now the procedures may
fail when called incorrectly):
.RS
.IP \(bu
The axis drawing routines can not handle inverse axes right now.
.IP \(bu
If the user provides an invalid date/time string, the routines simply
throw an error.
.RE
.PP
.SH RESIZING
\fBPlotchart\fR 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.
.PP
The code below is a simple example of how to do that:
.CS


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]
}
.CE
\fIPlease note:\fR
The code above will work fine for barcharts and many other types of
plots, but as \fBPlotchart\fR 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 \fBPlotchart\fR will have that.
.SH "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.
.PP
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.
.PP
The method works very simply:
.CS


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

.CE
.SH "CONFIGURATION OPTIONS"
The command plotconfig can be used to set all manner of options. The
syntax is:
.TP
\fB::Plotchart::plotconfig\fR \fIcharttype\fR \fIcomponent\fR \fIproperty\fR \fIvalue\fR
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.
.RS
.TP
string \fIcharttype\fR (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.
.TP
string \fIcomponent\fR (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.
.TP
string \fIproperty\fR (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.
.TP
string \fIvalue\fR (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.
.sp
Note, that in some cases an empty value is useful. Use "none" in this
case - it can be useful for colours and for formats.
.RE
.PP
Below is a more detailed list of the components and properties:
.IP \(bu
Axes come in a wide variety:
.RS
.IP \(bu
leftaxis, rightaxis, topaxis, bottomaxis for the plots with a
rectangular shape.
.IP \(bu
xaxis, yaxis and zaxis are used for the 3D plots
.IP \(bu
axis, this represents the radial and tangential axes of a polar plot
.RE
.IP
All axes have the following properties:
.RS
.IP \(bu
color - the colour of the line and the tickmarks
.IP \(bu
thickness - the width of the line of the axis itself, not the tickmarks
.IP \(bu
ticklength - the length of the tickmarks in pixels. A positive value is
outward, a negative value is inward.
.IP \(bu
font - the font for the labels and the text at the axis
.IP \(bu
format - the format for rendering the (numerical) labels. For the time
axis it is the format for a date and time.
.IP \(bu
textcolor - the colour for the labels and the text.
.RE
.IP \(bu
The \fImargin\fR 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.
.IP \(bu
The \fItext\fR 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).
.IP \(bu
The \fIbackground\fR 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).
.IP \(bu
The \fIlegend\fR has three properties: background, border and position.
See the legend subcommand for the meaning.
.PP
See the examples in plotdemos7.tcl for it use.
.SH "SCROLLING FOR TIMECHARTS AND GANTT CHARTS"
For two types of plots automatic scrolling management has been
implemented: timecharts and Gantt charts. The subcommands \fIhscroll\fR
and \fIvscroll\fR associate (existing) scrollbars to the plot, in much
the same way as for text and canvas widgets.
.PP
Once the association is made, the scrollbars are automatically
updated if:
.IP \(bu
You add an item with a period wider than the current one.
.IP \(bu
You add a vertical line for a time beyond the current bounds.
.IP \(bu
You add an extra item beyond the number that was used to create the
chart.
.PP
For instance:
.CS


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

.CE
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.
.SH "ARRANGING MULTIPLE PLOTS IN A CANVAS"
The command \fIplotpack\fR 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.
.TP
\fB::Plotchart::plotpack\fR \fIw\fR \fIdir\fR \fIargs\fR
Copy the contents of the plots/charts into another widget, in a manner
similar to the \fIpack\fR geometry manager.
.RS
.TP
widget \fIw\fR (in)
The name of the canvas widget to copy the plots/charts into
.TP
string \fIdir\fR (in)
The direction of the arrangement - top, left, bottom or right
.TP
list \fIargs\fR (in)
List of plots/charts to be copied.
.RE
.PP
For example:
.CS


    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

.CE
.SH "NOTES ON TAGS"
P.M.
.SH "TODO - SOME PRIVATE NOTES"
I have the following wishlist:
.IP \(bu
Isometric plots - allow new items to be implemented easily.
.IP \(bu
A general 3D viewer - emphasis on geometry, not a ray-tracer.
.IP \(bu
Several improvements for boxplots:
.RS
.IP \(bu
Height of the box scales with the logarithm of the number of points
.IP \(bu
Marker line to indicate a "current" value
.IP \(bu
Box drawn from quantiles
.RE
.PP
.SH 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
.SH COPYRIGHT
.nf
Copyright (c) 2007 Arjen Markus <arjenmarkus@users.sourceforge.net>

.fi