documentation working commit
authorTony Cook <tony@develop-help.com>
Sat, 24 Jul 2010 04:49:54 +0000 (04:49 +0000)
committerTony Cook <tony@develop-help.com>
Sat, 24 Jul 2010 04:49:54 +0000 (04:49 +0000)
Changes
Graph.pm
lib/Imager/Graph/Pie.pm
lib/Imager/Graph/Vertical.pm

diff --git a/Changes b/Changes
index c24f5d2..358280a 100644 (file)
--- a/Changes
+++ b/Changes
@@ -10,9 +10,6 @@ More cool changes from Patrick Michaud:
  - Area charts
    https://rt.cpan.org/Ticket/Display.html?id=7
 
- - Imager::Graph::Horizontal::add_column_data_series() renamed to
-   add_bar_data_series() and now adds the series as a "bar" series.
-
 Other changes:
 
  - horizonal_gridlines (vertical charts) and vertical_gridlines
@@ -35,6 +32,7 @@ Other changes:
  - for vertical and horizontal charts, allow the fill of the graph
    area to be controlled separately from the base bg (graph.fill)
 
+
  - tests
 
 Bug fixes:
@@ -48,6 +46,10 @@ Bug fixes:
  - labels supplied to draw() are now used for vertical and horizontal
    charts
 
+ - Imager::Graph::Horizontal::add_column_data_series() renamed to
+   add_bar_data_series() and now adds the series as a "bar" series.
+   add_column_data_series() did nothing useful for a horizontal chart.
+
 TODO:
 
  - control of drawing markers for:
@@ -56,13 +58,7 @@ TODO:
 
    - line
 
- - tic size/positioning
-
- - gap between tic and labels
-
- - tests:
-
-   - test idempotent for h
+ - test line markers
 
  - document:
 
@@ -70,8 +66,6 @@ TODO:
 
    - graph outline and gridline styles
 
-   - document no{feature}
-
 
 Imager-Graph 0.07 - 21 May 2009
 =================
index 13f1a98..5a4165a 100644 (file)
--- a/Graph.pm
+++ b/Graph.pm
@@ -618,14 +618,21 @@ sub set_data_line_colors {
 =head1 FEATURES
 
 Each graph type has a number of features.  These are used to add
-various items that are displayed in the graph area.  Some common
-methods are:
+various items that are displayed in the graph area.
+
+Features can be controlled by calling methods on the graph object, or
+by passing a C<features> parameter to draw().
+
+Some common features are:
 
 =over
 
 =item show_legend()
 
-adds a box containing boxes filled with the data filess, with
+Feature: legend
+X<legend><features, legend>
+
+adds a box containing boxes filled with the data fills, with
 the labels provided to the draw method.  The legend will only be
 displayed if both the legend feature is enabled and labels are
 supplied.
@@ -638,7 +645,12 @@ sub show_legend {
 
 =item show_outline()
 
-draws a border around the data areas.
+Feature: outline
+X<outline>X<features, outline>
+
+If enabled, draw a border around the elements representing data in the
+graph, eg. around each pie segments on a pie chart, around each bar on
+a bar chart.
 
 =cut
 
@@ -648,10 +660,18 @@ sub show_outline {
 
 =item show_labels()
 
+Feature: labels
+X<labels>X<features, labels>
+
 labels each data fill, usually by including text inside the data fill.
 If the text does not fit in the fill, they could be displayed in some
-other form, eg. as callouts in a pie graph.  There usually isn't much
-point in including both labels and a legend.
+other form, eg. as callouts in a pie graph.
+
+For pie charts there isn't much point in enabling both the C<legend>
+and C<labels> features.
+
+For other charts, the labels label the independent variable, while the
+legend describes the color used to plot the dependent variables.
 
 =cut
 
@@ -661,6 +681,9 @@ sub show_labels {
 
 =item show_drop_shadow()
 
+Feature: dropshadow
+X<dropshadow>X<features, dropshadow>
+
 a simple drop shadow is shown behind some of the graph elements.
 
 =cut
@@ -671,7 +694,11 @@ sub show_drop_shadow {
 
 =item reset_features()
 
-Unsets all of the features
+Unsets all of the features.
+
+Note: this disables all features, even those enabled by default for a
+style.  They can then be enabled by calling feature methods or by
+supplying a C<feature> parameter to the draw() method.
 
 =cut
 
@@ -682,27 +709,27 @@ sub reset_features {
 
 =back
 
-Additionally, features can be set by passing them into the draw() method:
+Additionally, features can be set by passing them into the draw()
+method, named as above:
 
 =over
 
-=item legend
+=item *
 
-adds a box containing boxes filled with the data filess, with
-the labels provided to the draw method.  The legend will only be
-displayed if both the legend feature is enabled and labels are
-supplied.
+if supplied as an array reference, then any element C<no>I<featurename> will
+disable that feature, while an element I<featurename> will enable it.
 
-=item labels
+=item *
 
-labels each data fill, usually by including text inside the data fill.
-If the text does not fit in the fill, they could be displayed in some
-other form, eg. as callouts in a pie graph.  There usually isn't much
-point in including both labels and a legend.
+if supplied as a scalar, it is treated as if it were a reference to
+an array containing only that scalar.
 
-=item dropshadow
+=item *
 
-a simple drop shadow is shown behind some of the graph elements.
+if supplied as a hash reference, then a C<reset> key with a true value
+will avoid inheriting any default features, a key I<feature> with a
+false value will disable that feature and a key I<feature> with a true
+value will enable that feature.
 
 =back
 
@@ -809,7 +836,7 @@ The background of the graph.
 
 Used to define basic background and foreground colors for the graph.
 The bg color may be used for the background of the graph, and is used
-as a default for the background of hatcheed fills.  The fg is used as
+as a default for the background of hatched fills.  The fg is used as
 the default for line and text colors.
 
 =item font
@@ -911,7 +938,7 @@ Defaults to 'right' and 'top'.
 
 =item padding
 
-the gap between the legend patches and text and the outside of it's
+the gap between the legend patches and text and the outside of its
 box, or to the legend border, if any.
 
 =item outsidepadding
@@ -1523,8 +1550,14 @@ $styles{'ocean_flat'} = {
 
 =item $self->_style_setup(\%opts)
 
-Uses the values from %opts to build a customized hash describing the
-way the graph should be drawn.
+Uses the values from %opts, the custom style set by methods, the style
+set by the style parameter or the set_style() method and the built in
+chart defaults to build a working style.
+
+The working style features member is also populated with the active
+features for the chart.
+
+The working style is stored in the C<_style> member of $self.
 
 =cut
 
@@ -2523,6 +2556,12 @@ sub _box {
   }
 }
 
+=item _feature_enabled($feature_name)
+
+Check if the given feature is enabled in the work style.
+
+=cut
+
 sub _feature_enabled {
   my ($self, $name) = @_;
 
index 5a190d7..1280bb0 100644 (file)
@@ -58,6 +58,9 @@ your graph.  The features you can use with pie graphs are:
 
 =item show_callouts_onAll_segments()
 
+Feature: allcallouts.
+X<allcallouts>X<features, allcallouts>
+
 all labels are presented as callouts
 
 =cut
@@ -68,6 +71,9 @@ sub show_callouts_onAll_segments {
 
 =item show_only_label_percentages()
 
+Feature: labelspconly
+X<labelspconly>X<features, labelspconly>
+
 only show the percentage, not the labels.
 
 =cut
@@ -78,6 +84,9 @@ sub show_only_label_percentages {
 
 =item show_label_percentages()
 
+Feature: labelspc
+X<labelspc>X<features, labelspc>
+
 adds the percentage of the pie to each label.
 
 =cut
@@ -88,7 +97,7 @@ sub show_label_percentages {
 
 =back
 
-Additionally, arguments can be added to draw() :
+Inherited features:
 
 =over
 
@@ -101,18 +110,6 @@ adds a legend to your graph.  Requires the labels parameter
 labels each segment of the graph.  If the label doesn't fit inside the
 segment it is presented as a callout.
 
-=item labelspc
-
-adds the percentage of the pie to each label.
-
-=item labelspconly
-
-the segments are labels with their percentages only.
-
-=item allcallouts
-
-all labels are presented as callouts
-
 =item outline
 
 the pie segments are outlined.
index 059680b..ac31453 100644 (file)
@@ -2,7 +2,35 @@ package Imager::Graph::Vertical;
 
 =head1 NAME
 
-  Imager::Graph::Vertical- A super class for line/bar/column charts
+Imager::Graph::Vertical- A super class for line/bar/column/area charts
+
+=head1 SYNOPSIS
+
+  use Imager::Graph::Vertical;
+
+  my $vert = Imager::Graph::Vertical->new;
+  $vert->add_column_data_series(\@data, "My data");
+  $vert->add_area_data_series(\@data2, "Area data");
+  $vert->add_stacked_column_data_series(\@data3, "stacked data");
+  $vert->add_line_data_series(\@data4, "line data");
+  my $img = $vert->draw();
+
+  use Imager::Graph::Column;
+  my $column = Imager::Graph::Column->new;
+  $column->add_data_series(\@data, "my data");
+  my $img = $column->draw();
+
+=head1 DESCRIPTION
+
+This is a base class that implements the functionality for column,
+stacked column, line and area charts where the dependent variable is
+represented in changes in the vertical position.
+
+The subclasses, L<Imager::Graph::Column>,
+L<Imager::Graph::StackedColumn>, L<Imager::Graph::Line> and
+L<Imager::Graph::Area> simply provide default data series types.
+
+=head1 METHODS
 
 =cut
 
@@ -13,11 +41,12 @@ use Imager::Graph;
 
 use constant STARTING_MIN_VALUE => 99999;
 
-=over 4
+=over
 
 =item add_data_series(\@data, $series_name)
 
-Add a data series to the graph, of the default type.
+Add a data series to the graph, of the default type.  This requires
+that the graph object be one of the derived graph classes.
 
 =cut
 
@@ -96,10 +125,10 @@ sub add_area_data_series {
   return;
 }
 
-
 =item set_y_max($value)
 
-Sets the maximum y value to be displayed.  This will be ignored if the y_max is lower than the highest value.
+Sets the maximum y value to be displayed.  This will be ignored if the
+y_max is lower than the highest value.
 
 =cut
 
@@ -109,7 +138,8 @@ sub set_y_max {
 
 =item set_y_min($value)
 
-Sets the minimum y value to be displayed.  This will be ignored if the y_min is higher than the lowest value.
+Sets the minimum y value to be displayed.  This will be ignored if the
+y_min is higher than the lowest value.
 
 =cut
 
@@ -119,7 +149,8 @@ sub set_y_min {
 
 =item set_column_padding($int)
 
-Sets the padding between columns.  This is a percentage of the column width.  Defaults to 0.
+Sets the padding between columns.  This is a percentage of the column
+width.  Defaults to 0.
 
 =cut
 
@@ -129,9 +160,13 @@ sub set_column_padding {
 
 =item set_range_padding($percentage)
 
-Sets the padding to be used, as a percentage.  For example, if your data ranges from 0 to 10, and you have a 20 percent padding, the y axis will go to 12.
+Sets the padding to be used, as a percentage.  For example, if your
+data ranges from 0 to 10, and you have a 20 percent padding, the y
+axis will go to 12.
 
-Defaults to 10.  This attribute is ignored for positive numbers if set_y_max() has been called, and ignored for negative numbers if set_y_min() has been called.
+Defaults to 10.  This attribute is ignored for positive numbers if
+set_y_max() has been called, and ignored for negative numbers if
+set_y_min() has been called.
 
 =cut
 
@@ -720,8 +755,6 @@ sub _draw_area {
   return 1;
 }
 
-
-
 sub _line_marker {
   my ($self, $index) = @_;
 
@@ -978,10 +1011,17 @@ sub _add_data_series {
   return;
 }
 
+=back
+
+=head1 FEATURES
+
 =over
 
 =item show_horizontal_gridlines()
 
+Feature: horizontal_gridlines
+X<horizontal_gridlines>X<features, horizontal_gridlines>
+
 Enables the C<horizontal_gridlines> feature, which shows horizontal
 gridlines at the y-tics.
 
@@ -997,6 +1037,9 @@ sub show_horizontal_gridlines {
 
 =item set_horizontal_gridline_style(style => $style, color => $color)
 
+Style: hgrid.
+X<hgrid>X<style parameters, hgrid>
+
 Set the style and color of horizonal gridlines.
 
 See: L<Imager::Graph/"Line styles">
@@ -1012,9 +1055,79 @@ sub set_horizontal_gridline_style {
   return 1;
 }
 
+=item show_graph_outline($flag)
+
+Feature: graph_outline
+X<graph_outline>X<features, graph_outline>
+
+If no flag is supplied, unconditionally enable the graph outline.
+
+If $flag is supplied, enable/disable the graph_outline feature based
+on that.
+
+Enabled by default.
+
+=cut
+
+sub show_graph_outline {
+  my ($self, $flag) = @_;
+
+  @_ == 1 and $flag = 1;
+
+  $self->{custom_style}{features}{graph_outline} = $flag;
+
+  return 1;
+}
+
+=item set_graph_outline_style(color => ...)
+
+=item set_graph_outline_style(style => ..., color => ...)
+
+Style: graph.outline
+X<graph.outline>X<style parameters, graph.outline>
+
+Sets the style of the graph outline.
+
+Default: the style C<fg>.
+
+=cut
+
+sub set_graph_outline_style {
+  my ($self, %opts) = @_;
+
+  $self->{custom_style}{graph}{outline} = \%opts;
+
+  return 1;
+}
+
+=item set_graph_fill_style(I<fill parameters>)
+
+Style: graph.fill
+X<graph.fill>X<style parameters, graph.fill>
+
+Set the fill used to fill the graph data area.
+
+Default: the style C<bg>.
+
+eg.
+
+  $graph->set_graph_fill_style(solid => "FF000020", combine => "normal");
+
+=cut
+
+sub set_graph_fill_style {
+  my ($self, %opts) = @_;
+
+  $self->{custom_style}{graph}{fill} = \%opts;
+
+  return 1;
+}
+
 =item use_automatic_axis()
 
-Automatically scale the Y axis, based on L<Chart::Math::Axis>.  If Chart::Math::Axis isn't installed, this sets an error and returns undef.  Returns 1 if it is installed.
+Automatically scale the Y axis, based on L<Chart::Math::Axis>.  If
+Chart::Math::Axis isn't installed, this sets an error and returns
+undef.  Returns 1 if it is installed.
 
 =cut
 
@@ -1030,7 +1143,8 @@ sub use_automatic_axis {
 
 =item set_y_tics($count)
 
-Set the number of Y tics to use.  Their value and position will be determined by the data range.
+Set the number of Y tics to use.  Their value and position will be
+determined by the data range.
 
 =cut