view release on metacpan or  search on metacpan

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

=head2 start_side, end_side

This is either the letter C<b> or C<r> for the bottom or right side of the shape to be connected to and from.

If the C<start>, C<start_index>, and C<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.

=head2 flip_h, flip_v

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

=head2 rotation

Shape rotation, in degrees, from 0 to 360.

=head2 line, fill

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

See C<COLOURS IN EXCEL> in the main documentation for more information.

=head2 line_type

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

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

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

=head2 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 C<insert_shape()>.

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

=head2 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 C<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 C<insert_shape()> method returns a reference to the inserted shape (the master). This is not very useful for inserting multiple shapes, since the x...

=head1 TIPS

Use C<< $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-calcu...

=head1 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 C<shapes_*.pl> program in the C<examples> directory of the distro.

=head1 TODO

=over 4

=item * Add shapes which have custom geometries.

=item * Provide better integration of workbook formats for shapes.

=item * Add further validation of shape properties to prevent creation of workbooks that will not open.