NAME
PostScript::GraphStyle - style settings for postscript objects
SYNOPSIS
Each time a new object is created the default style will be slightly different.
use PostScript::GraphStyle;
use PostScript::File;
$psf = new PostScript::File();
while (...) {
$pgs = new PostScript::GraphStyle();
$psf->add_to_page( <<END_OF_CODE );
% code fragments using variables...
% setting colour or grey shade
gpaperdict begin
pocolor gpapercolor
end
% choosing a line width
powidth setlinewidth
% scaled relative to point sizing
0 ppsize rlineto
% showing the chosen point shape
100 200 ppshape
END_OF_CODE
}
It is possible to control how each new object varies.
$PostScript::GraphStyle::defaults{red} =
[ 0, 1, 0.2, 0.8, 0.4, 0.6 ];
$pgs = new PostScript::GraphStyle(
auto => [ qw(dashes cyan shape) ],
);
$psf = new PostScript::File();
while (...) {
$pgs = new PostScript::GraphStyle();
... the same postscript variables ...
}
Some of the styles may be overriden.
$pgs = new PostScript::GraphStyle(
auto => [ qw(red green blue) ],
color => 1,
line => {
width => 4,
outer_dashes => [],
outer_color => [1, 0, 0],
},
);Or the automatic default feature can be supressed and some or all details specified directly.
$pgs = new PostScript::GraphStyle(
auto => "none",
point => {
shape => "circle",
size => 12,
},
);DESCRIPTION
Creating a new style will by default do just that - create a new style. Such dynamic defaults are a main feature of this class and most users should not need to specify individual settings.
Settings are provided for three types of object. A line is any unfilled path, a bar is any filled path while a point is a filled path that may contain holes.
They all have outer and inner components. The inner component provides the main shape and colour, while the outer 'edge' is provided to insulate this from any background colour. Lines may be whole or broken and a variety of builtin shapes is provided. By default, repeated calls to new return styles that differ from one another although like everything else this can be under detailed user control if required.
The following functions return values set in the constructor. See "new" for more details.
same()
color()
line_outer_color()
line_outer_width()
line_outer_dashes()
line_inner_color()
line_inner_width()
line_inner_dashes()
bar_outer_color()
bar_outer_width()
bar_inner_color()
bar_inner_width()
point_size()
point_shape()
point_outer_color()
point_outer_width()
point_inner_color()
point_inner_width()head1 CONSTRUCTOR
new( [options] )
options can either be a list of hash keys and values or a single hash reference. In both cases the hash must have the same structure. There are a few principal keys and most of these refer to hashes holding a group of options. No attempt is made to constrain the combinations but not all are useful or sensible and bizarre choices will probably fail.
Global settings
These are mainly concerned with how the defaults are generated for each new PostScript::GraphStyle object.
auto
This can either be the string "none" or a list of features. The first feature mentioned will vary fastest from one style to the next while the last varies slowest. Any features not mentioned will not be varied. See "DYNAMIC DEFAULTS" for how to change the defaults for these features.
red green blue
yellow mauve cyan
dashes width shapes
size grayExample 1
$ps = new PostScript::GraphStyle(
auto => [qw( dashes shapes )],
);
Setting auto to the string 'none' (instead of the array) prevents the automatic generation of defaults, as does setting every option directly.
If nothing is given, the behaviour depends on whether this is the first call to new or a repeated call. If auto is not present or no list is given when the dynamic defaults are first initialized, all non-colour values are assumed. Calling new again without auto being specified returns the next set of defaults (the same if 'none' was given initially). Whenever auto is given a new list, the dynamic defaults are reset.
color
Set this to 0 to use shades of grey for monochrome printers.
This also must be set to 0 to cycle through user defined colours. This switch actually determines whether the colour value is taken from the defaults{grey} array or a composite of the red, green and blue arrays. So putting the custom colours into defaults{grey} and setting color to 0 reads these. The internal postscript code handles each format interchangeably, so the result is coloured gray!
$PostScript::GraphStyle::Defaults{gray} =
[ [ 0, 0, 0 ], # white
[ 0, 0, 1 ], # blue
[ 0, 1, 0 ], # green
[ 0, 1, 1 ], # cyan
[ 1, 0, 0 ], # red
[ 1, 0, 1 ], # mauve
[ 1, 1, 0 ], # yellow
[ 1, 1, 1 ], ]; # black
$gs = new PostScript::GraphStyle(
auto => [qw(gray)],
color => 0,
);
same
By default, the outer colour is the complement of the background (see "outer_color"). Setting this to 1 makes the outer colour the same as the background.
Graphic settings
The options described below belong within line, bar or point sub-hashes unless otherwise mentioned. For example, referring to the descriptions for color and size:
line => { color => ... } valid
point => { color => ... } valid
line => { size => ... } NOT valid
point => { size => ... } validAll color options take either a single greyscale decimal or a reference to an array holding decimals for red, green and blue components. All decimals should be between 0 and 1.0 inclusive.
color => 1 white
outer_color => 0 black
inner_color => [1, 0, 0] red
Example 2
$ps = new PostScript::GraphStyle(
defaults => "none",
line => {
width => 2,
inner_color => [ 1, 0.6, 0.4 ],
}
point => {
shape => "diamond",
size => 12,
color => [ 1, 0.8, 0.8 ],
inner_width => 2,
outer_width => 1,
}
);
color
A synonym for inner_color. See "new".
dashes
Set both inner and outer dash patterns. See "inner_dashes".
inner_color
The main colour of the line or point. See "new".
inner_dashes
This array ref holds values that determine any dash pattern. They are repeated as needed to give the size 'on' then 'off'. Examples are the best way to describe this.
inner_dashes => [] -------------------------
inner_dashes => [ 3 3 ] --- --- --- --- -
inner_dashes => [ 5 2 1 2 ] ----- - ----- - -----Only available for lines.
inner_width
The size of the central portion of the line. Although this can be set of points, size is more likely to be what you want. Probably should be no less than 0.1 to be visible - 0.24 on a 300dpi device or 1 on 72dpi. (Default: 0.5)
When used in conjunction with inner_dashes, setting inner and outer widths to the same value produces a two-colour dash.
outer_color
Colour for the 'edges' of the line or point. To be visible outer_width must be greater than <inner_width>. (Default: -1)
Note that the default is NOT a valid postscript value (although gpapercolor handles it fine. See "gpapercolor" in PostScript::GraphPaper. If default_bgnd() is called later, it fills all colours marked thus with a background colour now known.
outer_dashes
If this is unset, inner lines alternate with the outer colour. To get a dashed line, this should be the same value as inner_dashes. (Default: "[]")
Only available for lines.
outer_width
Total width of the line or point, including the border (which may be invisible, depending on colour). The edge is only visible if this is at least 0.5 greater than inner_width. 2 or 3 times inner_width is often best. (Default: 1.5)
When using the circle point shape, this should be quite small to allow the line to be visible inside the circle.
shape
This string specifies the built-in shape to use for points. Suitable values are "plus", "cross", "dot", "circle", "square" and "diamond". (Default: "dot")
Only available for points.
size
Width across the inner part of a point shape. (Default: 5)
Not available for lines.
width
Set the inner line width. The outer width is also set to twice this value.
ps_functions( ps [, dict [, set]] )
ps-
The PostScript::File object being written to.
dict-
The postscript dictionary where these 14 definitions are to be added.
set-
Put 0 here if the call to set() is not required.
Add style functions into the postscript prolog. Nothing works unless this is given. It is not included within new to give the opportunity to specify the postscript dictionary. Typically this would be the main 'userdict' replacement. The dictionary gpaperdict must be present. See "POSTSCRIPT CODE" in PostScript::GraphPaper).
This includes a call to "set".
set( ps, [ dict ] )
ps-
The PostScript::File object being written to.
dict-
If given, a selection of the 19 possible definitions are added to the postscript dictionary.
The point at which the style values are set into postscript. This is a convenient way of setting all the postscript variables at the same time as it calls each of the line, point and bar variants below. It is called by ps_functions which should be sufficient in most cases.
- set_line( ps, [ dict ] )
-
This sets the following postscript variables.
PostScript Perl method ========== =========== locolor line_outer_color lowidth line_outer_width lostyle line_outer_dashes licolor line_inner_color liwidth line_inner_width listyle line_inner_dashes - set_point( ps, [ dict ] )
-
This sets the following postscript variables.
PostScript Perl method ========== =========== ppshape point_shape ppsize point_size pocolor point_outer_color powidth point_outer_width picolor point_inner_color piwidth point_inner_width - set_bar( ps, [ dict ] )
-
This sets the following postscript variables.
PostScript Perl method ========== =========== bocolor bar_outer_color bowidth bar_outer_width bicolor bar_inner_color biwidth bar_inner_width
background( grey | arrayref [, same] )
The default outer colour setting (-1) is interpreted as 'use complement to graphpaper background'. Of course, it is not possible to bind that until the graphpaper object exists. Calling this function sets all outer colour values to be a complement of the colour given, unless same is set to non-zero. If not given, same takes on the value given to the constuctor or 0 by default.
DYNAMIC DEFAULTS
Although it is possible to specify styles directly, mostly the style just needs to be different from the last one. These dynamic defaults provide around 3600 variations which should be suitable for most cases.
The values themselves are placed in a pseudo-hash and can be replaced if desired. Permutations of these are then generated on demand. The permutation order is under user control.
defaults
This class variable must be explicitly requested:
use PostScript::GraphStyle qw(defaults);It is a pseudo-hash with fields red, green, blue, shape, width, dashes Thickness is 'width' elsewhere. Green is used for gray below. Each refers to an array of suitable values whose order is significant.
$defaults{blue} = [ 0.0, 1.0, 0.5 ];
$defaults{shape} = [qw(dot square cross)];
$defaults{dashes} = [ [], [3 3], [10 5 3 5] ];Specifying alternative values determines the pool of defaults. For example the following would ensure lines with 15 shades of red-orange-yellow.
$defaults{red} = [ 0.2, 1, 0.4, 0.8, 0.6 ];
$defaults{green} = [ 0, 0.8, 0.4 ];
$defaults{blue} = [ 0 ];
POSTSCRIPT CODE
PostScript variables
See "set" for the values accessible from postscript. All ...color variables are either a decimal or an array holding red, green and blue values. These are best passed to "gpapercolor" in PostScript::GraphPaper.
Setting Styles
The styles only have any effect by calling the postscript functions provided in the GraphStyle resource. They are all called initially by new. When using several styles at the same time it will be necessary to call one of the set_ methods to initialize the postscript variables before calling one of these functions to change the graphic state values.
line_inner
Sets the colour, width and dash pattern for a line.
line_outer
Sets the colour, width and dash pattern for a line's edge.
point_inner
Sets the colour and width for a point.
point_outer
Sets the colour and width for a point's edge.
bar_inner
Sets the colour and width for a bar.
bar_outer
Sets the colour and width for a bar's edge.
Drawing Functions
The functions which draw the shapes all remove 'x y' from the stack. They use a variable 'ppsize' which should be the total width of the shape.
make_plus
make_cross
make_dot
make_circle
make_square
make_diamond
BUGS
Using the compound colours yellow, mauve and cyan with other colours can have unpredictable results.
Using an auto colour with 'color => 0' fails to produce shades of grey.
AUTHOR
Chris Willmot, chris@willmot.org.uk
SEE ALSO
2 POD Errors
The following errors were encountered while parsing the POD:
- Around line 575:
'=item' outside of any '=over'
- Around line 697:
You forgot a '=back' before '=head3'