Lutz Gehlen > SVG-Rasterize-0.003008 > SVG::Rasterize::State

Download:
SVG-Rasterize-0.003008.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.003007   Source  

NAME ^

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

VERSION ^

Version 0.003007

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:

Public Attributes

parent

Can only be set at construction time. Stores a reference to the parent state object.

rasterize

Can only be set at construction time. Stores a 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 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).

This attribute is only provided for use in hooks. Note that it is not validated. If set at all it holds a blessed reference, but nothing else is checked (within this class).

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.

cdata

Can only be set on construction time. If the node is a character data node, those character data can be stored in here.

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.

defer_rasterization

Readonly attribute. Some elements (namely text elements) can only be rasterized once their entire content is known (e.g. for alignment issues). If an SVG::Rasterize::State object is initialized with such an element or if the parent state is deferring rasterization then this attribute is set to 1 at construction time. The content is then only rasterized once the root element of this subtree (i.e. the element whose parent is not deferring) is about to run out of scope.

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 Developers

init

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

multiply_matrices

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

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

shift_child_node

  $node = $state->shift_child_node

Shifts an element from the child_nodes list and returns it. This list has been populated (or not) at construction time via the child_nodes argument. This will usually only be the case if we are traversing through a DOM tree. If the list is exhausted (or has never been filled) then undef is returned.

Note that the elements of the child_nodes list have not been validated at all as they are not used within this object. They can be anything that has been provided at construction time.

process_node_extra

This method is named without an underscore and mentioned here because it is available for overloading. Logically, it rather belongs to the _process_... methods described under Internal Methods.

Called by _process_node at the very end, does nothing. Only available for overloading to enable subclasses to perform special processing (see e.g. SVG::Rasterize::State::Text).

DIAGNOSTICS ^

Exceptions

Not documented, yet. Sorry.

Warnings

Not documented, yet. Sorry.

INTERNALS ^

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.

AUTHOR ^

Lutz Gehlen, <perl at lutzgehlen.de>

LICENSE AND COPYRIGHT ^

Copyright 2010-2011 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.

syntax highlighting: