Chart::...operties(3)

📦
version 2.403.9 · 5 versions
, in opensuse-leap 16.0

💅 Chart::Manual::Properties(3) — User Contributed Perl Documentation ✨

okay bestie, welcome to the complete guide to Chart's changeable properties. This is the part where we make your chart stop acting shy and actually do what you want 💖

🌸 NAME

Chart::Manual::Properties — complete guide to Chart's changeable properties.

✨ INTRO

Individual properties of a chart can be changed via the set method, like this:

$chart_object->set( %properties);
$chart_object->set( key => 'value', ... );

This page documents all viable keys and values for those calls. No cap.

The first section lists the most common data types and their acceptable values.

heads up, bestie: every chart type reacts only to a distinct subset of properties. So the middle section groups all properties by chart type — or set of types — where they actually have an effect. The descriptions in that section are shortened to achieve a tabular overview.

A fuller description of each property lives in the third section, where they are sorted alphabetically.

The general layout of a chart image:

🧁 DATA TYPES

Every key expects values of a certain data type. The more often occurring types are sorted, enumerated, and described in this section.

boolean

Yes-or-no decisions. You can answer with the perlish 0 or 1, or with 'true' or 'false' — and those might be shortened to 't' and 'T' or 'f' and 'F'. 'none' as an alias of 'false' is also an option. slay.

code

Anonymous subroutine that usually takes the first argument and returns a transformed result:

sub { $_[0] + 1 }

color

The usual options are:

names:  'blue'

All names are tabulated visually and by name under "NAMES" in Chart::Property::DataType::Color::Constant. You can also define a color with integer values in the RGB or HSL space. Acceptable ranges are for RGB: 3x 0..255 and for HSL: 0..359, 2 x 0..100.

RGB triplets: [0,255,255]
RGB hashes: { Red =>   0,  Green => 255, Blue => 255 }
RGB hashes: { R   =>   0,  G     => 255, B    => 255 }
HSL hashes: { H   => 240,  S     => 100, L     => 50 }
HSL hashes: { hue => 240, saturation => 100, lightness => 50 }

Detailed explanation and even more options you find under Graphics::Toolkit::Color. iconic.

font

There are a handful of GD built-in font objects that can be referenced:

GD::Font->Tiny
GD::Font->Small
GD::Font->MediumBold
GD::Font->Large
GD::Font->Giant

integer

Whole numbers (without decimals) to set position, size and alike.

positive integer

Integers greater or equal zero.

string

Short texts for title, sub_title and labels on axis, tics and legend. Line breaks ("/n") are only acceptable inside single quotes and in the "title".

🦋 BY CHART TYPE

Summary of all properties, grouped by chart type where they are applicable. Sections are named after the Chart type in question, except All and NoPie. The format is: name ... type, description; default value.

🫶 All

Properties available in all chart types:

  • colors-background — "color" of whole image background; default 'white'.
  • colors-datasetx — "color" of points/lines/bars of dataset number x = 0..64.
  • colors-grid_lines — "color" of vertical and horizontal grid lines in the plot background; default 'black'.
  • colors-x_grid_lines — "color" of vertical grid lines; default 'black'.
  • colors-y_grid_lines — "color" of horizontal grid lines; default 'black'.
  • colors-text — "color" of all text; default 'black'.
  • colors-title — "color" of text above the graph; default 'black'.
  • colors-x_label — "color" of x-axis label text; default 'black'.
  • colors-y_label — "color" of y-axis (left side) label text; default 'black'.
  • colors-y_label2 — "color" of y-axis (right side) label text; default 'black'.
  • colors-misc — "color" of boxes, ticks, axis and alike; default 'black'.
  • f_x_tick — "code" that transforms "would have" into actual tick label on left x-axis; default "undef".
  • f_y_tick — "code" that transforms "would have" into actual tick label on right y-axis; default "undef".
  • graph_border — space between graph and title + legend in pixel; default 10.
  • grey_background — bool: sets plot background to grey; default 'true'.
  • imagemap — bool: enable imagemap_dump(); default 'false'.
  • label_font — "font" of axis labels; default GD::Font->MediumBold.
  • legend — qw[left right top bottom none]: placement of the legend; default 'right'.
  • legend_font — "font" of the text in the legend; default GD::Font->Small.
  • legend_labels — (array ref): labels of colors in legend; default "undef".
  • png_border — pos_int: space between graph parts and image edge in pixel; default 10.
  • sub_title — "string": text below the "title" in smaller letters; default ''.
  • text_space — pos_int: extra space around any text; default 2.
  • title — "string": text on top of a chart; default ''.
  • title_font — "font" of the title text; default GD::Font->Large.
  • transparent — bool: full image background transparency; default 'false'.
  • x_label — "string": x-axis label text; default ''.
  • y_label — "string": label on the standard, left y-axis; default ''.
  • y_label2 — "string": label on right y-axis, if different; default ''.

🧚 NoPie

Properties available in all chart types of kinda xy-plot, not Pie:

  • custom_x_ticks — (array ref): [0,3,4] displays 0th, 3rd, and 4th x-tick; default "undef".
  • grid_lines — bool: draw vertical and horizontal grid lines; default 'false'.
  • include_zero — bool: forces y-axis to include zero; default 'false'.
  • integer_ticks_only — bool: draw x-axis ticks with label only on whole values; default 'false'.
  • max_val — pos_int: maximum value on y-axis; default "undef".
  • max_x_ticks — pos_int: maximum of ticks and labels to draw on x-axis; default 100.
  • max_y_ticks — pos_int: maximum of ticks and labels to draw on y-axis; default 100.
  • min_val — pos_int: maximum value on y-axis; default "undef".
  • min_x_ticks — pos_int: minimum of ticks and labels to draw on x-axis; default 6 (min 2).
  • min_y_ticks — pos_int: minimum of ticks and labels to draw on y-axis; default 6 (min 2).
  • precision — pos_int: nr. of numerals after the decimal point in axis labels; default 3.
  • skip_int_ticks — pos_int: draw only n'th tick on whole x-value; default 1 (if "integer_ticks_only").
  • skip_x_ticks — pos_int: draw only every n'th tick with label; default 1.
  • sort — bool: sort data in ascending order; default 'false'.
  • tick_label_font — "font" of tick labels; default GD::Font->Small.
  • tick_len — pos_int: length of the x- and y-ticks in pixels; default 4.
  • x_grid_lines — bool: vertical grid lines matching x ticks; default 'false'.
  • x_ticks — qw[normal staggered vertical]: style of x-axis labels; default 'normal'.
  • xy_plot — bool: forces x-y-graph, with numeric x-axis; default 'false'.
  • y_axes — ('left', 'right', 'both'): position of y-axis; default 'left'.
  • y_grid_lines — bool: horizontal grid lines matching y ticks; default 'false'.

🍓 Bars

This includes Bars, StackedBars and HorizontalBars.

  • spaced_bars — bool: leave space between the groups of bars; default 'true'.

🌈 HorizontalBars

  • skip_y_ticks — pos_int: draw every n'th tick with label on y-axis; default 1.

💜 Composite

  • brush_style1 — brush style of points associated with left y-axis; default "undef".
  • brush_style2 — brush style of points associated with right y-axis; default "undef".
  • composite_info — (array of arrays) which data sets produce which chart types; default "undef".
  • f_y_tick1 — "code" that transforms "would have" into actual label on left y-axis; default "undef".
  • f_y_tick2 — "code" that transforms "would have" into actual label on right y-axis; default "undef".
  • legend_example_size — Length of the color example line in legend in pixel; default 20.
  • max_val1 — "code" maximum y value on the left axis; default "undef".
  • max_val2 — "code" maximum y value on the right axis; default "undef".
  • min_val1 — "code" minimum y value on the left axis; default "undef".
  • min_val2 — "code" minimum y value on the right axis; default "undef".
  • same_y_axes — "code" both y-axis have same min and max; default "undef".
  • y_ticks1 — pos_int: number of y ticks on left y-axis; default "undef".
  • y_ticks2 — pos_int: number of y ticks on right y-axis; default "undef".

🧭 Direction

  • angle_interval — pos_int: angle between radial lines; default 30.
  • arrow — bool: paint points as arrows; default 'false'.
  • brush_size — pos_int: width of the lines in pixels; default 6.
  • line — bool: connected points with lines; default 'false'.
  • max_circles — pos_int: max nr. of coordinate grid circles; default 100.
  • min_circles — pos_int: min nr. of coordinate grid circles; default 4 (min. 2).
  • pair — bool: use odd numbered data sets to build pairs with the next; default 'false'.
  • point — bool: paint points at all (or only lines); default 'false'.
  • polar — bool: reverse x axis; default 'false'.
  • pt_size — pos_int: radius of points in pixels; default 18.

😭 ErrorBars

  • brush_size — pos_int: width of the lines in pixels; default 6.
  • pt_size — pos_int: radius of points in pixels; default 18.
  • same_error — bool: same values for upper and lower error bounds; default 'false'.

🎀 Lines

Including chart type LinesPoints.

  • brush_size — pos_int: width of the lines in pixels; default 6.

⭐ Points

Including chart type LinesPoints.

  • brushStyle — shape of the points; default 'FilledCircle'.
  • pt_size — pos_int: radius of points in pixels; default 18.

🥧 Pie

  • label_values — qw[percent value both none]: label content on pie slice label; default 'percent'.
  • legend_label_values — qw[percent value both none]: label content in the legend; default 'value'.
  • legend_lines — bool: draw lines connecting pie slices and label; default 'false'.
  • ring — "real": percentage of visible radius; default 1 (full pie).

🦋 Split

  • interval — pos_int: interval of a plot segment; default 'undef'.
  • interval_ticks — pos_int: number of ticks on x-axis; default 5.
  • scale — "integer": factor for y-values; default 1.
  • start — "integer": start value of the first interval; default 'undef'.

👑 ALPHABETICALLY

angle_interval

"Direction" only: how many radial lines should be drawn. The default value is 30, which means that a line will be drawn every 30 degrees. Valid Values are: 0, 5, 10, 15, 20, 30, 45 and 60. If you choose 0, direction will draw no line.

arrow

"Direction" only: Bool that if 'true', chart will draw an arrow from the center to the point. Defaults to 'false'.

brush_size

"Lines" only: Integer sets the width of the lines in pixels. Default is 6.

background

see "colors"

brushStyle

Sets the shape of points for Chart::Points, Chart::LinesPoints.

  • (still the same option from before, we're literally mid-sentence, don't @ me) possible values are: 'FilledCircle', 'circle', 'donut', 'OpenCircle', 'fatPlus', 'triangle', 'upsidedownTriangle', 'square', 'hollowSquare', 'OpenRectangle', 'FilledDiamond', 'OpenDiamond', 'Star', 'OpenStar'. Default: 'FilledCircle'. Look at Demo at "Points" in Chart::Manual::Types. 🎀
  • brush_style1 — "Composite" only: the brush style of the points that belong to the left y-axis. 🖌️
  • brush_style2 — "Composite" only: the brush style of the points that belong to the right y-axis. 🖌️
  • colors — okay bestie, this key is special because sooo many things in a chart need coloring. That's why its value is a hash, and the keys inside that hash say exactly what gets colored. Each of those values has to be a color definition — a name, an RGB array ref, or an HSL hash ref. Like:
    $obj->set('colors' => {'background' => [255,255,255]});

That sets the background color to white (which, fun fact, is the default ✨). Valid keys are:

    'background' (background color for the image)
    'title' (color of the title)
    'text' (all the text in the chart)
    'x_label' (color of the x-axis label)
    'y_label' (color of the first y axis label)
    'y_label2' (color of the second y axis label)
    'grid_lines' (color of the grid lines)
    'x_grid_lines' (color of the x grid lines - for x axis ticks)
    'y_grid_lines' (color of the y grid lines - for to left y axis ticks)
    'y2_grid_lines' (color of the y2 grid lines - for right y axis ticks)
    'dataset0'..'dataset63' (the different datasets)
    'misc' (everything else, ie. axis, ticks, box around the legend)
NB. For composite charts, there is a limit of 8 datasets per component. The colors for 'dataset8' through 'dataset15' become the colors for 'dataset0' through 'dataset7' for the second component chart. 👀
  • composite_info — "Composite" only: tells you which data set gets visualized by which chart type. It should be a reference to an array of array references, with info like this:
    $obj->set ('composite_info' => [ ['Bars', [1,2]],
                     ['Lines', [3,4] ] ]);

This example would set the two component charts to be a bar chart and a line chart. It would use the first two data sets for the bar chart — and heads up, the numbering starts at 1, not zero like most of the other numbered things in Chart 😭 — and the second two data sets for the line chart. The default is undef.

NB. Chart::Composite can only do two component charts. That's the whole vibe. Periodt.
  • custom_x_ticks — used in "Points", "Lines", "Linespoints", "Errorbars", and "Bars" charts. This one lets you specify exactly which x-ticks and x-tick labels should be drawn 🎯. Give it a reference to an array of the ticks you want. Just remember I'm counting from the 0th element of the array. (ie., if 'custom_x_ticks' is assigned [0,3,4], then the 0th, 3rd, and 4th x-ticks will be displayed.)
  • datasetx — see "colors" (yep, that's the whole entry, go look up there 💅)
  • f_x_tick — needs a reference to a function ("code") which takes the x-tick labels generated by the '@data[0]' as its argument. Whatever that function returns can reformat the labels ✨. For instance:
    $obj -> set ('f_x_tick' => \&formatter );

An example for the function formatter: x labels are seconds since an event. The referenced function can transform this seconds to hour, minutes and seconds. 🕰️

  • f_y_tick — the same situation as for 'f_x_tick' but now used for y labels.
  • f_y_tick1 — "Composite" only: a "code" ref to a function which has one argument and has to return a string which labels the first resp. second y axis. Both default to undef.
  • f_y_tick2 — "Composite" only: a "code" ref to a function which has one argument and has to return a string which labels the first resp. second y axis. Both default to undef.
  • graph_border — "Pie" only: sets the number of pixels used as a border between the title/labels and the actual graph within the image. Defaults to 10.
  • grey_background — puts a nice soft grey background on the data plot area when set to 'true'. Default is 'true'. 🩶
  • grid_lines — bool: draw grid lines matching up to x and y ticks. Default is 'false'.
  • imagemap — lets Chart know you're gonna ask for info about the placement of the data, so you can create an image map from the png 🗺️. This info can be retrieved using the imagemap_dump() method.
NB. the imagemap_dump() method cannot be called until after the Chart has been generated. Respect the order, bestie. 🫶
  • include_zero — if 'true', forces the y-axis to include zero if it is not in the dataset range. Default is 'false'.

In general, it is better to use this than to set the "min_val" if that is all you want to achieve. 💡

  • integer_ticks_only — bool, specifies to draw the x- and y-ticks at floating point values (as normal) or, when set to 'true', only at integer values. Default: 'false'.
  • interval — "Split" only: sets the interval of one partition of plot. Defaults 'undef'.
  • interval_ticks — "Split" only: number of ticks for the x-axis. Defaults to 5.
  • label_font — changes the "font" of the axis labels. Default is GD::Font->MediumBold.
  • label_values — "Pie" only: what kind of value labels to show alongside the pie. Valid values are 'percent', 'value', 'both' and 'none'. Defaults to 'percent'. 🥧
  • legend — specifies the placement of the legend. Valid values are 'left', 'right', 'top', 'bottom'. Setting it to 'none' tells chart not to draw a legend at all. Default is 'right'.
  • legend_example_size — "Composite" only: length of the example line in the legend, in pixels. Defaults to 20.
  • legend_font — changes the "font" of the text in the legend. Default is GD::Font->Small.
  • legend_labels — an array reference containing texts, which are the labels assigned to each color in the legend. The amount has to correspond to the amount of data sets 👑
  @labels = ('foo', 'bar');
  $obj->set ('legend_labels' => \@labels);

Default is empty, in which case 'Dataset 1', 'Dataset 2', etc. are used as the labels.

  • legend_label_values — "Pie" only: what labels to draw in the legend. Valid values are c<'percent'>, 'value', 'both' and 'none'. Defaults to 'value'.
  • legend_lines — "Pie" only: bool deciding if lines connecting pie slices and label are drawn. Default is 'false'.
  • label_values — "Pie" only: labels to draw beside the pie slices. Valid values are 'percent', 'value', 'both' and 'none'. Defaults to 'percent'. (yes it's back, it's listed twice in the original — not a typo on my end, she just said it twice 💀)
  • line — "Direction" only: if you turn this option to 'true', then points will be connected with lines. Defaults to 'false'.
  • max_circles — "Direction" only: sets the maximum number of circles in the coordinate system. Default is 100. This limit is there to avoid plotting an unreasonable large number of ticks if non-round values are used for the min_val and max_val. 🙈
  • max_val — sets the maximum y-value on the graph, overriding the normal auto-scaling. Default is undef.
  • max_val1 — "Composite" only: maximum y-value for the first (left y-axis) components. Default to undef.
  • max_val2 — "Composite" only: maximum y-value for the second (right y-axis) components. Default to undef.
  • max_x_ticks — works similar as 'max_y_ticks' and 'min_y_ticks'. Of course, only for a xy_plot.
  • max_y_ticks — sets the maximum number of y_ticks to draw when generating a scale. Default is 100. This limit is used to avoid plotting an unreasonable large number of ticks if non-round values are used for the min_val and max_val.

The value for 'max_y_ticks' should be at least 5 times larger than 'min_y_ticks'.

  • min_circles — "Direction" only: sets the minimum number of circles when generating a scale for direction. Default is 4, minimum is 2.
  • min_val — sets the minimum y-value on the graph, overriding the normal auto-scaling. Default is undef.
Caution: should be used when setting 'max_val' and 'min_val' to floating point or non-round numbers. This is because the scale must start & end on a tick, ticks must have round-number intervals, and include round numbers. ⚠️

Example: Suppose your data set has a range of 35-114 units. If you specify them as the 'min_val' & 'max_val', the y_axis will be plotted with 80 ticks every 1 unit.. If no 'min_val' & 'max_val', the system will auto scale the range to 30-120 with 10 ticks every 10 units.

If the 'min_val' & 'max_val' are specified to excessive precision, they may be overridden by the system, plotting a maximum 'max_y_ticks' ticks.

  • min_val1 — "Composite" only: minimum y-value for the first (left y-axis) component. Default to undef.
  • min_val2 — "Composite" only: minimum y-value for the second (right y-axis) component. Default to undef.
  • min_x_ticks — works similar as 'max_y_ticks' and 'min_y_ticks'. Of course, only for a xy_plot.
  • min_y_ticks — sets the minimum number of y_ticks to draw when generating a scale. Default is 6. The minimum is 2.
  • no_cache — adds Pragma: no-cache to the http header while output for CGI.
Be careful with this one, as Netscape 4.5 is unfriendly with POST using this method. 💀
  • pairs — Direction only: bool — if 'true', Chart uses the first dataset as a set of degrees and the second dataset as a set of values. Then, the third set is a set of degrees and the fourth a set of values ... If 'pairs' is set to 'false', Chart uses the first dataset as a set of angels and all following datasets as sets of values. Defaults to 'false'. 😇
  • png_border — sets the number of pixels used as a border between the graph and the edges of the image. Defaults to 10.
  • point — indicates to draw points in a direction chart. 'true' or 'false' possible. Defaults to 'true'.
  • polar — "Direction" only: if set 'true', the maximum x value is in the center of the coordinate system. Defaults to 'false'. 🧭
  • precision — sets the number of numerals after the decimal point. Affects in most cases the y-axis. But also the x-axis if "xy_plot" was set and also the labels in a pie chart. Defaults to 3.
  • pt_size — "Points" and "LinesPoints" only: sets the radius of the points in pixels. Default is 18.
  • ring — "Pie" only: sets the "thickness" of the pie, the percentage of the radius which is visible. Defaults to 1 (full pie chart). Good values are between 0.2 and 0.4. 🍩
  • scale — "Split" only: every y-value will be multiplied with that value, but the scale won't change. Which means that split allows one to overdraw certain rows! Only useful if you want to give prominence to the maximal amplitudes of the data. Defaults to 1.
  • same_error — "ErrorBars" only: tells chart that you want use the same error value of a data point if set to 'true'. Look at the documentation to see how the module ErrorBars works. Default: 'false'.
  • same_y_axes — "Composite" only: forces both component charts to use the same maximum and minimum y-values if set to 'true'. This helps to keep the composite charts from being too confusing 🌀. Default is "undef".
  • skip_int_ticks — if it’s 'true', the labels and ticks get drawn every *n*th tick, no cap. Of course in horizontalBars it affects the x-axis 💅. Default is 1 — no skipping.
  • skip_x_ticks — sets the number of x-ticks and x-tick labels to skip. Like, if 'skip_x_ticks' was set to 4, Chart would draw every 4th x-tick and x-tick label. Default is "undef".
  • skip_y_ticks — HorizontalBars only: draw only every n'th tick with a label on the y-axis. The page then literally says “does for other charts.” — yes, that’s the actual text, bestie 💀. Defaults to 1 (draw all).
  • sort — in a xy-plot, the data gets sorted ascending if set to 'true'. (Should be set if the data isn’t sorted, especially in Lines, Split and LinesPoints.) In a Pareto Chart the data gets sorted descending. Defaults to 'false'.
  • spaced_bars — Bars only: leaves space between the groups of bars at each data point when set to 'true'. This just makes it easier to read a bar chart. Default is 'true'.
  • start — Split only: sets the start value of the first interval. If the x coordinate of the first data point is zero, you should 'set' to zero. Default is 'undef'.
  • sub_title — write a sub-title under the title in smaller letters. Default is empty.
  • text_space — sets the amount of space left on the sides (lext and right) of text, (title, legend, label) to make it more readable. Defaults to 2.
  • tick_label_font — this is the font for the tick labels. It also needs a GD font object as an argument. Default is GD::Font->Small.
  • tick_len — sets the length of the x- and y-ticks in pixels. Default is 4.
  • title — content of title text. If empty, no title is drawn. It recognizes '\n' as a newline, and acts accordingly. Remember, if you want to use normal quotation marks instead of single quotation marks then you have to quote "\\n". Default is empty.
  • title_font — this option changes the font of the title. Default is GD::Font->Large.
  • transparent — makes the background of the whole image transparent if set to 'true'. Useful for making web page images. Default is 'false'.
  • x_grid_lines — draws vertical grid lines matching up to x ticks if set to 'true'. Default is 'false'.
  • x_label — tells Chart what to use for the x-axis label. If empty, no label is drawn. Default is empty.
  • x_ticks — specifies how to draw the x-tick labels. Valid values are 1: 'normal', 2: 'staggered' (alternating on upper and lower row — for very long labels), and 3: 'vertical' (the labels are draw upwards in right angle). Default is 'normal'.
  • xy_plot — forces Chart to plot a x-y-graph, which means that the x-axis is also numeric if set to 'true'. Very useful for mathematical graphs. Works for Lines, Points, LinesPoints and ErrorBars. Split makes always a xy_plot. Defaults to 'false'.
  • y_label — tells Chart what to use for labels on the standard, left y-axis. If empty, no label is drawn. Default is empty ('').
  • y_label2 — text of the label on the second, right y-axis (if different from left). If empty, no label is drawn. Default is empty ('').
  • y_axes — tells Chart where to place the y-axis. Has no effect on Composite and Pie. Valid values are 'left', 'right' and 'both'. Defaults to 'left'.
  • y_grid_lines — draws horizontal grid lines matching up to y ticks if set to 'true'. Default is 'false'.
  • y_ticks1 — Composite only: number of y ticks to use on the first and second y-axis (y_ticks2). Please note that if you just set the 'y_ticks' option, both axes will use that number of y ticks. Both default to undef.
  • y_ticks2 — see "y_ticks1" 👆.

Copyright 2022 David Bonner, Herbert Breunung.

This program is free software; you can redistribute it and/or modify it under same terms as Perl itself.

🌈 AUTHOR 🌈

David Bonner, Chart Group,

Herbert Breunung, <lichtkind@cpan.org> 💌

okay that’s a wrap, bestie — page source/version is perl v5.42.0, dated 2022-11-29 🫶✨

📦 where this page comes from