| 1 |
|
| 2 |
=encoding UTF-8 |
| 3 |
|
| 4 |
=head1 NAME |
| 5 |
|
| 6 |
Chart::Manual::Properties - complete guide to Chart's changeable properties |
| 7 |
|
| 8 |
=head1 INTRO |
| 9 |
|
| 10 |
Individual properties of a chart can be changed via method C<set>: |
| 11 |
|
| 12 |
$chart_object->set( %properties); |
| 13 |
$chart_object->set( key => 'value', ... ); |
| 14 |
|
| 15 |
This page documents all viable keys and values for this calls. |
| 16 |
|
| 17 |
The first section lists the most common data types and their acceptable |
| 18 |
values. |
| 19 |
|
| 20 |
Please note that all chart L<type|Chart::Manual::Types> reacts only to |
| 21 |
a distinct subset of properties. The L<section section|/"BY CHART TYPE"> |
| 22 |
therefore groups all properties by chart type or set of types, where they |
| 23 |
have an effect. The descriptions in this section are shortened to achive |
| 24 |
a tabular overview. |
| 25 |
|
| 26 |
A fuller description of each property provides the |
| 27 |
L<third section|/ALPHABETICALLY>, where they are alpabetically sorted. |
| 28 |
|
| 29 |
The general layout of a chart image: |
| 30 |
|
| 31 |
=for HTML <p> |
| 32 |
<img src="https://raw.githubusercontent.com/lichtkind/Chart/main/dev/example/manual/layout.png" alt="layout"> |
| 33 |
</p> |
| 34 |
|
| 35 |
=head1 DATA TYPES |
| 36 |
|
| 37 |
Every key expects values of a certain data type. The more often occurring |
| 38 |
types are sorted, enumerated and decibed in this section. |
| 39 |
|
| 40 |
=head2 boolean |
| 41 |
|
| 42 |
Yes or no decisions you can answer with the perlish C<0> or C<1> as well |
| 43 |
as with C<'true'> or C<'false'>, which might be shortened to C<'t'> and C<'T'> |
| 44 |
or C<'f'> and C<'F'>. C<'none'> as an alias of C<'false'> is also an option. |
| 45 |
|
| 46 |
=head2 code |
| 47 |
|
| 48 |
Anonymous subroutine that usually takes the first argument and returns |
| 49 |
a transformed result: |
| 50 |
|
| 51 |
sub { $_[0] + 1 } |
| 52 |
|
| 53 |
=head2 color |
| 54 |
|
| 55 |
The usual options are: |
| 56 |
|
| 57 |
names: 'blue' |
| 58 |
|
| 59 |
All names are tabulated visually and by name under L<Chart::Property::DataType::Color::Constant/NAMES>. |
| 60 |
You can also define a color with integer values in the RGB or HSL space. |
| 61 |
Acceptable ranges are for RGB: 3x 0..255 and for HSL: 0..359, 2 x 0..100. |
| 62 |
|
| 63 |
RGB triplets: [0,255,255] |
| 64 |
RGB hashes: { Red => 0, Green => 255, Blue => 255 } |
| 65 |
RGB hashes: { R => 0, G => 255, B => 255 } |
| 66 |
HSL hashes: { H => 240, S => 100, L => 50 } |
| 67 |
HSL hashes: { hue => 240, saturation => 100, lightness => 50 } |
| 68 |
|
| 69 |
Detailed explanation and even more options you find under L<Graphics::Toolkit::Color>. |
| 70 |
|
| 71 |
=head2 font |
| 72 |
|
| 73 |
There are a handful GD built in font object, than can be referenced: |
| 74 |
|
| 75 |
GD::Font->Tiny |
| 76 |
GD::Font->Small |
| 77 |
GD::Font->MediumBold |
| 78 |
GD::Font->Large |
| 79 |
GD::Font->Giant |
| 80 |
|
| 81 |
=head2 integer |
| 82 |
|
| 83 |
Whole numbers (without decimals) to set position, size and alike. |
| 84 |
|
| 85 |
=head2 positive integer |
| 86 |
|
| 87 |
Integers greater or equal zero. |
| 88 |
|
| 89 |
=head2 string |
| 90 |
|
| 91 |
Short texts for title, sub_title and labels on axis, tics and legend. |
| 92 |
Line breaks (C</n>) are only acceptable inside single quotes and in the |
| 93 |
L</title>. |
| 94 |
|
| 95 |
|
| 96 |
=head1 BY CHART TYPE |
| 97 |
|
| 98 |
Summary of all properties, grouped by chart type where there applicable. |
| 99 |
Sections are named after the Chart type in question, except B<All> and B<NoPie>. |
| 100 |
The format is: name ... L<type|/"DATA TYPES">, description; C<default value>. |
| 101 |
|
| 102 |
Click on name for a longer explanation. |
| 103 |
|
| 104 |
|
| 105 |
=head2 All |
| 106 |
|
| 107 |
Properties available in all chart types: |
| 108 |
|
| 109 |
L<colors-background|/colors> ... L</color> of whole image background ; C<'white'> |
| 110 |
|
| 111 |
L<colors-datasetx|/colors> ..... L</color> of points/lines/bars of dataset number x = 0..64 |
| 112 |
|
| 113 |
L<colors-grid_lines|/colors> ... L</color> of vertical and horizontal grid lines in the plot background; C<'black'> |
| 114 |
|
| 115 |
L<colors-x_grid_lines|/colors> . L</color> of vertical grid lines; C<'black'> |
| 116 |
|
| 117 |
L<colors-y_grid_lines|/colors> . L</color> of horizontal grid lines; C<'black'> |
| 118 |
|
| 119 |
L<colors-text|/colors> ......... L</color> of all text ; C<'black'> |
| 120 |
|
| 121 |
L<colors-title|/colors> ........ L</color> of text above the graph ; C<'black'> |
| 122 |
|
| 123 |
L<colors-x_label|/colors> ...... L</color> of x-axis label text; C<'black'> |
| 124 |
|
| 125 |
L<colors-y_label|/colors> ...... L</color> of y-axis (left side) label text; C<'black'> |
| 126 |
|
| 127 |
L<colors-y_label2|/colors> .... L</color> of y-axis (right side) label text; C<'black'> |
| 128 |
|
| 129 |
L<colors-misc|/colors> ....... L</color> of boxes, ticks, axis and alike; C<'black'> |
| 130 |
|
| 131 |
L</f_x_tick> ................ L</code> that transforms "would have" into actual tick label on left x-axis; C<undef> |
| 132 |
|
| 133 |
L</f_y_tick> ............... L</code> that transforms "would have" into actual tick label on right y-axis; C<undef> |
| 134 |
|
| 135 |
L</graph_border> .......... space between graph and title + legend in pixel; C<10> |
| 136 |
|
| 137 |
L</grey_background> ...... L<bool|/boolean>: sets plot background to grey; C<'true'> |
| 138 |
|
| 139 |
L</imagemap> ............ L<bool|/boolean>: enable imagemap_dump(); C<'false'> |
| 140 |
|
| 141 |
L</label_font> .......... L</font> of axis labels; GD::Font->MediumBold |
| 142 |
|
| 143 |
L</legend> .............. qw[left right top bottom none]: placement of the legend; C<'right'> |
| 144 |
|
| 145 |
L</legend_font> ......... L</font> of the text in the legend; GD::Font->Small. |
| 146 |
|
| 147 |
L</legend_labels> ....... (array ref): labels of colors in legend; C<undef> |
| 148 |
|
| 149 |
L</png_border> .......... L<pos_int|/"positive integer">: space between graph parts and image edge in pixel; C<10> |
| 150 |
|
| 151 |
L</sub_title> ........... L</string>: text below the L</title> in smaller letters; C<''> |
| 152 |
|
| 153 |
L</text_space> .......... L<pos_int|/"positive integer">: extra space around any text; C<2> |
| 154 |
|
| 155 |
L</title> ............... L</string>: text on top of a chart; C<''> |
| 156 |
|
| 157 |
L</title_font> .......... L</font> of the title text; GD::Font->Large |
| 158 |
|
| 159 |
L</transparent> ......... L<bool|/boolean>: full image background transparency; C<'false'> |
| 160 |
|
| 161 |
L</x_label> ............. L</string>: x-axis label text; C<''> |
| 162 |
|
| 163 |
L</y_label> ............. L</string>:label on the standard, left y-axis; C<''> |
| 164 |
|
| 165 |
L</y_label2> ............ L</string>:label on right y-axis, if different; C<''> |
| 166 |
|
| 167 |
|
| 168 |
=head2 NoPie |
| 169 |
|
| 170 |
Properties available in all chart types of kinda xy-plot, not L</Pie>: |
| 171 |
|
| 172 |
L</custom_x_ticks> ..... (array ref): [0,3,4] displays 0th, 3rd, and 4th x-tick; C<undef> |
| 173 |
|
| 174 |
L</grid_lines> ......... L<bool|/boolean>: draw vertical and horizontal grid lines; C<'false'> |
| 175 |
|
| 176 |
L</include_zero> ....... L<bool|/boolean>: forces y-axis to include zero; C<'false'> |
| 177 |
|
| 178 |
L</integer_ticks_only> . L<bool|/boolean>: draw x-axis ticks with label only on whole values; C<'false'> |
| 179 |
|
| 180 |
L</max_val> ............ L<pos_int|/"positive integer">: maximum value on y-axis; C<undef> |
| 181 |
|
| 182 |
L</max_x_ticks> ........ L<pos_int|/"positive integer">: maximum of ticks and labels to draw on x-axis; C<100> |
| 183 |
|
| 184 |
L</max_y_ticks> ........ L<pos_int|/"positive integer">: maximum of ticks and labels to draw on y-axis; C<100> |
| 185 |
|
| 186 |
L</min_val> ............ L<pos_int|/"positive integer">: maximum value on y-axis; C<undef> |
| 187 |
|
| 188 |
L</min_x_ticks> ........ L<pos_int|/"positive integer">: minimum of ticks and labels to draw on x-axis; C<6> (min 2) |
| 189 |
|
| 190 |
L</min_y_ticks> ........ L<pos_int|/"positive integer">: minimum of ticks and labels to draw on y-axis; C<6> (min 2) |
| 191 |
|
| 192 |
L</precision> .......... L<pos_int|/"positive integer">: nr. of numerals after the decimal point in axis labels; C<3> |
| 193 |
|
| 194 |
L</skip_int_ticks> ..... L<pos_int|/"positive integer">: draw only n'th tick on whole x-value; C<1> (if L</integer_ticks_only>) |
| 195 |
|
| 196 |
L</skip_x_ticks> ....... L<pos_int|/"positive integer">: draw only every n'th tick with label; C<1> |
| 197 |
|
| 198 |
L</sort> ............... L<bool|/boolean>: sort data in ascending order; C<'false'> |
| 199 |
|
| 200 |
L</tick_label_font> .... L</font> of tick labels; GD::Font->Small |
| 201 |
|
| 202 |
L</tick_len> ........... L<pos_int|/"positive integer">: length of the x- and y-ticks in pixels; C<4> |
| 203 |
|
| 204 |
L</x_grid_lines> ....... L<bool|/boolean>: vertical grid lines matching x ticks; C<'false'> |
| 205 |
|
| 206 |
L</x_ticks> ............ qw[normal staggered vertical]: style of x-axis labels; C<'normal'> |
| 207 |
|
| 208 |
L</xy_plot> ............ L<bool|/boolean>: forces x-y-graph, with numeric x-axis; C<'false'> |
| 209 |
|
| 210 |
L</y_axes> ............. (C<'left'>, C<'right'>, C<'both'>): position of y-axis;C<'left'> |
| 211 |
|
| 212 |
L</y_grid_lines> ....... L<bool|/boolean>: horizontal grid lines matching y ticks; C<'false'> |
| 213 |
|
| 214 |
|
| 215 |
=head2 Bars |
| 216 |
|
| 217 |
This includes Bars StackedBars and HorizontalBars. |
| 218 |
|
| 219 |
L</spaced_bars> ........ L<bool|/boolean>: leave space between the groups of bars; C<'true'> |
| 220 |
|
| 221 |
|
| 222 |
=head2 HorizontalBars |
| 223 |
|
| 224 |
L</skip_y_ticks> ....... L<pos_int|/"positive integer">: draw every n'th tick with label on y-axis; C<1> |
| 225 |
|
| 226 |
|
| 227 |
=head2 Composite |
| 228 |
|
| 229 |
L</brush_style1> ....... brush style of points associated with left y-axis; C<undef> |
| 230 |
|
| 231 |
L</brush_style2> ....... brush style of points associated with right y-axis; C<undef> |
| 232 |
|
| 233 |
L</composite_info> ..... (array of arrays) which data sets produce which chart types; C<undef> |
| 234 |
|
| 235 |
L</f_y_tick1> .......... L</code> that transforms "would have" into actual label on left y-axis; C<undef> |
| 236 |
|
| 237 |
L</f_y_tick2> .......... L</code> that transforms "would have" into actual label on right y-axis; C<undef> |
| 238 |
|
| 239 |
L</legend_example_size> Length of the color example line in legend in pixel; C<20> |
| 240 |
|
| 241 |
L</max_val1> ........... L</code> maximum y value on the left axis; C<undef> |
| 242 |
|
| 243 |
L</max_val2> ........... L</code> maximum y value on the right axis; C<undef> |
| 244 |
|
| 245 |
L</min_val1> ........... L</code> minimum y value on the left axis; C<undef> |
| 246 |
|
| 247 |
L</min_val2> ........... L</code> minimum y value on the right axis; C<undef> |
| 248 |
|
| 249 |
L</same_y_axes> ........ L</code> both y-axis have same min and max; C<undef> |
| 250 |
|
| 251 |
L</y_ticks1> ........... L<pos_int|/"positive integer">: number of y ticks on left y-axis; C<undef> |
| 252 |
|
| 253 |
L</y_ticks2> ........... L<pos_int|/"positive integer">: number of y ticks on right y-axis; C<undef> |
| 254 |
|
| 255 |
|
| 256 |
=head2 Direction |
| 257 |
|
| 258 |
L</angle_interval> ..... L<pos_int|/"positive integer">: angle between radial lines; C<30> |
| 259 |
|
| 260 |
L</arrow> .............. L<bool|/boolean>: paint points as arrows; C<'false'> |
| 261 |
|
| 262 |
L</brush_size> ......... L<pos_int|/"positive integer">: width of the lines in pixels; C<6> |
| 263 |
|
| 264 |
L</line> ............... L<bool|/boolean>: connected points with lines; C<'false'> |
| 265 |
|
| 266 |
L</max_circles> ........ L<pos_int|/"positive integer">: max nr. of coordinate grid circles; C<100> |
| 267 |
|
| 268 |
L</min_circles> ........ L<pos_int|/"positive integer">: min nr. of coordinate grid circles; C<4> (min. 2) |
| 269 |
|
| 270 |
L</pair> ............... L<bool|/boolean>: use odd numbered data sets to build pairs with the next; C<'false'> |
| 271 |
|
| 272 |
L</point> .............. L<bool|/boolean>: paint points at all (or only lines); C<'false'> |
| 273 |
|
| 274 |
L</polar> .............. L<bool|/boolean>: reverse x axis; C<'false'> |
| 275 |
|
| 276 |
L</pt_size> ............ L<pos_int|/"positive integer">: radius of points in pixels; C<18> |
| 277 |
|
| 278 |
|
| 279 |
=head2 ErrorBars |
| 280 |
|
| 281 |
L</brush_size> ......... L<pos_int|/"positive integer">: width of the lines in pixels; C<6> |
| 282 |
|
| 283 |
L</pt_size> ............ L<pos_int|/"positive integer">: radius of points in pixels; C<18> |
| 284 |
|
| 285 |
L</same_error> ......... L<bool|/boolean>: same values for upper and lower error bounds; C<'false'> |
| 286 |
|
| 287 |
|
| 288 |
=head2 Lines |
| 289 |
|
| 290 |
including chart type LinesPoints |
| 291 |
|
| 292 |
L</brush_size> ......... L<pos_int|/"positive integer">: width of the lines in pixels; C<6> |
| 293 |
|
| 294 |
|
| 295 |
=head2 Points |
| 296 |
|
| 297 |
including chart type LinesPoints |
| 298 |
|
| 299 |
L</brushStyle> ......... shape of the points; C<'FilledCircle'> |
| 300 |
|
| 301 |
L</pt_size> ............ L<pos_int|/"positive integer">: radius of points in pixels; C<18> |
| 302 |
|
| 303 |
|
| 304 |
=head2 Pie |
| 305 |
|
| 306 |
L</label_values> ....... qw[percent value both none]: label content on pie slice label; C<'percent'> |
| 307 |
|
| 308 |
L</legend_label_values> qw[percent value both none]: label content in the legend; C<'value'> |
| 309 |
|
| 310 |
L</legend_lines> ....... L<bool|/boolean>: draw lines connecting pie slices and label; C<'false'> |
| 311 |
|
| 312 |
L</ring> ............... L</real>: percentage of visible radius; C<1> (full pie) |
| 313 |
|
| 314 |
|
| 315 |
=head2 Split |
| 316 |
|
| 317 |
L</interval> ........... L<pos_int|/"positive integer">: interval of a plot segment; C<'undef'> |
| 318 |
|
| 319 |
L</interval_ticks> ..... L<pos_int|/"positive integer">: number of ticks on x-axis; C<5> |
| 320 |
|
| 321 |
L</scale> .............. L</integer>: factor for y-values; C<1> |
| 322 |
|
| 323 |
L</start> .............. L</integer>: start value of the first interval; C<'undef'> |
| 324 |
|
| 325 |
|
| 326 |
=head1 ALPHABETICALLY |
| 327 |
|
| 328 |
=head2 angle_interval |
| 329 |
|
| 330 |
L</Direction> only: how many radial lines should be drawn. |
| 331 |
The default value is 30, which means that a line will be drawn every |
| 332 |
30 degrees. Valid Values are: 0, 5, 10, 15, 20, 30, 45 and 60. |
| 333 |
If you choose 0, direction will draw no line. |
| 334 |
|
| 335 |
=head2 arrow |
| 336 |
|
| 337 |
L</Direction> only: L<Bool|/boolean> that if C<'true'>, chart will draw a |
| 338 |
arrow from the center to the point. Defaults to C<'false'>. |
| 339 |
|
| 340 |
=head2 brush_size |
| 341 |
|
| 342 |
L</Lines> only: Integer sets the width of the lines in pixels. Default is 6. |
| 343 |
|
| 344 |
=head2 background |
| 345 |
|
| 346 |
see L</colors> |
| 347 |
|
| 348 |
=head2 brushStyle |
| 349 |
|
| 350 |
Sets the shape of points for Chart::Points, Chart::LinesPoints. |
| 351 |
|
| 352 |
Possible values are: 'FilledCircle', 'circle', 'donut', 'OpenCircle', |
| 353 |
'fatPlus', 'triangle', 'upsidedownTriangle', 'square', 'hollowSquare', |
| 354 |
'OpenRectangle', 'FilledDiamond', 'OpenDiamond', 'Star', 'OpenStar'. |
| 355 |
Default: 'FilledCircle'. Look at Demo at L<Chart::Manual::Types/Points>. |
| 356 |
|
| 357 |
=head2 brush_style1 |
| 358 |
|
| 359 |
L</Composite> only: brush style of points associated with left y-axis. |
| 360 |
|
| 361 |
=head2 brush_style2 |
| 362 |
|
| 363 |
L</Composite> only: brush style of points associated with right y-axis. |
| 364 |
|
| 365 |
=head2 colors |
| 366 |
|
| 367 |
The key C<colors> is special, because there are a lot of things that |
| 368 |
need to be colored. That's why its value is a hash with keys within, |
| 369 |
which name what exactly needs to be colored. Their value has to be a |
| 370 |
L<color> definition (name, RGB array ref or HSL hash ref): |
| 371 |
|
| 372 |
$obj->set('colors' => {'background' => [255,255,255]}); |
| 373 |
|
| 374 |
sets the background color to white (which is the default). Valid keys are: |
| 375 |
|
| 376 |
'background' (background color for the image) |
| 377 |
'title' (color of the title) |
| 378 |
'text' (all the text in the chart) |
| 379 |
'x_label' (color of the x-axis label) |
| 380 |
'y_label' (color of the first y axis label) |
| 381 |
'y_label2' (color of the second y axis label) |
| 382 |
'grid_lines' (color of the grid lines) |
| 383 |
'x_grid_lines' (color of the x grid lines - for x axis ticks) |
| 384 |
'y_grid_lines' (color of the y grid lines - for to left y axis ticks) |
| 385 |
'y2_grid_lines' (color of the y2 grid lines - for right y axis ticks) |
| 386 |
'dataset0'..'dataset63' (the different datasets) |
| 387 |
'misc' (everything else, ie. axis, ticks, box around the legend) |
| 388 |
|
| 389 |
NB. For composite charts, there is a limit of 8 datasets per component. |
| 390 |
The colors for 'dataset8' through 'dataset15' become the colors |
| 391 |
for 'dataset0' through 'dataset7' for the second component chart. |
| 392 |
|
| 393 |
=head2 composite_info |
| 394 |
|
| 395 |
L</Composite> only: information about which data set gets visualized by |
| 396 |
which chart type. It should be a reference to an array of array references, |
| 397 |
containing information like the following: |
| 398 |
|
| 399 |
$obj->set ('composite_info' => [ ['Bars', [1,2]], |
| 400 |
['Lines', [3,4] ] ]); |
| 401 |
|
| 402 |
This example would set the two component charts to be a bar chart and |
| 403 |
a line chart. It would use the first two data sets for the bar |
| 404 |
chart (note that the numbering starts at 1, not zero like most of |
| 405 |
the other numbered things in Chart), and the second two data sets |
| 406 |
for the line chart. The default is undef. |
| 407 |
|
| 408 |
NB. Chart::Composite can only do two component charts. |
| 409 |
|
| 410 |
=head2 custom_x_ticks |
| 411 |
|
| 412 |
Used in L</Points>, L</Lines>, L</Linespoints>, L</Errorbars>, and |
| 413 |
L</Bars> charts. This option allows you to you to specify exactly which |
| 414 |
x-ticks and x-tick labels should be drawn. It should be assigned a |
| 415 |
reference to an array of desired ticks. Just remember that I'm counting |
| 416 |
from the 0th element of the array. (ie., if 'custom_x_ticks' is assigned |
| 417 |
[0,3,4], then the 0th, 3rd, and 4th x-ticks will be displayed) |
| 418 |
|
| 419 |
=head2 datasetx |
| 420 |
|
| 421 |
see L</colors> |
| 422 |
|
| 423 |
=head2 f_x_tick |
| 424 |
|
| 425 |
Needs a reference to a function (L</code>) which uses the x-tick labels |
| 426 |
generated by the '@data[0]' as the argument. The result of this function |
| 427 |
can reformat the labels. For instance |
| 428 |
|
| 429 |
$obj -> set ('f_x_tick' => \&formatter ); |
| 430 |
|
| 431 |
An example for the function formatter: x labels are seconds since an event. |
| 432 |
The referenced function can transform this seconds to hour, minutes and seconds. |
| 433 |
|
| 434 |
=head2 f_y_tick |
| 435 |
|
| 436 |
The same situation as for 'f_x_tick' but now used for y labels. |
| 437 |
|
| 438 |
=head2 f_y_tick1 |
| 439 |
|
| 440 |
L</Composite> only: L</code> ref to a function which has one argument |
| 441 |
and has to return a string which labels the first resp. second y axis. |
| 442 |
Both default to undef. |
| 443 |
|
| 444 |
=head2 f_y_tick2 |
| 445 |
|
| 446 |
L</Composite> only: L</code> ref to a function which has one argument |
| 447 |
and has to return a string which labels the first resp. second y axis. |
| 448 |
Both default to undef. |
| 449 |
|
| 450 |
=head2 graph_border |
| 451 |
|
| 452 |
L</Pie> only: Sets the number of pixels used as a border between the |
| 453 |
title/labels and the actual graph within the image. Defaults to 10. |
| 454 |
|
| 455 |
=head2 grey_background |
| 456 |
|
| 457 |
Puts a nice soft grey background on the data plot area when set to C<'true'>. |
| 458 |
Default is C<'true'>. |
| 459 |
|
| 460 |
=head2 grid_lines |
| 461 |
|
| 462 |
L<bool|/boolean>: draw grid lines matching up to x and y ticks. |
| 463 |
Default is C<'false'>. |
| 464 |
|
| 465 |
=head2 imagemap |
| 466 |
|
| 467 |
Lets Chart know you're going to ask for information about the placement |
| 468 |
of the data for use in creating an image map from the png. This information |
| 469 |
can be retrieved using the L<imagemap_dump()|Chart::Manual::Methods/imagemap_dump> |
| 470 |
method. NB. that the imagemap_dump() method cannot be called until after |
| 471 |
the Chart has been L<generated|"/Chart::Manual::Workflows/create image">. |
| 472 |
|
| 473 |
=head2 include_zero |
| 474 |
|
| 475 |
If C<'true'>, forces the y-axis to include zero if it is not in the dataset |
| 476 |
range. Default is C<'false'>. |
| 477 |
|
| 478 |
In general, it is better to use this, than to set the L</min_val> if that |
| 479 |
is all you want to achieve. |
| 480 |
|
| 481 |
=head2 integer_ticks_only |
| 482 |
|
| 483 |
L<bool|/boolean> specifies to draw the x- and y-ticks at floating point |
| 484 |
values (as normal) or when set to C<'true'> only at integer values. |
| 485 |
Default: C<'false'> |
| 486 |
|
| 487 |
=head2 interval |
| 488 |
|
| 489 |
L</Split> only: Sets the interval of one partition of plot. Defaults 'undef'. |
| 490 |
|
| 491 |
=head2 interval_ticks |
| 492 |
|
| 493 |
L</Split> only: Number of ticks for the x-axis. Defaults to 5. |
| 494 |
|
| 495 |
=head2 label_font |
| 496 |
|
| 497 |
This option changes the L</font> of the axis labels. |
| 498 |
Default is GD::Font->MediumBold. |
| 499 |
|
| 500 |
=head2 label_values |
| 501 |
|
| 502 |
L</Pie> only: What kind of value labels to show alongside the pie. |
| 503 |
Valid values are C<'percent'>, C<'value'>, C<'both'> and C<'none'>. |
| 504 |
Defaults to C<'percent'>. |
| 505 |
|
| 506 |
=head2 legend |
| 507 |
|
| 508 |
Specifies the placement of the legend. Valid values are C<'left'>, |
| 509 |
C<'right'>, C<'top'>, C<'bottom'>. Setting this to C<'none'> tells chart |
| 510 |
not to draw a legend. Default is C<'right'>. |
| 511 |
|
| 512 |
=head2 legend_example_size |
| 513 |
|
| 514 |
L</Composite> only: Length of the example line in the legend in pixels. |
| 515 |
Defaults to C<20>. |
| 516 |
|
| 517 |
=head2 legend_font |
| 518 |
|
| 519 |
This option changes the L</font> of the text in the legend. |
| 520 |
Default is GD::Font->Small. |
| 521 |
|
| 522 |
=head2 legend_labels |
| 523 |
|
| 524 |
Array reference containing texts, which are the labels assigned to each |
| 525 |
color in the legend. Amount has to correspond to the amount of data sets. |
| 526 |
|
| 527 |
@labels = ('foo', 'bar'); |
| 528 |
$obj->set ('legend_labels' => \@labels); |
| 529 |
|
| 530 |
Default is empty, in which case C<'Dataset 1'>, C<'Dataset 2'>, etc. are |
| 531 |
used as the labels. |
| 532 |
|
| 533 |
=head2 legend_label_values |
| 534 |
|
| 535 |
L</Pie> only: What labels to draw in the legend. Valid values are |
| 536 |
c<'percent'>, C<'value'>, C<'both'> and C<'none'>. Defaults to C<'value'>. |
| 537 |
|
| 538 |
=head2 legend_lines |
| 539 |
|
| 540 |
L</Pie> only: L<bool|/boolean> to decide if lines connecting pie slices |
| 541 |
and label are drawn. Default is C<'false'>. |
| 542 |
|
| 543 |
=head2 label_values |
| 544 |
|
| 545 |
L</Pie> only: Labels to draw beside the pie slices. Valid values are |
| 546 |
C<'percent'>, C<'value'>, C<'both'> and C<'none'>. Defaults to C<'percent'>. |
| 547 |
|
| 548 |
=head2 line |
| 549 |
|
| 550 |
L</Direction> only: If you turn this option to C<'true'>, then point will |
| 551 |
be connected with lines. Defaults to C<'false'>. |
| 552 |
|
| 553 |
=head2 max_circles |
| 554 |
|
| 555 |
L</Direction> only: Sets the maximum number of circles in the coordinate system. |
| 556 |
Default is 100. This limit is used to avoid plotting an unreasonable |
| 557 |
large number of ticks if non-round values are used for the min_val and max_val. |
| 558 |
|
| 559 |
=head2 max_val |
| 560 |
|
| 561 |
Sets the maximum y-value on the graph, overriding the normal auto-scaling. |
| 562 |
Default is undef. |
| 563 |
|
| 564 |
=head2 max_val1 |
| 565 |
|
| 566 |
L</Composite> only: Maximum y-value for the first (left y-axis) components. |
| 567 |
Default to undef. |
| 568 |
|
| 569 |
=head2 max_val2 |
| 570 |
|
| 571 |
L</Composite> only: Maximum y-value for the second (right y-axis) components. |
| 572 |
Default to undef. |
| 573 |
|
| 574 |
=head2 max_x_ticks |
| 575 |
|
| 576 |
Work similar as 'max_y_ticks' and 'min_y_ticks'. Of course, only for a |
| 577 |
xy_plot. |
| 578 |
|
| 579 |
=head2 max_y_ticks |
| 580 |
|
| 581 |
Sets the maximum number of y_ticks to draw when generating a scale. |
| 582 |
Default is 100. This limit is used to avoid plotting an unreasonable |
| 583 |
large number of ticks if non-round values are used for the min_val |
| 584 |
and max_val. |
| 585 |
|
| 586 |
The value for 'max_y_ticks' should be at least 5 times larger than |
| 587 |
'min_y_ticks'. |
| 588 |
|
| 589 |
=head2 min_circles |
| 590 |
|
| 591 |
L</Direction> only: Sets the minimum number of circles when generating |
| 592 |
a scale for direction. Default is 4, minimum is 2. |
| 593 |
|
| 594 |
=head2 min_val |
| 595 |
|
| 596 |
Sets the minimum y-value on the graph, overriding the normal auto-scaling. |
| 597 |
Default is undef. |
| 598 |
|
| 599 |
Caution: should be used when setting 'max_val' and 'min_val' to floating |
| 600 |
point or non-round numbers. This is because the scale must start & end |
| 601 |
on a tick, ticks must have round-number intervals, and include round |
| 602 |
numbers. |
| 603 |
|
| 604 |
Example: Suppose your data set has a range of 35-114 units. If you specify |
| 605 |
them as the 'min_val' & 'max_val', the y_axis will be plotted with 80 ticks |
| 606 |
every 1 unit.. If no 'min_val' & 'max_val', the system will auto scale the |
| 607 |
range to 30-120 with 10 ticks every 10 units. |
| 608 |
|
| 609 |
If the 'min_val' & 'max_val' are specified to excessive precision, they may |
| 610 |
be overridden by the system, plotting a maximum 'max_y_ticks' ticks. |
| 611 |
|
| 612 |
=head2 min_val1 |
| 613 |
|
| 614 |
L</Composite> only: Minimum y-value for the first (left y-axis) component. |
| 615 |
Default to undef. |
| 616 |
|
| 617 |
=head2 min_val2 |
| 618 |
|
| 619 |
L</Composite> only: Minimum y-value for the second (right y-axis) component. |
| 620 |
Default to undef. |
| 621 |
|
| 622 |
=head2 min_x_ticks |
| 623 |
|
| 624 |
Work similar as 'max_y_ticks' and 'min_y_ticks'. Of course, only for a |
| 625 |
xy_plot. |
| 626 |
|
| 627 |
=head2 min_y_ticks |
| 628 |
|
| 629 |
Sets the minimum number of y_ticks to draw when generating a scale. |
| 630 |
Default is 6, The minimum is 2. |
| 631 |
|
| 632 |
=head2 no_cache |
| 633 |
|
| 634 |
Adds Pragma: no-cache to the http header while output for CGI. |
| 635 |
Be careful with this one, as Netscape 4.5 is unfriendly with POST |
| 636 |
using this method. |
| 637 |
|
| 638 |
=head2 pairs |
| 639 |
|
| 640 |
L<Direction> only: L<bool|/boolean> if C<'true'>, Chart uses the first |
| 641 |
dataset as a set of degrees and the second dataset as a set of values. |
| 642 |
Then, the third set is a set of degrees and the fourth a set of values ... |
| 643 |
If 'pairs' is set to C<'false'>, Chart uses the first dataset as a set of |
| 644 |
angels and all following datasets as sets of values. Defaults to C<'false'>. |
| 645 |
|
| 646 |
=head2 png_border |
| 647 |
|
| 648 |
Sets the number of pixels used as a border between the graph |
| 649 |
and the edges of the image. Defaults to 10. |
| 650 |
|
| 651 |
=head2 point |
| 652 |
|
| 653 |
Indicates to draw points in a direction chart. C<'true'> or C<'false'> |
| 654 |
possible. Defaults to C<'true'>. |
| 655 |
|
| 656 |
=head2 polar |
| 657 |
|
| 658 |
L</Direction> only: If set C<'true'>, the maximum x value is in the center |
| 659 |
of the coordinate system. Defaults to C<'false'>. |
| 660 |
|
| 661 |
=head2 precision |
| 662 |
|
| 663 |
Sets the number of numerals after the decimal point. Affects in most |
| 664 |
cases the y-axis. But also the x-axis if L</xy_plot> was set and also |
| 665 |
the labels in a pie chart. Defaults to C<3>. |
| 666 |
|
| 667 |
=head2 pt_size |
| 668 |
|
| 669 |
L</Points> and L</LinesPoints> only: Sets the radius of the points |
| 670 |
in pixels. Default is C<18>. |
| 671 |
|
| 672 |
=head2 ring |
| 673 |
|
| 674 |
L</Pie> only: sets the "thickness" of the pie, the percentage of |
| 675 |
the radius, which is visible. Defaults to C<1> (full pie chart). |
| 676 |
Good values are between C<0.2> and C<0.4>. |
| 677 |
|
| 678 |
=head2 scale |
| 679 |
|
| 680 |
L</Split> only: Every y-value will be multiplied with that value, but |
| 681 |
the scale won't change. Which means that split allows one to overdraw |
| 682 |
certain rows! Only useful if you want to give prominence to the maximal |
| 683 |
amplitudes of the data. Defaults to C<1>. |
| 684 |
|
| 685 |
=head2 same_error |
| 686 |
|
| 687 |
L</ErrorBars> only: It tells chart that you want use the same |
| 688 |
error value of a data point if set to C<'true'>. Look at the documentation |
| 689 |
to see how the module ErrorBars works. Default: C<'false'>. |
| 690 |
|
| 691 |
=head2 same_y_axes |
| 692 |
|
| 693 |
L</Composite> only: Forces both component charts to use the same maximum |
| 694 |
and minimum y-values if set to C<'true'>. This helps to keep the composite |
| 695 |
charts from being too confusing. Default is C<undef>. |
| 696 |
|
| 697 |
=head2 skip_int_ticks |
| 698 |
|
| 699 |
If C<'true'> the labels and ticks will be drawn every nth tick. Of course |
| 700 |
in horizontalBars it affects the x-axis. Default to C<1>, no skipping. |
| 701 |
|
| 702 |
=head2 skip_x_ticks |
| 703 |
|
| 704 |
Sets the number of x-ticks and x-tick labels to skip. (ie. |
| 705 |
if 'skip_x_ticks' was set to 4, Chart would draw every 4th x-tick |
| 706 |
and x-tick label). Default is C<undef>. |
| 707 |
|
| 708 |
=head2 skip_y_ticks |
| 709 |
|
| 710 |
L</HorizontalBars> only: Draw only every n'th tick with label on y-axis. |
| 711 |
does for other charts. Defaults to C<1> (draw all). |
| 712 |
|
| 713 |
=head2 sort |
| 714 |
|
| 715 |
In a xy-plot, the data will be sorted ascending if set to C<'true'>. |
| 716 |
(Should be set if the data isn't sorted, especially in Lines, Split |
| 717 |
and LinesPoints) In a Pareto Chart the data will be sorted descending. |
| 718 |
Defaults to C<'false'>. |
| 719 |
|
| 720 |
=head2 spaced_bars |
| 721 |
|
| 722 |
L</Bars> only: Leaves space between the groups of bars at each data point |
| 723 |
when set to C<'true'>. This just makes it easier to read a bar chart. |
| 724 |
Default is C<'true'>. |
| 725 |
|
| 726 |
=head2 start |
| 727 |
|
| 728 |
L</Split> only: Sets the start value of the first interval. |
| 729 |
If the x coordinate of the first data point is zero, you should 'set' to |
| 730 |
zero. Default is C<'undef'>. |
| 731 |
|
| 732 |
=head2 sub_title |
| 733 |
|
| 734 |
Write a sub-title under the L</title> in smaller letters. |
| 735 |
Default is empty. |
| 736 |
|
| 737 |
=head2 text_space |
| 738 |
|
| 739 |
Sets the amount of space left on the sides (lext and right) of text, |
| 740 |
(title, legend, label) to make it more readable. Defaults to C<2>. |
| 741 |
|
| 742 |
=head2 tick_label_font |
| 743 |
|
| 744 |
This is the font for the tick labels. It also needs |
| 745 |
a GD font object as an argument. Default is GD::Font->Small. |
| 746 |
|
| 747 |
=head2 tick_len |
| 748 |
|
| 749 |
Sets the length of the x- and y-ticks in pixels. Default is C<4>. |
| 750 |
|
| 751 |
=head2 title |
| 752 |
|
| 753 |
Content of title text. If empty, no title is drawn. |
| 754 |
It recognizes '\n' as a newline, and acts accordingly. |
| 755 |
Remember, if you want to use normal quotation marks instead of single |
| 756 |
quotation marks then you have to quote "\\n". Default is empty. |
| 757 |
|
| 758 |
=head2 title_font |
| 759 |
|
| 760 |
This option changes the L</font> of the title. Default is GD::Font->Large. |
| 761 |
|
| 762 |
=head2 transparent |
| 763 |
|
| 764 |
Makes the background of the whole image transparent if set to C<'true'>. |
| 765 |
Useful for making web page images. Default is C<'false'>. |
| 766 |
|
| 767 |
=head2 x_grid_lines |
| 768 |
|
| 769 |
Draws vertical grid lines matching up to x ticks if set to C<'true'>. |
| 770 |
Default is C<'false'>. |
| 771 |
|
| 772 |
=head2 x_label |
| 773 |
|
| 774 |
Tells Chart what to use for the x-axis label. If empty, no label |
| 775 |
is drawn. Default is empty. |
| 776 |
|
| 777 |
=head2 x_ticks |
| 778 |
|
| 779 |
Specifies how to draw the x-tick labels. Valid values are 1: C<'normal'>, |
| 780 |
2: C<'staggered'> (alternating on upper and lower row - for very long labels), |
| 781 |
and 3: C<'vertical'> (the labels are draw upwards in right angle). |
| 782 |
Default is C<'normal'>. |
| 783 |
|
| 784 |
=head2 xy_plot |
| 785 |
|
| 786 |
Forces Chart to plot a x-y-graph, which means, that the x-axis is also |
| 787 |
numeric if set to C<'true'>. Very useful for mathematical graphs. |
| 788 |
Works for Lines, Points, LinesPoints and ErrorBars. Split makes always a |
| 789 |
xy_plot. Defaults to C<'false'>. |
| 790 |
|
| 791 |
=head2 y_label |
| 792 |
|
| 793 |
Tells Chart what to use for labels on the standard, left y-axis. |
| 794 |
If empty, no label is drawn. Default is empty (C<''>). |
| 795 |
|
| 796 |
=head2 y_label2 |
| 797 |
|
| 798 |
Text of the label on the second, right y-axis (if different from left). |
| 799 |
If empty, no label is drawn. Default is empty (C<''>). |
| 800 |
|
| 801 |
=head2 y_axes |
| 802 |
|
| 803 |
Tells Chart where to place the y-axis. Has no effect on Composite and Pie. |
| 804 |
Valid values are C<'left'>, C<'right'> and C<'both'>. Defaults to C<'left'>. |
| 805 |
|
| 806 |
=head2 y_grid_lines |
| 807 |
|
| 808 |
Draws horizontal grid lines matching up to y ticks if set to C<'true'>. |
| 809 |
Default is C<'false'>. |
| 810 |
|
| 811 |
=head2 y_ticks1 |
| 812 |
|
| 813 |
L<Composite> only: number of y ticks to use on the first and |
| 814 |
second y-axis (y_ticks2). Please note that if you just set the 'y_ticks' |
| 815 |
option, both axes will use that number of y ticks. Both default to undef. |
| 816 |
|
| 817 |
=head2 y_ticks2 |
| 818 |
|
| 819 |
see L</y_ticks1> |
| 820 |
|
| 821 |
=head1 COPYRIGHT & LICENSE |
| 822 |
|
| 823 |
Copyright 2022 David Bonner, Herbert Breunung. |
| 824 |
|
| 825 |
This program is free software; you can redistribute it and/or modify it |
| 826 |
under same terms as Perl itself. |
| 827 |
|
| 828 |
=head1 AUTHOR |
| 829 |
|
| 830 |
David Bonner, Chart Group, |
| 831 |
|
| 832 |
Herbert Breunung, <[email protected]> |
| 833 |
|
| 834 |
|
| 835 |
=cut |