Chart::Base Class Reference

- Main Page
- Related Pages
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Attributes | List of all members
Chart::Base Class Reference

Base class for Chart; all other classes derived from here. More...

Inheritance diagram for Chart::Base:
[legend]
Collaboration diagram for Chart::Base:
[legend]

## Public Attributes
Hash | named_colors
| RGB values of named colors.

## Public Class Methods
object | new ()
| Standard normal constructor. Calls.

## Public Object Methods
int | set (hash opts)
| Set all options.
hash | getopts ()
| get all options
int | add_pt (list data)
| Graph API Add one dataset (as a list) to the dataref.
| add_pt (\\\list data)
| Graph API Add one dataset (as a reference to a list) to the dataref via.
int | add_dataset (list data)
| Graph API Add many datasets (implemented as a list) to the dataref,.
int | add_dataset (\\\list data)
| Graph API Add many datasets (implemented as a references to alist) to the dataref,.
int | add_datafile (scalar filename, scalar format)
| Graph API it's also possible to add a complete datafile Uses.
int | clear_data ()
| Clear Graph API (by undefining 'dataref'.
arrayref | get_data ()
| Get array of data of the last graph.
int | png (scalar file, scalar dataref)
| Produce the graph of options set in png format.
int | cgi_png (scalar dataref)
| Produce the graph of options set in png format to be directly written for CGI.
int | scalar_png (scalar dataref)
| Produce the graph of options set in PNG format to be directly returned.
int | jpeg (scalar file, scalar dataref)
| Produce the graph of options set in JPG format to be directly plotted.
int | cgi_jpeg (scalar dataref)
| Produce the graph of options set in JPG format to be directly for CGI.
int | scalar_jpeg (scalar dataref)
| Produce the graph of options set in JPG format to be directly returned.
int | make_gd (scalar dataref)
| Produce the graph of options set in GD format to be directly.
| imagemap_dump ()
| get the information to turn the chart into an imagemap
| minimum (list array)
| determine minimum of an array of values
| maximum (list array)
| determine maximum of an array of values
| arccos (scalar a)
| Function arccos(a)
| arcsin (scalar a)
| Function arcsin(a)
| true (scalar arg)
| determine true value of argument
| false (scalar arg)
| determine false value of argument
| modulo (scalar a, scalar b)
| Calculate float($a % $b) as the internal operator '' does only calculate in integers.

## Private Functions
private int | _check_data
| Check the internal data to be displayed.
private int | _draw
| Plot the chart to the gd object Calls:
private int | _set_colors
| specify my colors
private int | _color_role_to_index
| return a (list of) color index(es) corresponding to the (list of) role(s)
private int | _brushStyles_of_roles
| return a (list of) brushStyles corresponding to the (list of) role(s)
private int | _draw_title
| draw the title for the chart
private int | _default_f_tick
| default tick conversion function This function is pointed to be $self->{f_x_tick} resp.
private float | _xyRatio
| Get ratio width_x/width_y.
private float | _xPixelInReal
| Get width of one Pixel in real coordinates in x-direction.
private float | _yPixelInReal
| Get width of one Pixel in real coordinates in y-direction.
private int | _init (scalar x, scalar y)
| Initialize all default options here.
private int | _copy_data (scalar extern_ref)
| Copy external data via a reference to internal memory.
private array | _color_spec_to_rgb (scalar role, scalar spec)
| Return an array (list of) rgb values for spec.
private int | _draw_sub_title ()
| draw the sub-title for the chart
private int | _sort_data ()
| sort the data nicely (mostly for the pareto charts and xy-plots)
private int | _find_x_scale ()
| For a xy-plot do the same for the x values, as '_find_y_scale' does for the y values!
private int | _find_y_scale ()
| find good values for the minimum and maximum y-value on the chart
private | _calcTickInterval (scalar dataset_min, scalar dataset_max, scalar flag_fixed_min, scalar flag_fixed_max, scalar minTicks, scalar maxTicks)
| Calculate the Interval between ticks in y direction.
private int | _calcXTickInterval (scalar min, scalar max, scalar minF, scalar maxF, scalar minTicks, scalar maxTicks)
| Calculate the Interval between ticks in x direction.
private int | _countTicks (scalar min, scalar max, scalar interval)
| Works out how many ticks would be displayed at that interval.
private int | _round2Tick (scalar input, scalar interval, scalar roundUP)
| Rounds up or down to the next tick of interval size.
private array | _sepFP (scalar num)
| Seperates a number into it's base 10 floating point exponent & mantisa.
private array | _find_y_range ()
| Find minimum and maximum value of y data sets.
private array | _find_x_range ()
| Find minimum and maximum value of x data sets.
private int | _plot ()
| main sub that controls all the plotting of the actual chart
private int | _draw_legend ()
| let the user know what all the pretty colors mean.
private int | _draw_bottom_legend ()
| put the legend on the bottom of the chart
private int | _draw_right_legend ()
| put the legend on the right of the chart
private int | _draw_top_legend ()
| put the legend on top of the chart
private int | _draw_left_legend ()
| put the legend on the left of the chart
private int | _draw_none_legend ()
| no legend to draw.
private int | _draw_x_label ()
| draw the label for the x-axis
private int | _draw_y_label ()
| draw the label for the y-axis
private int | _draw_ticks ()
| draw the ticks and tick labels
private int | _draw_x_number_ticks ()
| draw the ticks and tick labels
private int | _draw_x_ticks ()
| draw the x-ticks and their labels
private int | _draw_y_ticks ()
| draw the y-ticks and their labels
private int | _grey_background ()
| put a grey background on the plot of the data itself
private int | _draw_grid_lines ()
| draw grid_lines
private int | _draw_x_grid_lines ()
| draw grid_lines for x
private int | _draw_y_grid_lines ()
| draw grid_lines for y
private int | _draw_y2_grid_lines ()
| draw grid_lines for y
private int | _prepare_brush (scalar color, scalar type, scalar role)
| prepare brush

## Detailed Description

Base class for Chart; all other classes derived from here.

Base class from which all other classes are derived. This class provides all functions which are common for all classes

## Member Function Documentation

private Chart::Base::_calcTickInterval | ( | scalar | dataset_min,
|  | scalar | dataset_max,
|  | scalar | flag_fixed_min,
|  | scalar | flag_fixed_max,
|  | scalar | minTicks,
|  | scalar | maxTicks
| ) |  |

Calculate the Interval between ticks in y direction.

Calculate the Interval between ticks in y direction and compare the number of ticks to the user's given values min_y_ticks, max_y_ticks.

Parameters

  [in] | dataset_min | Minimal value in y direction
  [in] | dataset_max | Maximal value in y direction
  [in] | flag_fixed_min | Indicator whether the dataset_min value is fixed
  [in] | flag_fixed_max | Indicator whether the dataset_max value is fixed
  [in] | minTicks | Minimal number of ticks wanted
  [in] | maxTicks | Maximal number of ticks wanted

Returns
  Array of ($tickInterval, $tickCount, $pMin, $pMax)

Reimplemented in Chart::Direction.

private int Chart::Base::_calcXTickInterval | ( | scalar | min,
|  | scalar | max,
|  | scalar | minF,
|  | scalar | maxF,
|  | scalar | minTicks,
|  | scalar | maxTicks
| ) |  |

Calculate the Interval between ticks in x direction.

Calculate the Interval between ticks in x direction and compare the number of ticks to the user's given values minTicks, maxTicks.

Parameters

  [in] | min | Minimal value of dataset in x direction
  [in] | max | Maximal value of dataset in x direction
  [in] | minF | Inddicator if those min value is fixed
  [in] | maxF | Inddicator if those max value is fixed
  [in] | minTicks | Minimal number of tick in x direction
  [in] | maxTicks | Maximal number of tick in x direction

Returns
  $tickInterval, $tickCount, $pMin, $pMax

private array Chart::Base::_color_spec_to_rgb | ( | scalar | role,
|  | scalar | spec
| ) |  |

Return an array (list of) rgb values for spec.

Parameters

  [in] | role | name of a role
  [in] | spec | [r,g,b] or name

Returns
  array of rgb values as a list (i.e., \@rgb)

private int Chart::Base::_copy_data | ( | scalar | extern_ref | ) |

Copy external data via a reference to internal memory.

Remember the external reference.
Therefore, this function can anly be called once!

Parameters

  extern_ref | Reference to external data space

private int Chart::Base::_countTicks | ( | scalar | min,
|  | scalar | max,
|  | scalar | interval
| ) |  |

Works out how many ticks would be displayed at that interval.

Parameters

  min | Minimal value
  max | Maximal value
  interval | value

Returns
  ($tickCount, $minR, $maxR)

e.g min=2, max=5, interval=1, result is 4 ticks.
written by David Pottage of Tao Group.
$minR = $self->_round2Tick( $min, $interval, -1);
$maxR = $self->_round2Tick( $max, $interval, 1);
$tickCount = ( $maxR/$interval ) - ( $minR/$interval ) +1;

private int Chart::Base::_draw_bottom_legend | ( |  | ) |

put the legend on the bottom of the chart

Returns
  status

Reimplemented in Chart::Composite.

private int Chart::Base::_draw_grid_lines | ( |  | ) |

draw grid_lines

Returns
  status

private int Chart::Base::_draw_left_legend | ( |  | ) |

put the legend on the left of the chart

Returns
  status

Reimplemented in Chart::Composite.

private int Chart::Base::_draw_legend | ( |  | ) |

let the user know what all the pretty colors mean.

The user define the position of the legend by setting option 'legend' to 'top', 'bottom', 'left', 'right' or 'none'. The legend is positioned at the defined place, respectively.

Returns
  status

Reimplemented in Chart::Direction, Chart::Composite, and Chart::ErrorBars.

private int Chart::Base::_draw_none_legend | ( |  | ) |

no legend to draw.

Just return in this case. This routine may be overwritten by subclasses.

Returns
  1

Reimplemented in Chart::Composite.

private int Chart::Base::_draw_right_legend | ( |  | ) |

put the legend on the right of the chart

Returns
  status

Reimplemented in Chart::Composite.

private int Chart::Base::_draw_sub_title | ( |  | ) |

draw the sub-title for the chart

See Also
  _draw_title
  _draw_sub_title() is more or less obsolete as _draw_title() does the same by writing more than one line as the title. Both use decreased width and height of the font by one.

Returns
  status

private int Chart::Base::_draw_ticks | ( |  | ) |

draw the ticks and tick labels

Returns
  status

Reimplemented in Chart::Composite.

private int Chart::Base::_draw_top_legend | ( |  | ) |

put the legend on top of the chart

Returns
  status

Reimplemented in Chart::Composite.

private int Chart::Base::_draw_x_grid_lines | ( |  | ) |

draw grid_lines for x

Returns
  status

private int Chart::Base::_draw_x_label | ( |  | ) |

draw the label for the x-axis

Get font for labels
Get the color of x_label or text
Get size of font
and write x-Label

Returns
  status

private int Chart::Base::_draw_x_number_ticks | ( |  | ) |

draw the ticks and tick labels

Returns
  status

private int Chart::Base::_draw_x_ticks | ( |  | ) |

draw the x-ticks and their labels

Returns
  status

Reimplemented in Chart::Composite, Chart::Direction, and Chart::HorizontalBars.

private int Chart::Base::_draw_y2_grid_lines | ( |  | ) |

draw grid_lines for y

Returns
  status

Reimplemented in Chart::Composite.

private int Chart::Base::_draw_y_grid_lines | ( |  | ) |

draw grid_lines for y

Returns
  status

Reimplemented in Chart::Composite.

private int Chart::Base::_draw_y_label | ( |  | ) |

draw the label for the y-axis

Returns
  status

private int Chart::Base::_draw_y_ticks | ( |  | ) |

draw the y-ticks and their labels

Returns
  status

Reimplemented in Chart::Composite, Chart::Direction, and Chart::HorizontalBars.

private array Chart::Base::_find_x_range | ( |  | ) |

Find minimum and maximum value of x data sets.

Returns
  ( min, max )

private int Chart::Base::_find_x_scale | ( |  | ) |

For a xy-plot do the same for the x values, as '_find_y_scale' does for the y values!

See Also
  _find_y_scale

Returns
  status

private array Chart::Base::_find_y_range | ( |  | ) |

Find minimum and maximum value of y data sets.

Returns
  ( min, max, flag_all_integers )

Reimplemented in Chart::Direction, Chart::Mountain, and Chart::ErrorBars.

private int Chart::Base::_find_y_scale | ( |  | ) |

find good values for the minimum and maximum y-value on the chart

Returns
  status

New version, re-written by David Pottage of Tao Group.
This code is AS IS and comes with NO WARRANTY

This Sub calculates correct values for the following class local variables, if they have not been set by the user.

max_val, min_val: The maximum and minimum values for the y axis.
y_ticks: The number of ticks to plot on the y scale, including the end points. e.g. If the scale runs from 0 to 50, with ticks every 10, y_ticks will have the value of 6.
y_tick_labels: An array of strings, each is a label for the y axis.
y_tick_labels_length: The length to allow for B tick labels. (How long is the longest?)

Reimplemented in Chart::Direction, and Chart::HorizontalBars.

private int Chart::Base::_grey_background | ( |  | ) |

put a grey background on the plot of the data itself

Returns
  status

private int Chart::Base::_init | ( | scalar | x,
|  | scalar | y
| ) |  |

Initialize all default options here.

Parameters

  [in] | x | Width of the final image in pixels (Default: 400)
  [in] | y | Height of the final image in pixels (Default: 300)

private int Chart::Base::_plot | ( |  | ) |

main sub that controls all the plotting of the actual chart

Returns
  status

private int Chart::Base::_prepare_brush | ( | scalar | color,
|  | scalar | type,
|  | scalar | role
| ) |  |

prepare brush

set the gdBrush object to tick GD into drawing fat lines & points of interesting shapes Needed by "Lines", "Points" and "LinesPoints" All hacked up by Richard Dice rdice.nosp@m.@pob.nosp@m.ox.co.nosp@m.m Sunday 16 May 1999

Parameters

  color |
  type | 'line','point'
  role |

Returns
  status

private int Chart::Base::_round2Tick | ( | scalar | input,
|  | scalar | interval,
|  | scalar | roundUP
| ) |  |

Rounds up or down to the next tick of interval size.

$roundUP can be +1 or -1 to indicate if rounding should be up or down.
written by David Pottage of Tao Group.

Parameters

  input |
  interval |
  roundUP |

Returns
  retN*interval

private array Chart::Base::_sepFP | ( | scalar | num | ) |

Seperates a number into it's base 10 floating point exponent & mantisa.

written by David Pottage of Tao Group.

Parameters

  num | Floating point number

Returns
  ( exponent, mantissa)

private int Chart::Base::_sort_data | ( |  | ) |

sort the data nicely (mostly for the pareto charts and xy-plots)

Returns
  status

int Chart::Base::add_datafile | ( | scalar | filename,
|  | scalar | format
| ) |  |

Graph API
it's also possible to add a complete datafile
Uses.

See Also
  add_pt
  add_dataset

Parameters

  [in] | filename | Name of file which contents is to be added
  [in] | format | 'pt' or 'set' to distiguish between function add_pt() in case of 'pt' or function add_dataset() in case of 'set'

int Chart::Base::add_dataset | ( | list | data | ) |

Graph API
Add many datasets (implemented as a list) to the dataref,.

Parameters

  data | Dataset (list) to add

Reimplemented in Chart::Direction.

int Chart::Base::add_dataset | ( | \\\list | data | ) |

Graph API
Add many datasets (implemented as a references to alist) to the dataref,.

Parameters

  data | Dataset (reference to a list) to add

int Chart::Base::add_pt | ( | list | data | ) |

Graph API
Add one dataset (as a list) to the dataref.

Parameters

  data | Dataset to add

Chart::Base::add_pt | ( | \\\list | data | ) |

Graph API
Add one dataset (as a reference to a list) to the dataref via.

    for ( 0 .. $#data )
    {
       push $self->{'dataref'}->[$_] }, $data[$_];
    }

Parameters

  data | Dataset to add

Chart::Base::arccos | ( | scalar | a | ) |

Function arccos(a)

Parameters

  a | Value

Returns
  arccos(a)

Chart::Base::arcsin | ( | scalar | a | ) |

Function arcsin(a)

Parameters

  a | Value

Returns
  arcsin(a)

int Chart::Base::cgi_jpeg | ( | scalar | dataref | ) |

Produce the graph of options set in JPG format to be directly for CGI.

called after the options are set, this method invokes all my private methods to actually draw the chart and plot the data

Parameters

  [in] | dataref | Reference to external data space

Returns
  Status of the plot

int Chart::Base::cgi_png | ( | scalar | dataref | ) |

Produce the graph of options set in png format to be directly written for CGI.

called after the options are set, this method invokes all my private methods to actually draw the chart and plot the data

Parameters

  [in] | dataref | Reference to external data space

Returns
  Status of the plot

int Chart::Base::clear_data | ( |  | ) |

Clear Graph API (by undefining 'dataref'.

Returns
  Status of function

Chart::Base::false | ( | scalar | arg | ) |

determine false value of argument

Parameters

  [in] | arg | Bool value to check for true

Returns
  1 if argument is equal to false, FALSE, 0, f, F or undefined

arrayref Chart::Base::get_data | ( |  | ) |

Get array of data of the last graph.

Returns
  Reference to data set of the last graph

hash Chart::Base::getopts | ( |  | ) |

get all options

Returns
  hash of all set options so far
  set options as a hash

Chart::Base::imagemap_dump | ( |  | ) |

get the information to turn the chart into an imagemap

Returns
  Reference to an array of the image

Reimplemented in Chart::Composite.

int Chart::Base::jpeg | ( | scalar | file,
|  | scalar | dataref
| ) |  |

Produce the graph of options set in JPG format to be directly plotted.

Called after the options are set, this method invokes all my private methods to actually draw the chart and plot the data. The output has the jpeg format in opposite to png format produced by

See Also
  png

Uses the following private functions:

See Also
  _set_colors
  _copy_data
  _check_data
  _draw

Parameters

  [in] | file | Name of file to write graph to
  [in] | dataref | Reference to external data space

Returns
  Status of the plot

int Chart::Base::make_gd | ( | scalar | dataref | ) |

Produce the graph of options set in GD format to be directly.

called after the options are set, this method invokes all my private methods to actually draw the chart and plot the data

Parameters

  dataref | Reference to data

Returns
  Status of the plot

Chart::Base::maximum | ( | list | array | ) |

determine maximum of an array of values

Parameters

  array | List of numerical values ()

Returns
  Maximal value of list of values

Chart::Base::minimum | ( | list | array | ) |

determine minimum of an array of values

Parameters

  array | List of numerical values (@array)

Returns
  Minimal value of list of values

Chart::Base::modulo | ( | scalar | a,
|  | scalar | b
| ) |  |

Calculate float($a % $b) as the internal operator '' does only calculate in integers.

Parameters

  [in] | a | a in ab
  [in] | b | b in ab

Returns
  $a % $b in float

object Chart::Base::new | ( |  | ) |

Standard normal constructor.
Calls.

Returns
  A new object.

See Also
  _init

int Chart::Base::png | ( | scalar | file,
|  | scalar | dataref
| ) |  |

Produce the graph of options set in png format.

called after the options are set, this method invokes all my private methods to actually draw the chart and plot the data

See Also
  _set_colors
  _copy_data
  _check_data
  _draw

Parameters

  [in] | file | Name of file to write graph to
  [in] | dataref | Reference to external data space

Returns
  Status of the plot

int Chart::Base::scalar_jpeg | ( | scalar | dataref | ) |

Produce the graph of options set in JPG format to be directly returned.

called after the options are set, this method invokes all my private methods to actually draw the chart and return the image to the caller

Parameters

  dataref | Reference to data area

Returns
  returns the jpeg image as a scalar value, so that the programmer-user can do whatever the heck s/he wants to with it

int Chart::Base::scalar_png | ( | scalar | dataref | ) |

Produce the graph of options set in PNG format to be directly returned.

called after the options are set, this method invokes all my private methods to actually draw the chart and return the image to the caller

Parameters

  dataref | Reference to data

Returns
  returns the png image as a scalar value, so that the programmer-user can do whatever the heck s/he wants to with it

int Chart::Base::set | ( | hash | opts | ) |

Set all options.

main method for customizing the chart, lets users specify values for different parameters
The options are saved locally to be able to output them via

See Also
  getopts()

Parameters

  [in] | opts | Hash of options to the Chart

Returns
  ok or croak

Reimplemented in Chart::Composite, and Chart::Direction.

Chart::Base::true | ( | scalar | arg | ) |

determine true value of argument

Parameters

  [in] | arg | Bool value to check for true

Returns
  1 if argument is equal to TRUE, true, 1, t, T, and defined

## Member Data Documentation

private int Chart::Base::_brushStyles_of_roles

return a (list of) brushStyles corresponding to the (list of) role(s)

Parameters

  list_of_roles | List of roles (\@list_of_roles)

Returns
  (list of) brushStyle(s) corresponding to the (list of) role(s) in \@_.

private int Chart::Base::_check_data

Check the internal data to be displayed.

Make sure the data isn't really weird and collect some basic info about it
Not logical data is 'carp'ed.

Returns
  status of check

private int Chart::Base::_color_role_to_index

return a (list of) color index(es) corresponding to the (list of) role(s)

wantarray is a special keyword which returns a flag indicating which context your subroutine has been called in. It will return one of three values.

- true: If your subroutine has been called in list context
- false: If your subroutine has been called in scalar context
- undef: If your subroutine has been called in void context

Returns
  a (list of) color index(es) corresponding to the (list of) role(s) in \@_.

private int Chart::Base::_default_f_tick

default tick conversion function This function is pointed to be $self->{f_x_tick} resp.

$self->{f_y_tick} if the user does not provide another function

Returns
  status

private int Chart::Base::_draw

Plot the chart to the gd object
Calls:

See Also
  _draw_title
  _draw_sub_title
  _sort_data
  _plot

Returns
  status

private int Chart::Base::_draw_title

draw the title for the chart

The title was defined by the user in set('title' => ....)
The user may define some title lines by separating them via character '\n';
The used font is taken from 'title_font';
The used color is calculated by function '_color_role_to_index' based on 'title' or 'text'

See Also
  _color_role_to_index

Returns
  status

private int Chart::Base::_set_colors

specify my colors

Returns
  status

private float Chart::Base::_xPixelInReal

Get width of one Pixel in real coordinates in x-direction.

Returns
  width(interval) of reality in x direction

private float Chart::Base::_xyRatio

Get ratio width_x/width_y.

Returns
  ratio width_x and width_y

private float Chart::Base::_yPixelInReal

Get width of one Pixel in real coordinates in y-direction.

Returns
  width(interval) of reality in y direction

Hash Chart::Base::named_colors

RGB values of named colors.

see URL http://en.wikipedia.org/wiki/Web_colors#X11_color_names

The documentation for this class was generated from the following file:

- Chart/Base.pm