/ 
PostScript-Graph-0.11
River stage zero No dependents
/ PostScript::Graph::Key

NAME

PostScript::Graph::Key - a Key area for PostScript::Graph::Paper

SYNOPSIS

use PostScript::File;
use PostScript::Graph::Key;
use PostScript::Graph::Paper;

Typical

    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
    }

All options

    my $gp = new PostScript::Graph::Paper(
	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,
	horizontal_spacing => 4,
	vertical_spacing => 6,
	icon_height => 12,
	icon_width => 40,
	text_size => 10,
	text_width => 72,
	text_color => 0,
	text_font => 'Courier',
	title => 'My Key',
	title_color => [1, 0, 0],
	title_font => 'Times-Bold',
	title_size => 14,
    };

DESCRIPTION

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 opportunity is provided to draw an icon with each key item. Ideally, this should use the same code and style as is used on the graph.

CONSTRUCTOR

new( [options] )

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.

All values are in PostScript native units (1/72 inch).

file

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)

background

Background colour for the key rectangle. (Default: 1)

graph_paper

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)

horizontal_spacing

The gaps between edges, icon and text. (Defaults to spacing)

icon_height

Vertical space for each icon. This will never be smaller than the height of the text. (Defaults to text_size)

icon_width

Amount of horizontal space to allow for the icon to the left of each label. (Defaults to text_size)

max_height

The vertical space available for the key rectangle. GraphKey tries to fit as many items as possible within this before adding another column.

num_items

The number of items that will be placed in the key.

outline_color

Colour of the box's outline. (Default: 0)

outline_width

Width of the box's outline. (Default: 0.75)

spacing

A larger value gives a less crowded feel, reduce it if you are short of space. Think printing leading. (Default: 4)

text_color

Colour of the text used in the body of the key. (Default: 0)

text_font

Font used for the key body text. (Default: "Helvetica")

text_size

Size of the font used for the key body text. (Default: 10)

text_width

Amount of room allowed for the text label on each key item. (Defaults to four times the font size)

title

The heading at the top of the key rectangle. (Default: "Key")

title_color

Colour of the key heading. (Default: 0)

title_font

The font used for the heading. (Default: "Helvetica-Bold")

title_size

Size of the font used for the heading. (Default: 12)

vertical_spacing

The gap between key items. (Defaults to spacing)

OBJECT METHODS

width()

Return the width required for the key rectangle.

height()

Return the height required for the key rectangle.

build_key( [graph_paper] )

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.

add_key_item( label, code [, psfile] )

label

The text for this key item

code

Postscript code which draws the icon.

psfile

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.

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.

	$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

ps_functions( ps )

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.

POSTSCRIPT CODE

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.

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

BUGS

Very likely. This is still alpha software and has only been tested in very predictable conditions.

AUTHOR

Chris Willmot, chris@willmot.co.uk

SEE ALSO

PostScript::File, PostScript::Graph::Style, PostScript::Graph::Paper.