Tk Library Source Code

Documentation
Login


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

Plotchart - Simple plotting and charting package

Table Of Contents

SYNOPSIS

package require Tcl ?8.5?
package require Tk ?8.5?
package require Plotchart ?2.6.2?

::Plotchart::createXYPlot w xaxis yaxis args
::Plotchart::createStripchart w xaxis yaxis args
::Plotchart::createTXPlot w timeaxis xaxis args
::Plotchart::createXLogYPlot w xaxis yaxis args
::Plotchart::createLogXYPlot w xaxis yaxis args
::Plotchart::createLogXLogYPlot w xaxis yaxis args
::Plotchart::createPolarPlot w radius_data args
::Plotchart::createWindrose w radius_data sectors
::Plotchart::createIsometricPlot w xaxis yaxis stepsize
::Plotchart::createHistogram w xaxis yaxis args
::Plotchart::create3DPlot w xaxis yaxis zaxis args
::Plotchart::create3DRibbonPlot w yaxis zaxis
::Plotchart::createPiechart w
::Plotchart::createSpiralPie w
::Plotchart::createRadialchart w names scale style
::Plotchart::createBarchart w xlabels yaxis noseries args
::Plotchart::createHorizontalBarchart w xaxis ylabel noseries
::Plotchart::create3DBarchart w yaxis nobars
::Plotchart::create3DRibbonChart w names yaxis zaxis
::Plotchart::createBoxplot w xdata ydata orientation
::Plotchart::createTimechart w time_begin time_end args
::Plotchart::createGanttchart w time_begin time_end args
::Plotchart::createRightAxis w_or_plot yaxis
::Plotchart::createTableChart w columns ?widths?
::Plotchart::createTernaryDiagram w args
::Plotchart::createNormalPlot w xscale args
::Plotchart::createStatusTimeline w xaxis ylabel args
::Plotchart::createDendrogram w args
$anyplot title text position
$anyplot subtitle text
$anyplot canvas
$anyplot saveplot filename args
$anyplot xtext text
$anyplot ytext text
$anyplot vtext text
$anyplot xsubtext text
$anyplot ysubtext text
$anyplot vsubtext text
$anyplot xconfig -option value ...
$anyplot yconfig -option value ...
$anyplot background part colour_or_image dir ?brightness?
$anyplot xticklines colour ?dash?
$anyplot yticklines colour ?dash?
$anyplot legend series text ?spacing?
$anyplot removefromlegend series
$anyplot legendconfig -option value ...
$anyplot balloon x y text dir
$anyplot balloonconfig args
$anyplot plaintext x y text dir
$anyplot plaintextconfig args
$anyplot object itemtype series args
$anyplot deletedata
$xyplot plot series xcrd ycrd
$normalplot plot series mean stdev data
$normalplot diagonal
$xyplot plotlist series xlist ylist every
$xyplot region series xlist ylist
$xyplot minmax series xcrd ymin ymax
$histogram plotcumulative series xcrd ycrd
$xyplot trend series xcrd ycrd
$xyplot rchart series xcrd ycrd
$xyplot interval series xcrd ymin ymax ?ycentr?
$xyplot box-and-whiskers series xcrd ycrd
$xyplot violin series xcrd ycrd
$xyplot vector series xcrd ycrd ucmp vcmp
$xyplot vectorconfig series -option value ...
$xyplot dot series xcrd ycrd value
$xyplot dotconfig series -option value ...
$xyplot contourlines xcrd ycrd values ?classes?
$xyplot contourlinesfunctionvalues xvec yvec valuesmat ?classes?
$xyplot contourfill xcrd ycrd values ?classes?
$xyplot contourbox xcrd ycrd values ?classes?
$xyplot colorMap colours
$xyplot legendisolines values classes
$xyplot legendshades values classes
$xyplot grid xcrd ycrd
$xyplot xband ymin ymax
$xyplot yband xmin xmax
$xyplot labeldot x y text orient
$polarplot plot series radius angle
$windrose plot data colour
$plot3d plotfunc function
$plot3d plotfuncont function contours
$plot3d gridsize nxcells nycells
$plot3d plotdata data
$plot3d interpolatedata data contours
$plot3d colour fill border
$plot3d ribbon yzpairs
$plot3d plot yzpairs
$xyplot dataconfig series -option value ...
$pie plot data
$pie colours colour1 colour2 ...
$pie explode segment
$radial plot data colour thickness
$pie colours colour1 colour2 ...
$barchart plot series ydata colour ?dir? ?brightness?
$barchart config -option value ...
$barchart plot series xdata colour ?dir? ?brightness?
$barchart config -option value ...
$barchart plot label yvalue colour
$barchart config -option value ...
$ribbon line xypairs colour
$ribbon area xypairs colour
$boxplot plot series label values
$boxplot violin series label values
$timechart period text time_begin time_end colour
$timechart addperiod time_begin time_end colour
$timechart milestone text time colour
$timechart addmilestone time colour
$timechart vertline text time colour
$timechart hscroll scrollbar
$timechart vscroll scrollbar
$ganttchart task text time_begin time_end completed
$ganttchart milestone text time colour
$ganttchart vertline text time
$ganttchart connect from to
$ganttchart summary text args
$ganttchart color keyword newcolor
$ganttchart font keyword newfont
$ganttchart hscroll scrollbar
$ganttchart vscroll scrollbar
$isoplot plot rectangle x1 y1 x2 y2 colour
$isoplot plot filled-rectangle x1 y1 x2 y2 colour
$isoplot plot circle xc yc radius colour
$isoplot plot filled-circle xc yc radius colour
$table row items
$table separator
$table formatcommand procname
$table cellconfigure args
$ternary plot series xcrd ycrd zcrd text dir
$ternary line series coords
$ternary fill series coords
$ternary text xtext ytext ztext
$ternary ticklines colour
$timeline plot series item start stop color
$timeline vertline text time args
$dendrogram plot series data
::Plotchart::viewPort w pxmin pymin pxmax pymax
::Plotchart::worldCoordinates w xmin ymin xmax ymax
::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
::Plotchart::coordsToPixel w x y
::Plotchart::coords3DToPixel w x y z
::Plotchart::polarCoordinates w radmax
::Plotchart::polarToPixel w rad phi
::Plotchart::pixelToCoords w x y
::Plotchart::pixelToIndex w x y
::Plotchart::determineScale xmin xmax inverted
::Plotchart::determineScaleFromList values inverted
::Plotchart::plotconfig charttype component property value
::Plotchart::plotstyle subcmd style args
::Plotchart::eraseplot anyplot
::Plotchart::createTargetDiagram w limits scale
$target plot series xvalues yvalues
::Plotchart::createPerformanceProfile w max
$performance plot series_and_data_pairs
::Plotchart::createTaylorDiagram w radius_data args
$taylor plot series stdev corr
::Plotchart::createHeatmap w rowlabels columnlabels args
$heatmap plot row label data
$heatmap plot column label data
$heatmap plot cell rowlabel columnlabel value
$heatmap scale values min max
$heatmap scale colours mincolour maxcolour
::Plotchart::createCircleplot w labels args
$circleplot connect label1 label2 colour width
$circleplot modify label args
::Plotchart::plotmethod charttype methodname plotproc
::Plotchart::plotpack w dir args
$anyplot bindplot event command args
$anyplot bindlast series event command

DESCRIPTION

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

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

package require Plotchart

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

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

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

$s title "Data series"

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

With version 1.5 a new command has been introduced: plotconfig, which can be used to configure the plot options for particular types of plots and charts (cf. CONFIGURATION OPTIONS AND OTHER COMMANDS) With version 1.8.3 several new features were introduced, which allow more interactivity (cf. INTERACTIVE USE) With version 2.0 it has become possible to put several plots or charts in one canvas.

PLOT CREATION COMMANDS

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

PLOT METHODS

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

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

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

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

For normal plots:

For xy, x-log y, log-x-y, log-x-log-y plots there is the additional command plotlist, which is useful for plotting a large amount of data:

Other commands for xy, x-log y, log-x-y, log-x-log-y plots are region and minmax to draw filled polygons:

Note on histograms:

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

For histograms you can also use the plotcumulative command:

The arguments mean exactly the same as for the plot command, but the data are accumulated to the previous values.

For xy plots:

For polar plots:

For wind rose diagrams:

For 3D plots:

For 3D ribbon plots:

For xy plots, stripcharts, histograms, polar plots and ternary diagrams:

For piecharts and spiral pies:

For radial charts:

For vertical barcharts:

For horizontal barcharts:

For 3D barcharts:

For 3D ribbon charts:

For boxplots:

For timecharts:

For Gantt charts:

For isometric plots (to be extended):

For tables you can use the following subcommands:

For ternary diagrams you can use the following subcommands:

For status timeline plots you can use the following subcommands:

For dendrograms there is one specific subcommand:

COORDINATE TRANSFORMATIONS

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

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

MISSING VALUES

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

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

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

The effect varies according to the type of plot:

OTHER OUTPUT FORMATS

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

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

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

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

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

In summary:

SPECIAL EFFECTS

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

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

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

$s background gradient green top-down

$s dataconfig series1 -filled up -fillcolour white

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

$s plaintext 30.0 60.0 "Peak" south

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

ROOM FOR IMPROVEMENT

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

RESIZING

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

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

package require Plotchart

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

bind .c <Configure> {doResize}

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

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

proc doResize {} {
    global redo

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

    set redo [after 50 doPlot]
}

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

Alternatively, you can use the xyplot package which is built on top of Plotchart. This package supports zooming in and zooming out, as well as resizing the plot as a whole. Here is a small demonstration program:

# xyplot_demo.tcl --
#     Demonstration of the xyplot package
#

package require xyplot

set xydata1 {}
set xydata2 {}
set xydata3 {}
set xydata4 {}
for { set i 0 } { $i < 1024 } { incr i } {
    lappend xydata1 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2))}]
    lappend xydata2 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6))}]
    lappend xydata3 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6) + 0.0625 * sin($i/256.0*3.1415*10))}]
    lappend xydata4 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6) + 0.0625 * sin($i/256.0*3.1415*10) + 0.015625 * sin($i/256.0*3.1415*14))}]
}

set xyp [xyplot .xyp -xformat "%5.0f" -yformat "%5.0f" -title "XY plot testing" -background gray90]
pack $xyp -fill both -expand true

set s1 [$xyp add_data sf1 $xydata1 -legend "Serie 1 data" -color red]
set s2 [$xyp add_data sf2 $xydata2 -legend "Serie 2 data" -color green]
set s3 [$xyp add_data sf3 $xydata3 -legend "Serie 3 data" -color blue]
set s4 [$xyp add_data sf4 $xydata4 -legend "Serie 4 data" -color orange]

set xyp2 [xyplot .xyp2 -xticks 8 -yticks 4 -yformat %.2f -xformat %.0f]
pack $xyp2 -fill both -expand true

set s1 [$xyp2 add_data sf1 $xydata1]
set s2 [$xyp2 add_data sf2 $xydata2]
set s3 [$xyp2 add_data sf3 $xydata3]
set s4 [$xyp2 add_data sf4 $xydata4]

Zooming in is done by selecting a rectangle with the left mouse button pressed. Zooming out is done by pressing the right mouse button. If you resize the window, the canvases inside are resized too. If you zoom in, you can scroll the plot via the scrollbars that are automatically attached.

ZOOMING IN

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

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

The method works very simply:

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

CONFIGURATION OPTIONS AND OTHER COMMANDS

The commands plotconfig and plotstyle can be used to set all manner of options. The command eraseplot can be used to completely erase a plot or chart. The syntax of these commands is:

Below is a detailed list of the components and properties:

See the examples in plotdemos7.tcl for its use.

SCROLLING FOR TIMECHARTS AND GANTT CHARTS

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

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

For instance:

package require Plotchart

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

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

source plotchart.tcl

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

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

$s vscroll .y
$s hscroll .x

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

SPECIALISED PLOTS

Most of the plot and chart types described above have a fairly general use and you simply prepares the data to be plotted yourself. This section describes several plot types that are more specialised, in the sense that they have specific purposes and you pass raw data that are then processed in the plotting routines.

Currently there are the following types:

Most of the general methods for XY-plots work for these plots as well, but their creation and the methods to plot the data are very specific.

ADDING SPECIFIC PLOT METHODS

The command plotmethod can be used to add new methods for a particular plot or chart type. It is intended to help you develop specialised graphical displays.

Here is a trivial example of how to use this:

#
# The custom method "doodle" always adds the text "DOODLE"
# to the plot
#
proc doodle {p w x y} {
    $p plaintext $x $y "DOODLE"
}
::Plotchart::plotmethod xyplot doodle doodle

#
# Use it
pack [canvas .c]

set p [::Plotchart::createXYPlot .c {0 100 10} {0 20 5}]

$p doodle 40 10

TABLE CHARTS

To show what you can do with table charts, here is a simple example that plots a number of random data. The colours depend on the range that the data belong to. For this the procedure setColor is used.

package require Plotchart

pack [canvas .c -bg white -height 300] -fill both -expand yes

::Plotchart::plotconfig table frame outerwidth 3
::Plotchart::plotconfig table frame color red

set t [::Plotchart::createTableChart .c {"Column 1" "Column 2" "Column 3"} 80]


proc setColor {table widget row col value} {
    $table cellconfigure -background white -color black
    if { $value < 2.0 } {
        $table cellconfigure -background red -color white
    }
    if { $value > 6.0 } {
        $table cellconfigure -background green
    }

    return [format "%6.3f" $value]
}

# Command must already exist ...
$t formatcommand setColor

$t title "Demonstration of table charts"
$t separator

for {set i 0} {$i < 9} {incr i} {
    set row {}

    for {set j 0} {$j < 3} {incr j} {
        lappend row [expr {10.0 * rand()}]
    }

    if { $i == 3 } {
        $t separator
    }

    $t row $row
}

CONTROL DISPLAYS

TODO

USING DATE/TIME LABELS

The options -timeformat and -gmt are used to control the display of date/time labels along the x-axis for those plot types for which it makes sense. These options were implemented to take care of date/time labels for stripcharts, as you can also use custom labels (the option -xlabels) if the axis is "static". Since this is not the case for stripcharts, this was not an option (Tcllib/Tklib bug 3613718). You can also specify the -locale option to get a localised date/time label. The example below illustrates how to use the -timeformat option. The -gmt option merely suppresses the handling of daylight saving time by the [clock format] command.

package require Plotchart

pack [canvas .c -width 500 -bg white]

#
# Note that we need to present the x values as clock seconds
#
set start [clock scan  "0:00"]
set stop  [clock scan "10:00"]
set s [Plotchart::createStripchart .c [list $start $stop 7200] {0 10 1} -timeformat "%H:%M"]

# With a locale like "de":
#set s [Plotchart::createStripchart .c [list $start $stop 7200] {0 10 1} -timeformat "%H:%M" -locale de]

foreach {x y} {0 0 2 5 5 2 9 9 12 10} {
    set x [expr {$start + 3600 * $x}] ;# Convert hour to clock seconds
    $s plot a $x $y
}

The plot subcommand simply interprets the x and y data as straightforward numbers, so that you need to do the conversion from date/time to "clock seconds" yourself.

ARRANGING MULTIPLE PLOTS IN A CANVAS

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

For example:

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

... fill the plots ...

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

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

A different method is to use the -box and -axesbox options when creating the plot. These control the area in the canvas where the plot or chart will be drawn.

The -box option takes as its value a list of four numbers:

Specifying the width and height makes it easier to reposition the area with respect to other plots.

The -axesbox option is meant to make aligning the axes of a plot with those of other plots easier. The option takes a list of six arguments:

With this option the area the axes occupy is first determined and the complete area is derived from the margins.

For example:

set p2 [::Plotchart::createXYPlot .c {0 10 1} {-5 5 2.5} -axesbox [list $p1 ne 0 0 200 200]]

will create a second plot whose left axis coincides with the right axis of plot "\$p1" and the top of the axis is at the same heigt as well - because the axes are positioned at a point 0 pixels to the left and 0 pixels below the north-east corner.

INTERACTIVE USE

Plotchart has several features for interactive use (cf. NOTES ON TAGS):

If you require different forms of interaction, not covered by Plotchart itself, you can use the tags on the various canvas elements to define other bindings.

The bindplot and bindlast are defined as follows:

Here is an example - show the values of the data points in an annotation (from the sample code in plotdemos12.tcl):

#
# Procedure for showing an annotation
#
proc showAnnotation {xcoord ycoord plot w} {

    $plot balloon $xcoord $ycoord "Data point: [format "%.3f, %.3f" $xcoord $ycoord]" north

    after 2000 [list removeAnnotation $w]
}

#
# Procedure for erase an annotation
#
proc removeAnnotation {w} {

    # Use the tags to remove all annotations
    $w delete BalloonText
    $w delete BalloonFrame
}

#
# Create a simple plot and a label
#
pack [canvas .c -bg white] [label .l -textvariable coords]

set p [::Plotchart::createXYPlot .c {0 1000 200} {0 10 1}]

$p dataconfig series1 -type both -symbol cross

foreach x {1 2 5 10 20 50 100 200 500 1000} {
    $p plot series1 $x [expr {log($x)}]

    #
    # Show the annotation for each data point
    #
    $p bindlast series1 <Enter> [list showAnnotation $p %W]
}

NOTES ON TAGS

The implementation of Plotchart relies heavily on the canvas's ability to identify graphical objects by tags and to change the drawing order of the objects. This section documents the tags that are used.

(Note: the tags are not always used consistently - see the notes appearing with the various tags. This section describes the current state.)

General graphical objects:

XY-plots (all types of axes):

Items such as labelled dots only have the "data" tag.

Piecharts and spiral pies:

Barcharts:

Barcharts use the same tags as xy-plots (but for gradient-filled bars the data_seriesname is not used).

Histograms and isometric plots:

Currently the only tag used is "data".

Time-charts:

As these plots are scrollable, several tags are used specific to the scrolling: vertscroll, horizscroll, below, lowest, above, timeline, tline. Each item also has a tag of the form "item_number", where "number" is to be replaced by the actual sequence number of the item.

Gantt charts:

In addition to the tags described for the time-charts, the following tags are used: description, completed, summary and summarybar.

Radial charts and polar plots:

Currently the radial lines indicating the grid have no tags. The graphical objects associated with data only have the "data" tag.

Windroses:

Only the tag data_number is currently used ("number" should be replaced by the sequence number of the data, starting at 0.

Contour and isoline plots:

No tags are used.

3D plots and 3D ribbon plots:

Tags are used for the axes and for the data objects:

Charts decorated with 3D effects:

The following tags are used to identify various types of graphical objects: platform, background, d, u, ticklines.

The text associated with the bars has no tags. The ribbon lines and areas have no tags either.

Tables:

Tags used are: frame, cellbg and celltext

Special plot types (target diagrams, Taylor diagrams:

Tags used are: limits, limit_labels, reference In addition: To implement multiple plots and charts in a single canvas, all items also get as a tag the plot/chart they belong to. This enables Plotchart to manipulate only those items.

TODO - SOME PRIVATE NOTES

I have the following wishlist:

<

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category plotchart of the Tklib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation. <

COPYRIGHT

Copyright © 2022 Arjen Markus