view release on metacpan or  search on metacpan

lib/Excel/Writer/XLSX/Shape.pm  view on Meta::CPAN

    $worksheet->insert_shape( 'C3', $ellipse );
    $worksheet->insert_shape( 'D3', $plus );


=head1 DESCRIPTION

The C<Excel::Writer::XLSX::Shape> module is used to create Shape objects for L<Excel::Writer::XLSX>.

A Shape object is created via the Workbook C<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 C<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);


=head1 METHODS

=head2 add_shape( %properties )

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

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

The available properties are shown below.

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

The C<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 C<$x> and C<$y> cell offsets it is possible to position a shape anywhere on the canvas of a worksheet.

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


=head1 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 C<set_properties()> method:

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

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

=head2 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.

=head2 type

Defines the type of the object such as C<rect>, C<ellipse> or C<triangle>:

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

The default type is C<rect>.

The full list of available shapes is shown below.

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


=over 4

=item * 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

=item * Arrow Shapes

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

=item * Connector Shapes

    bentConnector2   bentConnector3   bentConnector4
    bentConnector5   curvedConnector2 curvedConnector3
    curvedConnector4 curvedConnector5 straightConnector1

=item * 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

=item * Flow Chart Shapes

    flowChartAlternateProcess  flowChartCollate        flowChartConnector
    flowChartDecision          flowChartDelay          flowChartDisplay