Shape - A class for creating Excel Drawing shapes

Author

       Dave Clarke dclarke@cpan.org

Copyright

       (c) MM-MMXXIII, John McNamara.

       All  Rights  Reserved.  This module is free software. It may be used, redistributed and/or modified under
       the same terms as Perl itself.

perl v5.36.0                                       2023-04-12                    Excel::Writer::XLSX::Shape(3pm)

Description

       The "Excel::Writer::XLSX::Shape" module is used to create Shape objects for Excel::Writer::XLSX.

       A Shape object is created via the Workbook "add_shape()" method:

           my $shape_rect = $workbook->add_shape( type => 'rect' );

       Once the object is created it can be inserted into a worksheet using the "insert_shape()" method:

           $worksheet->insert_shape('A1', $shape_rect);

       A Shape can be inserted multiple times if required.

           $worksheet->insert_shape('A1', $shape_rect);
           $worksheet->insert_shape('B2', $shape_rect, 20, 30);

Example

           #!/usr/bin/perl

           use strict;
           use warnings;
           use Excel::Writer::XLSX;

           my $workbook  = Excel::Writer::XLSX->new( 'shape.xlsx' );
           my $worksheet = $workbook->add_worksheet();

           # Add a default rectangle shape.
           my $rect = $workbook->add_shape();

           # Add an ellipse with centered text.
           my $ellipse = $workbook->add_shape(
               type => 'ellipse',
               text => "Hello\nWorld"
           );

           # Add a plus shape.
           my $plus = $workbook->add_shape( type => 'plus');

           # Insert the shapes in the worksheet.
           $worksheet->insert_shape( 'B3', $rect );
           $worksheet->insert_shape( 'C3', $ellipse );
           $worksheet->insert_shape( 'D3', $plus );

       See also the "shapes_*.pl" program in the "examples" directory of the distro.

Methods

add_shape(%properties)
       The "add_shape()" Workbook method specifies the properties of the Shape in hash "property => value"
       format:

           my $shape = $workbook->add_shape( %properties );

       The available properties are shown below.

   insert_shape($row,$col,$shape,$x,$y,$scale_x,$scale_y)
       The "insert_shape()" Worksheet method sets the location and scale of the shape object within the
       worksheet.

           # Insert the shape into the worksheet.
           $worksheet->insert_shape( 'E2', $shape );

       Using the cell location and the $x and $y cell offsets it is possible to position a shape anywhere on the
       canvas of a worksheet.

       A more detailed explanation of the "insert_shape()" method is given in the main Excel::Writer::XLSX
       documentation.

Name

       Shape - A class for creating Excel Drawing shapes

Shape Properties

Any shape property can be queried or modified by the corresponding get/set method:

my $ellipse = $workbook->add_shape( %properties );
$ellipse->set_type( 'plus' ); # No longer an ellipse!
my $type = $ellipse->get_type(); # Find out what it really is.

Multiple shape properties may also be modified in one go by using the "set_properties()" method:

$shape->set_properties( type => 'ellipse', text => 'Hello' );

The properties of a shape object that can be defined via "add_shape()" are shown below.

name
Defines the name of the shape. This is an optional property and the shape will be given a default name if
not supplied. The name is generally only used by Excel Macros to refer to the object.

type
Defines the type of the object such as "rect", "ellipse" or "triangle":

my $ellipse = $workbook->add_shape( type => 'ellipse' );

The default type is "rect".

The full list of available shapes is shown below.

See also the "shapes_all.pl" program in the "examples" directory of the distro. It creates an example
workbook with all supported shapes labelled with their shape names.

• Basic Shapes

blockArc can chevron cube decagon
diamond dodecagon donut ellipse funnel
gear6 gear9 heart heptagon hexagon
homePlate lightningBolt line lineInv moon
nonIsoscelesTrapezoid noSmoking octagon parallelogram pentagon
pie pieWedge plaque rect round1Rect
round2DiagRect round2SameRect roundRect rtTriangle smileyFace
snip1Rect snip2DiagRect snip2SameRect snipRoundRect star10
star12 star16 star24 star32 star4
star5 star6 star7 star8 sun
teardrop trapezoid triangle

• Arrow Shapes

bentArrow bentUpArrow circularArrow curvedDownArrow
curvedLeftArrow curvedRightArrow curvedUpArrow downArrow
leftArrow leftCircularArrow leftRightArrow leftRightCircularArrow
leftRightUpArrow leftUpArrow notchedRightArrow quadArrow
rightArrow stripedRightArrow swooshArrow upArrow
upDownArrow uturnArrow

• Connector Shapes

bentConnector2 bentConnector3 bentConnector4
bentConnector5 curvedConnector2 curvedConnector3
curvedConnector4 curvedConnector5 straightConnector1

• Callout Shapes

accentBorderCallout1 accentBorderCallout2 accentBorderCallout3
accentCallout1 accentCallout2 accentCallout3
borderCallout1 borderCallout2 borderCallout3
callout1 callout2 callout3
cloudCallout downArrowCallout leftArrowCallout
leftRightArrowCallout quadArrowCallout rightArrowCallout
upArrowCallout upDownArrowCallout wedgeEllipseCallout
wedgeRectCallout wedgeRoundRectCallout

• Flow Chart Shapes

flowChartAlternateProcess flowChartCollate flowChartConnector
flowChartDecision flowChartDelay flowChartDisplay
flowChartDocument flowChartExtract flowChartInputOutput
flowChartInternalStorage flowChartMagneticDisk flowChartMagneticDrum
flowChartMagneticTape flowChartManualInput flowChartManualOperation
flowChartMerge flowChartMultidocument flowChartOfflineStorage
flowChartOffpageConnector flowChartOnlineStorage flowChartOr
flowChartPredefinedProcess flowChartPreparation flowChartProcess
flowChartPunchedCard flowChartPunchedTape flowChartSort
flowChartSummingJunction flowChartTerminator

• Action Shapes

actionButtonBackPrevious actionButtonBeginning actionButtonBlank
actionButtonDocument actionButtonEnd actionButtonForwardNext
actionButtonHelp actionButtonHome actionButtonInformation
actionButtonMovie actionButtonReturn actionButtonSound

• Chart Shapes

Not to be confused with Excel Charts.

chartPlus chartStar chartX

• Math Shapes

mathDivide mathEqual mathMinus mathMultiply mathNotEqual mathPlus

• Stars and Banners

arc bevel bracePair bracketPair chord
cloud corner diagStripe doubleWave ellipseRibbon
ellipseRibbon2 foldedCorner frame halfFrame horizontalScroll
irregularSeal1 irregularSeal2 leftBrace leftBracket leftRightRibbon
plus ribbon ribbon2 rightBrace rightBracket
verticalScroll wave

• Tab Shapes

cornerTabs plaqueTabs squareTabs

text
This property is used to make the shape act like a text box.

my $rect = $workbook->add_shape( type => 'rect', text => "Hello\nWorld" );

The text is super-imposed over the shape. The text can be wrapped using the newline character "\n".

id
Identification number for internal identification. This number will be auto-assigned, if not assigned, or
if it is a duplicate.

format
Workbook format for decorating the shape text (font family, size, and decoration).

start,start_index
Shape indices of the starting point for a connector and the index of the connection. Index numbers are
zero-based, start from the top dead centre and are counted clockwise.

Indices are typically created for vertices and centre points of shapes. They are the blue connection
points that appear when connection shapes are selected manually in Excel.

end,end_index
Same as above but for end points and end connections.

start_side,end_side
This is either the letter "b" or "r" for the bottom or right side of the shape to be connected to and
from.

If the "start", "start_index", and "start_side" parameters are defined for a connection shape, the shape
will be auto located and linked to the starting and ending shapes respectively. This can be very useful
for flow and organisation charts.

flip_h,flip_v
Set this value to 1, to flip the shape horizontally and/or vertically.

rotation
Shape rotation, in degrees, from 0 to 360.

line,fill
Shape colour for the outline and fill. Colours may be specified as a colour index, or in RGB format, i.e.
"AA00FF".

See "COLOURS IN EXCEL" in the main documentation for more information.

line_type
Line type for shape outline. The default is solid. The list of possible values is:

dash, sysDot, dashDot, lgDash, lgDashDot, lgDashDotDot, solid

valign,align
Text alignment within the shape.

Vertical alignment can be:

Setting Meaning
======= =======
t Top
ctr Centre
b Bottom

Horizontal alignment can be:

Setting Meaning
======= =======
l Left
r Right
ctr Centre
just Justified

The default is to centre both horizontally and vertically.

scale_x,scale_y
Scale factor in x and y dimension, for scaling the shape width and height. The default value is 1.

Scaling may be set on the shape object or via "insert_shape()".

adjustments
Adjustment of shape vertices. Most shapes do not use this. For some shapes, there is a single adjustment
to modify the geometry. For instance, the plus shape has one adjustment to control the width of the
spokes.

Connectors can have a number of adjustments to control the shape routing. Typically, a connector will
have 3 to 5 handles for routing the shape. The adjustment is in percent of the distance from the starting
shape to the ending shape, alternating between the x and y dimension. Adjustments may be negative, to
route the shape away from the endpoint.

stencil
Shapes work in stencil mode by default. That is, once a shape is inserted, its connection is separated
from its master. The master shape may be modified after an instance is inserted, and only subsequent
insertions will show the modifications.

This is helpful for Org charts, where an employee shape may be created once, and then the text of the
shape is modified for each employee.

The "insert_shape()" method returns a reference to the inserted shape (the child).

Stencil mode can be turned off, allowing for shape(s) to be modified after insertion. In this case the
"insert_shape()" method returns a reference to the inserted shape (the master). This is not very useful
for inserting multiple shapes, since the x/y coordinates also gets modified.

Synopsis

       To create a simple Excel file containing shapes using Excel::Writer::XLSX:

           #!/usr/bin/perl

           use strict;
           use warnings;
           use Excel::Writer::XLSX;

           my $workbook  = Excel::Writer::XLSX->new( 'shape.xlsx' );
           my $worksheet = $workbook->add_worksheet();

           # Add a default rectangle shape.
           my $rect = $workbook->add_shape();

           # Add an ellipse with centered text.
           my $ellipse = $workbook->add_shape(
               type => 'ellipse',
               text => "Hello\nWorld"
           );

           # Add a plus shape.
           my $plus = $workbook->add_shape( type => 'plus');

           # Insert the shapes in the worksheet.
           $worksheet->insert_shape( 'B3', $rect );
           $worksheet->insert_shape( 'C3', $ellipse );
           $worksheet->insert_shape( 'D3', $plus );

Tips

       Use "$worksheet->hide_gridlines(2)" to prepare a blank canvas without gridlines.

       Shapes  do not need to fit on one page. Excel will split a large drawing into multiple pages if required.
       Use the page break preview to show page boundaries superimposed on the drawing.

       Connected shapes will auto-locate in Excel if you move either the starting  shape  or  the  ending  shape
       separately. However, if you select both shapes (lasso or control-click), the connector will move with it,
       and the shape adjustments will not re-calculate.

Todo

       •   Add shapes which have custom geometries.

       •   Provide better integration of workbook formats for shapes.

       •   Add further validation of shape properties to prevent creation of workbooks that will not open.

       •   Auto connect shapes that are not anchored to cell A1.

       •   Add automatic shape connection to shape vertices besides the object centre.

       •   Improve automatic shape connection to shapes with concave sides (e.g. chevron).