remove 5.005 inappropriate use warnings

[imager-graph.git] / Graph.pm

diff --git a/Graph.pm b/Graph.pm
index 2aa2c77c18b23677c60e576035ed0ab38380fe39..93e05f8c1a3e4c061f49c6adf0cb26587b8f12ed 100644 (file)
--- a/Graph.pm
+++ b/Graph.pm
@@ -9,7 +9,7 @@ Imager::Graph - Perl extension for producing Graphs using the Imager library.
 
   use Imager::Graph::SubClass;
   my $chart = Imager::Graph::SubClass->new;
-  my $img = $chart->draw(data=>..., ...)
+  my $img = $chart->draw(data=> \@data, ...)
     or die $chart->error;
 
 =head1 DESCRIPTION
@@ -28,7 +28,7 @@ use vars qw($VERSION);
 use Imager qw(:handy);
 use Imager::Fountain;
 
-$VERSION = '0.05';
+$VERSION = '0.06';
 
 # the maximum recursion depth in determining a color, fill or number
 use constant MAX_DEPTH => 10;
@@ -70,10 +70,16 @@ the value can be a hashref containing sub values.
 The C<style> parameter will selects a basic color set, and possibly
 sets other related parameters.  See L</"STYLES">.
 
-  my $img = $graph->draw(data=>\@data,
-                         title=>{ text=>"Hello, World!",
-                                  size=>36,
-                                  color=>'FF0000' });
+ my $font = Imager::Font->new(file => 'ImUgly.ttf');
+ my $img = $chart->draw(
+                 data    => \@data,
+                 font    => $font,
+                 title   => {
+                                 text  => "Hello, World!",
+                                 size  => 36,
+                                 color => 'FF0000'
+                            }
+                 );
 
 When referring to a single sub-value this documentation will refer to
 'title.color' rather than 'the color element of title'.
@@ -93,8 +99,6 @@ The currently defined styles are:
 a light grey background with no outlines.  Uses primary colors for the
 data fills.
 
-This is the default style.
-
 =item primary_red
 
 a light red background with no outlines.  Uses primary colors for the
@@ -128,6 +132,8 @@ background and data fills, and adds a drop shadow.
 You can override the value used for text and outlines by setting the
 C<fg> parameter.
 
+This is the default style.
+
 =item fount_rad
 
 also designed as a "pretty" style this uses radial fountain fills for
@@ -680,6 +686,14 @@ Sets the error field of the object and returns an empty list or undef,
 depending on context.  Should be used for error handling, since it may
 provide some user hooks at some point.
 
+The intended usage is:
+
+  some action
+    or return $self->_error("error description");
+
+You should almost always return the result of _error() or return
+immediately afterwards.
+
 =cut
 
 sub _error {
@@ -705,7 +719,8 @@ sub _style_defs {
   \%style_defs;
 }
 
-my $def_style = 'primary';
+# Let's make the default something that looks really good, so folks will be interested enough to customize the style.
+my $def_style = 'fount_lin';
 
 my %styles =
   (
@@ -924,6 +939,8 @@ Retrieve some general 'thing'.
 
 Supports the 'lookup(foo)' mechanism.
 
+Returns an empty list on failure.
+
 =cut
 
 sub _get_thing {
@@ -1025,6 +1042,8 @@ sub _get_number {
 Retrieves an integer from the style.  This is a simple wrapper around
 _get_number() that rounds the result to an integer.
 
+Returns an empty list on failure.
+
 =cut
 
 sub _get_integer {
@@ -1044,6 +1063,8 @@ Uses Imager::Color->new to translate normal scalars into color objects.
 
 Allows the lookup(name) mechanism.
 
+Returns an empty list on failure.
+
 =cut
 
 sub _get_color {
@@ -1084,6 +1105,8 @@ the 'lookup(name)' mechanism.
 This function does the fg and bg initialization for hatched fills, and
 translation of *_ratio for fountain fills (using the $box parameter).
 
+Returns an empty list on failure.
+
 =cut
 
 sub _translate_fill {
@@ -1186,11 +1209,9 @@ fill.
 
 sub _make_img {
   my ($self) = @_;
-  
-  my ($width, $height) = (256, 256);
 
-  $width = $self->_get_number('width');
-  $height = $self->_get_number('height');
+  my $width = $self->_get_number('width') || 256;
+  my $height = $self->_get_number('height') || 256;
   my $channels = $self->{_style}{channels};
 
   $channels ||= 3;
@@ -1202,6 +1223,15 @@ sub _make_img {
   $img;
 }
 
+=item _text_style($name)
+
+Returns parameters suitable for calls to Imager::Font's bounding_box()
+and draw() methods intended for use in defining text styles.
+
+Returns an empty list on failure.
+
+=cut
+
 sub _text_style {
   my ($self, $name) = @_;
 
@@ -1214,10 +1244,10 @@ sub _text_style {
     %work = %{$self->{_style}{text}};
   }
   $work{font}
-      or return $self->_error("$name has no font parameter");
+    or return $self->_error("$name has no font parameter");
 
   $work{font} = $self->_get_thing("$name.font")
-    or return $self->_error("invalid font");
+    or return $self->_error("No $name.font defined, either set $name.font or font to a font");
   UNIVERSAL::isa($work{font}, "Imager::Font")
       or return $self->_error("$name.font is not a font");
   if ($work{color} && !ref $work{color}) {
@@ -1231,10 +1261,19 @@ sub _text_style {
   %work;
 }
 
+=item _text_bbox($text, $name)
+
+Returns a bounding box for the specified $text as styled by $name.
+
+Returns an empty list on failure.
+
+=cut
+
 sub _text_bbox {
   my ($self, $text, $name) = @_;
 
-  my %text_info = $self->_text_style($name);
+  my %text_info = $self->_text_style($name)
+    or return;
 
   my @bbox = $text_info{font}->bounding_box(%text_info, string=>$text,
                                            canon=>1);
@@ -1357,7 +1396,8 @@ sub _draw_legend_horizontal {
   my @sizes;
   my @offsets;
   for my $label (@$labels) {
-    my @text_box = $self->_text_bbox($label, 'legend');
+    my @text_box = $self->_text_bbox($label, 'legend')
+      or return;
     push(@sizes, \@text_box);
     my $entry_width = $patchsize + $gap + $text_box[2];
     if ($pos == 0) {
@@ -1453,7 +1493,8 @@ sub _draw_legend_vertical {
   my ($width, $height) = (0,0);
   my @sizes;
   for my $label (@$labels) {
-    my @box = $self->_text_bbox($label, 'legend');
+    my @box = $self->_text_bbox($label, 'legend')
+      or return;
     push(@sizes, \@box);
     $width = $box[2] if $box[2] > $width;
     if ($minrowsize > $box[3]) {
@@ -1535,11 +1576,13 @@ sub _draw_title {
   my ($self, $img, $chart_box) = @_;
 
   my $title = $self->{_style}{title}{text};
-  my @box = $self->_text_bbox($title, 'title');
+  my @box = $self->_text_bbox($title, 'title')
+    or return;
   my $yoff = $box[1];
   @box[0,1] = (0,0);
   $self->_align_box(\@box, $chart_box, 'title');
-  my %text_info = $self->_text_style('title');
+  my %text_info = $self->_text_style('title')
+    or return;
   $img->string(%text_info, x=>$box[0], 'y'=>$box[3] + $yoff, text=>$title);
   $self->_remove_box($chart_box, \@box);
   1;