Go to the first, previous, next, last section, table of contents.

Barchart widgets - 1

Author(s): Isabel Martín García.

Version: 1.11#222 (2004/5/24, 13:8:7 CEST)

Version of last change: 1.11#137 (2003/12/31, 0:14:2 CET)

This module defines predicates to show barchart widgets. The three predicates exported by this module plot two-variable data as regular bars in a window. They all share the following features:

Particular features will be pointed out in the corresponding predicate.

Usage and interface (genbar1)

Documentation on exports (genbar1)

PREDICATE: barchart1/7:

barchart1(Header, BarchartTitle, XTitle, XVector, YTitle, YVector, Footer)

The y axis range is determined from the limits of the data. Two examples are given to demonstrate clearly how to call the predicates. In the first example the user sets the bar appearance, in the second one the appearance features will be chosen by the system and the colors that have been assigned to the variables Color1, Color2 and Pattern will be shown also.

Example 1: 

barchart1('This is the header text',
  'Barchart title',
  'xaxistitle',
  [ ['bar1','legend_element1','Blue','Yellow','pattern1'],
           ['bar2','legend_element2','Plum','SeaGreen','pattern2'],
           ['bar3','legend_element3','Turquoise','Yellow',
	    'pattern5'] ],
  'yaxixtitle',
  [20,10,59],
  'footer').

Example 2: 

barchart1('This is the header text',
  'Barchart title',
  'xaxistitle',
  [ ['element1','legend_element1',Color1,Color2,Pattern],
            ['element2','legend_element2'],
            ['element3','legend_element3'] ],
  'yaxixtitle',
  [20,10,59],
  'footer').

Usage:

PREDICATE: barchart1/9:

barchart1(Header, BTitle, XTitle, XVector, YTitle, YVector, YMax, YMin, Footer)

You can set the minimum and maximum limits of the y axis. Data outside the limits will not be plotted. Each limit, as you can check by looking at the axis_limit/1 definition, is a number. If the argument is a variable the limit will be calculated from the data (i.e., if YMax value is YValueMax the maximum y axis limit will calculated using the largest data value).

Example: 

barchart1('This is the header text',
  'Barchart title',
  'xaxistitle',
  [ ['element1','e1','Blue','Yellow','pattern1'],
      ['element2','e2','Turquoise','Plum','pattern5'],
      ['element3','e3','Turquoise','Green','pattern5'] ],
  'yaxixtitle',
  [20,10,59],
  70,
  _,
  'footer').

Usage:

PREDICATE: percentbarchart1/7:

percentbarchart1(Header, BTitle, XTitle, XVector, YTitle, YVector, Footer)

The y axis maximum coordinate value is 100. The x axis limits are automatically worked out.

Example: 

percentbarchart1('This is a special barchart to represent percentages',
  'Barchart with legend',
  'My xaxistitle',
  [ [1,'bar1','Blue','Yellow','pattern1'],
       [8,'bar2','MediumTurquoise','Plum','pattern5'] ],
  'My yaxixtitle',
  [80,10],
  'This is the footer text').

Usage:

REGTYPE: yelement/1: 

yelement(Y) :-
        number(Y).

Y is the bar lenght, so it must be a numeric value.

Both Prolog and Tcl-Tk support integers and floats. Integers are usually specified in decimal, but if the first character is 0 the number is read in octal (base 8), and if the first two characters are 0x, the number is read in hexadecimal (base16). Float numbers may be specified using most of the forms defined for ANSI C, including the following examples:

Note: Be careful when using floats. While 8. or 7.e4 is interpreted by Tcl-tk as 8.0 and 7.0e4, Prolog will not read them as float numbers. Example: 

        ?- number(8.e+5).
        {SYNTAX ERROR: (lns 130-130) , or ) expected in arguments
        number ( 8 
        ** here **
        . e + 5 ) . 
        }

        no
        ?- number(8.).
        {SYNTAX ERROR: (lns 138-138) , or ) expected in arguments
        number ( 8 
        ** here **
        . ) . 
        }

        no

        ?- number(8.0e+5).

        yes
        ?- number(8.0).

        yes

Precision: Tcl-tk internally represents integers with the C type int, which provides at least 32 bits of precision on most machines. Since Prolog integers can (in some implementations) exceed 32 bits but the precision in Tcl-tk depends on the machine, it is up to the progammer to ensure that the values fit into the maximum precision of the machine for integers. Real numbers are represented with the C type double, which is usually represented with 64-bit values (about 15 decimal digits of precision) using the IEEE Floating Point Standard.

Conversion: If the list is composed by integers and floats, Tcl-tk will convert integers to floats.

REGTYPE: axis_limit/1: 
axis_limit(X) :-
        number(X).
axis_limit(_1).

This type is defined in order to set the minimum and maximum limits of the axes. Data outside the limits will not be plotted. Each limit, is a number or a variable. If the argument is not a number the limit will be calculated from the data (i.e., if YMax value is Var the maximum y axis limit will be calculated using the largest data value).

REGTYPE: header/1:

Usage: header(X)

REGTYPE: title/1:

Usage: title(X)

REGTYPE: footer/1:

Usage: footer(X)

Documentation on internals (genbar1)

REGTYPE: xbarelement1/1: 
xbarelement1([XValue,LegendElement]) :-
        atomic(XValue),
        atomic(LegendElement).
xbarelement1([XValue,LegendElement,ForegColor,BackgColor,SPattern]) :-
        atomic(XValue),
        atomic(LegendElement),
        color(ForegColor),
        color(BackgColor),
        pattern(SPattern).

Defines the attributes of the bar.

XValue
bar label. Although XValue values may be numbers, the will be treated as labels. Different elements with the same label will produce different bars.
LegendElement
Legend element name. It may be a number or an atom and equal or different to the XValue. Every LegendElement value of the list must be unique.
ForegColor
It sets the Foreground color of the bar. Its value must be a valid color, otherwise the system will throw an exception. If the argument value is a variable, it gets instantiated to a color chosen by the library.
BackgColor
It sets the Background color of the bar. Its value must be a valid color, otherwise the system will throw an exception. If the argument value is a variable, it gets instantiated to a color chosen by the library.
SPattern
It sets the stipple of the bar. Its value must be a valid pattern, otherwise the system will throw an exception. If the argument value is a variable, it gets instantiated to a pattern chosen by the library.

Go to the first, previous, next, last section, table of contents.