1Plotchart(n)                       Plotchart                      Plotchart(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       Plotchart - Simple plotting and charting package
9

SYNOPSIS

11       package require Tcl  ?8.4?
12
13       package require Tk  ?8.4?
14
15       package require Plotchart  ?1.6?
16
17       ::Plotchart::createXYPlot w xaxis yaxis
18
19       ::Plotchart::createStripchart w xaxis yaxis
20
21       ::Plotchart::createTXPlot w timeaxis xaxis
22
23       ::Plotchart::createXLogYPlot w xaxis yaxis
24
25       ::Plotchart::createPolarPlot w radius_data
26
27       ::Plotchart::createIsometricPlot w xaxis yaxis stepsize
28
29       ::Plotchart::createHistogram w xaxis yaxis
30
31       ::Plotchart::create3DPlot w xaxis yaxis zaxis
32
33       ::Plotchart::createPiechart w
34
35       ::Plotchart::createRadialchart w names scale style
36
37       ::Plotchart::createBarchart w xlabels yaxis noseries
38
39       ::Plotchart::createHorizontalBarchart w ylabels xaxis noseries
40
41       ::Plotchart::create3DBarchart w yaxis nobars
42
43       ::Plotchart::create3DRibbonChart w names yaxis zaxis
44
45       ::Plotchart::createBoxplot w xaxis ylabels
46
47       ::Plotchart::createTimechart w time_begin time_end args
48
49       ::Plotchart::createGanttchart w time_begin time_end args
50
51       ::Plotchart::createRightAxis w yaxis
52
53       $anyplot title text
54
55       $anyplot saveplot filename args
56
57       $anyplot xtext text
58
59       $anyplot ytext text
60
61       $anyplot xconfig -option value ...
62
63       $anyplot yconfig -option value ...
64
65       $anyplot background part colour_or_image dir
66
67       $anyplot xticklines colour
68
69       $anyplot yticklines colour
70
71       $anyplot legendconfig -option value ...
72
73       $anyplot legend series text
74
75       $anyplot balloon x y text dir
76
77       $anyplot balloonconfig args
78
79       $xyplot plot series xcrd ycrd
80
81       $xyplot trend series xcrd ycrd
82
83       $xyplot rchart series xcrd ycrd
84
85       $xyplot interval series xcrd ymin ymax ?ycentr?
86
87       $xyplot box-and-whiskers series xcrd ycrd
88
89       $xyplot vector series xcrd ycrd ucmp vcmp
90
91       $xyplot vectorconfig series -option value ...
92
93       $xyplot dot series xcrd ycrd value
94
95       $xyplot dotconfig series -option value ...
96
97       $xyplot contourlines xcrd ycrd values ?classes?
98
99       $xyplot contourfill xcrd ycrd values ?classes?
100
101       $xyplot contourbox xcrd ycrd values ?classes?
102
103       $xyplot colorMap colours
104
105       $xyplot grid xcrd ycrd
106
107       $polarplot plot series radius angle
108
109       $plot3d plotfunc function
110
111       $plot3d plotfuncont function contours
112
113       $plot3d gridsize nxcells nycells
114
115       $plot3d plotdata data
116
117       $plot3d colours fill border
118
119       $xyplot dataconfig series -option value ...
120
121       $pie plot data
122
123       $pie colours colour1 colour2 ...
124
125       $radial plot data colour thickness
126
127       $pie colours colour1 colour2 ...
128
129       $barchart plot series ydata colour
130
131       $barchart plot series xdata colour
132
133       $barchart plot label yvalue colour
134
135       $barchart config -option value ...
136
137       $ribbon line xypairs colour
138
139       $ribbon area xypairs colour
140
141       $boxplot plot label values
142
143       $timechart period text time_begin time_end colour
144
145       $timechart milestone text time colour
146
147       $timechart vertline text time
148
149       $timechart hscroll scrollbar
150
151       $timechart vscroll scrollbar
152
153       $ganttchart task text time_begin time_end completed
154
155       $ganttchart milestone text time colour
156
157       $ganttchart vertline text time
158
159       $ganttchart connect from to
160
161       $ganttchart summary text args
162
163       $ganttchart color keyword newcolor
164
165       $ganttchart font keyword newfont
166
167       $ganttchart hscroll scrollbar
168
169       $ganttchart vscroll scrollbar
170
171       $isoplot plot rectangle x1 y1 x2 y2 colour
172
173       $isoplot plot filled-rectangle x1 y1 x2 y2 colour
174
175       $isoplot plot circle xc yc radius colour
176
177       $isoplot plot filled-circle xc yc radius colour
178
179       ::Plotchart::viewPort w pxmin pymin pxmax pymax
180
181       ::Plotchart::worldCoordinates w xmin ymin xmax ymax
182
183       ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
184
185       ::Plotchart::coordsToPixel w x y
186
187       ::Plotchart::coords3DToPixel w x y z
188
189       ::Plotchart::polarCoordinates w radmax
190
191       ::Plotchart::polarToPixel w rad phi
192
193       ::Plotchart::pixelToCoords w x y
194
195       ::Plotchart::pixelToIndex w x y
196
197       ::Plotchart::determineScale xmin xmax inverted
198
199       ::Plotchart::plotconfig charttype component property value
200
201       ::Plotchart::plotpack w dir args
202
203______________________________________________________________________________
204

DESCRIPTION

206       Plotchart  is  a  Tcl-only package that focuses on the easy creation of
207       xy-plots, barcharts and other common types of graphical  presentations.
208       The emphasis is on ease of use, rather than flexibility. The procedures
209       that create a plot use the entire canvas window, making the  layout  of
210       the plot completely automatic.
211
212       This results in the creation of an xy-plot in, say, ten lines of code:
213
214                  package require Plotchart
215
216                  canvas .c -background white -width 400 -height 200
217                  pack   .c -fill both
218
219                  #
220                  # Create the plot with its x- and y-axes
221                  #
222                  set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
223
224                  foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {
225                      $s plot series1 $x $y
226                  }
227
228                  $s title "Data series"
229
230
231       A drawback of the package might be that it does not do any data manage‐
232       ment. So if the canvas that holds the plot is to be resized, the  whole
233       plot  must be redrawn.  The advantage, though, is that it offers a num‐
234       ber of plot and chart types:
235
236       ·      XY-plots like the one  shown  above  with  any  number  of  data
237              series.
238
239       ·      Stripcharts,  a  kind  of  XY-plots where the horizontal axis is
240              adjusted automatically. The result is a kind of  sliding  window
241              on the data series.
242
243       ·      Polar  plots,  where the coordinates are polar instead of carte‐
244              sian.
245
246       ·      Histograms, for plotting statistical information.
247
248       ·      Isometric plots, where the scale of the coordinates in  the  two
249              directions  is  always  the same, i.e. a circle in world coordi‐
250              nates appears as a circle on the screen.
251
252              You can zoom in and out, as well as pan with these plots  (Note:
253              this  works  best  if no axes are drawn, the zooming and panning
254              routines do not distinguish the axes), using the  mouse  buttons
255              with the control key and the arrow keys with the control key.
256
257       ·      Piecharts, with automatic scaling to indicate the proportions.
258
259       ·      Barcharts, with either vertical or horizontal bars, stacked bars
260              or bars side by side.
261
262       ·      Timecharts, where bars indicate a time period and milestones  or
263              other important moments in time are represented by triangles.
264
265       ·      3D plots (both for displaying surfaces and 3D bars)
266
267       With  version  1.5 a new command has been introduced: plotconfig, which
268       can be used to configure the plot options for particular types of plots
269       and charts (cf. CONFIGURATION OPTIONS)
270

PLOT CREATION COMMANDS

272       You  create the plot or chart with one single command and then fill the
273       plot with data:
274
275       ::Plotchart::createXYPlot w xaxis yaxis
276              Create a new xy-plot (configuration type: xyplot).
277
278              widget w (in)
279                     Name of the existing canvas widget to hold the plot.
280
281              list xaxis (in)
282                     A 3-element list containing minimum, maximum and stepsize
283                     for  the  x-axis,  in  this order.  For an inverted axis,
284                     where the maximum appears on  the  left-hand  side,  use:
285                     maximum, minimum and a negative stepsize.
286
287              list yaxis (in)
288                     A 3-element list containing minimum, maximum and stepsize
289                     for the y-axis, in this order.   For  an  inverted  axis,
290                     where  the  maximum  appears at the bottom, use: maximum,
291                     minimum and a negative stepsize.
292
293
294       ::Plotchart::createStripchart w xaxis yaxis
295              Create a new strip chart (configuration type:  stripchart).  The
296              only  difference to a regular XY plot is that the x-axis will be
297              automatically adjusted when the  x-coordinate  of  a  new  point
298              exceeds the maximum.
299
300              widget w (in)
301                     Name of the existing canvas widget to hold the plot.
302
303              list xaxis (in)
304                     A 3-element list containing minimum, maximum and stepsize
305                     for the x-axis, in this order.  Note that an inverted  x-
306                     axis is not supported for this type of plot.
307
308              list yaxis (in)
309                     A 3-element list containing minimum, maximum and stepsize
310                     for the y-axis, in this order.   For  an  inverted  axis,
311                     where  the  maximum  appears at the bottom, use: maximum,
312                     minimum and a negative stepsize.
313
314
315       ::Plotchart::createTXPlot w timeaxis xaxis
316              Create a new time-x-plot (configuration type: txplot). The hori‐
317              zontal  axis represents the date/time of the data and the verti‐
318              cal axis the values themselves.
319
320              widget w (in)
321                     Name of the existing canvas widget to hold the plot.
322
323              list timeaxis (in)
324                     A 3-element  list  containing  the  minimum  and  maximum
325                     date/time  to be shown and the stepsize (in days) for the
326                     time-axis, in this order.  Note that  an  inverted  time-
327                     axis is not supported.
328
329              list xaxis (in)
330                     A 3-element list containing minimum, maximum and stepsize
331                     for the vertical axis, in this order.   For  an  inverted
332                     axis, where the maximum appears at the bottom, use: maxi‐
333                     mum, minimum and a negative stepsize.
334
335
336       ::Plotchart::createXLogYPlot w xaxis yaxis
337              Create a new xy-plot where the y-axis has  a  logarithmic  scale
338              (configuration type: xlogyplot).
339
340              The data should be given as for a linear scale, as the logarith‐
341              mic transformation is taken of internally.
342
343              widget w (in)
344                     Name of the existing canvas widget to hold the plot.
345
346              list xaxis (in)
347                     A 3-element list containing minimum, maximum and stepsize
348                     for  the  x-axis,  in  this order.  For an inverted axis,
349                     where the maximum appears on  the  left-hand  side,  use:
350                     maximum, minimum and a negative stepsize.
351
352              list yaxis (in)
353                     A  2-element  list containing minimum and maximum for the
354                     y-axis, in this order.  Note that an inverted logarithmic
355                     axis is not supported.
356
357
358       ::Plotchart::createPolarPlot w radius_data
359              Create a new polar plot (configuration type: polarplot).
360
361              widget w (in)
362                     Name of the existing canvas widget to hold the plot.
363
364              list radius_data (in)
365                     A  2-element  list containing maximum radius and stepsize
366                     for the radial axis, in this order.
367
368
369       ::Plotchart::createIsometricPlot w xaxis yaxis stepsize
370              Create a new isometric plot, where the vertical and the horizon‐
371              tal coordinates are scaled so that a circle will truly appear as
372              a circle (configuration type: isometric).
373
374              widget w (in)
375                     Name of the existing canvas widget to hold the plot.
376
377              list xaxis (in)
378                     A 2-element list containing minimum, and maximum for  the
379                     x-axis, in this order.
380
381              list yaxis (in)
382                     A  2-element list containing minimum, and maximum for the
383                     y-axis, in this order.
384
385              float|noaxes stepsize (in)
386                     Either the stepsize used by  both  axes  or  the  keyword
387                     noaxes  to  signal  the  plot that it should use the full
388                     area of the widget, to not draw any of the axes.
389
390
391       ::Plotchart::createHistogram w xaxis yaxis
392              Create a new histogram (configuration type: histogram).
393
394              widget w (in)
395                     Name of the existing canvas widget to hold the plot.
396
397              list xaxis (in)
398                     A 3-element list containing minimum, maximum and stepsize
399                     for the x-axis, in this order.
400
401              list yaxis (in)
402                     A 3-element list containing minimum, maximum and stepsize
403                     for the y-axis, in this order.
404
405
406       ::Plotchart::create3DPlot w xaxis yaxis zaxis
407              Create a new 3D plot.
408
409              widget w (in)
410                     Name of the existing canvas widget to hold the plot.
411
412              list xaxis (in)
413                     A 3-element list containing minimum, maximum and stepsize
414                     for the x-axis, in this order.
415
416              list yaxis (in)
417                     A 3-element list containing minimum, maximum and stepsize
418                     for the y-axis, in this order.
419
420              list zaxis (in)
421                     A 3-element list containing minimum, maximum and stepsize
422                     for the z-axis, in this order.
423
424
425       ::Plotchart::createPiechart w
426              Create a new piechart (configuration type: piechart).
427
428              widget w (in)
429                     Name of the existing canvas widget to hold the plot.
430
431
432       ::Plotchart::createRadialchart w names scale style
433              Create a new radial chart (the data are drawn as a line connect‐
434              ing the  spokes  of  the  diagram)  (configuration  type:  radi‐
435              alchart).
436
437              widget w (in)
438                     Name of the existing canvas widget to hold the plot.
439
440              list names (in)
441                     Names for the spokes.
442
443              float scale (in)
444                     Scale  value  to determine the position of the data along
445                     the spokes.
446
447              float style (in)
448                     Style of the chart (optional). One of:
449
450                     ·      lines - the default: draw the data as  independent
451                            polylines.
452
453                     ·      cumulative  - draw the data as polylines where the
454                            data are accumulated.
455
456                     ·      filled - draw the data as  filled  polygons  where
457                            the data are accumulated
458
459
460       ::Plotchart::createBarchart w xlabels yaxis noseries
461              Create  a  new  barchart with vertical bars (configuration type:
462              vertbars). The horizontal axis will display the labels contained
463              in  the argument xlabels. The number of series given by noseries
464              determines both the width of the bars, and the  way  the  series
465              will be drawn.
466
467              If  the  keyword  stacked was specified the series will be drawn
468              stacked on top of each other.  Otherwise  each  series  that  is
469              drawn will be drawn shifted to the right.
470
471              The  number  of series determines the width of the bars, so that
472              there is space of that number of bars. If you  use  a  floating-
473              point  number,  like 2.2, instead of an integer, like 2, a small
474              gap between the sets of bars will be drawn - the  width  depends
475              on the fractional part.
476
477              widget w (in)
478                     Name of the existing canvas widget to hold the plot.
479
480              list xlabels (in)
481                     List of labels for the x-axis. Its length also determines
482                     the number of bars that will be plotted per series.
483
484              list yaxis (in)
485                     A 3-element list containing minimum, maximum and stepsize
486                     for the y-axis, in this order.
487
488              int|stacked noseries (in)
489                     The  number of data series that will be plotted. This has
490                     to be an integer number greater than zero (if stacked  is
491                     not used).
492
493
494       ::Plotchart::createHorizontalBarchart w ylabels xaxis noseries
495              Create  a new barchart with horizontal bars (configuration type:
496              horizbars). The vertical axis will display the labels  contained
497              in  the argument ylabels. The number of series given by noseries
498              determines both the width of the bars, and the  way  the  series
499              will be drawn.
500
501              If  the  keyword  stacked was specified the series will be drawn
502              stacked from left to right. Otherwise each series that is  drawn
503              will be drawn shifted upward.
504
505              widget w (in)
506                     Name of the existing canvas widget to hold the plot.
507
508              list ylabels (in)
509                     List of labels for the y-axis. Its length also determines
510                     the number of bars that will be plotted per series.
511
512              list xaxis (in)
513                     A 3-element list containing minimum, maximum and stepsize
514                     for the x-axis, in this order.
515
516              int|stacked noseries (in)
517                     The  number of data series that will be plotted. This has
518                     to be an integer number greater than zero (if stacked  is
519                     not used).
520
521
522       ::Plotchart::create3DBarchart w yaxis nobars
523              Create a new barchart with 3D vertical bars (configuration type:
524              3dbars). The horizontal axis will display the  labels  per  bar.
525              The  number  of bars given by nobars determines the position and
526              the width of the bars. The colours can be varied per bar.  (This
527              type  of  chart  was  inspired  by  the  Wiki page on 3D bars by
528              Richard Suchenwirth.)
529
530              widget w (in)
531                     Name of the existing canvas widget to hold the plot.
532
533              list yaxis (in)
534                     A 3-element list containing minimum, maximum and stepsize
535                     for the y-axis, in this order.
536
537              int nobars (in)
538                     The number of bars that will be plotted.
539
540
541       ::Plotchart::create3DRibbonChart w names yaxis zaxis
542              Create a new "ribbon chart" (configuration type: 3dribbon). This
543              is a chart where the data series are represented as ribbons in a
544              three-dimensional axis system. Along the x-axis (which is "into"
545              the screen) the names are plotted, each  representing  a  single
546              series.  The  first  plot command draws the furthest series, the
547              second draws the series in front of that and so on.
548
549              widget w (in)
550                     Name of the existing canvas widget to hold the plot.
551
552              widget w (in)
553                     Names of the series, plotted as labels along the x-axis
554
555              list yaxis (in)
556                     A 3-element list containing minimum, maximum and stepsize
557                     for the y-axis (drawn horizontally!), in this order.
558
559              list zaxis (in)
560                     A 3-element list containing minimum, maximum and stepsize
561                     for the z-axis (drawn vertically), in this order.
562
563              int nobars (in)
564                     The number of bars that will be plotted.
565
566
567       ::Plotchart::createBoxplot w xaxis ylabels
568              Create a new boxplot with horizontal  boxes  (box-and-whiskers).
569              The  y-axis  is  drawn with labels. The boxes are drawn based on
570              the raw data (see the plot subcommand for this type of plot).
571
572              widget w (in)
573                     Name of the existing canvas widget to hold the plot.
574
575              list xaxis (in)
576                     A 3-element list containing minimum, maximum and stepsize
577                     for the y-axis, in this order.
578
579              list ylabels (in)
580                     List of labels for the y-axis. Its length also determines
581                     the number of boxes that can be plotted. The  labels  are
582                     also used in the plot subcommand.
583
584
585       ::Plotchart::createTimechart w time_begin time_end args
586              Create  a  new  timechart  (configuration type: timechart).  The
587              time axis (= x-axis) goes from time_begin to time_end,  and  the
588              vertical spacing is determined by the number of items to plot.
589
590              widget w (in)
591                     Name of the existing canvas widget to hold the plot.
592
593              string time_begin (in)
594                     The  start time given in a form that is recognised by the
595                     clock scan command (e.g. "1 january 2004").
596
597              string time_end (in)
598                     The end time given in a form that is  recognised  by  the
599                     clock scan command (e.g. "1 january 2004").
600
601              arguments args (in)
602                     The remaining arguments can be:
603
604                     ·      The  expected/maximum number of items. This deter‐
605                            mines the vertical spacing. (If given, it must  be
606                            the first argument after "time_end"
607
608                     ·      The  keyword  -barheight  and the number of pixels
609                            per bar. This is an alternative method  to  deter‐
610                            mine the vertical spacing.
611
612                     ·      The  keyword -ylabelwidth and the number of pixels
613                            to reserve for the labels at the y-axis.
614
615       ::Plotchart::createGanttchart w time_begin time_end args
616              Create a new Gantt chart (configuration type: ganttchart).   The
617              time  axis  (= x-axis) goes from time_begin to time_end, and the
618              vertical spacing is determined by the number of items  to  plot.
619              Via the specific commands you can then add tasks and connections
620              between the tasks.
621
622              widget w (in)
623                     Name of the existing canvas widget to hold the plot.
624
625              string time_begin (in)
626                     The start time given in a form that is recognised by  the
627                     clock scan command (e.g. "1 january 2004").
628
629              string time_end (in)
630                     The  end  time  given in a form that is recognised by the
631                     clock scan command (e.g. "1 january 2004").
632
633              arguments args (in)
634                     The remaining arguments can be:
635
636                     ·      The expected/maximum number of items. This  deter‐
637                            mines the vertical spacing. (If given this way, it
638                            must be the first argument after "time_end")
639
640                     ·      The expected/maximum width of the descriptive text
641                            (roughly  in  characters,  for  the  actual  space
642                            reserved for the text, it is assumed that a  char‐
643                            acter  is  about ten pixels wide). Defaults to 20.
644                            (If given this way, it must be the second argument
645                            after "time_end").
646
647                     ·      The  keyword  -barheight  and the number of pixels
648                            per bar. This is an alternative method  to  deter‐
649                            mine the vertical spacing.
650
651                     ·      The  keyword -ylabelwidth and the number of pixels
652                            to reserve for the labels at the y-axis.
653
654       ::Plotchart::createRightAxis w yaxis
655              Create a plot command that will use a right axis instead of  the
656              left  axis  (configuration  type:  inherited  from  the existing
657              plot). The widget (w) must already contain an ordinary plot,  as
658              the  horizontal  axis  and  other properties are reused. To plot
659              data using the right axis, use this new command,  to  plot  data
660              using the left axis, use the original plot command.
661
662              widget w (in)
663                     Name of the existing canvas widget to hold the plot.
664
665              list yaxis (in)
666                     A 3-element list containing minimum, maximum and stepsize
667                     for the y-axis, in this order.
668
669

PLOT METHODS

671       Each of the creation commands explained in the last section returns the
672       name of a new object command that can be used to manipulate the plot or
673       chart. The subcommands available to a chart command depend on the  type
674       of the chart.
675
676       General  subcommands  for  all types of charts. $anyplot is the command
677       returned by the creation command:
678
679       $anyplot title text
680              Specify the title of the whole chart.
681
682              string text (in)
683                     The text of the title to be drawn.
684
685
686       $anyplot saveplot filename args
687              Draws the plot into a file, using PostScript.
688
689              string filename (in)
690                     Contain the path name of the file to write the plot to.
691
692              list args (in)
693                     Optionally you can specify the option -format "some  pic‐
694                     ture format" to store the plot in a different file than a
695                     PostScript file. This, however, relies on the Img package
696                     to do the actual job.
697
698                     Note:  Because  the window holding the plot must be fully
699                     visible before Img can successfully grab it, it is raised
700                     first.   On  some  systems,  for instance Linux with KDE,
701                     raising a window is not done automatically,  but  instead
702                     you  need to click on the window in the task bar. Similar
703                     things happen on Windows XP.
704
705                     There seems to be  something  wrong  under  some  circum‐
706                     stances,  so instead of waiting for the visibility of the
707                     window, the procedure simply waits two seconds. It is not
708                     ideal, but it seems to work better.
709
710
711       $anyplot xtext text
712              Specify  the  title  of the (horizontal) x-axis, for those plots
713              that have a straight x-axis.
714
715              string text (in)
716                     The text of the x-axis label to be drawn.
717
718
719       $anyplot ytext text
720              Specify the title of the (horizontal) y-axis,  for  those  plots
721              that have a straight y-axis.
722
723              string text (in)
724                     The text of the y-axis label to be drawn.
725
726
727       $anyplot xconfig -option value ...
728              Set  one  or  more configuration parameters for the x-axis.  The
729              following options are supported:
730
731              format fmt
732                     The format for the numbers along the axis.
733
734              ticklength length
735                     The length of the tickmarks (in pixels).
736
737              ticklines boolean
738                     Whether to draw ticklines (true) or not (false).
739
740              scale scale_data
741                     New scale data for the axis, i.e. a 3-element  list  con‐
742                     taining  minimum,  maximum  and stepsize for the axis, in
743                     this order.
744
745                     Beware: Setting this option will clear all data from  the
746                     plot.
747
748
749       $anyplot yconfig -option value ...
750              Set  one  or  more configuration parameters for the y-axis. This
751              method accepts the same options and values as the  method  xcon‐
752              fig.
753
754       $anyplot background part colour_or_image dir
755              Set the background of a part of the plot
756
757              string part
758                     Which  part  of  the  plot:  "axes" for the axes area and
759                     "plot" for the inner part. The interpretation depends  on
760                     the type of plot. Two further possibilities are:
761
762                     ·      image,  in which case a predefined image is loaded
763                            into the background of the plot.
764
765                     ·      gradient, in which case the background is coloured
766                            in different shades of the given colour. The "dir"
767                            argument specifies  the  direction  in  which  the
768                            colour gets whiter.
769
770              string colour_or_image
771                     Colour  for  that part or the name of the image if "part"
772                     is "image"
773
774              string dir
775                     The direction of the gradient. One of: top-down,  bottom-
776                     up, left-right or right-left.
777
778
779       $anyplot xticklines colour
780              Draw vertical ticklines at each tick location
781
782              string colour
783                     Colour  of  the  lines.  Specifying  an empty colour ("")
784                     removes them again.  Defaults to "black"
785
786
787       $anyplot yticklines colour
788              Draw horizontal ticklines at each tick location
789
790              string colour
791                     Colour of the lines.  Specifying  an  empty  colour  ("")
792                     removes them again Defaults to "black"
793
794
795       $anyplot legendconfig -option value ...
796              Set one or more options for the legend. The legend is drawn as a
797              rectangle with text and graphics inside.
798
799              background colour
800                     Set the colour of the background (the default  colour  is
801                     white).   Set  to the empty string for a transparant leg‐
802                     end.
803
804              border colour
805                     Set the colour of  the  border  (the  default  colour  is
806                     white). Set to the empty string if you do not want a bor‐
807                     der.
808
809              canvas c
810                     Draw the legend in a different canvas widget. This  gives
811                     you the freedom to position the legend outside the actual
812                     plot.
813
814              position corner
815                     Set the position of the legend. May be one of:  top-left,
816                     top-right, bottom-left or bottom-right. (Default value is
817                     top-right.)
818
819
820       $anyplot legend series text
821              Add an entry to the legend. The series determines which  graphi‐
822              cal  symbol is to be used. (As a side effect the legend is actu‐
823              ally drawn.)
824
825              string series
826                     Name of the data series. This determines  the  colour  of
827                     the line and the symbol (if any) that will be drawn.
828
829              string text
830                     Text to be drawn next to the line/symbol.
831
832
833       $anyplot balloon x y text dir
834              Add  balloon  text  to the plot (except for 3D plots). The arrow
835              will point to the given x- and y-coordinates. For xy-graphs  and
836              such, the coordinates are directly related to the axes; for ver‐
837              tical barcharts the x-coordinate is measured as  the  number  of
838              bars minus 1 and similar for horizontal barcharts.
839
840              float x
841                     X-coordinate  of  the point that the arrow of the balloon
842                     will point to.
843
844              float y
845                     Y-coordinate of the point that the arrow of  the  balloon
846                     will point to.
847
848              string text
849                     Text to be drawn in the balloon.
850
851              string dir
852                     Direction  of the arrow, one of: north, north-east, east,
853                     south-east, south, south-west, west or north-west.
854
855
856       $anyplot balloonconfig args
857              Configure the balloon text for the plot. The new  settings  will
858              be used for the next balloon text.
859
860              font fontname
861                     Font to be used for the text
862
863              justify left|center|right
864                     Way to justify multiline text
865
866              textcolour colour
867                     Colour for the text (synonym: textcolor)
868
869              background colour
870                     Background colour for the balloon
871
872              outline colour
873                     Colour of the outline of the balloon
874
875              margin value
876                     Margin around the text (in pixels)
877
878              rimwidth value
879                     Width of the outline of the balloon (in pixels)
880
881              arrowsize value
882                     Length factor for the arrow (in pixels)
883
884
885       Note:  The  commands xconfig and yconfig are currently implemented only
886       for XY-plots and only the option -format has any effect.
887
888       For xy plots, stripcharts, histograms and time-x-plots:
889
890       $xyplot plot series xcrd ycrd
891              Add a data point to the plot.
892
893              string series (in)
894                     Name of the data series the new point belongs to.
895
896              float xcrd (in)
897                     X-coordinate of the new point.  (For  time-x  plots  this
898                     must  be  valid date/time that can be read with the clock
899                     scan command).
900
901              float ycrd (in)
902                     Y-coordinate of the new point.
903
904       Note on histograms:
905
906       For histograms the x-coordinate that is given is interpreted to be  the
907       x-coordinate  of the right side of the bar. The first bar starts at the
908       y-axis on the left. To completely fill the range  of  the  x-axis,  you
909       should draw a bar at the maximum x-coordinate.
910
911       For xy plots:
912
913       $xyplot trend series xcrd ycrd
914              Draw or update a trend line using the data given sofar.
915
916              string series (in)
917                     Name of the data series the trend line belongs to.
918
919              float xcrd (in)
920                     X-coordinate of the new data point
921
922              float ycrd (in)
923                     Y-coordinate of the new data point
924
925       $xyplot rchart series xcrd ycrd
926              Draw data in the same way as the plot method, but with two lines
927              added that indicate the expected range  (+/-  3*standard  devia‐
928              tion) of the data.
929
930              string series (in)
931                     Name of the data series the data point belongs to.
932
933              float xcrd (in)
934                     X-coordinate of the new data point
935
936              float ycrd (in)
937                     Y-coordinate of the new data point
938
939       $xyplot interval series xcrd ymin ymax ?ycentr?
940              Add a vertical error interval to the plot. The interval is drawn
941              from ymin to ymax. If the ycentr argument is given, a symbol  is
942              drawn at that position.
943
944              string series (in)
945                     Name of the data series the interval belongs to.
946
947              float xcrd (in)
948                     X-coordinate of the interval
949
950              float ymin (in)
951                     Minimum y-coordinate of the interval.
952
953              float ymax (in)
954                     Maximum y-coordinate of the interval.
955
956              float ycentr (in)
957                     Y-coordinate to draw the symbol at (optional)
958
959       $xyplot box-and-whiskers series xcrd ycrd
960              Draw  a  box and whiskers in the plot. If the argument xcrd is a
961              list of several values and the argument ycrd is a single  value,
962              a horizontal box is drawn with the quartiles determined from the
963              list of values contained in xcrd.
964
965              If, instead, the argument ycrd contains a list of several values
966              and  the  argument  xcrd  a single value, then a vertical box is
967              drawn and the quartiles are determined from ycrd. (There must be
968              exactly  one  list  of  several  values.  Otherwise  an error is
969              reported.)
970
971              The option -boxwidth (default: 10 pixels) determines  the  width
972              (or height) of the box.
973
974              string series (in)
975                     Name of the data series the box-and-whiskers belongs to.
976
977              float xcrd (in)
978                     X-coordinate of the box or a list of values.
979
980              float ymin (in)
981                     Y-coordinate of the box or a list of values.
982
983       $xyplot vector series xcrd ycrd ucmp vcmp
984              Draw  a  vector  in  the plot. The vector can be given as either
985              cartesian coordinates or as length/angle, where the angle is  in
986              degrees and is interpreted according to the mathematical conven‐
987              tion or the nautical.  (See the vectorconfig subcommand)
988
989              string series (in)
990                     Name of the series the vector belongs to. Determines  the
991                     appearance and interpretation.
992
993              float xcrd (in)
994                     X-coordinate of the point where the arrow appears
995
996              float ycrd (in)
997                     Y-coordinate of the point where the arrow appears
998
999              float ucmp (in)
1000                     X-component or the length of the vector
1001
1002              float ycentr (in)
1003                     Y-component or the angle of the vector
1004
1005       $xyplot vectorconfig series -option value ...
1006              ] Set the vector drawing options for a particular series
1007
1008              string series (in)
1009                     Name of the series the vector belongs to.
1010
1011              The options can be one of the following:
1012
1013              colour The colour of the arrow (default: black; synonym: color)
1014
1015              scale value
1016                     The  scale factor used to convert the length of the arrow
1017                     into a number of pixels (default: 1.0)
1018
1019              centred onoff
1020                     Logical value indicating that the xy-coordinates  are  to
1021                     be  used  as  the  start  of  the  arrow or as the centre
1022                     (default: 0; synonym: centered)
1023
1024              type keyword
1025                     Interpretation of the vector components. Can  be  "carte‐
1026                     sian"  (default),  in  which case the x- and y-components
1027                     are expected, "polar" (the angle  0  coincides  with  the
1028                     positive  x-axis,  90 coincides with the positive y-axis)
1029                     or "nautical" (0 is "north" and 90 is "east").
1030
1031
1032       $xyplot dot series xcrd ycrd value
1033              Draw a dot in the plot. The size and colour is determined by the
1034              value and by the options set for the series it belongs to.  (See
1035              the dotconfig subcommand)
1036
1037              string series (in)
1038                     Name of the series the dot belongs  to.  Determines  size
1039                     and colour
1040
1041              float xcrd (in)
1042                     X-coordinate of the point where the arrow appears
1043
1044              float ycrd (in)
1045                     Y-coordinate of the point where the arrow appears
1046
1047              float value (in)
1048                     Value determining size and colour
1049
1050       $xyplot dotconfig series -option value ...
1051              ] Set the dot drawing options for a particular series
1052
1053              string series (in)
1054                     Name of the series the dot belongs to.
1055
1056              The options can be one of the following:
1057
1058              colour The  colour of the dot if no scaling is used or the value
1059                     exceeds the last limit of the classes.
1060
1061              scale value
1062                     The scale factor used  to  convert  the  value  into  the
1063                     radius of the dot in pixels (default: 1.0)
1064
1065              radius value
1066                     The default radius of the dots, used if there is no scal‐
1067                     ing by value (in pixels; default: 3)
1068
1069              scalebyvalue onoff
1070                     Determines whether the dots all have the same size  or  a
1071                     size depending on the given value (default: on).
1072
1073              outline onoff
1074                     Draw a black circle around the dot or not (default: on)
1075
1076              classes list
1077                     Set   the  limits  and  the  corresponding  colours.  For
1078                     instance:
1079
1080
1081                         $xyplot series1 -classes {0 blue 1 green} -colour red
1082
1083
1084                     will cause a blue dot to be drawn for values smaller than
1085                     0, a green dot for values larger/equal 0 but lower than 1
1086                     and a red dot for values larger/equal 1.
1087
1088                     If there is no list of classes for the particular series,
1089                     the dots are scaled by the value.
1090
1091                     You can combine the colouring by value and the scaling by
1092                     value by setting a list of classes and setting the scale‐
1093                     byvalue option on.
1094
1095
1096       $xyplot contourlines xcrd ycrd values ?classes?
1097              Draw contour lines for the values given on the grid. The grid is
1098              defined by the xcrd and ycrd arguments (they give the x- and  y-
1099              coordinates  of  the grid cell corners). The values are given at
1100              these corners. The classes determine  which  contour  lines  are
1101              drawn.  If a value on one of the corners is missing, the contour
1102              lines in that cell will not be drawn.
1103
1104              list xcrd (in)
1105                     List of lists, each value is an x-coordinate for  a  grid
1106                     cell corner
1107
1108              list ycrd (in)
1109                     List  of  lists, each value is an y-coordinate for a grid
1110                     cell corner
1111
1112              list values (in)
1113                     List of lists, each value is the value  at  a  grid  cell
1114                     corner
1115
1116              list classes (in)
1117                     List  of  class values or a list of lists of two elements
1118                     (each inner list the class value and  the  colour  to  be
1119                     used).  If  empty  or missing, the classes are determined
1120                     automatically.
1121
1122                     Note: The class values must enclose the  whole  range  of
1123                     values.
1124
1125
1126       $xyplot contourfill xcrd ycrd values ?classes?
1127              Draw  filled contours for the values given on the grid. (The use
1128              of this method is identical to the "contourlines" method).
1129
1130       $xyplot contourbox xcrd ycrd values ?classes?
1131              Draw the cells as filled quadrangles. The colour  is  determined
1132              from the average of the values on all four corners.
1133
1134       $xyplot colorMap colours
1135              Set  the  colours to be used with the contour methods. The argu‐
1136              ment is either a predefined colourmap (grey/gray,  jet,  hot  or
1137              cool) or a list of colours. When selecting the colours for actu‐
1138              ally drawing the contours, the given colours  will  be  interpo‐
1139              lated (based on the HLS scheme).
1140
1141              list colours (in)
1142                     List  of colour names or colour values or one of the pre‐
1143                     defined maps:
1144
1145                     ·      grey or gray: gray colours from dark to light
1146
1147                     ·      jet: rainbow colours
1148
1149                     ·      hot: colours from yellow via red to darkred
1150
1151                     ·      cool: colours from cyan via blue to magenta
1152
1153       $xyplot grid xcrd ycrd
1154              Draw the grid cells as lines connecting the (valid) grid points.
1155
1156              list xcrd (in)
1157                     List of lists, each value is an x-coordinate for  a  grid
1158                     cell corner
1159
1160              list ycrd (in)
1161                     List  of  lists, each value is an y-coordinate for a grid
1162                     cell corner
1163
1164       For polar plots:
1165
1166       $polarplot plot series radius angle
1167              Add a data point to the polar plot.
1168
1169              string series (in)
1170                     Name of the data series the new point belongs to.
1171
1172              float radius (in)
1173                     Radial coordinate of the new point.
1174
1175              float angle (in)
1176                     Angular coordinate of the new point (in degrees).
1177
1178       For 3D plots:
1179
1180       $plot3d plotfunc function
1181              Plot a function defined over two variables x and y.  The resolu‐
1182              tion  is  determined by the set grid sizes (see the method grid‐
1183              size for more information).
1184
1185              string function (in)
1186                     Name of the procedure that calculates the z-value for the
1187                     given  x  and  y coordinates. The procedure has to accept
1188                     two float arguments (x is first argument,  y  is  second)
1189                     and return a floating-point value.
1190
1191
1192       $plot3d plotfuncont function contours
1193              Plot  a  function  defined  over two variables x and y using the
1194              contour levels in contours to colour the surface.   The  resolu‐
1195              tion  is  determined by the set grid sizes (see the method grid‐
1196              size for more information).
1197
1198              string function (in)
1199                     Name of the procedure that calculates the z-value for the
1200                     given  x  and  y coordinates. The procedure has to accept
1201                     two float arguments (x is first argument,  y  is  second)
1202                     and return a floating-point value.
1203
1204              list contours (in)
1205                     List of values in ascending order that represent the con‐
1206                     tour levels (the boundaries between the  colours  in  the
1207                     contour map).
1208
1209
1210       $plot3d gridsize nxcells nycells
1211              Set the grid size in the two directions. Together they determine
1212              how many polygons will be drawn for a function plot.
1213
1214              int nxcells (in)
1215                     Number of grid cells in x direction. Has to be an integer
1216                     number greater than zero.
1217
1218              int nycells (in)
1219                     Number of grid cells in y direction. Has to be an integer
1220                     number greater than zero.
1221
1222
1223       $plot3d plotdata data
1224              Plot a matrix of data.
1225
1226              list data (in)
1227                     The data to be plotted. The data has to be provided as  a
1228                     nested  list with 2 levels. The outer list contains rows,
1229                     drawn in y-direction, and each row is a list  whose  ele‐
1230                     ments are drawn in x-direction, for the columns. Example:
1231
1232
1233
1234                         set data {
1235                         {1.0 2.0 3.0}
1236                         {4.0 5.0 6.0}
1237                         }
1238
1239
1240
1241       $plot3d colours fill border
1242              Configure the colours to use for polygon borders and inner area.
1243
1244              color fill (in)
1245                     The colour to use for filling the polygons.
1246
1247              color border (in)
1248                     The colour to use for the border of the polygons.
1249
1250       For xy plots, stripcharts and polar plots:
1251
1252       $xyplot dataconfig series -option value ...
1253              Set  the  value for one or more options regarding the drawing of
1254              data of a specific series.
1255
1256              string series (in)
1257                     Name of the data series whose configuration we are chang‐
1258                     ing.
1259
1260       The following options are allowed:
1261
1262              colour c
1263
1264              color c
1265                     The colour to be used when drawing the data series.
1266
1267              type enum
1268                     The  drawing mode chosen for the series.  This can be one
1269                     of line, symbol, or both.
1270
1271              symbol enum
1272                     What kind of symbol to draw. The value of this option  is
1273                     ignored  when  the drawing mode line was chosen. This can
1274                     be one of plus, cross, circle, up (triangle pointing up),
1275                     down  (triangle  pointing  down),  dot  (filled  circle),
1276                     upfilled or downfilled (filled triangles).
1277
1278              filled enum
1279                     Whether to fill the area above or below the data line  or
1280                     not. Can be one of: no, up or down (SPECIAL EFFECTS)
1281
1282              fillcolour colour
1283                     Colour  to  use when filling the area associated with the
1284                     data line.
1285
1286       For piecharts:
1287
1288       $pie plot data
1289              Fill a piechart.
1290
1291              list data (in)
1292                     A list of pairs (labels and values). The values determine
1293                     the  relative size of the circle segments. The labels are
1294                     drawn beside the circle.
1295
1296       $pie colours colour1 colour2 ...
1297              Set the colours to be used.
1298
1299              color colour1 (in)
1300                     The first colour.
1301
1302              color colour2 (in)
1303                     The second colour, and so on.
1304
1305       For radial charts:
1306
1307       $radial plot data colour thickness
1308              Draw a new line in the radial chart
1309
1310              list data (in)
1311                     A list of data (one for each spoke). The values determine
1312                     the  distance  from the centre of the line connecting the
1313                     spokes.
1314
1315              color colour (in)
1316                     The colour for the line.
1317
1318              int thickness (in)
1319                     An optional argument for the thickness of the line.
1320
1321       $pie colours colour1 colour2 ...
1322              Set the colours to be used.
1323
1324              color colour1 (in)
1325                     The first colour.
1326
1327              color colour2 (in)
1328                     The second colour, and so on.
1329
1330       For vertical barcharts:
1331
1332       $barchart plot series ydata colour
1333              Add a data series to a barchart.
1334
1335              string series (in)
1336                     Name of the series the values belong to.
1337
1338              list ydata (in)
1339                     A list of values, one for each x-axis label.
1340
1341              color colour (in)
1342                     The colour of the bars.
1343
1344       For horizontal barcharts:
1345
1346       $barchart plot series xdata colour
1347              Add a data series to a barchart.
1348
1349              string series (in)
1350                     Name of the series the values belong to.
1351
1352              list xdata (in)
1353                     A list of values, one for each y-axis label.
1354
1355              color colour (in)
1356                     The colour of the bars.
1357
1358       For 3D barcharts:
1359
1360       $barchart plot label yvalue colour
1361              Add the next bar to the barchart.
1362
1363              string label (in)
1364                     The label to be shown below the column.
1365
1366              float yvalue (in)
1367                     The value that determines the height of the column
1368
1369              color colour (in)
1370                     The colour of the column.
1371
1372       $barchart config -option value ...
1373              Set one or more configuration parameters. The following  options
1374              are supported:
1375
1376              usebackground boolean
1377                     Whether  to draw walls to the left and to the back of the
1378                     columns or not
1379
1380              useticklines boolean
1381                     Whether to draw ticklines on the walls or not
1382
1383              showvalues boolean
1384                     Whether to show the values or not
1385
1386              labelfont newfont
1387                     Name of the font to use for labels
1388
1389              labelcolour colour
1390                     Colour for the labels
1391
1392              valuefont newfont
1393                     Name of the font to use for the values
1394
1395              valuecolour colour
1396                     Colour for the values
1397
1398       For 3D ribbon charts:
1399
1400       $ribbon line xypairs colour
1401              Plot the given xy-pairs as a ribbon in the chart
1402
1403              list xypairs (in)
1404                     The pairs of x/y values to be drawn (the series is  drawn
1405                     as a whole)
1406
1407              color colour (in)
1408                     The colour of the ribbon.
1409
1410       $ribbon area xypairs colour
1411              Plot the given xy-pairs as a ribbon with a filled area in front.
1412              The effect is that of a box with the data as its upper surface.
1413
1414              list xypairs (in)
1415                     The pairs of x/y values to be drawn (the series is  drawn
1416                     as a whole)
1417
1418              color colour (in)
1419                     The colour of the ribbon/area.
1420
1421       For boxplots:
1422
1423       $boxplot plot label values
1424              Add a box-and-whisker to the plot.
1425
1426              string label (in)
1427                     The label along the y-axis to which the data belong
1428
1429              list values (in)
1430                     List  of  raw  values,  the  extent  of  the  box and the
1431                     whiskers will be determined from this list.
1432
1433       For timecharts:
1434
1435       $timechart period text time_begin time_end colour
1436              Add a time period to the chart.
1437
1438              string text (in)
1439                     The text describing the period.
1440
1441              string time_begin (in)
1442                     Start time of the period.
1443
1444              string time_end (in)
1445                     Stop time of the period.
1446
1447              color colour (in)
1448                     The colour of the bar (defaults to black).
1449
1450
1451       $timechart milestone text time colour
1452              Add a milestone (represented as an point-down triangle)  to  the
1453              chart.
1454
1455              string text (in)
1456                     The text describing the milestone.
1457
1458              string time (in)
1459                     Time at which the milestone must be positioned.
1460
1461              color colour (in)
1462                     The colour of the triangle (defaults to black).
1463
1464
1465       $timechart vertline text time
1466              Add  a  vertical  line  (to  indicate the start of the month for
1467              instance) to the chart.
1468
1469              string text (in)
1470                     The text appearing at the top  (an  abbreviation  of  the
1471                     date/time for instance).
1472
1473              string time (in)
1474                     Time at which the line must be positioned.
1475
1476       $timechart hscroll scrollbar
1477              Connect  a  horizontal scrollbar to the chart. See also the sec‐
1478              tion on scrolling.
1479
1480              widget scrollbar (in)
1481                     The horizontal scrollbar that is to be connected  to  the
1482                     chart
1483
1484       $timechart vscroll scrollbar
1485              Connect  a vertical scrollbar to the chart. See also the section
1486              on scrolling.
1487
1488              widget scrollbar (in)
1489                     The vertical scrollbar that is to  be  connected  to  the
1490                     chart
1491
1492       For Gantt charts:
1493
1494       $ganttchart task text time_begin time_end completed
1495              Add a task with its period and level of completion to the chart.
1496              Returns a list of canvas items that  can  be  used  for  further
1497              manipulations, like connecting two tasks.
1498
1499              string text (in)
1500                     The text describing the task.
1501
1502              string time_begin (in)
1503                     Start time of the task.
1504
1505              string time_end (in)
1506                     Stop time of the task.
1507
1508              float completed (in)
1509                     The percentage of the task that is completed.
1510
1511
1512       $ganttchart milestone text time colour
1513              Add  a  milestone (represented as an point-down triangle) to the
1514              chart.
1515
1516              string text (in)
1517                     The text describing the milestone.
1518
1519              string time (in)
1520                     Time at which the milestone must be positioned.
1521
1522              color colour (in)
1523                     The colour of the triangle (defaults to black).
1524
1525
1526       $ganttchart vertline text time
1527              Add a vertical line (to indicate the  start  of  the  month  for
1528              instance) to the chart.
1529
1530              string text (in)
1531                     The  text  appearing  at  the top (an abbreviation of the
1532                     date/time for instance).
1533
1534              string time (in)
1535                     Time at which the line must be positioned.
1536
1537
1538       $ganttchart connect from to
1539              Add an arrow that connects the from task with the to task.
1540
1541              list from (in)
1542                     The list of items returned by  the  "task"  command  that
1543                     represents the task from which the arrow starts.
1544
1545              string text (in)
1546                     The text summarising the tasks
1547
1548              list args (in)
1549                     One  or more tasks (the lists returned by the "task" com‐
1550                     mand). They are shifted down to make room  for  the  sum‐
1551                     mary.
1552
1553              list to (in)
1554                     The  list  of  items  returned by the "task" command that
1555                     represents the task at which the arrow ends.
1556
1557
1558       $ganttchart summary text args
1559              Add a summary item that spans all the tasks listed. The  graphi‐
1560              cal representation is a thick bar running from the leftmost task
1561              to the rightmost.
1562
1563              Use this command before connecting the tasks, as the arrow would
1564              not be shifted down!
1565
1566              string text (in)
1567                     The text summarising the tasks
1568
1569              list args (in)
1570                     One  or more tasks (the lists returned by the "task" com‐
1571                     mand). They are shifted down to make room  for  the  sum‐
1572                     mary.
1573
1574
1575       $ganttchart color keyword newcolor
1576              Set  the colour of a part of the Gantt chart. These colours hold
1577              for all items of that type.
1578
1579              string keyword (in)
1580                     The keyword indicates which part of the  Gantt  chart  to
1581                     change:
1582
1583                     ·      description - the colour of the descriptive text
1584
1585                     ·      completed  -  the  colour of the filled bar repre‐
1586                            senting the completed part of a task
1587
1588                     ·      left - the colour for the part  that  is  not  yet
1589                            completed
1590
1591                     ·      odd - the background colour for the odd entries
1592
1593                     ·      even - the background colour for the even entries
1594
1595                     ·      summary - the colour for the summary text
1596
1597                     ·      summarybar - the colour for the bar for a summary
1598
1599              string newcolor (in)
1600                     The new colour for the chosen items.
1601
1602
1603       $ganttchart font keyword newfont
1604              Set  the font of a part of the Gantt chart. These fonts hold for
1605              all items of that type.
1606
1607              string keyword (in)
1608                     The keyword indicates which part of the  Gantt  chart  to
1609                     change:
1610
1611                     ·      description - the font used for descriptive text
1612
1613                     ·      summary - the font used for summaries
1614
1615                     ·      scale - the font used for the time scale
1616
1617              string newfont (in)
1618                     The new font for the chosen items.
1619
1620       $ganttchart hscroll scrollbar
1621              Connect  a  horizontal scrollbar to the chart. See also the sec‐
1622              tion on scrolling.
1623
1624              widget scrollbar (in)
1625                     The horizontal scrollbar that is to be connected  to  the
1626                     chart
1627
1628       $ganttchart vscroll scrollbar
1629              Connect  a vertical scrollbar to the chart. See also the section
1630              on scrolling.
1631
1632              widget scrollbar (in)
1633                     The vertical scrollbar that is to  be  connected  to  the
1634                     chart
1635
1636       For isometric plots (to be extended):
1637
1638       $isoplot plot rectangle x1 y1 x2 y2 colour
1639              Plot the outlines of a rectangle.
1640
1641              float x1 (in)
1642                     Minimum x coordinate of the rectangle to be drawn.
1643
1644              float y1 (in)
1645                     Minimum y coordinate of the rectangle.
1646
1647              float x2 (in)
1648                     Maximum x coordinate of the rectangle to be drawn.
1649
1650              float y2 (in)
1651                     Maximum y coordinate of the rectangle.
1652
1653              color colour (in)
1654                     The colour of the rectangle.
1655
1656
1657       $isoplot plot filled-rectangle x1 y1 x2 y2 colour
1658              Plot a rectangle filled with the given colour.
1659
1660              float x1 (in)
1661                     Minimum x coordinate of the rectangle to be drawn.
1662
1663              float y1 (in)
1664                     Minimum y coordinate of the rectangle.
1665
1666              float x2 (in)
1667                     Maximum x coordinate of the rectangle to be drawn.
1668
1669              float y2 (in)
1670                     Maximum y coordinate of the rectangle.
1671
1672              color colour (in)
1673                     The colour of the rectangle.
1674
1675
1676       $isoplot plot circle xc yc radius colour
1677              Plot the outline of a circle.
1678
1679              float xc (in)
1680                     X coordinate of the circle's centre.
1681
1682              float yc (in)
1683                     Y coordinate of the circle's centre.
1684
1685              color colour (in)
1686                     The colour of the circle.
1687
1688
1689       $isoplot plot filled-circle xc yc radius colour
1690              Plot a circle filled with the given colour.
1691
1692              float xc (in)
1693                     X coordinate of the circle's centre.
1694
1695              float yc (in)
1696                     Y coordinate of the circle's centre.
1697
1698              color colour (in)
1699                     The colour of the circle.
1700
1701       There  are a number of public procedures that may be useful in specific
1702       situations: Pro memorie.
1703

COORDINATE TRANSFORMATIONS

1705       Besides the commands that deal with  the  plots  and  charts  directly,
1706       there  are a number of commands that can be used to convert world coor‐
1707       dinates to pixels and vice versa.  These include:
1708
1709       ::Plotchart::viewPort w pxmin pymin pxmax pymax
1710              Set the viewport for window w. Should  be  used  in  cooperation
1711              with ::Plotchart::worldCoordinates.
1712
1713              widget w (in)
1714                     Name of the window (canvas widget) in question.
1715
1716              float pxmin (in)
1717                     Left-most pixel coordinate.
1718
1719              float pymin (in)
1720                     Top-most  pixel  coordinate (remember: the vertical pixel
1721                     coordinate starts with 0 at the top!).
1722
1723              float pxmax (in)
1724                     Right-most pixel coordinate.
1725
1726              float pymax (in)
1727                     Bottom-most pixel coordinate.
1728
1729
1730       ::Plotchart::worldCoordinates w xmin ymin xmax ymax
1731              Set the extreme world coordinates for window w. The world  coor‐
1732              dinates  need not be in ascending order (i.e. xmin can be larger
1733              than xmax, so that a reversal of the x-axis is achieved).
1734
1735              widget w (in)
1736                     Name of the window (canvas widget) in question.
1737
1738              float xmin (in)
1739                     X-coordinate to be mapped to left side of viewport.
1740
1741              float ymin (in)
1742                     Y-coordinate to be mapped to bottom of viewport.
1743
1744              float xmax (in)
1745                     X-coordinate to be mapped to right side of viewport.
1746
1747              float ymax (in)
1748                     Y-coordinate to be mapped to top side of viewport.
1749
1750
1751       ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
1752              Set the extreme three-dimensional world coordinates  for  window
1753              w.  The  world  coordinates need not be in ascending order (i.e.
1754              xmin can be larger than xmax, so that a reversal of  the  x-axis
1755              is achieved).
1756
1757              widget w (in)
1758                     Name of the window (canvas widget) in question.
1759
1760              float xmin (in)
1761                     X-coordinate  to  be mapped to front side of the 3D view‐
1762                     port.
1763
1764              float ymin (in)
1765                     Y-coordinate to be mapped to left side of the viewport.
1766
1767              float zmin (in)
1768                     Z-coordinate to be mapped to bottom of viewport.
1769
1770              float xmax (in)
1771                     X-coordinate to be mapped to back side of viewport.
1772
1773              float ymax (in)
1774                     Y-coordinate to be mapped to right side of viewport.
1775
1776              float zmax (in)
1777                     Z-coordinate to be mapped to top side of viewport.
1778
1779
1780       ::Plotchart::coordsToPixel w x y
1781              Return a list of pixel coordinates valid for the given window.
1782
1783              widget w (in)
1784                     Name of the window (canvas widget) in question.
1785
1786              float x (in)
1787                     X-coordinate to be mapped.
1788
1789              float y (in)
1790                     Y-coordinate to be mapped.
1791
1792
1793       ::Plotchart::coords3DToPixel w x y z
1794              Return a list of pixel coordinates valid for the given window.
1795
1796              widget w (in)
1797                     Name of the window (canvas widget) in question.
1798
1799              float x (in)
1800                     X-coordinate to be mapped.
1801
1802              float y (in)
1803                     Y-coordinate to be mapped.
1804
1805              float y (in)
1806                     Z-coordinate to be mapped.
1807
1808
1809       ::Plotchart::polarCoordinates w radmax
1810              Set the extreme polar coordinates for window w. The angle always
1811              runs from 0 to 360 degrees and the radius starts at 0. Hence you
1812              only need to give the maximum radius.  Note: If the viewport  is
1813              not square, this procedure will not adjust the extremes, so that
1814              would result in an elliptical plot. The creation routine  for  a
1815              polar plot always determines a square viewport.
1816
1817              widget w (in)
1818                     Name of the window (canvas widget) in question.
1819
1820              float radmax (in)
1821                     Maximum radius.
1822
1823
1824       ::Plotchart::polarToPixel w rad phi
1825              Wrapper  for a call to ::Plotchart::coordsToPixel, which assumes
1826              the world coordinates and viewport are set  appropriately.  Con‐
1827              verts  polar coordinates to pixel coordinates.  Note: To be use‐
1828              ful it should be accompanied by a matching ::Plotchart::worldCo‐
1829              ordinates  procedure. This is automatically taken care of in the
1830              creation routine for polar plots.
1831
1832              widget w (in)
1833                     Name of the window (canvas widget) in question.
1834
1835              float rad (in)
1836                     Radius of the point.
1837
1838              float phi (in)
1839                     Angle to the positive x-axis.
1840
1841
1842       ::Plotchart::pixelToCoords w x y
1843              Return a list of world coordinates valid for the given window.
1844
1845              widget w (in)
1846                     Name of the window (canvas widget) in question.
1847
1848              float x (in)
1849                     X-pixel to be mapped.
1850
1851              float y (in)
1852                     Y-pixel to be mapped.
1853
1854       ::Plotchart::pixelToIndex w x y
1855              Return the index of the pie segment containing the pixel coordi‐
1856              nates (x,y)
1857
1858              widget w (in)
1859                     Name of the window (canvas widget) in question, holding a
1860                     piechart.
1861
1862              float x (in)
1863                     X-pixel to be mapped.
1864
1865              float y (in)
1866                     Y-pixel to be mapped.
1867
1868       Furthermore there is a routine to determine "pretty"  numbers  for  use
1869       with an axis:
1870
1871       ::Plotchart::determineScale xmin xmax inverted
1872              Determine  "pretty"  numbers  from  the given range and return a
1873              list containing the minimum, maximum and stepsize  that  can  be
1874              used for a (linear) axis.
1875
1876              float xmin (in)
1877                     Rough minimum value for the scaling
1878
1879              float xmax (in)
1880                     Rough maximum value for the scaling.
1881
1882              boolean inverted (in)
1883                     Optional  argument: if 1, then the returned list produces
1884                     an inverted axis. Defaults to 0 (the axis  will  be  from
1885                     minimum to maximum)
1886

MISSING VALUES

1888       Often  data  that need to be plotted contain gaps - in a series of mea‐
1889       surement data, they can occur because the equipment  failed,  a  sample
1890       was  not  collected  correctly or for many other reasons. The Plotchart
1891       handles these gaps by assuming that one or  both  coordinates  of  such
1892       data points are an empty string:
1893
1894
1895                  #
1896                  # Create the plot with its x- and y-axes
1897                  #
1898                  set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
1899
1900                  foreach {x y} {0.0 32.0 10.0 {} 25.0 60.0 78.0 11.0 } {
1901                      $s plot series1 $x $y
1902                  }
1903
1904       The effect varies according to the type of plot:
1905
1906       ·      For  xy-plots,  radial  plots  and strip charts the missing data
1907              point causes a gap in the line through the points.
1908
1909       ·      For barchats, missing values are treated as if a value  of  zero
1910              was given.
1911
1912       ·      For  time  charts and Gantt charts missing values cause errors -
1913              there is no use for them there.
1914

OTHER OUTPUT FORMATS

1916       Besides output to the canvas on screen, the module is capable, via can‐
1917       vas  postscript,  of producing PostScript files. One may wonder whether
1918       it is possible to extend this set of output formats and the  answer  is
1919       "yes".  This  section  tries to sum up the aspects of using this module
1920       for another sort of output.
1921
1922       One way you can create output files in a different format, is by  exam‐
1923       ining  the  contents  of the canvas after everything has been drawn and
1924       render that contents in the right form. This is  probably  the  easiest
1925       way,  as  it involves nothing more than the re-creation of all the ele‐
1926       ments in the plot that are already there.
1927
1928       The drawback of that method is that you need to have a  display,  which
1929       is not always the case if you run a CGI server or something like that.
1930
1931       An  alternative is to emulate the canvas command. For this to work, you
1932       need to know which canvas subcommands are used and what for. Obviously,
1933       the  create  subcommand  is  used  to create the lines, texts and other
1934       items. But also the raise and lower subcommands are used, because  with
1935       these  the  module can influence the drawing order - important to simu‐
1936       late a clipping rectangle around the axes.  (The  routine  DrawMask  is
1937       responsible  for  this  - if the output format supports proper clipping
1938       areas, then a redefinition of this routine might just solve this).
1939
1940       Furthermore, the module uses the cget subcommand to find out the  sizes
1941       of  the  canvas.  A more mundane aspect of this is that the module cur‐
1942       rently assumes that the text is 14 pixels high and that  80  pixels  in
1943       width  suffice for the axis' labels. No "hook" is provided to customise
1944       this.
1945
1946       In summary:
1947
1948       ·      Emulate the create subcommand to create all  the  items  in  the
1949              correct format
1950
1951       ·      Emulate  the  cget subcommand for the options -width and -height
1952              to allow the correct calculation of the rectangle's position and
1953              size
1954
1955       ·      Solve the problem of raising and lowering the items so that they
1956              are properly clipped, for instance  by  redefining  the  routine
1957              DrawMask.
1958
1959       ·      Take care of the currently fixed text size properties
1960

SPECIAL EFFECTS

1962       As an example of some special effects you can achieve, here is the code
1963       for a plot where the area below the data line varies in colour:
1964
1965
1966              canvas .c  -background white -width 400 -height 200
1967              pack .c -fill both
1968
1969              set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
1970
1971              $s background gradient green top-down
1972
1973              $s dataconfig series1 -filled up -fillcolour white
1974
1975              $s plot series1  0.0 20.0
1976              $s plot series1 10.0 20.0
1977              $s plot series1 30.0 50.0
1978              $s plot series1 35.0 45.0
1979              $s plot series1 45.0 25.0
1980              $s plot series1 75.0 55.0
1981              $s plot series1 100.0 55.0
1982
1983              $s plaintext 30.0 60.0 "Peak" south
1984
1985       The trick is to fill the background with a  colour  that  changes  from
1986       green  at  the top to white at the bottom. Then the area above the data
1987       line is filled with a white polygon. Thus the green shading varies with
1988       the height of the line.
1989

ROOM FOR IMPROVEMENT

1991       In  this version there are a lot of things that still need to be imple‐
1992       mented:
1993
1994       ·      More robust handling of incorrect calls (right  now  the  proce‐
1995              dures may fail when called incorrectly):
1996
1997              ·      The  axis  drawing  routines  can not handle inverse axes
1998                     right now.
1999
2000              ·      If the user provides an  invalid  date/time  string,  the
2001                     routines simply throw an error.
2002

RESIZING

2004       Plotchart  has  not  been designed to create plots and charts that keep
2005       track of the data that are put in. This means that  if  an  application
2006       needs to allow the user to resize the window holding the plot or chart,
2007       it must take care to redraw the complete plot.
2008
2009       The code below is a simple example of how to do that:
2010
2011
2012              package require Plotchart
2013
2014              grid [canvas .c -background white] -sticky news
2015              grid columnconfigure . 0 -weight 1
2016              grid rowconfigure . 0 -weight 1
2017
2018              bind .c <Configure> {doResize}
2019
2020              proc doPlot {} {
2021                  #
2022                  # Clean up the contents (see also the note below!)
2023                  #
2024                  .c delete all
2025
2026                  #
2027                  # (Re)draw the bar chart
2028                  #
2029                  set p [::Plotchart::createBarchart .c {x y z} {0 100 10} 3]
2030                  $p plot R {10 30 40} red
2031                  $p plot G {30 40 60} green
2032              }
2033
2034              proc doResize {} {
2035                  global redo
2036
2037                  #
2038                  # To avoid redrawing the plot many times during resizing,
2039                  # cancel the callback, until the last one is left.
2040                  #
2041                  if { [info exists redo] } {
2042                      after cancel $redo
2043                  }
2044
2045                  set redo [after 50 doPlot]
2046              }
2047       Please note: The code above will work fine for barcharts and many other
2048       types  of plots, but as Plotchart keeps some private information for xy
2049       plots, more is needed in these cases. This actually requires a  command
2050       "destroyPlot" to take care of such details. A next version of Plotchart
2051       will have that.
2052

ZOOMING IN

2054       As the Plotchart package does  not  keep  track  of  the  data  itself,
2055       rescaling  an existing plot - for instance when zooming in - would have
2056       to be done by redefining the plot and redrawing the data. However,  the
2057       canvas  widget  offers  a  way out by scaling and moving items, so that
2058       zooming in becomes a bit simpler.
2059
2060       Whether zooming is indeed useful, depends on the  type  of  plot.  Cur‐
2061       rently  it is defined for XY-plots only. The method is called "rescale"
2062       and simply redraws the axes and scales and moves the data items so that
2063       they  conform  to  the  new  axes. The drawback is that any symbols are
2064       scaled by the same amount. The rescale method works best for plots that
2065       only have lines, not symbols.
2066
2067       The method works very simply:
2068
2069
2070                 $p rescale {newxmin newxmax newxstep} {newymin newymax newystep}
2071
2072

CONFIGURATION OPTIONS

2074       The  command  plotconfig  can be used to set all manner of options. The
2075       syntax is:
2076
2077       ::Plotchart::plotconfig charttype component property value
2078              Set a new value for the property of a component in a  particular
2079              chart  or plot type or query its current value. Each argument is
2080              optional.
2081
2082              string charttype (in)
2083                     The type of chart or plot  (see  the  configuration  type
2084                     that  is mentioned for each create command). If not given
2085                     or empty, a list of chart types is  returned.  If  it  is
2086                     given, the properties for that particular type are used.
2087
2088              string component (in)
2089                     The  component  of  the  plot/chart: leftaxis, rightaxis,
2090                     background, margin and so on. If not given  or  empty,  a
2091                     list of components is returned. If it is given, the prop‐
2092                     erties for that particular component will be set for that
2093                     particular type of chart.
2094
2095              string property (in)
2096                     The  property  of  the component of the plot/chart: text‐
2097                     color, thickness of the axis line, etc. If not  given  or
2098                     empty,  a list of properties is returned. If it is given,
2099                     that particular property for  that  particular  component
2100                     will be set for that particular type of chart.
2101
2102              string value (in)
2103                     The  new  value  for  the property. If empty, the current
2104                     value is  returned.   If  the  value  is  "default",  the
2105                     default value will be restored.
2106
2107                     Note,  that  in  some cases an empty value is useful. Use
2108                     "none" in this case - it can be useful  for  colours  and
2109                     for formats.
2110
2111       Below is a more detailed list of the components and properties:
2112
2113       ·      Axes come in a wide variety:
2114
2115              ·      leftaxis,  rightaxis,  topaxis,  bottomaxis for the plots
2116                     with a rectangular shape.
2117
2118              ·      xaxis, yaxis and zaxis are used for the 3D plots
2119
2120              ·      axis, this represents the radial and tangential axes of a
2121                     polar plot
2122
2123              All axes have the following properties:
2124
2125              ·      color - the colour of the line and the tickmarks
2126
2127              ·      thickness - the width of the line of the axis itself, not
2128                     the tickmarks
2129
2130              ·      ticklength - the length of the  tickmarks  in  pixels.  A
2131                     positive value is outward, a negative value is inward.
2132
2133              ·      font - the font for the labels and the text at the axis
2134
2135              ·      format - the format for rendering the (numerical) labels.
2136                     For the time axis it is the format for a date and time.
2137
2138              ·      textcolor - the colour for the labels and the text.
2139
2140       ·      The margin is important for the layout. Currently only the  rec‐
2141              tangular plots allow the margins to be set: left, right, top and
2142              bottom.  The values are in pixels.
2143
2144       ·      The text component is meant  for  any  text  appearing  via  the
2145              plaintext  subcommand.  The  properties are: textcolor, font and
2146              anchor (positioning of the text relative to  the  given  coordi‐
2147              nates).
2148
2149       ·      The  background  has two properties: outercolor, the colour out‐
2150              side of the actual plot, and innercolor, the colour  inside  the
2151              plot. (Note: only "outercolor" has now been implemented).
2152
2153       ·      The  legend  has  three properties: background, border and posi‐
2154              tion.  See the legend subcommand for the meaning.
2155
2156       See the examples in plotdemos7.tcl for it use.
2157

SCROLLING FOR TIMECHARTS AND GANTT CHARTS

2159       For two types of plots automatic scrolling management has  been  imple‐
2160       mented:  timecharts  and  Gantt  charts.  The  subcommands  hscroll and
2161       vscroll associate (existing) scrollbars to the plot, in much  the  same
2162       way as for text and canvas widgets.
2163
2164       Once  the association is made, the scrollbars are automatically updated
2165       if:
2166
2167       ·      You add an item with a period wider than the current one.
2168
2169       ·      You add a vertical line for a time beyond the current bounds.
2170
2171       ·      You add an extra item beyond the number that was used to  create
2172              the chart.
2173
2174       For instance:
2175
2176
2177              package require Plotchart
2178
2179              canvas .c -width 400 -height 200
2180              scrollbar .y -orient vertical
2181              scrollbar .x -orient horizontal
2182
2183              grid .c .y -sticky news
2184              grid .x    -sticky news
2185
2186              source plotchart.tcl
2187
2188              set s [::Plotchart::createTimechart .c "1 january 2004"  "31 december 2004" 4]
2189
2190              $s period "Spring" "1 march 2004" "1 june 2004" green
2191              $s period "Summer" "1 june 2004" "1 september 2004" yellow
2192              $s vertline "1 jan" "1 january 2004"
2193              $s vertline "1 apr" "1 april 2004"
2194              $s vertline "1 jul" "1 july 2004"
2195              $s vertline "1 oct" "1 october 2004"
2196              $s vertline "1 jan" "1 january 2005"
2197              $s vertline "1 apr" "1 april 2005"
2198              $s vertline "1 jul" "1 july 2005"
2199              $s milestone "Longest day" "21 july 2004"
2200              $s milestone "Longest day 2" "21 july 2004"
2201              $s milestone "Longest day 3" "21 july 2004"
2202              $s milestone "Longest day 4" "21 july 2004"
2203              $s milestone "Longest day 5" "21 july 2004"
2204              $s milestone "Longest day 6" "21 july 2004"
2205              $s title "Seasons (northern hemisphere)"
2206
2207              $s vscroll .y
2208              $s hscroll .x
2209
2210       The  original extent of the chart is from 1 january 2004 to 31 december
2211       2004. But because of the addition of vertical lines in  2005  and  more
2212       items  than  was specified at the creation of the chart, both the hori‐
2213       zontal and the vertical scrollbar will be enabled.
2214

ARRANGING MULTIPLE PLOTS IN A CANVAS

2216       The command plotpack allows you to copy the contents  of  a  plot  into
2217       another  canvas  widget. This canvas widget does not act as a composite
2218       plot, but it can be saved as a PostScript file for instance: Note:  the
2219       command simply takes a snapshot of the plots/charts as they are at that
2220       moment.
2221
2222       ::Plotchart::plotpack w dir args
2223              Copy the contents of the plots/charts into another widget, in  a
2224              manner similar to the pack geometry manager.
2225
2226              widget w (in)
2227                     The  name  of  the canvas widget to copy the plots/charts
2228                     into
2229
2230              string dir (in)
2231                     The direction of the arrangement - top, left,  bottom  or
2232                     right
2233
2234              list args (in)
2235                     List of plots/charts to be copied.
2236
2237       For example:
2238
2239
2240                  set p1 [createXYPlot ...]
2241                  set p2 [createBarchart ...]
2242
2243                  ... fill the plots ...
2244
2245                  toplevel .t
2246                  pack [canvas .t.c2 -width ...]
2247
2248                  #
2249                  # Copy the two plots above each other in the new canvas
2250                  #
2251                  plotpack .t.c2 top $p1 $p2
2252
2253

NOTES ON TAGS

2255       P.M.
2256

TODO - SOME PRIVATE NOTES

2258       I have the following wishlist:
2259
2260       ·      Isometric plots - allow new items to be implemented easily.
2261
2262       ·      A general 3D viewer - emphasis on geometry, not a ray-tracer.
2263
2264       ·      Several improvements for boxplots:
2265
2266              ·      Height of the box scales with the logarithm of the number
2267                     of points
2268
2269              ·      Marker line to indicate a "current" value
2270
2271              ·      Box drawn from quantiles
2272

KEYWORDS

2274       3D bars, 3D surfaces, bar charts, charts,  coordinate  transformations,
2275       coordinates, graphical presentation, isometric plots, pie charts, plot‐
2276       ting, polar plots, strip charts, time charts, xy-plots
2277
2279       Copyright (c) 2007 Arjen Markus <arjenmarkus@users.sourceforge.net>
2280
2281
2282
2283
2284plotchart                             1.6                         Plotchart(n)
Impressum