/ 
PostScript-Report-0.13
River stage zero No dependents
/ PostScript::Report::Role::Component

NAME

PostScript::Report::Role::Component - Something that can be drawn

VERSION

This document describes version 0.10 of PostScript::Report::Role::Component, released November 30, 2013 as part of PostScript-Report version 0.13.

DESCRIPTION

This role describes an object that knows how to draw itself on a report. A Component that contains other Components is a Container.

ATTRIBUTES

Inherited Attributes

These attributes control the component's formatting. To avoid having to set all of them on every component, their values are inherited much like CSS styles are inherited in HTML. If a component does not have an explicit value set, then the value is inherited from the parent. The inheritance may bubble up all the way to the Report object, which will always provide a default value.

All dimensions are in points.

align

This controls text alignment. It may be left, center, or right.

background

This is the background color for the Component. The color is a number in the range 0 to 1 (where 0 is black and 1 is white) for a grey background, or an arrayref of three numbers [ Red, Green, Blue ] where each number is in the range 0 to 1.

In addition, you can specify an RGB color in the HTML hex triplet form prefixed by # (like #FFFF00 or #FF0 for yellow).

Unlike the other formatting attributes, its value is not actually inherited, but since a Container draws the background for all its Components, the effect is the same.

border

This is the border style. It may be 1 for a solid border or 0 for no border. In addition, you may specify any combination of the letters T, B, L, and R (meaning top, bottom, left, and right) to have a border only on the specified side(s).

The thickness of the border is controlled by "line_width".

(Note: The string you give will be converted into the canonical representation, which has the letters upper case and in the order TBLR.)

font

This is the font used to draw normal text in the Component.

height

This is the height of the component.

line_width

This is the line width. It's used mainly as the border width. A line width of 0 means "as thin as possible".

width

This is the width of the component. In most cases, you will need to set this explicitly.

Optional Attributes

The following attributes are not present in all components, but when they are present, they should behave as described here. Attributes whose value can be inherited from the parent are marked (Inherited).

padding_bottom

(Inherited) This is the amount of space between the bottom of the component and the baseline of the text inside it. If this is too small, then the descenders (on letters like "p" and "y") will be cut off. (The exact minimum necessary depends on the selected font and size.)

padding_side

(Inherited) This is the amount of space between the side of the component and the text inside it.

value

This is the $value_source that the component will use to retrieve its contents. See "get_value" in PostScript::Report.

Internal Attribute

You probably won't need to use this attribute directly.

parent

This attribute contains a reference to the Container or Report that is the direct parent of this Component. It is used for inheritance of attribute values. It is filled in by the "init" method, and you will probably never deal with it directly.

METHODS

draw

$component->draw($x, $y, $report);

This method draws the component on the current page of the report at position $x, $y. This method must be provided by the component. The Component role provides a before draw modifier to draw the component's background.

draw_standard_border

$component->draw_standard_border($x, $y, $report);

This method draws a border around the component as specified by the "border" and "line_width" attributes. It can be called by a component's draw method, or added as an after modifier:

after draw => \&draw_standard_border;

dump

$component->dump($level);

This method (for debugging purposes only) prints a representation of the component to the currently selected filehandle. (Inherited values are not shown.) Note that layout calculations are not done until the report is run, so you will normally see additional height and width values after calling "run".

$level (default 0) indicates the level of indentation to use.

The default implementation should be sufficient for most components.

id

$psID = $component->id;

In order to avoid stepping on each other's PostScript code, any PostScript identifiers created by a component should begin with this string. The default implementation returns the last component of the class name.

init

$component->init($parent, $report);

The init method of each component is called at the beginning of each report run. The default implementation sets the parent link to enable inheritance of attribute values.

Most components will need to provide an after modifier to do additional initialization, such as calculating height or width. Also, the component should add its standard procedures to $report->ps_functions.

report

$component->report;

This returns the PostScript::Report object that this Component ultimately belongs to, or undef if it is not currently owned by a Report. (You should only call this after the init method has been called.)

SEE ALSO

The following components are available by default:

Checkbox

This displays a box, which contains a checkmark if the associated value is true.

Field

This is a standard text field.

FieldTL

This is a text field with a label in the corner. It also (optionally) supports multiple lines with word wrap.

HBox

This Container draws its children in a horizontal row.

Image

This allows you to include an EPS file.

Spacer

This is just an empty box for padding.

VBox

This Container draws its children in a vertical column.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-PostScript-Report AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-Report.

You can follow or contribute to PostScript-Report's development at https://github.com/madsen/postscript-report.

ACKNOWLEDGMENTS

I'd like to thank Micro Technology Services, Inc. http://www.mitsi.com, who sponsored development of PostScript-Report, and fREW Schmidt, who recommended me for the job. It wouldn't have happened without them.

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.