The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
SVG-Rasterize-0.003001
River stage zero No dependents
++
/ SVG::Rasterize::State

NAME

SVG::Rasterize::State - state of settings during traversal

VERSION

Version 0.002002

DESCRIPTION

An instance of this class saves one state during the traversal through an SVG tree. At encounter of a new child element the old state is pushed to a stack and retrieved later. A state saves the current transformation matrix, style settings and so on. Part of this functionality overlaps with the ability of Cairo to push its state onto a stack, but I do not want to entirely rely on that because I am not sure if everything can be handled in that way and also because future alternative backends might not have this feature.

This class is instanced only by SVG::Rasterize. The information of this document will mainly be interesting for maintainers of SVG::Rasterize and possibly for advanced users who want to write hooks.

INTERFACE

Constructors

new

  $state = SVG::Rasterize::State->new(%args)

Creates a new SVG::Rasterize::State object and calls init(%args). If you subclass SVG::Rasterize::State overload init, not new.

Supported arguments:

  • rasterize (mandatory): SVG::Rasterize object

  • parent (optional): the parent state object, always expected except for the root

  • node_name (mandatory): name of the current node

  • node_attributes (mandatory): HASH reference

  • node (optional): must offer a getChildren method if provided; unused except for children, but available for hooks

  • matrix (optional): must be an ARRAY reference if provided

Public Attributes

rasterize

Can only be set at construction time. Stores a weakened reference to the SVG::Rasterize object.

node

Can only be set at construction time. If the SVG data to rasterize are provided as an SVG object (or, in fact, some DOM object in general) this attribute stores the node object for which this state object was created. All processing (except children, see nextChild) uses the node_name and node_attributes attributes which are always present. It is also recommended that you use these instead of node wherever possible. For example, $node->getAttributes might be undefined or not normalized (see White Space Handling in SVG::Rasterize).

node_name

Can only be set at construction time. Stores the name of the current node even if node above is undef. If it differs from $node->getNodeName (usage not recommended), node_name is used.

node_attributes

Can only be set at construction time (any arguments to the accessor are silently ignored). Stores the attributes of the current node as a HASH reference even if node above is undef. The accessor does not create a copy of the hash, so changes will affect the hash stored in the object. This is on purpose to give you full control e.g. inside a hook. In case the node has no attributes an empty HASH reference is returned. If the content differs from $node->getAttributes (usage not recommended), node_attributes is used.

matrix

Readonly attribute (you can change the contents, of course, but this is considered a hack bypassing the interface). Stores an ARRAY reference with 6 numbers [a, b, c, d, e, f] such that the matrix

  ( a  c  e )
  ( b  d  f )
  ( 0  0  1 )

represents the map from coordinates in the current user coordinate system to the output pixel grid. See multiply_matrices in SVG::Rasterize for more background.

Before you use the matrix directly have a look at transform below.

Methods for Users

The distinction between users and developers is a bit arbitrary because these methods are only interesting for users who write hooks which makes them almost a developer.

map_length

  $state->map_length($length)

This method takes a length and returns the corresponding value in px according to the conversion rates described in the ADVANCED TOPICS section of SVG::Rasterize. Surrounding white space is not allowed.

Examples:

  $x = $rasterize->map_length('5.08cm');  # returns 180
  $x = $rasterize->map_length(10);        # returns 10
  $x = $rasterize->map_length('  1in ');  # error
  $x = $rasterize->map_length('50%')      # depends on context

Note that there is no $state->map_length($number, $unit) interface like in map_abs_length in SVG::Rasterize. It can be added on request.

Currently, relative units are not supported.

transform

  ($x_abs, $y_abs) = $state->transform($x, $y)

Takes an x and a y coordinate and maps them from the current user space to the output pixel coordinate system using the current value of matrix. $x and $y can be numbers or lengths (see Lengths versus Numbers in SVG::Rasterize).

Methods for Subclass Developers

init

See new for a description of the interface. If you overload init, your method should also call this one.

nextChild

  $node = $state->nextChild

This method only works when traversing through a DOM tree. When the state object is instantiated it saves references to all children in a list. This method shifts from this list and returns the result. If the list is exhausted (or has never been filled because there was no node object) then it returns undef.

multiply_matrices

Alias to multiply_matrices in SVG::Rasterize. The alias is established via the typeglob:

  *multiply_matrices = \&SVG::Rasterize::multiply_matrices;

DIAGNOSTICS

Exceptions

Not documented, yet. Sorry.

Warnings

Not documented, yet. Sorry.

BUGS AND LIMITATIONS

No bugs have been reported. Please report any bugs or feature requests to bug-svg-rasterize at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SVG-Rasterize. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.

INTERNALS

Private Attributes

  • _parent

    Stores a weakened reference to the parent state object. This attribute should maybe become public readonly for use in hooks.

Internal Methods

These methods are just documented for myself. You can read on to satisfy your voyeuristic desires, but be aware of that they might change or vanish without notice in a future version.

  • _process_node

    Called after creation of the state object. Checks for relevant attributes and processes them.

    Does not take any arguments and does not return anything.

  • _process_transform_attribute

    Parses the string given in a transform attribute and sets the matrix attribute accordingly.

    Does not take any parameters and does not return anything. Expects that $self->{matrix} is set properly (which it is in _process_node).

  • _process_viewBox_attribute

    Parses the viewBox and preserveAspectRatio attributes (if present) of the current node and modifies the current transformation matrix accordingly.

    Does not take any parameters and does not return anything. Expects that $self->{matrix} is set properly (which it is in _process_node).

  • _process_style_properties

    Creates a hash with current style properties which are taken from (in order of decreasing preference) the style attribute or the respective property attribute or (if inheritable) from the parent state or from the hash of default values in SVG::Rasterize::Properties.

    Does not take any arguments. Returns the properties HASH reference.

AUTHOR

Lutz Gehlen, <perl at lutzgehlen.de>

LICENSE AND COPYRIGHT

Copyright 2010 Lutz Gehlen.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.