Excel:...:Shape(3pm)

💖 NAME 💖

Shape — a whole class for making Excel Drawing shapes, bestie. Like, actual shapes. In actual Excel. Periodt.

It's Excel::Writer::XLSX::Shape, aka Shape(3pm), hanging out in the User Contributed Perl Documentation fam. 🎀

---

✨ SYNOPSIS ✨

okay so picture this: you wanna make a simple Excel file with shapes in it, using Excel::Writer::XLSX. Here's the whole vibe:

#!/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 );

look at that. three little shapes, all living their best lives in shape.xlsx. the rectangle said nothing and served cunt, the ellipse came with text, and the plus just showed up. iconic behavior honestly. 👑

---

🦋 DESCRIPTION 🦋

So the Excel::Writer::XLSX::Shape module is the one that makes Shape objects for Excel::Writer::XLSX. That's it. That's the job. 🫶

You don't just summon a Shape out of thin air (well, kind of you do, but through the Workbook). You make one with the add_shape() method:

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

and then once your little guy exists, you drop it into a worksheet with insert_shape():

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

and the best part? a Shape can be inserted multiple times if you want. it's not a one-and-done situation. reuse that shape, she's versatile:

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

no cap, same object, two spots. lowkey efficient. 💅

---

💅 METHODS 💅

🌸 add_shape( %properties )

This is the Workbook method, and it's the one that specifies all the properties of your Shape. You feed it stuff in hash property => value format, like:

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

Every property you can possibly pass is listed down below. go wild. ✨

🎀 insert_shape( $row, $col, $shape, $x, $y, $scale_x, $scale_y )

And this one is the Worksheet method — it sets where your shape object goes on the worksheet and how big it gets scaled. the location AND the scale, both handled:

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

So here's the tea: by combining the cell location with the $x and $y cell offsets, you can position a shape literally anywhere on the canvas of a worksheet. anywhere. the whole canvas is yours, main character energy only. 🌈

If you want the full, detailed, deep-dive explanation of the insert_shape() method, it lives in the main Excel::Writer::XLSX documentation. go read it, it's giving thorough. 📚

---

more coming bestie, don't go anywhere 💜

📐 SHAPE PROPERTIES 📐

okay bestie, here's the tea: literally any shape property can be queried or modified by its matching 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.

and if you're feeling efficient (iconic behaviour), you can change a whole bunch of properties at once with set_properties() 💅

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

so here's every single property you can define via add_shape(), no skips, no crumbs ✨

name

Sets the name of the shape. It's optional, bestie — if you don't hand one over, the shape just gets a default name. The name is generally only used by Excel Macros to refer to the object.

type

This one sets the type of the object, like "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.

also go peek at 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, bestie 💀

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 makes 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

The shape indices of the starting point for a connector, plus the index of the connection. Index numbers are zero-based, they start from the top dead centre and get counted clockwise 🔄

Indices are typically created for vertices and centre points of shapes. They're the blue connection points that show up when you select connection shapes manually in Excel.

end, end_index

Same energy 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. obsessed 😌

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 the 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:

• t — Top
• ctr — Centre
• b — Bottom

Horizontal alignment can be:

• 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's 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.

---

💡 TIPS 💡

• Use "$worksheet->hide_gridlines(2)" to prepare a blank canvas without gridlines. clean slate energy ✨
• 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. noted, fr fr 📝

---

🌈 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 );

also check out the "shapes_*.pl" program in the "examples" directory of the distro 🦋

---

📝 TODO 📝

the to-do list, bestie — they're working on it 💅

• 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).

---

👑 AUTHOR 👑

Dave Clarke dclarke@cpan.org

💖 COPYRIGHT 💖

okay bestie, final section, the legal one — but make it fashion ✨

• (c) MM-MMXXV, John McNamara.

All Rights Reserved.

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

no gatekeeping here — take it, share it, remix it, just keep it under Perl's own terms, periodt 💅

---

and that's a wrap on the whole page, bestie!! 🎀 you read literally every option, every property, every TODO — main character energy, no cap 👑

this cutie was rendered by perl v5.40.1 on 2025-12-22, and it's page Excel:...:Shape(3pm) in the flesh. go make some iconic spreadsheets 🌈 bye pookie, slay responsibly 💖