PostScript::Graph::Key - a Key area for PostScript::Graph::Paper
use PostScript::File; use PostScript::Graph::Key; use PostScript::Graph::Paper;
A Key panel is drawn to the right of its associated graph. The area needed for the Key panel must be calculated before the graph Paper can be drawn in the remaining space.
my $ps = new PostScript::File; my @bbox = $psf->get_page_bounding_box(); # Calculate variables from the graph data # planned layout and available space ... my $gk = new PostScript::Graph::Key( num_items => ... , max_height => ... , text_width => ... , icon_width => ... , icon_height => ... , ); # Need to pass this to GraphPaper my $width = $pgk->width(); my $gp = new PostScript::Graph::Paper( file => $ps, chart => { key_width => $width, }, ); # Now we can link the two $gk->build_key( $gp ); foreach $line (@lines) { ... draw line on graph_paper ... $gk->add_key_item( $title, <<END ); ... postscript code ... drawing icon END }
my $gp = new PostScript::Graph::Key( file => $ps_file, graph_paper => $ps_gpaper, max_height => 500, num_items => 5, background => 0.9, outline_color => [0.5, 0.5, 0.2], outline_wdith => 0.8, spacing => 4, horz_spacing => 4, vert_spacing => 6, icon_height => 12, icon_width => 40, text_width => 72, text_font => { size => 10, color => 0, font => 'Courier', }, title => 'My Key', title_font => { color => [1, 0, 0], font => 'Times-Bold', size => 14, }, };
This module is designed as a supporting part of the PostScript::Graph suite. For top level modules that output something useful, see
PostScript::Graph::Bar PostScript::Graph::Stock PostScript::Graph::XY
A companion object to PostScript::Graph::Paper, this is used by any module that requies a Key for a graph. The size and shape is automatically adjusted to accomodate the number of items in the space available, adding more columns if there is not enough vertical space. The textual description now wraps onto multiple lines if needed.
The opportunity is provided to draw an icon with each key item using the same code and style as is used on the graph. This is accomplished in distinct phases.
The total space available is typically obtained from PostScript::File, but must be known so that PostScript::Graph::Key and PostScript::Graph::Paper can divide it between them.
All the graph lines must exist before the graph is drawn. PostScript::Graph::Paper needs to calculate the axes and suggest the height available for the Key which will be placed to the right of the graph.
The PostScript::Graph::Key constructor calculates the outer box dimensions from the items required and the space available. In particular the number of text rows per item must be worked out and how many columns will be needed.
The key width can then be passed to the PostScript::Graph::Paper constructor, which works out the space available for the graph and usually draws the background grid.
build_key can then be called to draw the outer box and heading next to the grid.
For each graph line, the line can be drawn on the paper and its icons drawn in the key box at the same time, using the same PostScript::Graph::Style settings.
options should be either a list of hash keys and values or a hash reference. Unlike other objects in this series, a couple of these (max_height and num_items) are required. Another difference is that all options occur within a flat space - there are no sub-groups. This is because it is expected that this module will only be used as part of another Chart object, with these options passed as a group through that constructor.
options
max_height
num_items
All values are in PostScript native units (1/72 inch).
If num_items is an integer, the textual description will have one line per item. Where long descriptions are needed, item_labels can be given instead. It should refer to a list of the strings to be placed next to each key icon. The constructor calculates the number of rows needed when this text is wrapped within text_width. The text is only actually wrapped when add_key_item is called.
item_labels
text_width
Background colour for the key rectangle. (Default: 1)
If graph_paper is not given, this probably should be. It is the PostScript::File object that holds the graph being constructed. It is possible to specify this later, when calling add_key_item. (No default)
graph_paper
A kludge provided to fine-tune how well the text labels fit into the box. It is not possible to get the actual width of proportional font strings from PostScript, so this gives the opportunity to guess an 'average width' for particular fonts. (Default: 0.5)
If given, this should be a PostScript::Graph::Paper object. A GraphKey needs to know which GraphPaper has allocated space for it. But the GraphPaper need the GraphKey to have already worked out how much space it needs. The best solution is to create the GraphKey before the GraphPaper, then pass the latter to build_chart. (No default)
The gaps between edges, icon and text. (Defaults to spacing)
spacing
Vertical space for each icon. This will never be smaller than the height of the text. (Defaults to text_size)
text_size
Amount of horizontal space to allow for the icon to the left of each label. (Defaults to text_size)
As an alternative to specifying the number of items (which must be single lines of text), this takes an array ref pointing to a list of all the key labels that will later be added. The same wrapping algorithm is applied to both. The box dimensions are calculated from these, but the actual text printed should be passed seperately to add_key_item.
The vertical space available for the key rectangle. GraphKey tries to fit as many items as possible within this before adding another column. Required - there is no default.
The number of items that will be placed in the key. Required unless item_labels is given.
Colour of the box's outline. (Default: 0)
Width of the box's outline. (Default: 0.75)
A larger value gives a less crowded feel, reduce it if you are short of space. Think printing leading. (Default: 4)
Colour of the text used in the body of the key. (Default: 0)
Font used for the key body text. (Default: "Helvetica")
Size of the font used for the key body text. (Default: 10)
Amount of room allowed for the text label on each key item. (Defaults to four times the font size)
The heading at the top of the key rectangle. (Default: "Key")
Colour of the key heading. (Default: 0)
The font used for the heading. (Default: "Helvetica-Bold")
Size of the font used for the heading. (Default: 12)
The gap between key items. (Defaults to spacing)
Return the width required for the key rectangle.
Return the height required for the key rectangle.
This is where the position of the key area is fixed and the outline and heading are drawn. It must be called before add_key_item.
The text for this key item
Postscript code which draws the icon.
The PostScript::File object the code will be written to. If it was not given to new as either file or graph_paper, it must be given here.
file
A number of postscript variables are provided to help with the drawing. See <L/POSTSCRIPT CODE> for the full list.
kix0 left edge of icon area kiy0 bottom edge kix1 right edge kiy1 top edge
Your code should use its own dictionary and can refer to dictionaries you have begun but not yet ended at this point. For example, here is the code used by PostScript::Graph::XY. It calculates the mid point of a diagonal line and draws it using the same functions used for the main chart. line_outer etc. are provided by PostScript::Graph::Style to change style settings, draw1point just expects 'x y' and drawxyline expects an array of coordinates followed by the greatest index allowed.
line_outer
draw1point
drawxyline
$graphkey->add_key_item( $line->{ytitle}, <<END_KEY_ITEM ); 2 dict begin /kpx kix0 kix1 add 2 div def /kpy kiy0 kiy1 add 2 div def point_outer kpx kpy draw1point [ kix0 kiy0 kix1 kiy1 ] 3 2 copy line_outer drawxyline line_inner drawxyline point_inner kpx kpy draw1point end END_KEY_ITEM
Normally, this is called in build_key, but is provided as a class function so the dictionary may be still available even when a Key object is not required.
None of the postscript functions defined in this module would have application outside it. However, the following variables are defined within the graphkeydict dictionary and may be of some use.
graphkeydict
kix0 left edge of icon area kiy0 bottom edge kix1 right edge kiy1 top edge kvspc vertical spacing khspc horizontal spacing kdxicon width of icon area kdyicon height of icon area kdxtext width of text area kdytext height of text area kfont font used for text ksize font size used kcol colour of font used
Too much space is allocated to wrapped text if accompanied by a large icon.
Chris Willmot, chris@willmot.org.uk
PostScript::File, PostScript::Graph::Style and PostScript::Graph::Paper for the other modules in this suite.
PostScript::Graph::Bar, PostScript::Graph::XY and Finance::Shares::Chart for modules that use this one.
To install PostScript::Graph::XY, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PostScript::Graph::XY
CPAN shell
perl -MCPAN -e shell install PostScript::Graph::XY
For more information on module installation, please visit the detailed CPAN module installation guide.