Chart::Clicker(3pm)

💖 Chart::Clicker 💖

okay bestie, sit DOWN, because this is the manpage for Chart::Clicker(3pm) — a.k.a. User Contributed Perl Documentation, a.k.a. the charting module that makes your data look absolutely iconic. no cap.

---

✨ NAME ✨

Chart::Clicker — powerful, extensible charting. that's it, that's the whole vibe. 🦋

🌸 VERSION 🌸

version 2.90 — she's grown, she's thriving, she's serving. 💅

🎀 SYNOPSIS 🎀

here's the tea, the whole thing, copy-paste-able and adorable:

use Chart::Clicker;

my $cc = Chart::Clicker->new;

my @values = (42, 25, 86, 23, 2, 19, 103, 12, 54, 9);
$cc->add_data('Sales', \@values);

# alternately, you can add data one bit at a time...
foreach my $v (@values) {
  $cc->add_data('Sales', $v);
}

# Or, if you want to specify the keys you can use a hashref
my $data = { 12 => 123, 13 => 341, 14 => 1241 };
$cc->add_data('Sales', $data);

$cc->write_output('foo.png');

like. look at that. a whole chart in like nine lines. main character energy fr fr. 👑

🌈 DESCRIPTION 🌈

Chart::Clicker wants to be a powerful, extensible charting package that makes genuinely, actually pretty output. like, output you'd show people. output you'd put on a slide and not apologize for. ✨

Charts can be saved as png, svg, pdf and postscript. yes all of them. she contains multitudes. 💜

Clicker flexes the power of Graphics::Primitive to make snazzy graphics without being tied to any specific backend — so she can switch it up whenever. and if you're new here, bestie, you probs wanna start with Chart::Clicker::Tutorial. that's the beginner-friendly doorway, walk through it. 🚪🦋

🍓 EXAMPLES 🍓

for actual code examples, go look at the examples repository on GitHub:

http://github.com/gphat/chart-clicker-examples/

real code, real charts, real inspiration. go consume. 😌

👑 FEATURES 👑

🖌️ Renderers

Clicker supports all of these renderers, and honestly? the range. she's got range:

• Line
• StackedLine
• Bar
• StackedBar
• Area
• StackedArea
• Bubble
• CandleStick
• Point
• Pie
• PolarArea

pick your fighter. 💅

📊 ADDING DATA 📊

the synopsis up there shows you the simple way to add data:

my @values = (42, 25, 86, 23, 2, 19, 103, 12, 54, 9);
foreach my $v (@values) {
  $cc->add_data('Sales', $v);
}

this is a convenience method, provided specifically so the simple cases stay simple (as they should). and adding multiple Series to a chart? literally just change the name argument of add_data. every unique first argument becomes its own separate series. it's giving effortless. if you want the full lore, see the docs for add_data.

BUT. if you wanna use the more advanced features of Clicker, you gotta shake off the simple method and build your Series & DataSets explicitly:

use Chart::Clicker::Data::Series;
use Chart::Clicker::Data::DataSet;

...

my $series = Chart::Clicker::Data::Series->new(
  keys    => [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ],
  values  => [ 42, 25, 86, 23, 2, 19, 103, 12, 54, 9 ],
);

my $ds = Chart::Clicker::Data::DataSet->new(series => [ $series ]);

$cc->add_to_datasets($ds);

fun fact: this used to be the only way to add data. then everybody kept asking for the common case to be easier, and that's how add_data was born. the people spoke, Clicker listened. 🫶

🧚 CONTEXTS 🧚

so normally you've got a couple datasets chillin' on the same axes. that's the standard use case. but sometimes you wanna chart one or more datasets on different axes. the classic reason? comparing two datasets of vastly different scale. like, number of employees in an office (1-10) vs. monthly revenues (10s of thousands). on a normal chart, the employee count would show up as a sad little flat line squished at the bottom. tragic. 😭

to fix that, Clicker has contexts. a context is a pair of axes, a renderer, and a name. and the name is the 'key' you use to refer to that context.

my $context = Chart::Clicker::Context->new( name => 'sales' );
$clicker->add_to_contexts($context);

$dataset->context('sales');

$clicker->add_to_datasets($dataset);

new contexts get a fresh domain and range axis, and they default to a Line renderer. slay. ✨

⚠️ Caveat, and this one matters: Clicker expects the default context — the one identified by the string default — to always be present. some of Clicker's internals pull their values straight from that context. so use the default context unless you genuinely need more than one. and if you do need more than one? use default as your base context. don't skip her, she's the foundation. 💀

🖼️ FORMATS & OUTPUT 🖼️

Clicker supports PNG, SVG, PDF and PostScript output. to change your output type, specify it when you create your Clicker object:

my $cc = Chart::Clicker->new(format => 'pdf', ...);
# ...
$cc->write_output('chart.pdf');

and if you're trying to get a scalar of the output for HTTP or similar shenanigans, you can do this:

# ... make your chart
$cc->draw;
my $image_data = $cc->rendered_data;

and hey — if you happen to be using Catalyst, go peek at Catalyst::View::Graphics::Primitive. they already did the work, bestie. 🌸

💎 ATTRIBUTES 💎

🎨 background_color

Set/Get the background color. defaults to white.

🖊️ border

Set/Get the border.

🌈 color_allocator

Set/Get the color_allocator for this chart.

🗂️ contexts

Set/Get the contexts for this chart.

📚 datasets

Get/Set the datasets for this chart.

🚗 driver

Set/Get the driver used to render this Chart. defaults to Graphics::Primitive::Driver::Cairo.

📼 format

Get the format for this Chart. Required in the constructor. Must be one of Png, Pdf, Ps or Svg.

🏃 plot_mode

Fast or slow plot mode. when in fast mode, data elements that are deemed superfluous or invisible just. don't get drawn. skipped. ghosted. default is 'slow'.

📐 grid_over

Flag controlling whether the grid is rendered over the data. defaults to 0. pro tip: you probably wanna set the grid's background color to an alpha of 0 if you turn this on.

📏 height

Set/Get the height. defaults to 300.

🧩 layout_manager

Set/Get the layout manager. defaults to Layout::Manager::Compass.

🗺️ legend

Set/Get the legend that will be used with this chart.

🧭 legend_position

The position the legend will be added. should be one of north, south, east, west or center, as required by Layout::Manager::Compass.

📍 marker_overlay

Set/Get the marker overlay object that'll be used if this chart has markers. this one is lazily constructed, to save time. she shows up when she's needed. 💅

🎉 over_decorations

Set/Get an arrayref of "over decorations" — i.e. things that get drawn OVER the chart. this is an advanced feature. see overaxis-bar.pl in the examples.

🛋️ padding

Set/Get the padding. defaults to 3px on all sides. give her some room to breathe.

🎬 plot

Set/Get the plot on which things are drawn.

🌳 subgraphs

you can add "child" graphs to this one via add_subgraph. they must be Chart::Clicker objects, and they get added to the bottom of the existing chart. this is a rather esoteric feature. iykyk. 🙈

🏷️ title

Set/Get the title component for this chart. Important: this is a Graphics::Primitive::TextBox, NOT a string. so to set the title of a chart you access the TextBox's text method:

$cc->title->text('A Title!');
$cc->title->font->size(20);
# etc, etc

if the title has text, then it gets added to the chart at the position specified by title_position.

you should consult the documentation for Graphics::Primitive::TextBox for stuff like padding and text rotation. and if you're adding it to the top and you want some padding between it and the plot, you can:

$cc->title->padding->bottom(5);

🧭 title_position

The position the title will be added. should be one of north, south, east, west or center, as required by Layout::Manager::Compass.

📌 Heads up: if no angle is set for the title, then it will be changed to -1.5707 if the title position is east or west. yes, automatically. she rotates herself. iconic.

📐 width

Set/Get the width. defaults to 500.

🛠️ METHODS 🛠️

🔢 context_count

Get a count of contexts.

📝 context_names

Get a list of context names.

🗑️ delete_context ($name)

Remove the context with the specified name. bye bestie. 👋

🔍 get_context ($name)

Get the context with the specified name.

💾 set_context ($name, $context)

Set a context of the specified name.

📦 add_to_datasets

Add the specified dataset (or arrayref of datasets) to the chart.

🧮 dataset_count

Get a count of datasets.

🎯 get_dataset ($index)

Get the dataset at the specified index.

🌊 rendered_data

Returns the data for this chart as a scalar. perfect for 'streaming' to a client. 🌊✨

🎀 add_to_over_decorations

Add an over decoration to the list.

🔎 get_over_decoration ($index)

Get the over decoration at the specified index.

🧾 over_decoration_count

Get a count of over decorations.

➕ add_to_contexts

Add the specified context to the chart.

🌿 add_subgraph

Add a subgraph to this chart.

🖌️ draw

Draw this chart. do the thing. ✨

🗃️ get_datasets_for_context

Returns an arrayref containing all datasets for the given context. this is what the renderers use to get their list of datasets to chart.

🍰 add_data ($name, $data)

Convenience method for adding data to the chart. can be called one of three ways:

🌟 scalar

Passing a name and a scalar will append the scalar data to that series' data.

$cc->add_data('Sales', 1234);
$cc->add_data('Sales', 1235);

this will result in a Series named 'Sales' with two values. simple. clean.

🌟 arrayref

Passing a name and an arrayref works pretty much the same as the scalar method above, except it appends the supplied arrayref to the existing one. and guess what — you can mix it with the scalar method. they play nice.

$cc->add_data('Sales', \@some_sales);
$cc->add_data('Sales', \@some_more_sales);
# This works still!
$cc->add_data('Sales', 1234);

🌟 hashref

this one lets you pass both keys and values in all at once. a whole little bundle. 🎁

$cc->add_data('Sales', { 2009 => 1234, 2010 => 1235 });
# appends to last call
$cc->add_data('Sales', { 2011 => 1234, 2012 => 1235 });

⚠️ you may call the hashref version after the scalar or arrayref versions. but you may not add a scalar or arrayref after adding a hashref — because it's genuinely not clear what indices should be used for that new data. so order matters, bestie. hashref goes last. 💀

🎭 set_renderer ($renderer_object, [ $context ])

Sets the renderer on the specified context. if no context is provided, then 'default' is assumed.

✍️ write

This method is passed through to the underlying driver. you only actually need to call this if you manually called draw beforehand. most of the time you want write_output instead. just saying. 👀

💾 write_output ($path)

Write the chart output to the specified location. output is written in the format provided to the constructor (which defaults to Png). internally, it calls draw for you — she handles it.

🚨 If you use this method, do NOT call draw first! she's already on it. doubling up is not the move.

$c->write_output('/path/to/the.png');

📐 inside_width

Get the width available in this container after taking away space for insets and borders.

📐 inside_height

Get the height available in this container after taking away space for insets and borders.

💀 ISSUES WITH CENTOS 💀

there have been numerous reports of problems with Chart::Clicker when using CentOS. and the fix has usually been updating the version of cairo. reports say upgrading to at least cairo-1.8.8-3 makes things actually work properly. 🛠️

the author hesitates to provide any other data here, because it may get out of date fast. so if you have trouble, feel free to drop an email and they'll tell you what they know.

💜 CONTRIBUTORS 💜

many thanks to the individuals who contributed various bits — legends, all of them:

• Ash Berlin
• Brian Cassidy
• Guillermo Roditi
• Torsten Schoenfeld
• Yuval Kogman

📂 SOURCE 📂

Chart::Clicker is on github:

http://github.com/gphat/chart-clicker/tree/master

✍️ AUTHOR ✍️

Cory G Watson <gphat@cpan.org>

---

👀 okay wait — this is only part 1 of 2. do not close the tab. there is more. stay tuned, bestie. 🦋💖

--- 🌸 ---

💖 COPYRIGHT AND LICENSE 💖

okay bestie this is the part where we give credit where credit is due, and the credit goes to Cory G Watson fr fr:

This software is copyright (c) 2016 by Cory G Watson.

and the legal tea, served fresh ☕:

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

so yeah — you can redistribute it, you can modify it, it's giving very much open-source royalty behavior 👑, just keep it on the same terms as perl itself. no cap, that's the whole vibe. slay 💅

---

🎀 and that's a wrap on Chart::Clicker(3pm), bestie!! this little icon of a manpage rode in on perl v5.36.0, dated 2022-10-14, and it ate every single time ✨🦋 go forth and make the prettiest charts, you absolute main character 💜🍓🧚

k bye love u, go plot something gorgeous 💖