/ 
Term-Fabulous-0.01
/ Term::Fabulous::Chart::Series

NAME

Term::Fabulous::Chart::Series - One data series of an XY chart

SYNOPSIS

# Series are made by the charts from hashes:
my $chart = Term::Fabulous::Widget::LineChart->new(
	series => [ { name => 'CPU', data => [ 12, 40, 33 ], color => '#3987e5', curve => 'monotone' } ],
);
$chart->add_points( CPU => 51, 47 );

DESCRIPTION

The data and the options of one series of a Term::Fabulous::Widget::XYChart. The chart widgets create series from the hashes in their series parameter (see "SERIES" in Term::Fabulous::Widget::XYChart) and change them through their own methods; you do not need this class directly. It checks every option and data point when it is given, so a wrong value dies at once with the series' name in the message.

CONSTRUCTOR

new

my $series = Term::Fabulous::Chart::Series->new(
	owner => 'My::Chart',
	name  => 'CPU',
	type  => 'line',
	slot  => 0,
	data  => [ 12, 40, 33 ],
	color => '#3987e5',
	curve => 'monotone',
);

owner (the class name of the chart, which starts every message), name (a non-empty string), type (line, area, bar or scatter) and slot (the palette slot) are required. data (default: none) and color (default: undef, the palette's) are checked as "set_data, add_points, clear" and "color, color_opacity, set_color" check them, and every option of "SERIES" in Term::Fabulous::Widget::XYChart may be given. Unknown parameters die. Two more parameters serve the charts:

described_as

How the messages about the options name the series. Default: undef, series 'NAME' (curve of series 'CPU' must be ...); the empty string leaves the series out (curve must be ...), for the options a chart takes for all of its series.

check_points

A code reference called with the series and an array reference of its new points (as "points, count" holds them) before they are stored: from the constructor, set_data, add_points and parsed_points. It dies for points the chart cannot show (a radar chart: a label it does not have), and the data stays as it was. Default: none.

METHODS

name, type, slot

The series' name, its type (line, area, bar or scatter) and its palette slot (the color it has when it has no color of its own).

set_type

$series->set_type('area');

Changes the type. Drops the series' own marker when the new type cannot draw with it. Dies for an unknown type.

color, color_opacity, set_color

The color as a packed 0xRRGGBB integer (undef: the palette's), and its alpha as an opacity from 0 to 1. set_color takes every color form of Term::Fabulous::Color or a packed integer; undef returns to the palette's color.

option, set_option

my $curve = $series->option('curve');
$series->set_option( curve => 'monotone' );

Reads and sets one option (see "Series keys" in Term::Fabulous::Widget::XYChart); undef means the chart's setting. Both die for an unknown option name; set_option also dies for an invalid value.

set_data, add_points, clear

Replace, extend or empty the data. A data point is a number (the y value, its x is its position in the series), undef (a gap), [ $x, $y ] or { x => $x, y => $y }. With max_points, the oldest points are dropped. An invalid point, or one check_points refuses, dies and changes nothing.

parsed_points, push_parsed

my @parsed = $series->parsed_points( 4, [ 5, 6 ] );    # dies for invalid points
$series->push_parsed(@parsed);

add_points in two steps, for a caller that adds to several series at once and must not change any of them when one refuses its points. parsed_points parses and checks new points as add_points does (their numbers in messages follow the points the series has) and returns them, storing nothing; push_parsed stores what it returned, drops the oldest points with max_points and returns the series.

points, count

The points as [ $x_or_undef, $y_or_undef ] (read only) and their number.

keep_last

$series->keep_last(100);

Drops all but the newest points, as max_points does.

is_visible

False when the series' visible option is false. Default: true.

revision

A number that changes with every change of the series.

dash_pattern

my $pattern = $series->dash_pattern('dashed');

The subpixel pattern of a line style.

marker_names, option_names

my @markers = Term::Fabulous::Chart::Series->marker_names('bar');

The markers a type of series can be drawn with, and the names of all options.

SEE ALSO

Term::Fabulous::Widget::XYChart.