NAME

SVG::Grid - Address SVG images using cells of $n1 x $n2 pixels

Synopsis

This is scripts/synopsis.pl:

#!/usr/bin/env perl

use strict;
use utf8;
use warnings;

use SVG::Grid;

# ------------

my($cell_width)   = 40;
my($cell_height)  = 40;
my($x_cell_count) =  3;
my($y_cell_count) =  3;
my($x_offset)     = 40;
my($y_offset)     = 40;
my($svg)          = SVG::Grid -> new
(
	cell_width   => $cell_width,
	cell_height  => $cell_height,
	x_cell_count => $x_cell_count,
	y_cell_count => $y_cell_count,
	x_offset     => $x_offset,
	y_offset     => $y_offset,
);

$svg -> frame('stroke-width' => 3);
$svg -> text
(
	'font-size'   => 20,
	'font-weight' => '400',
	text          => 'Front Garden',
	x             => $svg -> x_offset,     # Pixel co-ord.
	y             => $svg -> y_offset / 2, # Pixel co-ord.
);
$svg -> text
(
	'font-size'   => 14,
	'font-weight' => '400',
	text          => '--> N',
	x             => $svg -> width - 2 * $svg -> cell_width, # Pixel co-ord.
	y             => $svg -> y_offset / 2,                   # Pixel co-ord.
);
$svg -> grid(stroke => 'blue');
$svg -> image_link
(
	href   => 'http://savage.net.au/Flowers/Chorizema.cordatum.html',
	image  => 'http://savage.net.au/Flowers/images/Chorizema.cordatum.0.jpg',
	show   => 'new',
	title  => 'MouseOver® an image',
	x      => 1, # Cell co-ord.
	y      => 2, # Cell co-ord.
);
$svg -> rectangle_link
(
	href   => 'http://savage.net.au/Flowers/Alyogyne.huegelii.html',
	show   => 'new',
	title  => 'MouseOver™ a rectangle',
	x      => 2, # Cell co-ord.
	y      => 3, # Cell co-ord.
);
$svg -> text_link
(
	href   => 'http://savage.net.au/Flowers/Aquilegia.McKana.html',
	stroke => 'rgb(255, 0, 0)',
	show   => 'new',
	text   => '3,1',
	title  => 'MouseOvér some text',
	x      => 3, # Cell co-ord.
	y      => 1, # Cell co-ord.
);
$svg -> write(output_file_name => 'data/synopsis.svg');

Output: http://savage.net.au/assets/images/articles/synopsis.svg

Description

SVG::Grid allows you to mostly use cell co-ordinates (like a spreadsheet) to place items on an SVG image. These co-ordinates are in the form (x, y) = (integer, integer), where x and y refer to the position of a cell within a row and a column. You define these rows and columns when you call the "new(%options)" method. Cell co-ordinates are numbered 1 .. N.

Here, mostly means all method calls except adding text via the "text(%options)]" method. With text(), you use pixels locations so that the text can be placed anywhere. Pixel co-ordinates are numbered 0 .. N.

Note: Objects of type SVG::Grid are not daughters of SVG. They are stand-alone objects.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Installation

Install SVG::Grid as you would any Perl module:

Run:

cpanm SVG::Grid

or run:

sudo cpan SVG::Grid

And then:

perl Makefile.PL
make (or dmake or nmake)
make test
make install

Constructor and Initialization

new() is called as my($svg) = SVG::Grid -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type SVG::Grid.

Key-value pairs accepted in the parameter list (see corresponding methods for details [e.g. "text(%options)"]:

o cell_height => $integer

The height of each cell, in pixels.

Default: 40.

o cell_width => $integer

The width of each cell, in pixels.

Default: 40.

o colors => $hashref

The set of default colors, so you don't have to provide a color parameter to various methods.

It also means you can refer to colors by their names, rather than the awkward 'rgb($R, $G, $B)' structures that the SVG module uses.

Default:

$self -> colors
({
	black     => 'rgb(  0,   0,   0)',
	blue      => 'rgb(  0,   0, 255)',
	dimgray   => 'rgb(105, 105, 105)',
	indianred => 'rgb(205,  92,  92)',
	red       => 'rgb(255,   0,   0)',
	silver    => 'rgb(192, 192, 192)',
	white     => 'rgb(255, 255, 255)',
});

o output_file_name =>

The name of the SVG file to write, if the "write(%options)" method is called.

Default: ''.

o style => $hashref

The default style to use, so you don't have to provide a style parameter to various methods.

Default:

$self -> style
({
	'fill-opacity'	=> 0,
	font            => 'Arial',
	'font-size'     => 14,
	'font-weight'   => 'normal',
	stroke          => 'rgb(0, 0, 0)',
	'stroke-width'  => 1,
});

o x_cell_count => $integer

The number of cells aross the SVG.

Each cell will be cell_width pixels wide.

Default: 30.

o x_offset => $integer

The distance between the left and right sides of the SVG and the co-ordinate grid, in pixels.

Default: 40.

o y_cell_count => $integer

The number of cells down the SVG.

Each cell will be cell_height pixels high.

Default: 30.

o y_offset => $integer

The distance between the top and bottom sides of the SVG and the co-ordinate grid, in pixels.

Methods

cell_height()

Gets the height of each cell, in pixels.

cell_height is a parameter to "new()".

cell_width()

Gets the width of each cell, in pixels.

cell_width is a parameter to "new()".

colors([$hashref])

Here, [] indicates an optional parameter.

Gets or sets the default hashref of colors.

colors is a parameter to "new()".

frame([%options])

Draws the frame.

This method uses these keys in %options:

o fill-opacity: Default: 0.
o stroke: Default: 'rgb(105, 105, 105)' aka dimgray.
o stroke-width: Default: 1.

grid(%options)

Draws a grid onto the SVG.

This method uses these keys in %options:

o font-size: Default: 14.
o stroke: Default: 'rgb(105, 105, 105)' aka dimgray.
o stroke-width: Default: 1;
o text_color: Default: 'rgb(0, 0, 255)' aka blue.

height()

Returns the calculated height, in pixels, of the SVG.

image_link(%options)

Places an image onto the SVG and makes it clickable.

This method uses these keys in %options:

o href => $url

This is the link you are taken to if you click in the specified image. Sample:

href => 'http://savage.net.au/Flowers/Chorizema.cordatum.html'

o image => $url

This is the image which appears on the SVG, and which is made clickable. Sample:

image => 'http://savage.net.au/Flowers/images/Chorizema.cordatum.0.jpg'

o show => $string

For $string you must choose one of the SVG specification values: embed|new|none|other|replace.

The SVG specification for Behavior Attributes.

Note: The parameter passed to SVG is actually called -show.

Default: 'new'

'new' is similar to the effect achieved by the following HTML fragment:

<A HREF="http://www.example.org" target="_blank">...</A>

o title => $string.

This string, if not empty, is passed to SVG as the value of the -title parameter.

The effect is to activate a tooltip when you MouseOver the image.

o x => $integer

This is the cell # across the SVG.

Cell co-ordinates are numbered 1 .. N.

o y => $integer

This is the cell # down the SVG.

Cell co-ordinates are numbered 1 .. N.

output_file_name($string)

Here, [] indicates an optional parameter.

Gets or sets the name of the output file.

output_file_name is a parameter to "new()".

rectangle_link(%options)

Places a rectangle (which fills a cell) onto the SVG and makes it clickable.

This method uses these keys in %options:

o fill

Default: 'rgb(205, 92, 92)' aka indianred.

o fill-opacity

Default: 0.5.

o href => $url

This is the link you are taken to if you click in the rectangle specified by (x, y). Sample:

href => 'http://savage.net.au/Flowers/Alyogyne.huegelii.html'

o stroke

Default: 'rgb(105, 105, 105)' aka dimgray.

o show => $string

For $string you must choose one of the SVG specification values: embed|new|none|other|replace.

The SVG specification for Behavior Attributes.

Note: The parameter passed to SVG is actually called -show.

Default: 'new'

'new' is similar to the effect achieved by the following HTML fragment:

<A HREF="http://www.example.org" target="_blank">...</A>

o title => $string.

This string, if not empty, is passed to SVG as the value of the -title parameter.

The effect is to activate a tooltip when you MouseOver the rectangle.

o x => $integer

This is the cell # across the SVG.

Cell co-ordinates are numbered 1 .. N.

o y => $integer

This is the cell # down the SVG.

Cell co-ordinates are numbered 1 .. N.

style([$hashref])

Here, [] indicates an optional parameter.

Gets or sets the default hashref of styles.

style is a parameter to "new()".

svg()

Returns the internal SVG object.

text(%options)

Places a text string onto the SVG.

Warning: This method uses (x, y) in pixels.

This method uses these keys in %options:

o fill-opacity

Default: 0.

o font-size

Default: 14.

o font-weight

Default: 'normal'.

o stroke

Default: 'rgb(105, 105, 105)' aka dimgray.

o x => $integer

This is the pixel # across the SVG.

Pixel co-ordinates are numbered 0 .. N.

o y => $integer

This is the pixel # down the SVG.

Pixel co-ordinates are numbered 0 .. N.

text_link(%options)

Places a text string onto the SVG and makes it clickable.

The clickable area is just the text. The remainer of the cell does not respond to the click.

This method uses these keys in %options:

o fill-opacity

Default: 0.

o font-size

Default: 14.

o font-weight

Default: 'normal'.

o href => $url

This is the link you are taken to if you click in the text in the cell specified by (x, y). Sample:

href => 'http://savage.net.au/Flowers/Aquilegia.McKana.html'

o stroke

Default: 'rgb(105, 105, 105)' aka dimgray.

o stroke-width

Default: 1.

o show => $string

For $string you must choose one of the SVG specification values: embed|new|none|other|replace.

The SVG specification for Behavior Attributes.

Note: The parameter passed to SVG is actually called -show.

Default: 'new'

'new' is similar to the effect achieved by the following HTML fragment:

<A HREF="http://www.example.org" target="_blank">...</A>

o text => $string

This is the text which will be written into the cell and made clickable.

o title => $string.

This string, if not empty, is passed to SVG as the value of the -title parameter.

The effect is to activate a tooltip when you MouseOver the rectangle.

o x => $integer

This is the cell # across the SVG.

Cell co-ordinates are numbered 1 .. N.

o y => $integer

This is the cell # down the SVG.

Cell co-ordinates are numbered 1 .. N.

width()

Returns the calculated width, in pixels, of the SVG.

write(%options)

Writes the SVG to the file name passed to "new(%options)" or passed to write(). The latter value has priority.

x_cell_count()

Gets the count of cells horizontally.

x_cell_count is a parameter to "new()".

x_offset()

Gets the horizontal gap between the edges of the SVG and the grid.

x_offset is a parameter to "new()".

y_cell_count()

Gets the count of cells vertically.

y_cell_count is a parameter to "new()".

y_offset()

Gets the vertical gap between the edges of the SVG and the grid.

y_offset is a parameter to "new()".

FAQ

Does this module support Unicode?

Yes. The "write(%options)" method uses an encoding of UTF-8 on the output file handle.

Note: To use Unicode, you must include 'use utf8;' in your programs. See scripts/synopsis.pl.

Does this module support tootips via MouseOver?

Yes. Just search this document for 'MouseOver'.

Does this module use the SVG 'g' element?

No. This means there is no grouping done by default. Nevertheless, you can call "svg()" to get the internal SVG object, and use 'g' yourself at any time.

See https://www.w3.org/TR/SVG11/struct.html#Groups for details of the 'g' element.

How does this module handle duplicate element ids?

By using method parameters to generate a hopefully-unique id. This line copied from the "image_link(%options)" method shows the general technique I've used:

id => "image_$options{x}_$options{y}", # Try to make it unique.

Is there any difference between `fill` and `stroke` for text?

I don't think so, but I have had some odd results. Ultimately, you need to read the docs for the SVG module to see what it expects.

Is there any way to hide the coordinate numbering system?

Not in V 1.00. However, it is on the TODO list.

Machine-Readable Change Log

The file Changes was converted into Changelog.ini by Module::Metadata::Changes.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Repository

https://github.com/ronsavage/SVG-Grid

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=SVG::Grid.

Author

SVG::Grid was written by Ron Savage <ron@savage.net.au> in 2016.

My homepage: http://savage.net.au/

Copyright and Licence

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Perl License, a copy of which is available at:
http://dev.perl.org/licenses/

To install SVG::Grid, copy and paste the appropriate command in to your terminal.

cpanm

cpanm SVG::Grid

CPAN shell

perl -MCPAN -e shell
install SVG::Grid

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

Synopsis

Description

Distributions

Installation

Constructor and Initialization

Methods

cell_height()

cell_width()

colors([$hashref])

frame([%options])

grid(%options)

height()

image_link(%options)

output_file_name($string)

rectangle_link(%options)

style([$hashref])

svg()

text(%options)

text_link(%options)

width()

write(%options)

x_cell_count()

x_offset()

y_cell_count()

y_offset()

FAQ

Does this module support Unicode?

Does this module support tootips via MouseOver?

Does this module use the SVG 'g' element?

How does this module handle duplicate element ids?

Is there any difference between fill and stroke for text?

Is there any way to hide the coordinate numbering system?

See Also

Machine-Readable Change Log

Version Numbers

Repository

Support

Author

Copyright and Licence

Module Install Instructions

Is there any difference between `fill` and `stroke` for text?