From a4254f51b40429e61c1c710fca2dd03e62119ccf Mon Sep 17 00:00:00 2001 From: Martin Kamerbeek Date: Tue, 2 May 2006 14:48:42 +0000 Subject: [PATCH] Adding the first part of the graphing POD and changed the drawLabel function to have a saner api --- lib/WebGUI/Image.pm | 207 ++++++++++++++++-- lib/WebGUI/Image/Graph.pm | 279 ++++++++++++++++++++++++- lib/WebGUI/Image/Graph/Pie.pm | 5 +- lib/WebGUI/Image/Graph/XYGraph.pm | 260 ++++++++++++++++++++++- lib/WebGUI/Image/Graph/XYGraph/Bar.pm | 152 ++++++++++++++ lib/WebGUI/Image/Graph/XYGraph/Line.pm | 59 +++++- 6 files changed, 916 insertions(+), 46 deletions(-) diff --git a/lib/WebGUI/Image.pm b/lib/WebGUI/Image.pm index 9ed1f7241..70caf9db7 100644 --- a/lib/WebGUI/Image.pm +++ b/lib/WebGUI/Image.pm @@ -5,6 +5,12 @@ use Image::Magick; use WebGUI::Image::Palette; #------------------------------------------------------------------- +=head1 getBackgroundColor + +Returns the background color triplet. Defaults to #ffffff (white). + +=cut + sub getBackgroundColor { my $self = shift; @@ -12,6 +18,12 @@ sub getBackgroundColor { } #------------------------------------------------------------------- +=head1 getImageHeight + +Returns the height of the image in pixels. + +=cut + sub getImageHeight { my $self = shift; @@ -19,6 +31,12 @@ sub getImageHeight { } #------------------------------------------------------------------- +=head1 getImageWidth + +Returns the width in pixels of the image. + +=cut + sub getImageWidth { my $self = shift; @@ -26,6 +44,12 @@ sub getImageWidth { } #------------------------------------------------------------------- +=head1 getPalette + +Returns the palette object this image is set to. Defaults to the default palette. + +=cut + sub getPalette { my $self = shift; @@ -37,6 +61,13 @@ sub getPalette { } #------------------------------------------------------------------- +=head1 getXOffset + +Returns the horizontal offset of the center, relative to which the image is drawn. +Defaults to the physical center of the image. + +=cut + sub getXOffset { my $self = shift; @@ -44,6 +75,13 @@ sub getXOffset { } #------------------------------------------------------------------- +=head1 getYOffset + +Returns the vertical offset of the center, relative to which the image is drawn. +Defaults to the physical center of the image. + +=cut + sub getYOffset { my $self = shift; @@ -51,6 +89,12 @@ sub getYOffset { } #------------------------------------------------------------------- +=head1 image + +Returns the imagemagick object containing this image. + +=cut + sub image { my $self = shift; @@ -58,6 +102,24 @@ sub image { } #------------------------------------------------------------------- +=head1 new ( session, [ width, height ] ) + +Constructor for an image. Optionally you can pass the size of the image. + +=head2 session + +The webgui session object. + +=head2 width + +The width of the image in pixels. Defaults to 300. + +=head2 height + +The height of the image in pixels. Defaults to 300. + +=cut + sub new { my $class = shift; my $session = shift; @@ -76,6 +138,12 @@ sub new { } #------------------------------------------------------------------- +=head1 session + +Returns the the session object. + +=cut + sub session { my $self = shift; @@ -83,6 +151,18 @@ sub session { } #------------------------------------------------------------------- +=head1 setBackgroundColor ( colorTriplet ) + +Sets the backgroundcolor. Using this method will erase everything that is +already on the image. + +=head2 colorTriplet + +The color for the background. Supply as a html color triplet of the form +#ffffff. + +=cut + sub setBackgroundColor { my $self = shift; my $colorTriplet = shift; @@ -92,6 +172,16 @@ sub setBackgroundColor { } #------------------------------------------------------------------- +=head1 setImageHeight ( height) + +Set the height of the image. + +=head2 height + +The height of the image in pixels. + +=cut + sub setImageHeight { my $self = shift; my $height = shift; @@ -103,6 +193,16 @@ sub setImageHeight { } #------------------------------------------------------------------- +=head1 setImageWidth ( width ) + +Set the width of the image. + +=head2 width + +Teh width of the image in pixels. + +=cut + sub setImageWidth { my $self = shift; my $width = shift; @@ -114,6 +214,16 @@ sub setImageWidth { } #------------------------------------------------------------------- +=head1 setPalette ( palette ) + +Set the palette object this image will use. + +=head2 palette + +An instanciated WebGUI::Image::Palette object. + +=cut + sub setPalette { my $self = shift; my $palette = shift; @@ -122,6 +232,21 @@ sub setPalette { } #------------------------------------------------------------------- +=head1 saveToFileSystem ( path, [ filename ] ); + +Saves the image to the specified path and filename. + +=head2 path + +The directory where the image should be saved. + +=head2 filename + +The filename the image should get. If not passed it will default to the name set +by the setFilename method. + +=cut + sub saveToFileSystem { my $self = shift; my $path = shift; @@ -132,6 +257,14 @@ sub saveToFileSystem { # This doesn't seem to work... #------------------------------------------------------------------- +=head1 saveToScalar + +Returns a scalar containing the image contents. + +NOTE: This method does not work properly at the moment! + +=cut + sub saveToScalar { my $imageContents; my $self = shift; @@ -144,6 +277,21 @@ sub saveToScalar { } #------------------------------------------------------------------- +=head1 saveToStorageLocation ( storage, [ filename ] ) + +Save the image to the specified storage location. + +=head2 storage + +An instanciated WebGUI::Storage::Image object. + +=head2 filename + +The filename the image should get. If not passed it will default to the name set +by the setFilename method. + +=cut + sub saveToStorageLocation { my $self = shift; my $storage = shift; @@ -152,53 +300,70 @@ sub saveToStorageLocation { $self->image->Write($storage->getPath($filename)); } - #------------------------------------------------------------------- +=head1 text ( properties ) + +Extend the imagemagick Annotate method so alignment can be controlled better. + +=head2 properties + +A hash containing the imagemagick Annotate properties of your choice. +Additionally you can specify: + + alignHorizontal : The horizontal alignment for the text. Valid values + are: 'left', 'center' and 'right'. Defaults to 'left'. + alignVertical : The vertical alignment for the text. Valid values are: + 'top', 'center' and 'bottom'. Defaults to 'top'. + +You can use the align property to set the text justification. + +=cut + sub text { my $self = shift; - my %props = @_; + my %properties = @_; - my $anchorX = $props{x}; - my $anchorY = $props{y}; + my $anchorX = $properties{x}; + my $anchorY = $properties{y}; - my ($x_ppem, $y_ppem, $ascender, $descender, $width, $height, $max_advance) = $self->image->QueryMultilineFontMetrics(%props); + my ($x_ppem, $y_ppem, $ascender, $descender, $width, $height, $max_advance) = $self->image->QueryMultilineFontMetrics(%properties); # Process horizontal alignment - if ($props{alignHorizontal} eq 'center') { - $props{x} -= ($width / 2); + if ($properties{alignHorizontal} eq 'center') { + $properties{x} -= ($width / 2); } - elsif ($props{alignHorizontal} eq 'right') { - $props{x} -= $width; + elsif ($properties{alignHorizontal} eq 'right') { + $properties{x} -= $width; } # Process vertical alignment - if ($props{alignVertical} eq 'center') { - $props{y} -= ($height / 2); + if ($properties{alignVertical} eq 'center') { + $properties{y} -= ($height / 2); } - elsif ($props{alignVertical} eq 'bottom') { - $props{y} -= $height; + elsif ($properties{alignVertical} eq 'bottom') { + $properties{y} -= $height; } # Compensate for ImageMagicks 'ignore gravity when align is set' behaviour... - if ($props{align} eq 'Center') { - $props{x} += ($width / 2); + if ($properties{align} eq 'Center') { + $properties{x} += ($width / 2); } - elsif ($props{align} eq 'Right') { - $props{x} += $width; + elsif ($properties{align} eq 'Right') { + $properties{x} += $width; } # Compensate for ImageMagick's 'put all text a line up when align is set' behaviour... - $props{y} += $y_ppem; + $properties{y} += $y_ppem; # We must delete these keys or else placement can go wrong for some reason... - delete($props{alignHorizontal}); - delete($props{alignVertical}); + delete($properties{alignHorizontal}); + delete($properties{alignVertical}); $self->image->Annotate( #Leave align => 'Left' here as a default or all text will be overcompensated. align => 'Left', - %props, + %properties, gravity => 'NorthWest', antialias => 'true', ); diff --git a/lib/WebGUI/Image/Graph.pm b/lib/WebGUI/Image/Graph.pm index 0ec5d4eac..84fcec707 100644 --- a/lib/WebGUI/Image/Graph.pm +++ b/lib/WebGUI/Image/Graph.pm @@ -8,6 +8,17 @@ use List::Util; our @ISA = qw(WebGUI::Image); +=head1 addDataset ( dataset ) + +Adds a dataset to the graph. Please not that not all graph types can handle +multiple datasets and will therefore ignore any dataset but the first. + +=head2 dataset + +An arrayref containg the values of the data. The dat must be numeric. + +=cut + #------------------------------------------------------------------- sub addDataset { my $self = shift; @@ -16,6 +27,20 @@ sub addDataset { push(@{$self->{_datasets}}, $dataset); } +=head1 configurationForm + +Returns a hashref containing the form where the properties of your graph type +can be set. Your pluging should extend this method by append the form to the +hashref returned by the super method and returning the reference. + +The key for this entry must be unique, so use the namespace of your plugin +without the WebGUI::Image part; the :: converted to and underscore and +everything in lowercase. + +Check some of the plugins that come with WebGUI for examples. + +=cut + #------------------------------------------------------------------- sub configurationForm { my $self = shift; @@ -71,11 +96,28 @@ sub configurationForm { } #------------------------------------------------------------------- +=head1 drawLabel ( label, [ properties ] ) + +Draws a label with your preferred properties. Defaults the font, font size and +color which you can override. + +=head2 label + +The text of the label you want to print. + +=head2 properties + +A hash containing imagemagick Annotate properties. + +=cut + sub drawLabel { my $self = shift; + my $label = shift; my %properties = @_; $self->text( + text => $label, font => $self->getLabelFont->getFile, fill => $self->getLabelColor, style => 'Normal', @@ -85,11 +127,34 @@ sub drawLabel { } #------------------------------------------------------------------- +=head1 formNamespace + +Returns the namespace used in the configuration form. You must extend this +method by concatenating an underscore and the last part of your namespace to the +output of the SUPER method. + +For examples please see the implementation in the plugins that come with WebGUI. + +=cut + sub formNamespace { return "Graph"; } #------------------------------------------------------------------- +=head1 getConfiguration + +Returns the configuration hashref of the plugin. You must extend this method by +adding your configuration keys to the hashref returned by the SUPER method. To +avoid conflicts prepend your configuration keys with the namespace of your +plugin, encoded as follows: take the part of the namespace without +WebGUI::Image, convert it to lowercase and substitute the :: with a single +underscore. + +Check out the plugins that are shipped with WebGUI for examples. + +=cut + sub getConfiguration { my $self = shift; @@ -107,6 +172,22 @@ sub getConfiguration { } #------------------------------------------------------------------- +=head1 getGraphingTab ( session, [ config ] ) + +Returns the contents of the graphing tab you can add to your asset. + +This is a class method, and therefore you must pass the WebGUI session object. + +=head2 session + +An instanciated WebGUI session object. + +=head2 config + +Optionally you can pass a configuration hash to populate the form + +=cut + sub getGraphingTab { my (%configForms, $output); my $class = shift; @@ -211,6 +292,18 @@ EOS } #------------------------------------------------------------------- +=head1 getDataset ( [ index ] ) + +Returns the dataset indicated by index. + +=head2 index + +The index of the array containing the datasets. The first dataset is indicated +by index 0. If ommitted this method returns an arrayref of arrayrefs containing +all datasets. + +=cut + sub getDataset { my $self = shift; my $index = shift; @@ -223,6 +316,17 @@ sub getDataset { } #------------------------------------------------------------------- +=head1 getLabel ( [ index ] ) + +Returns the index'th label or an arrayref containing all labels. + +=head2 index + +The index of label to return. Numbering starts at 0. If omitted an arrayref +containing all labels is returned. + +=cut + sub getLabel { my $self = shift; my $index = shift; @@ -232,6 +336,12 @@ sub getLabel { } #------------------------------------------------------------------- +=head1 getLabelColor + +Returns the triplet of the label color. Defaults to '#333333'. + +=cut + sub getLabelColor { my $self = shift; @@ -239,6 +349,21 @@ sub getLabelColor { } #------------------------------------------------------------------- +=head1 getLabelDimensions ( text, [ properties ] ) + +Returns a hashref containg the width and height in pixels of the passed text. +Width and height are referenced by the keys 'width' and 'height' respectively. + +=head2 text + +The text you want to know the dimensions of. + +=head2 properties + +Optionally you can pass a hashref containing imagemagick's Annotate properties. + +=cut + sub getLabelDimensions { my $self = shift; my $text = shift; @@ -258,6 +383,13 @@ sub getLabelDimensions { } #------------------------------------------------------------------- +=head1 getLabelFont + +Returns the WebGUI::Image::Font object this image is set to. Defaults to the +default font. + +=cut + sub getLabelFont { my $self = shift; @@ -265,6 +397,12 @@ sub getLabelFont { } #------------------------------------------------------------------- +=head1 getLabelFontSize + +Returns the font size of the labels. Defaults to 20. + +=cut + sub getLabelFontSize { my $self = shift; @@ -272,14 +410,26 @@ sub getLabelFontSize { } #------------------------------------------------------------------- +=head1 getLabelOffset + +Returns the label offset. This is the distance between the label and the axis. +Defaults to 10 pixels. + +=cut + sub getLabelOffset { my $self = shift; return $self->{_labels}->{labelOffset} || 10; } - #------------------------------------------------------------------- +=head1 getMaxValueFromDataset + +Returns the highest value of all added datasets. + +=cut + sub getMaxValueFromDataset { my $self = shift; @@ -306,6 +456,20 @@ sub getMaxValueFromDataset { } #------------------------------------------------------------------- +=head1 load ( session, namespace ) + +Instanciates an WebGUI::Graph object with the given namespace. + +=head2 session + +A WebGUI::Session object. + +=head2 namespace + +The full namespace of the plugin you want to load. + +=cut + sub load { my $self = shift; my $session = shift; @@ -320,6 +484,20 @@ sub load { } #------------------------------------------------------------------- +=head1 loadByConfiguration ( session, configuration ) + +Loads a plugin defined by a configuration hash. + +=head2 session + +A WebGUI::Session object. + +=head2 configuration + +A configuration hashref. + +=cut + sub loadByConfiguration { my $self = shift; my $session = shift; @@ -337,6 +515,17 @@ sub loadByConfiguration { } #------------------------------------------------------------------- +=head1 processConfigurationForm ( session ) + +Processes the configuration form that is submitted and returns the correct +instanciated graphing plugin. + +=head2 session + +The WebGUI session object. + +=cut + sub processConfigurationForm { my $self = shift; my $session = shift; @@ -352,14 +541,18 @@ my $graph = $self->load($session, $namespace); } #------------------------------------------------------------------- -sub setBackground { - my $self = shift; - my $backgroundColor = shift; - - $self->{_properties}->{backgroundColor} = $backgroundColor; -} +=head1 setConfiguration ( config ) + +Configures the pluging according to the configuration hashref that is passed. +You must extend this method by calling the SUPER method with the configuration +hashref and processing your part of the configuration options. + +=head2 config + +The configuration hashref. + +=cut -#------------------------------------------------------------------- sub setConfiguration { my $self = shift; my $config = shift; @@ -376,6 +569,16 @@ sub setConfiguration { }; #------------------------------------------------------------------- +=head1 setLabelColor ( color ) + +Sets the color triplet of the labels. + +=head2 color + +The triplet defining the color. The triplet should be in the form of '#ffffff'. + +=cut + sub setLabelColor { my $self = shift; my $color = shift; @@ -384,6 +587,16 @@ sub setLabelColor { } #------------------------------------------------------------------- +=head1 setLabelFont ( font ) + +Set the label font. + +=head2 font + +A WebGUI::Image::Font object. + +=cut + sub setLabelFont { my $self = shift; my $font = shift; @@ -392,6 +605,16 @@ sub setLabelFont { } #------------------------------------------------------------------- +=head1 setLabelFontSize ( size ) + +Sets the font size of the labels. + +=head2 size + +The desired font size. + +=cut + sub setLabelFontSize { my $self = shift; my $size = shift; @@ -400,6 +623,17 @@ sub setLabelFontSize { } #------------------------------------------------------------------- +=head1 setLabelOffset ( offset ) + +Sets the label offset. This is the distance in pixels between the labels and the +axis. + +=head2 offset + +The label offset. + +=cut + sub setLabelOffset { my $self = shift; my $offset = shift; @@ -408,6 +642,16 @@ sub setLabelOffset { } #------------------------------------------------------------------- +=head1 setLabels ( labels ) + +Sets the labels for the datasets. + +=head2 labels + +An arrayref containig the labels. + +=cut + sub setLabels { my $self = shift; my $labels = shift || []; @@ -416,6 +660,24 @@ sub setLabels { } #------------------------------------------------------------------- +=head1 wrapLabelToWidth ( text, maxWidth, [ properties ] ) + +Wraps a text string onto multiple lines having a width of maxWidth. + +=head2 text + +The text you want to wrap. + +=head2 maxWidth + +The width the string should have after wrapping/ + +=head2 properties + +An optional hashref containing imagemagick's Annotate properties. + +=cut + sub wrapLabelToWidth { my (@words, $part, @lines); my $self = shift; @@ -447,4 +709,3 @@ sub wrapLabelToWidth { 1; - diff --git a/lib/WebGUI/Image/Graph/Pie.pm b/lib/WebGUI/Image/Graph/Pie.pm index e83c6888e..3c409ac26 100644 --- a/lib/WebGUI/Image/Graph/Pie.pm +++ b/lib/WebGUI/Image/Graph/Pie.pm @@ -466,14 +466,13 @@ sub drawLabel { my $maxWidth = $anchorX; $maxWidth = $self->getImageWidth - $anchorX if ($slice->{avgAngle} > 1.5 * pi || $slice->{avgAngle} < 0.5 * pi); - $self->SUPER::drawLabel( - text => $self->wrapLabelToWidth($text, $maxWidth), + $self->SUPER::drawLabel($self->wrapLabelToWidth($text, $maxWidth), ( alignHorizontal => $horizontalAlign, align => $align, alignVertical => $verticalAlign, x => $anchorX, y => $endPointY, - ); + )); } #------------------------------------------------------------------- diff --git a/lib/WebGUI/Image/Graph/XYGraph.pm b/lib/WebGUI/Image/Graph/XYGraph.pm index ed85e6580..4b57d3e92 100644 --- a/lib/WebGUI/Image/Graph/XYGraph.pm +++ b/lib/WebGUI/Image/Graph/XYGraph.pm @@ -9,6 +9,13 @@ use POSIX; our @ISA = qw(WebGUI::Image::Graph); #------------------------------------------------------------------- +=head1 configurationForm + +The configuration form part for this object. See WebGUI::Image::Graph for +documentation. + +=cut + sub configurationForm { my ($configForms, $f); my $self = shift; @@ -75,6 +82,12 @@ sub configurationForm { } #------------------------------------------------------------------- +=head1 draw + +Draws the graph. + +=cut + sub draw { my $self = shift; @@ -92,6 +105,12 @@ sub draw { } #------------------------------------------------------------------- +=head1 drawAxis + +Draws the axis. + +=cut + sub drawAxis { my $self = shift; @@ -107,6 +126,12 @@ sub drawAxis { } #------------------------------------------------------------------- +=head1 drawLabels + +Draws the labels. + +=cut + sub drawLabels { my $self = shift; my $location = shift; @@ -116,14 +141,13 @@ sub drawLabels { # Draw x-axis labels foreach (@{$self->getLabel}) { my $text = $self->wrapLabelToWidth($_, $self->getAnchorSpacing->{x}); - $self->drawLabel( - text => $text, + $self->drawLabel($text, ( alignHorizontal => 'center', alignVertical => 'top', align => 'Center', x => $anchorPoint{x}, y => $anchorPoint{y}, - ); + )); $anchorPoint{x} += $self->getAnchorSpacing->{x}; #$groupWidth + $self->getGroupSpacing; $anchorPoint{y} += $self->getAnchorSpacing->{y}; @@ -134,18 +158,23 @@ sub drawLabels { $anchorPoint{y} = $self->getChartOffset->{y} + $self->getChartHeight; # for (1 .. $self->getYRange / $self->getYGranularity) { foreach (@{$self->getYLabels}) { - $self->drawLabel( - text => $_, + $self->drawLabel($_, ( alignHorizontal => 'right', alignVertical => 'center', x => $anchorPoint{x}, #$self->getChartOffset->{x} - $self->getLabelOffset, y => $anchorPoint{y}, #$self->getChartOffset->{y} + $self->getChartHeight - $self->getPixelsPerUnit * $_*$self->getYGranularity, - ); + )); $anchorPoint{y} -= $self->getPixelsPerUnit * $self->getYGranularity } } #------------------------------------------------------------------- +=head drawRulers + +Draws the rulers. + +=cut + sub drawRulers { my $self = shift; @@ -164,6 +193,13 @@ sub drawRulers { } #------------------------------------------------------------------- +=head1 formNamespace + +Extends the form namespace for this object. See WebGUI::Image::Graph for +documentation. + +=cut + sub formNamespace { my $self = shift; @@ -171,6 +207,12 @@ sub formNamespace { } #------------------------------------------------------------------- +=head1 getAxisColor + +Returns the color triplet for the axis. Defaults to '#222222'. + +=cut + sub getAxisColor { my $self = shift; @@ -178,13 +220,26 @@ sub getAxisColor { } #------------------------------------------------------------------- +=head1 getChartHeight + +Returns the height of the chart. Defaults to 200. + +=cut + sub getChartHeight { my $self = shift; - return $self->{_properties}->{chartHeight}; + return $self->{_properties}->{chartHeight} || 200; } #------------------------------------------------------------------- +=head1 getChartOffset + +Returns the coordinates of the top-left corner of the chart. he coordinates are +contained in a hasref with keys 'x' and 'y'. + +=cut + sub getChartOffset { my $self = shift; @@ -192,13 +247,25 @@ sub getChartOffset { } #------------------------------------------------------------------- +=head1 getChartWidth + +Returns the width of the chart. Defaults to 200. + +=cut + sub getChartWidth { my $self = shift; - return $self->{_properties}->{chartWidth}; + return $self->{_properties}->{chartWidth} || 200; } #------------------------------------------------------------------- +=head1 getConfiguration + +Returns a configuration hashref. See WebGUI::Image::Graph for documentation. + +=cut + sub getConfiguration { my $self = shift; @@ -216,6 +283,13 @@ sub getConfiguration { } #------------------------------------------------------------------- +=head1 getDrawMode + +Returns the drawmode. Currently supported are 'stacked' and 'sideBySide'. +Defaults to 'sideBySide'. + +=cut + sub getDrawMode { my $self = shift; @@ -223,6 +297,13 @@ sub getDrawMode { } #------------------------------------------------------------------- +=head1 getPixelsPerUnit + +Returns the number of pixels that correspond with one unit of the dataset +values. + +=cut + sub getPixelsPerUnit { my $self = shift; @@ -230,6 +311,12 @@ sub getPixelsPerUnit { } #------------------------------------------------------------------- +=head1 getRulerColor + +Returns the color triplet of the rulers in the graph. Defaults to '#777777'. + +=cut + sub getRulerColor { my $self = shift; @@ -237,13 +324,27 @@ sub getRulerColor { } #------------------------------------------------------------------- +=head1 getYGranularity + +Returns the granularity of the labels and rulers in the Y direction. Defaults to +10. This is value is in terms of the values in the dataset and has no direct +relation to pixels. + +=cut + sub getYGranularity { my $self = shift; - return $self->{_properties}->{yGranularity} || 50; + return $self->{_properties}->{yGranularity} || 10; } #------------------------------------------------------------------- +=head1 getYLabels + +Returns an arrayref containing the labels for the Y axis. + +=cut + sub getYLabels { my $self = shift; @@ -256,6 +357,13 @@ sub getYLabels { } #------------------------------------------------------------------- +=head1 getYRange + +Returns the maxmimal value of the range that contains a whole number of times +the y granularity and is bigger than the maximum value in the dataset. + +=cut + sub getYRange { my $self = shift; @@ -263,6 +371,17 @@ sub getYRange { } #------------------------------------------------------------------- +=head1 setAxisColor ( color ) + +Sets the color of the axis to the supplied value. + +=head2 color + +The triplet of the color you want to set the axis to. Must have the following +form: #ffffff. + +=cut + sub setAxisColor { my $self = shift; my $color = shift; @@ -271,6 +390,16 @@ sub setAxisColor { } #------------------------------------------------------------------- +=head1 setChartHeight ( height ) + +Sets the height of the chart to the specified value. + +=head2 height + +The desired height in pixels. + +=cut + sub setChartHeight { my $self = shift; my $height = shift; @@ -279,6 +408,17 @@ sub setChartHeight { } #------------------------------------------------------------------- +=head1 setChartOffset ( location ) + +Sets the location of the top-left corner of the graph within the image. + +=head2 location + +A hashref containing the desired location. Use the 'x' and 'y' as keys for the x +and y coordinate respectively. + +=cut + sub setChartOffset { my $self = shift; my $point = shift; @@ -287,6 +427,16 @@ sub setChartOffset { } #------------------------------------------------------------------- +=head1 setChartHeight ( width ) + +Sets the width of the chart to the specified value. + +=head2 width + +The desired width in pixels. + +=cut + sub setChartWidth { my $self = shift; my $width = shift; @@ -295,6 +445,17 @@ sub setChartWidth { } #------------------------------------------------------------------- +=head1 setConfiguration ( config ) + +Applies the settings in the given configuration hash. See WebGUI::Image::Graph +for more information. + +=head2 config + +A configuration hash. + +=cut + sub setConfiguration { my $self = shift; my $config = shift; @@ -315,6 +476,18 @@ sub setConfiguration { } #------------------------------------------------------------------- +=head1 setDrawMode ( mode ) + +Set the way the datasets are drawn. Currently supported are 'stacked' and +'sideBySide' which correspond to respectivly cumulative drawing and normal +processing. + +=head2 mode + +The desired mode. Can be 'sideBySide' or 'stacked'. + +=cut + sub setDrawMode { my $self = shift; my $mode = shift; @@ -327,6 +500,17 @@ sub setDrawMode { } #------------------------------------------------------------------- +=head1 setRulerColor ( color ) + +Set the color of the rulers. + +=head2 color + +The triplet of the desired ruler color. Must be in the following format: +'#ffffff'. + +=cut + sub setRulerColor { my $self = shift; my $color = shift; @@ -335,6 +519,16 @@ sub setRulerColor { } #------------------------------------------------------------------- +=head1 setShowAxis ( boolean ) + +Set whether or not to draw the axis. + +=head2 boolean + +If set to false the axis won't be drawn. + +=cut + sub setShowAxis { my $self = shift; my $yesNo = shift; @@ -343,6 +537,16 @@ sub setShowAxis { } #------------------------------------------------------------------- +=head1 setShowLabels ( boolean ) + +Set whether or not to draw the labels. + +=head2 boolean + +If set to false the labels won't be drawn. + +=cut + sub setShowLabels { my $self = shift; my $yesNo = shift; @@ -351,6 +555,16 @@ sub setShowLabels { } #------------------------------------------------------------------- +=head1 setShowRulers ( boolean ) + +Set whether or not to draw the rulers. + +=head2 boolean + +If set to false the rulers won't be drawn. + +=cut + sub setShowRulers { my $self = shift; my $yesNo = shift; @@ -359,6 +573,16 @@ sub setShowRulers { } #------------------------------------------------------------------- +=head1 setYGranularity ( value ) + +Sets the y granularity. See getYGranularity for explanation of this concept. + +=head2 value + +The granularity in dataset units, not pixels. + +=cut + sub setYGranularity { my $self = shift; my $granularity = shift; @@ -367,6 +591,12 @@ sub setYGranularity { } #------------------------------------------------------------------- +=head1 showAxis + +Returns a boolean indicating whether to draw the axis. + +=cut + sub showAxis { my $self = shift; @@ -375,6 +605,12 @@ sub showAxis { } #------------------------------------------------------------------- +=head1 showLabels + +Returns a boolean indicating whether to draw the labels. + +=cut + sub showLabels { my $self = shift; @@ -383,6 +619,12 @@ sub showLabels { } #------------------------------------------------------------------- +=head1 showRulers + +Returns a boolean indicating whether to draw the rulers. + +=cut + sub showRulers { my $self = shift; diff --git a/lib/WebGUI/Image/Graph/XYGraph/Bar.pm b/lib/WebGUI/Image/Graph/XYGraph/Bar.pm index 8f00cd0e9..7f2c62886 100644 --- a/lib/WebGUI/Image/Graph/XYGraph/Bar.pm +++ b/lib/WebGUI/Image/Graph/XYGraph/Bar.pm @@ -9,6 +9,13 @@ use Data::Dumper; our @ISA = qw(WebGUI::Image::Graph::XYGraph); #------------------------------------------------------------------- +=head1 configurationForm + +Creates the configuration form for this plugin. See WebGUI::Image::Graph for +more information. + +=cut + sub configurationForm { my $self = shift; @@ -34,6 +41,26 @@ my $f = WebGUI::HTMLForm->new($self->session); } #------------------------------------------------------------------- +=head1 drawBar ( bar, location, barWidth ) + +Draws a bar defined by bar and with width barWidth at location. + +=head2 bar + +A hashref defining the bar. Must contain keys 'height', 'strokeColor' and +'fillColor'. + +=head2 location + +A hashref containing the location of the bottom-left corner of the bar. Keys 'x' +and 'y' must specify the x- and y-coordinates respectively. + +=head2 barWidth + +The width of the bar in pixels. + +=cut + sub drawBar { my $self = shift; my $bar = shift; @@ -55,6 +82,12 @@ sub drawBar { } #------------------------------------------------------------------- +=head1 drawGraph + +Draws all the bars. + +=cut + sub drawGraph { my ($currentBar, %location); my $self = shift; @@ -82,6 +115,26 @@ sub drawGraph { } #------------------------------------------------------------------- +=head1 drawSideBySide ( bars, location, barWidth ) + +Draws the bars in side by side mode. Meaning that per datsetindex the bars +representing a single dataset are grouped. + +=head2 bars + +An arrayref containing all the bar description hashrefs as described in drawBar. + +=head2 location + +Hashref containing the initial coordinates of the lower-left corner of the +chart. Pass coords in keys 'x' and 'y'. + +=head2 barWidth + +The width of each bar in pixels. + +=cut + sub drawSideBySideBar { my $self = shift; my $bars = shift; @@ -97,6 +150,28 @@ sub drawSideBySideBar { } #------------------------------------------------------------------- +=head1 drawStacked ( bars, location, barWidth ) + +Draws the bars in side by side mode. Meaning that per datset-index the bars +representing a single dataset are stacked on top of each other. + +=head2 bars + +An arrayref containing all the bar description hashrefs as described in drawBar. + +=head2 location + +Hashref containing the initial coordinates of the lower-left corner of the +chart. Pass coords in keys 'x' and 'y'. + +=head2 barWidth + +The width of each bar in pixels. + +=cut + + + sub drawStackedBar { my $self = shift; my $bars = shift; @@ -112,6 +187,13 @@ sub drawStackedBar { } #------------------------------------------------------------------- +=head1 formNamespace + +Returns the form namespace of this plugin. See WegBUI::Image::Graph for +more elaborate information. + +=cut + sub formNamespace { my $self = shift; @@ -119,6 +201,13 @@ sub formNamespace { } #------------------------------------------------------------------- +=head1 getAnchorSpacing + +Returns the distance in pixels between two anchors on the x axis that define teh +placement of bars and labels. + +=cut + sub getAnchorSpacing { my $self = shift; @@ -133,6 +222,12 @@ sub getAnchorSpacing { } #------------------------------------------------------------------- +=head1 getBarSpacing + +Returns the width of the gap between two bars within a group in pixels. + +=cut + sub getBarSpacing { my $self = shift; @@ -140,6 +235,13 @@ sub getBarSpacing { } #------------------------------------------------------------------- +=head1 getConfiguration + +Returns the configuration hashref for this plugin. Refer to WebGUI::IMage::Graph +for a more detailed description. + +=cut + sub getConfiguration { my $self = shift; @@ -152,6 +254,12 @@ sub getConfiguration { } #------------------------------------------------------------------- +=head1 getGroupSpacing + +Returns the width of the gap between two groups of bars in pixels. + +=cut + sub getGroupSpacing { my $self = shift; @@ -159,6 +267,13 @@ sub getGroupSpacing { } #------------------------------------------------------------------- +=head1 getFirstAnchorLocation + +Returns a hashref containing the location of the leftmost x-axis anchor. +Location coordinates are encoded in keys 'x' and 'y'. + +=cut + sub getFirstAnchorLocation { my $self = shift; @@ -169,6 +284,12 @@ sub getFirstAnchorLocation { } #------------------------------------------------------------------- +=head1 processDataset + +Processes the dataset. Used by drawGraph. + +=cut + sub processDataSet { my ($barProperties); my $self = shift; @@ -192,6 +313,16 @@ sub processDataSet { } #------------------------------------------------------------------- +=head1 setBarSpacing ( gap ) + +Sets the distance between two bars in a group in pixels. + +=head2 gap + +The distance in pixels. + +=cut + sub setBarSpacing { my $self = shift; my $gap = shift; @@ -200,6 +331,17 @@ sub setBarSpacing { } #------------------------------------------------------------------- +=head1 setConfiguration ( config ) + +Applies the given configuration hash to this plugin. See WebGUI::Image::Graph +for more info. + +=head2 config + +The configuration hash. + +=cut + sub setConfiguration { my $self = shift; my $config = shift; @@ -213,6 +355,16 @@ sub setConfiguration { } #------------------------------------------------------------------- +=head1 setGroupSpacing ( gap ) + +Sets the distance between two groups of bars in pixels. + +=head2 gap + +The distance in pixels. + +=cut + sub setGroupSpacing { my $self = shift; my $gap = shift; diff --git a/lib/WebGUI/Image/Graph/XYGraph/Line.pm b/lib/WebGUI/Image/Graph/XYGraph/Line.pm index e470c7777..d288a8ee1 100644 --- a/lib/WebGUI/Image/Graph/XYGraph/Line.pm +++ b/lib/WebGUI/Image/Graph/XYGraph/Line.pm @@ -9,6 +9,12 @@ use Data::Dumper; our @ISA = qw(WebGUI::Image::Graph::XYGraph); #------------------------------------------------------------------- +=head1 drawGraph + +Draws all the lines. + +=cut + sub drawGraph { my ($currentBar, %location); my $self = shift; @@ -27,6 +33,28 @@ sub drawGraph { } #------------------------------------------------------------------- +=head1 drawLine ( line, location, interval ) + +Draws a bar defined by bar and with width barWidth at location. + +=head2 line + +A hashref defining the line. Must contain keys 'strokeColor' and +'dataset', the latter one being an arrayref containing all points of the line. + +=head2 location + +A hashref containing the location of the bottom-left corner of the line's +origin. Keys 'x' and 'y' must specify the x- and y-coordinates respectively. + +=head2 interval + +The distance between x-axis anchors in pixels. + +=cut + + + sub drawLine { my $self = shift; my $line = shift; @@ -54,6 +82,13 @@ sub drawLine { } #------------------------------------------------------------------- +=head1 formNamespace + +Returns the form namespace of this plugin. See WegBUI::Image::Graph for +more elaborate information. + +=cut + sub formNamespace { my $self = shift; @@ -61,6 +96,13 @@ sub formNamespace { } #------------------------------------------------------------------- +=head1 getAnchorSpacing + +Returns the distance in pixels between two anchors on the x axis that define teh +placement of bars and labels. + +=cut + sub getAnchorSpacing { my $self = shift; @@ -75,6 +117,13 @@ sub getAnchorSpacing { } #------------------------------------------------------------------- +=head1 getFirstAnchorLocation + +Returns a hashref containing the location of the leftmost x-axis anchor. +Location coordinates are encoded in keys 'x' and 'y'. + +=cut + sub getFirstAnchorLocation { my $self = shift; @@ -84,15 +133,17 @@ sub getFirstAnchorLocation { } } -# palette nog laten werken! #------------------------------------------------------------------- +=head1 processDataset + +Processes the dataset. Used by drawGraph. + +=cut + sub processDataSet { my ($barProperties); my $self = shift; -# my $maxElements = List::Util::max(map {scalar @$_} @{$self->{_datasets}}); -# my $numberOfDatasets = scalar @{$self->{_datasets}}; - my $palette = $self->getPalette; foreach (@{$self->{_datasets}}) { push (@{$self->{_lines}}, {