NAME

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

VERSION

version 0.0000_03

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.

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 arrayrefs 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 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.

cpanm Graphics::Grid

perl -MCPAN -e shell
install Graphics::Grid