/ 
Graphics-Grid-0.001
River stage zero No dependents
/ Graphics::Grid::GPar

NAME

Graphics::Grid::GPar - Graphical parameters used in Graphics::Grid

VERSION

version 0.001

SYNOPSIS

use Graphics::Grid::GPar;
my $gp1 = Graphics::Grid::GPar->new(col => "red", lwd => 2);

# or use the function interface
use Graphics::Grid::Functions qw(:all);
my $gp2 = gpar(col => ["blue", "red"], lty => "solid", fontsize => 16));

DESCRIPTION

This class represents the set of graphical parameter settings used in Graphics::Grid.

All grid viewports and graphical objects have an attribute called "gp", which is an object of this Graphics::Grid::GPar class. When a viewport is pushed onto the viewport stack and when a graphical object is drawn, the graphical parameters are enforced in such a way that a Graphics::Grid::GPar object, which is merged from the "gp" attribute of the graphical object and the current viewport, would have effect on the graphical output.

The default parameter settings are defined by the ROOT viewport, which takes its settings from the graphics device. These defaults may differ between devices.

Valid parameter names are:

  • col

    Colour for lines and borders. Stored values are objects of Graphics::Color::RGB.

  • fill

    Colour for filling rectangles, polygons, etc. Like col, stored values are objects of Graphics::Color::RGB.

  • alpha

    Alpha channel for transparency. During drawing the alpha setting is combined with the alpha channel for individual colours, like col and fill, by multiplying.

    This parameter is cumulative. If a viewport is pushed with a alpha of 0.5 then another viewport is pushed with a alpha of 0.5, the effective alpha is 0.25.

  • lty

    Line type. Allowed values are "blank", "solid", "dashed", "dotted", "dotdash", "longdash", "twodash".

  • lwd

    Line width.

  • lex

    Multiplier applied to line width. The effective line width is lwd*lex.

    This parameter is cumulative like alpha mentioned above.

  • lineend

    Line end style. Allowed values are "round", "butt", "square".

  • linejoin

    Line join style. Allowed values are "round, "mitre", "bevel".

  • linemitre

    Line mitre limit (number >= 1).

  • fontsize

    The size of text (in points).

  • fontfamily

    The font family (as a string).

  • fontface

    The font face. Allowed values are "plain", "bold", "italic", "oblique", and "bold_italic".

  • lineheight

    The height of a line as a multiple of the size of text

  • cex

    Multiplier applied to fontsize. The effective size of text is fontsize*cex. The size of a line is fontsize*cex*lineheight.

    This parameter is cumulative like alpha mentioned above.

All parameter values in object of this class are stored in arrayrefs, so they can be multiple values that represents settings for multiple components of a graphical object. The constructor of the class is designed in such a way that for each parameter you can specify either a single value or an arrayref of values. See below CONSTRUCTOR section for details.

Also note that dependending on the device driver implementation, some of the parameters may not be effective. For example, lineheight is not effective with Graphics::Grid::Driver::Cairo.

CLASS METHODS

names()

METHODS

at($idx)

This method returns an object of the same Graphics::Grid::GPar class. The returned object has at most one value for each of the parameters.

my $gp1 = Graphics::Grid::GPar->new(lwd => [2,3,4], lty => "solid");

# below is same as Graphics::Grid::GPar->new(lwd => 3, lty => "solid");
my $gp2 = $gp1->at(1);

$idx is applied like wrap-indexing. So below is same as above.

my $gp3 = $gp1->at(4);

merge($another_gp)

This method merges two gp objects and returns a merged new object.

my $gp_merged = $gp1->merge($gp2);

The merge is done is this way:

For a non-cumulative parameter, it would try to get value from the first object (let's say $gp1), and fallbacks to the second object ($gp2). If both the parameter is not defined in any of $gp1 and $gp2, the merged object would not have this parameter either. For example,

my $gp1 = Graphics::Grid::GPar->new(col => 'red');
my $gp2 = Graphics::Grid::GPar->new(col => 'green', fill => 'blue');

# the result of $gp1->merge($gp2) would be same as
Graphics::Grid::GPar->new(col => 'red', fill => 'blue');

For a cumulative parameter, the values of $gp1 and $gp2 are multiplied. If the array refs in $gp1 and $gp2 are not of same length, the shorter one would be padded with 1 when multiplying. That is,

my $gp1 = Graphics::Grid::GPar->new(lex => [1, 2, 3]);
my $gp2 = Graphics::Grid::GPar->new(lex => [1, 2]);

# the result of $gp1->merge($gp2) would be same as
Graphics::Grid::GPar->new(lex => [1, 4, 3]);

CONSTRUCTOR

All parameters for the constructor can be either a single value or an arrayref.

# below two are same
Graphics::Grid::GPar->new(lwd => 2);
Graphics::Grid::GPar->new(lwd => [2]);

# via the arrayref form you can specify multiple values for a parameter
Graphics::Grid::GPar->new(lwd => [2,3,4]);

col and fill also accepts string of color name or hex form.

# below ones are same
Graphics::Grid::GPar->new(col => "black");
Graphics::Grid::GPar->new(col => "#000000");
Graphics::Grid::GPar->new(
        col => Graphics::Color::RGB->new(red => 0, green => 0, blue => 0));
Graphics::Grid::GPar->new(col => ["black"]);
Graphics::Grid::GPar->new(col => ["#000000"]);
Graphics::Grid::GPar->new(
        col => [ Graphics::Color::RGB->new(red => 0, green => 0, blue => 0) ]);

Different parameters do not have to be of same arreyref length. In fact the parameters, when they are used in drawing, are wrap-indexed. That is, no matter a parameter is initialized by a single value or an array ref of multiple values, a device driver may use a parameter value as if it is an circular array indexed like $real_idx = $given_idx % $size_of_arrayref.

# below two are same
Graphics::Grid::GPar->new(lwd => [2,3,4], lty => "solid");
Graphics::Grid::GPar->new(lwd => [2,3,4], lty => ["solid", "solid", "solid"]);

# and they could be equivalent to
Graphics::Grid::GPar->new(lwd => [2,3,4,2], lty => [("solid") x 4]);
Graphics::Grid::GPar->new(lwd => [2,3,4,2,3], lty => [("solid") x 5]);
Graphics::Grid::GPar->new(lwd => [2,3,4,2,3,4], lty => [("solid") x 6]);
...

SEE ALSO

Graphics::Grid

Graphics::Grid::Functions

Graphics::Grid::Driver

Graphics::Color::RGB

AUTHOR

Stephan Loyd <sloyd@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018-2023 by Stephan Loyd.

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