From 2ecedbb7650f5ae126a040fd31cafbe9114345e6 Mon Sep 17 00:00:00 2001 From: Martin Kamerbeek Date: Tue, 9 May 2006 15:05:06 +0000 Subject: [PATCH] Added more and more pod, and fixed some pod bugs. --- lib/WebGUI/Image.pm | 78 ++-- lib/WebGUI/Image/Color.pm | 33 ++ lib/WebGUI/Image/Graph.pm | 122 ++++--- lib/WebGUI/Image/Graph/Pie.pm | 486 +++++++++++++++++++++++++ lib/WebGUI/Image/Graph/XYGraph.pm | 105 +++--- lib/WebGUI/Image/Graph/XYGraph/Bar.pm | 83 +++-- lib/WebGUI/Image/Graph/XYGraph/Line.pm | 39 +- lib/WebGUI/Image/Palette.pm | 89 +++-- 8 files changed, 847 insertions(+), 188 deletions(-) diff --git a/lib/WebGUI/Image.pm b/lib/WebGUI/Image.pm index 70caf9db7..3e37d6d39 100644 --- a/lib/WebGUI/Image.pm +++ b/lib/WebGUI/Image.pm @@ -4,8 +4,28 @@ use strict; use Image::Magick; use WebGUI::Image::Palette; +=head1 NAME + +Package WebGUI::Image + +=head1 DESCRIPTION + +Base class for image manipulations. + +=head1 SYNOPSIS + +This package purpous for now is to serve the basic needs of the graphing engine +built on top of this class. However, in the future this can be extended to allow +for all kinds of image manipulations within the WebGUI framework. + +=head1 METHODS + +These methods are available from this class: + +=cut + #------------------------------------------------------------------- -=head1 getBackgroundColor +=head2 getBackgroundColor Returns the background color triplet. Defaults to #ffffff (white). @@ -18,7 +38,7 @@ sub getBackgroundColor { } #------------------------------------------------------------------- -=head1 getImageHeight +=head2 getImageHeight Returns the height of the image in pixels. @@ -31,7 +51,7 @@ sub getImageHeight { } #------------------------------------------------------------------- -=head1 getImageWidth +=head2 getImageWidth Returns the width in pixels of the image. @@ -44,7 +64,7 @@ sub getImageWidth { } #------------------------------------------------------------------- -=head1 getPalette +=head2 getPalette Returns the palette object this image is set to. Defaults to the default palette. @@ -61,7 +81,7 @@ sub getPalette { } #------------------------------------------------------------------- -=head1 getXOffset +=head2 getXOffset Returns the horizontal offset of the center, relative to which the image is drawn. Defaults to the physical center of the image. @@ -75,7 +95,7 @@ sub getXOffset { } #------------------------------------------------------------------- -=head1 getYOffset +=head2 getYOffset Returns the vertical offset of the center, relative to which the image is drawn. Defaults to the physical center of the image. @@ -89,7 +109,7 @@ sub getYOffset { } #------------------------------------------------------------------- -=head1 image +=head2 image Returns the imagemagick object containing this image. @@ -102,19 +122,19 @@ sub image { } #------------------------------------------------------------------- -=head1 new ( session, [ width, height ] ) +=head2 new ( session, [ width, height ] ) Constructor for an image. Optionally you can pass the size of the image. -=head2 session +=head3 session The webgui session object. -=head2 width +=head3 width The width of the image in pixels. Defaults to 300. -=head2 height +=head3 height The height of the image in pixels. Defaults to 300. @@ -138,7 +158,7 @@ sub new { } #------------------------------------------------------------------- -=head1 session +=head2 session Returns the the session object. @@ -151,12 +171,12 @@ sub session { } #------------------------------------------------------------------- -=head1 setBackgroundColor ( colorTriplet ) +=head2 setBackgroundColor ( colorTriplet ) Sets the backgroundcolor. Using this method will erase everything that is already on the image. -=head2 colorTriplet +=head3 colorTriplet The color for the background. Supply as a html color triplet of the form #ffffff. @@ -172,11 +192,11 @@ sub setBackgroundColor { } #------------------------------------------------------------------- -=head1 setImageHeight ( height) +=head2 setImageHeight ( height) Set the height of the image. -=head2 height +=head3 height The height of the image in pixels. @@ -193,11 +213,11 @@ sub setImageHeight { } #------------------------------------------------------------------- -=head1 setImageWidth ( width ) +=head2 setImageWidth ( width ) Set the width of the image. -=head2 width +=head3 width Teh width of the image in pixels. @@ -214,11 +234,11 @@ sub setImageWidth { } #------------------------------------------------------------------- -=head1 setPalette ( palette ) +=head2 setPalette ( palette ) Set the palette object this image will use. -=head2 palette +=head3 palette An instanciated WebGUI::Image::Palette object. @@ -232,15 +252,15 @@ sub setPalette { } #------------------------------------------------------------------- -=head1 saveToFileSystem ( path, [ filename ] ); +=head2 saveToFileSystem ( path, [ filename ] ); Saves the image to the specified path and filename. -=head2 path +=head3 path The directory where the image should be saved. -=head2 filename +=head3 filename The filename the image should get. If not passed it will default to the name set by the setFilename method. @@ -257,7 +277,7 @@ sub saveToFileSystem { # This doesn't seem to work... #------------------------------------------------------------------- -=head1 saveToScalar +=head2 saveToScalar Returns a scalar containing the image contents. @@ -277,15 +297,15 @@ sub saveToScalar { } #------------------------------------------------------------------- -=head1 saveToStorageLocation ( storage, [ filename ] ) +=head2 saveToStorageLocation ( storage, [ filename ] ) Save the image to the specified storage location. -=head2 storage +=head3 storage An instanciated WebGUI::Storage::Image object. -=head2 filename +=head3 filename The filename the image should get. If not passed it will default to the name set by the setFilename method. @@ -301,11 +321,11 @@ sub saveToStorageLocation { } #------------------------------------------------------------------- -=head1 text ( properties ) +=head2 text ( properties ) Extend the imagemagick Annotate method so alignment can be controlled better. -=head2 properties +=head3 properties A hash containing the imagemagick Annotate properties of your choice. Additionally you can specify: diff --git a/lib/WebGUI/Image/Color.pm b/lib/WebGUI/Image/Color.pm index c50d846d7..a1e722236 100644 --- a/lib/WebGUI/Image/Color.pm +++ b/lib/WebGUI/Image/Color.pm @@ -3,6 +3,39 @@ package WebGUI::Image::Color; use strict; use Color::Calc; +=head1 NAME + +Package WebGUI::Image::Color + +=head1 DESCRIPTION + +Package for managing WebGUI colors. + +=head1 SYNOPSIS + +Colors actually consist of two colors: fill color and stroke color. Stroke color +is the color for lines and the border of areas, while the fill color is the +color that is used to fill that area. Fill color thus have no effect on lines. + +Each fill and stroke color consists of a Red, Green, Blue and Alpha component. +These values are given in hexadecimal notation. A concatenation of the Red, +Greean and Blue values, prepended with a '#' sign is called a triplet. A similar +combination that also includes the Alpha values at the end is called a quarted. + +Alpha value are used to define the transparency of the color. The higher the +value the more transparent the color is. If the alpha value = 00 the color is +opaque, where the color is completely invisible for an alpha value of ff. + +Colors are not saved to the database by default. If you want to do this you must +do so manually using the save and/or update methods. + +=head1 METHODS + +These methods are available from this class: + +=cut + + #------------------------------------------------------------------- =head1 canDelete diff --git a/lib/WebGUI/Image/Graph.pm b/lib/WebGUI/Image/Graph.pm index 84fcec707..91900db85 100644 --- a/lib/WebGUI/Image/Graph.pm +++ b/lib/WebGUI/Image/Graph.pm @@ -8,18 +8,42 @@ use List::Util; our @ISA = qw(WebGUI::Image); -=head1 addDataset ( dataset ) +=head1 NAME + +Package WebGUI::Image::Graph + +=head1 DESCRIPTION + +Base class for graphs. + +=head1 SYNOPSIS + +This package provides the basic needs for creating graphs. + +Among others this package provides the base methods for configuration forms, +dataset addition, loading plugins, and setting general parameters like +backgraound color. + +=cut + +=head1 METHODS + +These methods are available from this class: + +=cut + +#------------------------------------------------------------------- +=head2 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 +=head3 dataset An arrayref containg the values of the data. The dat must be numeric. =cut -#------------------------------------------------------------------- sub addDataset { my $self = shift; my $dataset = shift; @@ -27,7 +51,8 @@ sub addDataset { push(@{$self->{_datasets}}, $dataset); } -=head1 configurationForm +#------------------------------------------------------------------- +=head2 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 @@ -41,7 +66,6 @@ Check some of the plugins that come with WebGUI for examples. =cut -#------------------------------------------------------------------- sub configurationForm { my $self = shift; @@ -96,16 +120,16 @@ sub configurationForm { } #------------------------------------------------------------------- -=head1 drawLabel ( label, [ properties ] ) +=head2 drawLabel ( label, [ properties ] ) Draws a label with your preferred properties. Defaults the font, font size and color which you can override. -=head2 label +=head3 label The text of the label you want to print. -=head2 properties +=head3 properties A hash containing imagemagick Annotate properties. @@ -127,7 +151,7 @@ sub drawLabel { } #------------------------------------------------------------------- -=head1 formNamespace +=head2 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 @@ -142,7 +166,7 @@ sub formNamespace { } #------------------------------------------------------------------- -=head1 getConfiguration +=head2 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 @@ -172,17 +196,17 @@ sub getConfiguration { } #------------------------------------------------------------------- -=head1 getGraphingTab ( session, [ config ] ) +=head2 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 +=head3 session An instanciated WebGUI session object. -=head2 config +=head3 config Optionally you can pass a configuration hash to populate the form @@ -292,11 +316,11 @@ EOS } #------------------------------------------------------------------- -=head1 getDataset ( [ index ] ) +=head2 getDataset ( [ index ] ) Returns the dataset indicated by index. -=head2 index +=head3 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 @@ -316,11 +340,11 @@ sub getDataset { } #------------------------------------------------------------------- -=head1 getLabel ( [ index ] ) +=head2 getLabel ( [ index ] ) Returns the index'th label or an arrayref containing all labels. -=head2 index +=head3 index The index of label to return. Numbering starts at 0. If omitted an arrayref containing all labels is returned. @@ -336,7 +360,7 @@ sub getLabel { } #------------------------------------------------------------------- -=head1 getLabelColor +=head2 getLabelColor Returns the triplet of the label color. Defaults to '#333333'. @@ -349,16 +373,16 @@ sub getLabelColor { } #------------------------------------------------------------------- -=head1 getLabelDimensions ( text, [ properties ] ) +=head2 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 +=head3 text The text you want to know the dimensions of. -=head2 properties +=head3 properties Optionally you can pass a hashref containing imagemagick's Annotate properties. @@ -383,7 +407,7 @@ sub getLabelDimensions { } #------------------------------------------------------------------- -=head1 getLabelFont +=head2 getLabelFont Returns the WebGUI::Image::Font object this image is set to. Defaults to the default font. @@ -397,7 +421,7 @@ sub getLabelFont { } #------------------------------------------------------------------- -=head1 getLabelFontSize +=head2 getLabelFontSize Returns the font size of the labels. Defaults to 20. @@ -410,7 +434,7 @@ sub getLabelFontSize { } #------------------------------------------------------------------- -=head1 getLabelOffset +=head2 getLabelOffset Returns the label offset. This is the distance between the label and the axis. Defaults to 10 pixels. @@ -424,7 +448,7 @@ sub getLabelOffset { } #------------------------------------------------------------------- -=head1 getMaxValueFromDataset +=head2 getMaxValueFromDataset Returns the highest value of all added datasets. @@ -456,15 +480,15 @@ sub getMaxValueFromDataset { } #------------------------------------------------------------------- -=head1 load ( session, namespace ) +=head2 load ( session, namespace ) Instanciates an WebGUI::Graph object with the given namespace. -=head2 session +=head3 session A WebGUI::Session object. -=head2 namespace +=head3 namespace The full namespace of the plugin you want to load. @@ -484,15 +508,15 @@ sub load { } #------------------------------------------------------------------- -=head1 loadByConfiguration ( session, configuration ) +=head2 loadByConfiguration ( session, configuration ) Loads a plugin defined by a configuration hash. -=head2 session +=head3 session A WebGUI::Session object. -=head2 configuration +=head3 configuration A configuration hashref. @@ -515,12 +539,12 @@ sub loadByConfiguration { } #------------------------------------------------------------------- -=head1 processConfigurationForm ( session ) +=head2 processConfigurationForm ( session ) Processes the configuration form that is submitted and returns the correct instanciated graphing plugin. -=head2 session +=head3 session The WebGUI session object. @@ -541,13 +565,13 @@ my $graph = $self->load($session, $namespace); } #------------------------------------------------------------------- -=head1 setConfiguration ( config ) +=head2 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 +=head3 config The configuration hashref. @@ -569,11 +593,11 @@ sub setConfiguration { }; #------------------------------------------------------------------- -=head1 setLabelColor ( color ) +=head2 setLabelColor ( color ) Sets the color triplet of the labels. -=head2 color +=head3 color The triplet defining the color. The triplet should be in the form of '#ffffff'. @@ -587,11 +611,11 @@ sub setLabelColor { } #------------------------------------------------------------------- -=head1 setLabelFont ( font ) +=head2 setLabelFont ( font ) Set the label font. -=head2 font +=head3 font A WebGUI::Image::Font object. @@ -605,11 +629,11 @@ sub setLabelFont { } #------------------------------------------------------------------- -=head1 setLabelFontSize ( size ) +=head2 setLabelFontSize ( size ) Sets the font size of the labels. -=head2 size +=head3 size The desired font size. @@ -623,12 +647,12 @@ sub setLabelFontSize { } #------------------------------------------------------------------- -=head1 setLabelOffset ( offset ) +=head2 setLabelOffset ( offset ) Sets the label offset. This is the distance in pixels between the labels and the axis. -=head2 offset +=head3 offset The label offset. @@ -642,11 +666,11 @@ sub setLabelOffset { } #------------------------------------------------------------------- -=head1 setLabels ( labels ) +=head2 setLabels ( labels ) Sets the labels for the datasets. -=head2 labels +=head3 labels An arrayref containig the labels. @@ -660,19 +684,19 @@ sub setLabels { } #------------------------------------------------------------------- -=head1 wrapLabelToWidth ( text, maxWidth, [ properties ] ) +=head2 wrapLabelToWidth ( text, maxWidth, [ properties ] ) Wraps a text string onto multiple lines having a width of maxWidth. -=head2 text +=head3 text The text you want to wrap. -=head2 maxWidth +=head3 maxWidth The width the string should have after wrapping/ -=head2 properties +=head3 properties An optional hashref containing imagemagick's Annotate properties. diff --git a/lib/WebGUI/Image/Graph/Pie.pm b/lib/WebGUI/Image/Graph/Pie.pm index 95f3ae881..67125bd58 100644 --- a/lib/WebGUI/Image/Graph/Pie.pm +++ b/lib/WebGUI/Image/Graph/Pie.pm @@ -6,7 +6,43 @@ use constant pi => 3.14159265358979; our @ISA = qw(WebGUI::Image::Graph); +=head1 NAME + +Package WebGUI::Image::Graph::Pie + +=head1 DESCRIPTION + +Package to create pie charts, both 2d and 3d. + +=head1 SYNOPSIS + +Pie charts have a top height, bottom height which are the amounts of pixels the +top and bottom rise above and below the z = 0 plane respectively. These +properties can be used to create stepping effect. + +Also xeplosion and scaling of individual pie slices is possible. Labels can be +connected via sticks and aligned to top, bottom and center of the pie. + +The package automatically desides whether to draw in 2d or 3d mode based on the +angle by which the pie is tilted. + +=head1 METHODS + +These methods are available from this class: + +=cut + #------------------------------------------------------------------- +=head2 _mod2pi ( angle ) + +Returns the angle modulo 2*pi. + +=head3 angle + +The angle you want the modulo of. + +=cut + sub _mod2pi { my $angle = shift; @@ -222,6 +258,17 @@ sub addSlice { } #------------------------------------------------------------------- +=head2 calcCoordinates ( slice ) + +Calcs the coordinates of the corners of the given pie slice. + +=head3 slice + +Hashref containing the information that defines the slice. Must be formatted +like the slices built by addSlice. + +=cut + sub calcCoordinates { my ($pieHeight, $pieWidth, $offsetX, $offsetY, $coords); my $self = shift; @@ -249,6 +296,13 @@ sub calcCoordinates { } #------------------------------------------------------------------- +=head2 configurationForm + +The configuration form part for this object. See WebGUI::Image::Graph for +documentation. + +=cut + sub configurationForm { my $self = shift; @@ -324,6 +378,12 @@ my $configForms = $self->SUPER::configurationForm; } #------------------------------------------------------------------- +=head2 draw + +Draws the pie chart. + +=cut + sub draw { my ($currentSlice, $coordinates, $sliceData, $leftPlaneVisible, $rightPlaneVisible); my $self = shift; @@ -383,6 +443,16 @@ sub draw { } #------------------------------------------------------------------- +=head2 drawBottom ( slice ) + +Draws the bottom of the given pie slice. + +=head3 slice + +A slice hashref. See addSlice for more information. + +=cut + sub drawBottom { my $self = shift; my $slice = shift; @@ -391,6 +461,16 @@ sub drawBottom { } #------------------------------------------------------------------- +=head2 drawLabel ( slice ) + +Draws the label including stick if needed for the given pie slice. + +=head3 slice + +A slice properties hashref. + +=cut + sub drawLabel { my ($startRadius, $stopRadius, $pieHeight, $pieWidth, $startPointX, $startPointY, $endPointX, $endPointY); @@ -474,6 +554,16 @@ sub drawLabel { } #------------------------------------------------------------------- +=head2 drawLeftSide ( slice ) + +Draws the side connected to the startpoint of the slice. + +=head3 slice + +A slice properties hashref. + +=cut + sub drawLeftSide { my $self = shift; my $slice = shift; @@ -482,6 +572,25 @@ sub drawLeftSide { } #------------------------------------------------------------------- +=head2 drawPieSlice ( slice, offset, fillColor ) + +Draws a pie slice shape, ie. the bottom or top of a slice. + +=head3 slice + +A slice properties hashref. + +=head3 offset + +The offset in pixels for the y-direction. This is used to create the thickness +of the pie. + +=head3 fillColor + +The color with which the slice should be filled. + +=cut + sub drawPieSlice { my (%tip, %startCorner, %endCorner, $pieWidth, $pieHeight, $bigCircle, $strokePath); @@ -520,6 +629,16 @@ sub drawPieSlice { } #------------------------------------------------------------------- +=head2 drawRightSide ( slice ) + +Draws the side connected to the endpoint of the slice. + +=head3 slice + +A slice properties hashref. + +=cut + sub drawRightSide { my $self = shift; my $slice = shift; @@ -528,6 +647,16 @@ sub drawRightSide { } #------------------------------------------------------------------- +=head2 drawRim ( slice ) + +Draws the rim of the slice. + +=head3 slice + +A slice properties hashref. + +=cut + sub drawRim { my (%startSideTop, %startSideBottom, %endSideTop, %endSideBottom, $pieWidth, $pieHeight, $bigCircle); @@ -570,6 +699,27 @@ sub drawRim { } #------------------------------------------------------------------- +=head2 drawSide ( slice, [ cornerName ], [ fillColor ] ) + +Draws the sides connecting the rim and tip of a pie slice. + +=head3 slice + +A slice properties hashref. + +=head3 cornerName + +Specifies which side you want to draw, identified by the name of the corner that +attaches it to the rim. Can be either 'startCorner' or 'endCorner'. If ommitted +it will default to 'startCorner'. + +=head3 fillColor + +The color with which the side should be filled. If not passed the color for the +'startCorner' side will be defaulted to. + +=cut + sub drawSide { my (%tipTop, %tipBottom, %rimTop, %rimBottom); my $self = shift; @@ -608,6 +758,16 @@ sub drawSide { } #------------------------------------------------------------------- +=head2 drawBottom ( slice ) + +Draws the bottom of the given pie slice. + +=head3 slice + +A slice hashref. See addSlice for more information. + +=cut + sub drawTop { my $self = shift; my $slice = shift; @@ -616,6 +776,13 @@ sub drawTop { } #------------------------------------------------------------------- +=head2 formNamespace + +Extends the form namespace for this object. See WebGUI::Image::Graph for +documentation. + +=cut + sub formNamespace { my $self = shift; @@ -623,6 +790,12 @@ sub formNamespace { } #------------------------------------------------------------------- +=head2 getBottomHeight + +Returns the thickness of the bottom. Defaults to 0. + +=cut + sub getBottomHeight { my $self = shift; @@ -630,6 +803,12 @@ sub getBottomHeight { } #------------------------------------------------------------------- +=head2 getConfiguration + +Returns a configuration hashref. See WebGUI::Image::Graph for documentation. + +=cut + sub getConfiguration { my $self = shift; @@ -649,6 +828,13 @@ sub getConfiguration { } #------------------------------------------------------------------- +=head2 getDataset + +Returns the first dataset that is added. Pie charts can only handle one dataset +and therefore the first added dataset is used. + +=cut + sub getDataset { my $self = shift; @@ -656,6 +842,13 @@ sub getDataset { } #------------------------------------------------------------------- +=head2 getExplosionLength + +Returns the explosion length. This value indicates how much a slice will be +shifted from the center of the pie. Defaults to 0. + +=cut + sub getExplosionLength { my $self = shift; @@ -663,6 +856,12 @@ sub getExplosionLength { } #------------------------------------------------------------------- +=head2 getLabels + +Returns an arrayref containing the labels that belong to the slices. + +=cut + sub getLabels { my $self = shift; @@ -670,6 +869,13 @@ sub getLabels { } #------------------------------------------------------------------- +=head2 getLabelPosition + +Returns the position of the labels relative to the thickness of the pie. +Allowed positions are 'bottom', 'center' and 'top'. Defaults to 'top'. + +=cut + sub getLabelPosition { my $self = shift; @@ -677,6 +883,15 @@ sub getLabelPosition { } #------------------------------------------------------------------- +=head2 getPieMode + +Returns the mode in which the pie is drawn. Currently available are 'normal' and +'stepped'. The latter mode draws each pie slice with a smaller thickness, +creating a stairs like pie chart. Defaults to 'normal' which will cause the +graph to be drawn as a vanilla pie chart. + +=cut + sub getPieMode { my $self = shift; @@ -684,6 +899,12 @@ sub getPieMode { } #------------------------------------------------------------------- +=head2 getRadius + +Returns the radius of the pie in pixels. Defaults to 80. + +=cut + sub getRadius { my $self = shift; @@ -691,6 +912,16 @@ sub getRadius { } #------------------------------------------------------------------- +=head2 getScaleFactor + +Returns the factor with which the pies that are added afterwards should be +scaled. In effect this will cause the radius of the slice to grow or shrink, and +thus make slices stick out. + +Defaults to 1. + +=cut + sub getScaleFactor { my $self = shift; @@ -698,6 +929,16 @@ sub getScaleFactor { } #------------------------------------------------------------------- +=head2 getSlice ( [ sliceNumber ] ) + +Returns the sliceNumber'th slice properties hashref. Defaults to the slice last +added. + +=head3 sliceNumber + +The index of the slice you want. + +=cut sub getSlice { my $self = shift; my $slice = shift || (scalar(@{$self->{_slices}}) - 1); @@ -706,6 +947,13 @@ sub getSlice { } #------------------------------------------------------------------- +=head2 getStartAngle + +Rteurn the initial angle of the first slice. In effect all slices are rotated by +this value. + +=cut + sub getStartAngle { my $self = shift; @@ -713,6 +961,12 @@ sub getStartAngle { } #------------------------------------------------------------------- +=head2 getStickColor + +Returns the color of the sticks connecting pie and labels. Defaults to #333333. + +=cut + sub getStickColor { my $self = shift; @@ -720,6 +974,13 @@ sub getStickColor { } #------------------------------------------------------------------- +=head2 getStickLength + +Return the length of the sticks connecting the labels with the pie. Defaults to +0. + +=cut + sub getStickLength { my $self = shift; @@ -727,6 +988,12 @@ sub getStickLength { } #------------------------------------------------------------------- +=head2 getStickOffset + +Returns the distance between the label sticks and the pie. Defaults to 0. + +=cut + sub getStickOffset { my $self = shift; @@ -734,6 +1001,14 @@ sub getStickOffset { } #------------------------------------------------------------------- +=head2 getTiltAngle + +Returns the angle between the screen and the pie chart. Valid angles are 0 to 90 +degrees. Zero degrees results in a 2d pie where other values will generate a 3d +pie chart. Defaults to 55 degrees. + +=cut + sub getTiltAngle { my $self = shift; my $angle = shift; @@ -742,6 +1017,12 @@ sub getTiltAngle { } #------------------------------------------------------------------- +=head2 getTopHeight + +Returns the thickness of the top of the pie in pixels. Defaults to 20 pixels. + +=cut + sub getTopHeight { my $self = shift; @@ -749,6 +1030,13 @@ sub getTopHeight { } #------------------------------------------------------------------- +=head2 hasShadedSides + +A boolean value indicating whether the sides and the rim of the pie should be +drawn with a darkened color. + +=cut + sub hasShadedSides { my $self = shift; @@ -756,6 +1044,12 @@ sub hasShadedSides { } #------------------------------------------------------------------- +=head2 new + +Contstructor. See SUPER classes for additional parameters. + +=cut + sub new { my $class = shift; @@ -766,6 +1060,12 @@ sub new { } #------------------------------------------------------------------- +=head2 processDataset + +Takes the dataset and takes the necesarry steps for the pie to be drawn. + +=cut + sub processDataset { my $self = shift; my $total = 0; @@ -792,6 +1092,16 @@ sub processDataset { } #------------------------------------------------------------------- +=head2 setBottomHeight ( thickness ) + +Sets the thickness of the bottom. + +=head3 thickness + +The thickness of the bottom. + +=cut + sub setBottomHeight { my $self = shift; my $height = shift; @@ -800,6 +1110,20 @@ sub setBottomHeight { } #------------------------------------------------------------------- +=head2 setCenter( [ xOffset ], [ yOffset ] ) + +Sets the offset of the center of the graph relative to the center of the image. + +=head3 xOffset + +The offset in the x direction. Defaults to 0. + +=head3 yOffset + +The offset in the y direction. Defaults to 0. + +=cut + sub setCenter { my $self = shift; my $xCenter = shift || 0; @@ -810,6 +1134,17 @@ sub setCenter { } #------------------------------------------------------------------- +=head2 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; @@ -831,6 +1166,17 @@ sub setConfiguration { } #------------------------------------------------------------------- +=head2 setExplosionLength ( length ) + +Sets the explosion length. This value indicates how much a slice will be +shifted from the center of the pie. Defaults to 0. + +=head3 length + +The amount by which the slices should be exploded. + +=cut + sub setExplosionLength { my $self = shift; my $offset = shift; @@ -839,6 +1185,17 @@ sub setExplosionLength { } #------------------------------------------------------------------- +=head2 setLabelPosition ( position ) + +Sets the position of the labels relative to the thickness of the pie. +Allowed positions are 'bottom', 'center' and 'top'. Defaults to 'top'. + +=head3 position + +The position of the labels. + +=cut + sub setLabelPosition { my $self = shift; my $position = shift; @@ -847,6 +1204,19 @@ sub setLabelPosition { } #------------------------------------------------------------------- +=head2 setPieMode ( mode ) + +Sets the mode in which the pie is drawn. Currently available are 'normal' and +'stepped'. The latter mode draws each pie slice with a smaller thickness, +creating a stairs like pie chart. Defaults to 'normal' which will cause the +graph to be drawn as a vanilla pie chart. + +=head3 mode + +The mode. Either 'normal' or 'stepped'. + +=cut + sub setPieMode { my $self = shift; my $mode = shift; @@ -855,6 +1225,16 @@ sub setPieMode { } #------------------------------------------------------------------- +=head2 setRadius ( radius ) + +Sets the radius of the pie in pixels. Defaults to 80. + +=head3 radius + +The desired radius. + +=cut + sub setRadius { my $self = shift; my $radius = shift; @@ -865,6 +1245,39 @@ sub setRadius { } #------------------------------------------------------------------- +=head2 setScaleFactor ( multiplier ) + +Sets the factor with which the pies that are added afterwards should be +scaled. In effect this will cause the radius of the slice to grow or shrink, and +thus make slices stick out. + +Defaults to 1. + +=head3 multiplier + +The figure with which the the normal radius if the slices should be multiplied. + +=cut + +sub getScaleFactor { + my $self = shift; + my $scaleFactor = shift; + + $self->{_pieProperties}->{scaleFactor} = $scaleFactor; +} + +#------------------------------------------------------------------- +=head2 setStartAngle ( angle ) + +Sets the initial angle of the first slice. In effect all slices are rotated by +this value. + +=head3 angle + +The desired start angle in degrees. + +=cut + sub setStartAngle { my $self = shift; my $angle = shift; @@ -873,6 +1286,17 @@ sub setStartAngle { } #------------------------------------------------------------------- +=head2 setShadedSides ( shaded ) + +A boolean value indicating whether the sides and the rim of the pie should be +drawn with a darkened color. + +=head3 shaded + +The boolean switch. Set to 0 for normal sides. Set to 1 for shaded sides. + +=cut + sub setShadedSides { my $self = shift; my $onOff = shift; @@ -881,6 +1305,16 @@ sub setShadedSides { } #------------------------------------------------------------------- +=head2 setStickColor ( color ) + +Sets the color of the sticks connecting pie and labels. Defaults to #333333. + +=head3 color + +The desired color value. + +=cut + sub setStickColor { my $self = shift; my $color = shift; @@ -889,6 +1323,17 @@ sub setStickColor { } #------------------------------------------------------------------- +=head2 setStickLength ( length ) + +Sets the length of the sticks connecting the labels with the pie. Defaults to +0. + +=head3 length + +The length in pixels. + +=cut + sub setStickLength { my $self = shift; my $length = shift; @@ -897,6 +1342,16 @@ sub setStickLength { } #------------------------------------------------------------------- +=head2 setStickOffset ( offset ) + +Sets the distance between the label sticks and the pie. Defaults to 0. + +=head3 offset + +The distance in pixels. + +=cut + sub setStickOffset { my $self = shift; my $offset = shift || 0; @@ -905,6 +1360,20 @@ sub setStickOffset { } #------------------------------------------------------------------- +=head2 setTiltAngle ( angle ) + +Sets the angle between the screen and the pie chart. Valid angles are 0 to 90 +degrees. Zero degrees results in a 2d pie where other values will generate a 3d +pie chart. Defaults to 55 degrees. + +=head3 angle + +The tilt angle. Must be in the range from 0 to 90. If a value less than zero is +passed the angle will be set to 0. If a value greater than 90 is passed the +angle will be set to 90. + +=cut + sub setTiltAngle { my $self = shift; my $angle = shift; @@ -916,6 +1385,16 @@ sub setTiltAngle { } #------------------------------------------------------------------- +=head2 setTopHeight ( thickness ) + +Sets the thickness of the top of the pie in pixels. Defaults to 20 pixels. + +=head3 thickness + +The thickness of the top in pixels. + +=cut + sub setTopHeight { my $self = shift; my $height = shift; @@ -924,6 +1403,13 @@ sub setTopHeight { } #------------------------------------------------------------------- +=head2 sortSlices + +A sort routine for sorting the slices in drawing order. Must be run from within +the sort command. + +=cut + sub sortSlices { my ($startA, $stopA, $startB, $stopB, $distA, $distB); my $self = shift; diff --git a/lib/WebGUI/Image/Graph/XYGraph.pm b/lib/WebGUI/Image/Graph/XYGraph.pm index 4b57d3e92..6fa0ce8e6 100644 --- a/lib/WebGUI/Image/Graph/XYGraph.pm +++ b/lib/WebGUI/Image/Graph/XYGraph.pm @@ -8,8 +8,31 @@ use POSIX; our @ISA = qw(WebGUI::Image::Graph); +=head1 NAME + +Package WebGUI::Image::Graph::XYGraph + +=head1 DESCRIPTION + +Base class for flat xy charts. + +=head1 SYNOPSIS + +XY charts are graphs that have a x and a y coordinate. Examples are Line and Bar +graphs. + +This package provides basics needs for such graphs like methods for drawing +axis, labels, rulers and the likes. Also it has methods to set parameters +belonging to xy charts in general such as setting chart width. + +=head1 METHODS + +These methods are available from this class: + +=cut + #------------------------------------------------------------------- -=head1 configurationForm +=head2 configurationForm The configuration form part for this object. See WebGUI::Image::Graph for documentation. @@ -82,7 +105,7 @@ sub configurationForm { } #------------------------------------------------------------------- -=head1 draw +=head2 draw Draws the graph. @@ -105,7 +128,7 @@ sub draw { } #------------------------------------------------------------------- -=head1 drawAxis +=head2 drawAxis Draws the axis. @@ -126,7 +149,7 @@ sub drawAxis { } #------------------------------------------------------------------- -=head1 drawLabels +=head2 drawLabels Draws the labels. @@ -193,7 +216,7 @@ sub drawRulers { } #------------------------------------------------------------------- -=head1 formNamespace +=head2 formNamespace Extends the form namespace for this object. See WebGUI::Image::Graph for documentation. @@ -207,7 +230,7 @@ sub formNamespace { } #------------------------------------------------------------------- -=head1 getAxisColor +=head2 getAxisColor Returns the color triplet for the axis. Defaults to '#222222'. @@ -220,7 +243,7 @@ sub getAxisColor { } #------------------------------------------------------------------- -=head1 getChartHeight +=head2 getChartHeight Returns the height of the chart. Defaults to 200. @@ -233,7 +256,7 @@ sub getChartHeight { } #------------------------------------------------------------------- -=head1 getChartOffset +=head2 getChartOffset Returns the coordinates of the top-left corner of the chart. he coordinates are contained in a hasref with keys 'x' and 'y'. @@ -247,7 +270,7 @@ sub getChartOffset { } #------------------------------------------------------------------- -=head1 getChartWidth +=head2 getChartWidth Returns the width of the chart. Defaults to 200. @@ -260,7 +283,7 @@ sub getChartWidth { } #------------------------------------------------------------------- -=head1 getConfiguration +=head2 getConfiguration Returns a configuration hashref. See WebGUI::Image::Graph for documentation. @@ -283,7 +306,7 @@ sub getConfiguration { } #------------------------------------------------------------------- -=head1 getDrawMode +=head2 getDrawMode Returns the drawmode. Currently supported are 'stacked' and 'sideBySide'. Defaults to 'sideBySide'. @@ -297,7 +320,7 @@ sub getDrawMode { } #------------------------------------------------------------------- -=head1 getPixelsPerUnit +=head2 getPixelsPerUnit Returns the number of pixels that correspond with one unit of the dataset values. @@ -311,7 +334,7 @@ sub getPixelsPerUnit { } #------------------------------------------------------------------- -=head1 getRulerColor +=head2 getRulerColor Returns the color triplet of the rulers in the graph. Defaults to '#777777'. @@ -324,7 +347,7 @@ sub getRulerColor { } #------------------------------------------------------------------- -=head1 getYGranularity +=head2 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 @@ -339,7 +362,7 @@ sub getYGranularity { } #------------------------------------------------------------------- -=head1 getYLabels +=head2 getYLabels Returns an arrayref containing the labels for the Y axis. @@ -357,7 +380,7 @@ sub getYLabels { } #------------------------------------------------------------------- -=head1 getYRange +=head2 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. @@ -371,11 +394,11 @@ sub getYRange { } #------------------------------------------------------------------- -=head1 setAxisColor ( color ) +=head2 setAxisColor ( color ) Sets the color of the axis to the supplied value. -=head2 color +=head3 color The triplet of the color you want to set the axis to. Must have the following form: #ffffff. @@ -390,11 +413,11 @@ sub setAxisColor { } #------------------------------------------------------------------- -=head1 setChartHeight ( height ) +=head2 setChartHeight ( height ) Sets the height of the chart to the specified value. -=head2 height +=head3 height The desired height in pixels. @@ -408,11 +431,11 @@ sub setChartHeight { } #------------------------------------------------------------------- -=head1 setChartOffset ( location ) +=head2 setChartOffset ( location ) Sets the location of the top-left corner of the graph within the image. -=head2 location +=head3 location A hashref containing the desired location. Use the 'x' and 'y' as keys for the x and y coordinate respectively. @@ -427,11 +450,11 @@ sub setChartOffset { } #------------------------------------------------------------------- -=head1 setChartHeight ( width ) +=head2 setChartHeight ( width ) Sets the width of the chart to the specified value. -=head2 width +=head3 width The desired width in pixels. @@ -445,12 +468,12 @@ sub setChartWidth { } #------------------------------------------------------------------- -=head1 setConfiguration ( config ) +=head2 setConfiguration ( config ) Applies the settings in the given configuration hash. See WebGUI::Image::Graph for more information. -=head2 config +=head3 config A configuration hash. @@ -476,13 +499,13 @@ sub setConfiguration { } #------------------------------------------------------------------- -=head1 setDrawMode ( mode ) +=head2 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 +=head3 mode The desired mode. Can be 'sideBySide' or 'stacked'. @@ -500,11 +523,11 @@ sub setDrawMode { } #------------------------------------------------------------------- -=head1 setRulerColor ( color ) +=head2 setRulerColor ( color ) Set the color of the rulers. -=head2 color +=head3 color The triplet of the desired ruler color. Must be in the following format: '#ffffff'. @@ -519,11 +542,11 @@ sub setRulerColor { } #------------------------------------------------------------------- -=head1 setShowAxis ( boolean ) +=head2 setShowAxis ( boolean ) Set whether or not to draw the axis. -=head2 boolean +=head3 boolean If set to false the axis won't be drawn. @@ -537,11 +560,11 @@ sub setShowAxis { } #------------------------------------------------------------------- -=head1 setShowLabels ( boolean ) +=head2 setShowLabels ( boolean ) Set whether or not to draw the labels. -=head2 boolean +=head3 boolean If set to false the labels won't be drawn. @@ -555,11 +578,11 @@ sub setShowLabels { } #------------------------------------------------------------------- -=head1 setShowRulers ( boolean ) +=head2 setShowRulers ( boolean ) Set whether or not to draw the rulers. -=head2 boolean +=head3 boolean If set to false the rulers won't be drawn. @@ -573,11 +596,11 @@ sub setShowRulers { } #------------------------------------------------------------------- -=head1 setYGranularity ( value ) +=head2 setYGranularity ( value ) Sets the y granularity. See getYGranularity for explanation of this concept. -=head2 value +=head3 value The granularity in dataset units, not pixels. @@ -591,7 +614,7 @@ sub setYGranularity { } #------------------------------------------------------------------- -=head1 showAxis +=head2 showAxis Returns a boolean indicating whether to draw the axis. @@ -605,7 +628,7 @@ sub showAxis { } #------------------------------------------------------------------- -=head1 showLabels +=head2 showLabels Returns a boolean indicating whether to draw the labels. @@ -619,7 +642,7 @@ sub showLabels { } #------------------------------------------------------------------- -=head1 showRulers +=head2 showRulers Returns a boolean indicating whether to draw the rulers. diff --git a/lib/WebGUI/Image/Graph/XYGraph/Bar.pm b/lib/WebGUI/Image/Graph/XYGraph/Bar.pm index a6625db25..62a398593 100644 --- a/lib/WebGUI/Image/Graph/XYGraph/Bar.pm +++ b/lib/WebGUI/Image/Graph/XYGraph/Bar.pm @@ -7,8 +7,37 @@ use POSIX; our @ISA = qw(WebGUI::Image::Graph::XYGraph); +=head1 NAME + +Package WebGUI::Image::Graph::XYGraph::Bar + +=head1 DESCRIPTION + +Package for creating bar graphs. + +=head1 SYNOPSIS + +This package privides the logic for drawing 2d bar graphs, 3d bars are in the +pipeline but not yet ready for prime time. + +This module can draw bar graph in two forms: Stacked and Side by Side. The +diffrence is noticable only if more multiple dataset is used, the behaviour is +thus identical in case of one dataset. + +Stacked graphs place the bars belonging the same index within diffrent datasets +on top of each other given a grand total for all datasets. + +Sid by side graphs place bars with the same index next to each other, grouped by +index. This displays a better comaprison between datasets. + +=head1 METHODS + +These methods are available from this class: + +=cut + #------------------------------------------------------------------- -=head1 configurationForm +=head2 configurationForm Creates the configuration form for this plugin. See WebGUI::Image::Graph for more information. @@ -40,21 +69,21 @@ my $f = WebGUI::HTMLForm->new($self->session); } #------------------------------------------------------------------- -=head1 drawBar ( bar, location, barWidth ) +=head2 drawBar ( bar, location, barWidth ) Draws a bar defined by bar and with width barWidth at location. -=head2 bar +=head3 bar A hashref defining the bar. Must contain keys 'height', 'strokeColor' and 'fillColor'. -=head2 location +=head3 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 +=head3 barWidth The width of the bar in pixels. @@ -81,7 +110,7 @@ sub drawBar { } #------------------------------------------------------------------- -=head1 drawGraph +=head2 drawGraph Draws all the bars. @@ -114,21 +143,21 @@ sub drawGraph { } #------------------------------------------------------------------- -=head1 drawSideBySide ( bars, location, barWidth ) +=head2 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 +=head3 bars An arrayref containing all the bar description hashrefs as described in drawBar. -=head2 location +=head3 location Hashref containing the initial coordinates of the lower-left corner of the chart. Pass coords in keys 'x' and 'y'. -=head2 barWidth +=head3 barWidth The width of each bar in pixels. @@ -149,21 +178,21 @@ sub drawSideBySideBar { } #------------------------------------------------------------------- -=head1 drawStacked ( bars, location, barWidth ) +=head2 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 +=head3 bars An arrayref containing all the bar description hashrefs as described in drawBar. -=head2 location +=head3 location Hashref containing the initial coordinates of the lower-left corner of the chart. Pass coords in keys 'x' and 'y'. -=head2 barWidth +=head3 barWidth The width of each bar in pixels. @@ -186,7 +215,7 @@ sub drawStackedBar { } #------------------------------------------------------------------- -=head1 formNamespace +=head2 formNamespace Returns the form namespace of this plugin. See WegBUI::Image::Graph for more elaborate information. @@ -200,7 +229,7 @@ sub formNamespace { } #------------------------------------------------------------------- -=head1 getAnchorSpacing +=head2 getAnchorSpacing Returns the distance in pixels between two anchors on the x axis that define teh placement of bars and labels. @@ -221,7 +250,7 @@ sub getAnchorSpacing { } #------------------------------------------------------------------- -=head1 getBarSpacing +=head2 getBarSpacing Returns the width of the gap between two bars within a group in pixels. @@ -234,7 +263,7 @@ sub getBarSpacing { } #------------------------------------------------------------------- -=head1 getConfiguration +=head2 getConfiguration Returns the configuration hashref for this plugin. Refer to WebGUI::IMage::Graph for a more detailed description. @@ -253,7 +282,7 @@ sub getConfiguration { } #------------------------------------------------------------------- -=head1 getGroupSpacing +=head2 getGroupSpacing Returns the width of the gap between two groups of bars in pixels. @@ -266,7 +295,7 @@ sub getGroupSpacing { } #------------------------------------------------------------------- -=head1 getFirstAnchorLocation +=head2 getFirstAnchorLocation Returns a hashref containing the location of the leftmost x-axis anchor. Location coordinates are encoded in keys 'x' and 'y'. @@ -283,7 +312,7 @@ sub getFirstAnchorLocation { } #------------------------------------------------------------------- -=head1 processDataset +=head2 processDataset Processes the dataset. Used by drawGraph. @@ -312,11 +341,11 @@ sub processDataSet { } #------------------------------------------------------------------- -=head1 setBarSpacing ( gap ) +=head2 setBarSpacing ( gap ) Sets the distance between two bars in a group in pixels. -=head2 gap +=head3 gap The distance in pixels. @@ -330,12 +359,12 @@ sub setBarSpacing { } #------------------------------------------------------------------- -=head1 setConfiguration ( config ) +=head2 setConfiguration ( config ) Applies the given configuration hash to this plugin. See WebGUI::Image::Graph for more info. -=head2 config +=head3 config The configuration hash. @@ -354,11 +383,11 @@ sub setConfiguration { } #------------------------------------------------------------------- -=head1 setGroupSpacing ( gap ) +=head2 setGroupSpacing ( gap ) Sets the distance between two groups of bars in pixels. -=head2 gap +=head3 gap The distance in pixels. diff --git a/lib/WebGUI/Image/Graph/XYGraph/Line.pm b/lib/WebGUI/Image/Graph/XYGraph/Line.pm index 9e75c9cbb..e5c419d74 100644 --- a/lib/WebGUI/Image/Graph/XYGraph/Line.pm +++ b/lib/WebGUI/Image/Graph/XYGraph/Line.pm @@ -7,8 +7,29 @@ use POSIX; our @ISA = qw(WebGUI::Image::Graph::XYGraph); +=head1 NAME + +Package WebGUI::Image::Graph::XYGraph::Line + +=head1 DESCRIPTION + +Package for creating line graphs. + +=head1 SYNOPSIS + +This package privides the logic for drawing 2d line graphs, 3d lines are in the +pipeline but not yet ready for prime time. + +The possibilities are quite limited for now but will be enhanced upon in the future. + +=head1 METHODS + +These methods are available from this class: + +=cut + #------------------------------------------------------------------- -=head1 drawGraph +=head2 drawGraph Draws all the lines. @@ -32,21 +53,21 @@ sub drawGraph { } #------------------------------------------------------------------- -=head1 drawLine ( line, location, interval ) +=head2 drawLine ( line, location, interval ) Draws a bar defined by bar and with width barWidth at location. -=head2 line +=head3 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 +=head3 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 +=head3 interval The distance between x-axis anchors in pixels. @@ -81,7 +102,7 @@ sub drawLine { } #------------------------------------------------------------------- -=head1 formNamespace +=head2 formNamespace Returns the form namespace of this plugin. See WegBUI::Image::Graph for more elaborate information. @@ -95,7 +116,7 @@ sub formNamespace { } #------------------------------------------------------------------- -=head1 getAnchorSpacing +=head2 getAnchorSpacing Returns the distance in pixels between two anchors on the x axis that define teh placement of bars and labels. @@ -116,7 +137,7 @@ sub getAnchorSpacing { } #------------------------------------------------------------------- -=head1 getFirstAnchorLocation +=head2 getFirstAnchorLocation Returns a hashref containing the location of the leftmost x-axis anchor. Location coordinates are encoded in keys 'x' and 'y'. @@ -133,7 +154,7 @@ sub getFirstAnchorLocation { } #------------------------------------------------------------------- -=head1 processDataset +=head2 processDataset Processes the dataset. Used by drawGraph. diff --git a/lib/WebGUI/Image/Palette.pm b/lib/WebGUI/Image/Palette.pm index 63a33fddb..d1d4995ec 100644 --- a/lib/WebGUI/Image/Palette.pm +++ b/lib/WebGUI/Image/Palette.pm @@ -3,13 +3,36 @@ package WebGUI::Image::Palette; use strict; use WebGUI::Image::Color; +=head1 NAME + +Package WebGUI::Image::Palette + +=head1 DESCRIPTION + +Package for managing WebGUI palettes. + +=head1 SYNOPSIS + +Palettes are a list of WebGUI::Image::Color objects. Selecting a specific color +can be done by either passing a palette index, or by an API that cyles through +the palette. + +Along with methods for these operations methods for editing palettes are +provided from this class. + +=head1 METHODS + +These methods are available from this class: + +=cut + #------------------------------------------------------------------- -=head1 addColor ( color ) +=head2 addColor ( color ) Adds a color to this palette. The color will be automatically saved or updated to the database. -=head2 color +=head3 color A WebGUI::Image::Color object. @@ -31,7 +54,7 @@ sub addColor { } #------------------------------------------------------------------- -=head1 canDelete +=head2 canDelete Returns true if this palette can be deleted. @@ -45,7 +68,7 @@ sub canDelete { } #------------------------------------------------------------------- -=head1 canEdit +=head2 canEdit Returns true if this palette can be edited. @@ -58,7 +81,7 @@ sub canEdit { } #------------------------------------------------------------------- -=head1 delete +=head2 delete Deletes the palette from the database. This is only possible if the canDelete method returns true. @@ -81,7 +104,7 @@ sub delete { } #------------------------------------------------------------------- -=head1 getColor ( [ index ] ) +=head2 getColor ( [ index ] ) Returns the color at index in the palette. If index is not passed it will return the color at the index specified by the internal palette index counter, ie. the @@ -97,12 +120,12 @@ sub getColor { } #------------------------------------------------------------------- -=head1 getColorIndex ( color ) +=head2 getColorIndex ( color ) Returns the index of color. If the color is not in the palette it will return undef. -=head2 color +=head3 color A WebGUI::Image::Color object. @@ -123,7 +146,7 @@ sub getColorIndex { } #------------------------------------------------------------------- -=head1 getColorsInPalette +=head2 getColorsInPalette Returns a arrayref containing all color objects in the palette. @@ -137,7 +160,7 @@ sub getColorsInPalette { } #------------------------------------------------------------------- -=head1 getDefaultPaletteId +=head2 getDefaultPaletteId Returns the id of the default palette. @@ -150,7 +173,7 @@ sub getDefaultPaletteId { } #------------------------------------------------------------------- -=head1 getId +=head2 getId Returns the guid of this palette. @@ -163,7 +186,7 @@ sub getId { } #------------------------------------------------------------------- -=head1 getName +=head2 getName Returns the name of this palette. @@ -176,7 +199,7 @@ sub getName { } #------------------------------------------------------------------- -=head1 getNextColor +=head2 getNextColor Returns the next color in the palette relative to the internal palette index counter, and increases this counter to that color. If the counter already is at @@ -196,7 +219,7 @@ sub getNextColor { } #------------------------------------------------------------------- -=head1 getNumberOfColors +=head2 getNumberOfColors Returns the number of colors in the palette. @@ -209,7 +232,7 @@ sub getNumberOfColors { } #------------------------------------------------------------------- -=head1 getPaletteIndex +=head2 getPaletteIndex Returns the index the internal palette index counter is set to. Ie. it returns the current color. @@ -223,7 +246,7 @@ sub getPaletteIndex { } #------------------------------------------------------------------- -=head1 getPaletteList +=head2 getPaletteList Returns a hashref containing a list of all available palettes. The keys are the palette id's and the value are the names of the palettes. @@ -238,7 +261,7 @@ sub getPaletteList { } #------------------------------------------------------------------- -=head1 getPreviousColor +=head2 getPreviousColor Returns the previous color in the palette relative to the internal palette index counter, and decreases this counter to that color. If the counter already is at @@ -258,20 +281,20 @@ sub getPreviousColor { } #------------------------------------------------------------------- -=head1 new ( session, paletteId, [ name ]) +=head2 new ( session, paletteId, [ name ]) Constructor for this class. -=head2 session +=head3 session A WebGUI::Session object. -=head2 paletteId +=head3 paletteId The guid of the palette you want to instanciate. If you want to create a new palette use 'new' for this value. -=head2 name +=head3 name The name of this palette. If not given it will default to 'untitled'. You can also adjust this parameter through the setName method. @@ -315,14 +338,14 @@ sub new { } #------------------------------------------------------------------- -=head1 removeColor ( index ) +=head2 removeColor ( index ) Removes color at index. NOTE: This method does not delete the color from the database. If you want to do this you must do it manually. -=head2 index +=head3 index The index of the color you want to remove. If not given nothing will happen. @@ -350,7 +373,7 @@ sub removeColor { } #------------------------------------------------------------------- -=head1 session +=head2 session Returns the WebGUI::Session object. @@ -363,17 +386,17 @@ sub session { } #------------------------------------------------------------------- -=head1 setColor ( index, color ) +=head2 setColor ( index, color ) Sets palette position index to color. This method will automatically save or update the color. Index must be within the current palette. To add additional colors use the addColor method. -=head2 index +=head3 index The index within the palette where you want to put the color. -=head2 color +=head3 color The WebGUI::Image::Color object. @@ -405,7 +428,7 @@ sub setColor { Set the name of this palette. -=head2 name +=head3 name A scalar containing the desired name. @@ -424,13 +447,13 @@ sub setName { } #------------------------------------------------------------------- -=head1 setPaletteIndex ( index ) +=head2 setPaletteIndex ( index ) Set the internal palette index counter. In other words, it sets the current color to the specified index. If index exceeds the maximum index number it will be set to the maximum index. -=head2 index +=head3 index The index you want to set the counter to. @@ -449,15 +472,15 @@ sub setPaletteIndex { } #------------------------------------------------------------------- -=head1 swapColors ( firstIndex, secondIndex ) +=head2 swapColors ( firstIndex, secondIndex ) Swaps the position of two colors within the palette. -=head2 firstIndex +=head3 firstIndex The index of one of the colors to swap. -=head2 secondIndex +=head3 secondIndex The index of the other color to swap.