If this parameter is NULL or "", a list
containing the SVG document, coordinate information, and JavaScript
utility functions are returned.
exportCoords
If this parameter is not none a coordinates file is exported.
If this parameter is file, the coordinates information is
written to a file, while inline will include the contents
within the SVG document.
exportMappings
If this parameter is not none a mapping file is exported.
If this parameter is file, the mapping information is written
to a file, while inline will include the contents within the
SVG document.
exportJS
If this parameter is not none a JavaScript file is written out.
This contains useful functions for manipulating gridSVG plots in the
browser, including unit conversion functions.
If this parameter is file, the JavaScript file is written to
a file, while inline will include the contents within the SVG
document.
res
The device resolution to print at (in DPI).
If NULL, this is automatically calculated to be the
resolution of the current device. Typically the PDF device would be
used, and this uses a resolution of 72, i.e. 72 DPI.
prefix
A prefix to apply to all generated SVG ID attributes. Useful for
ensuring unique IDs when many SVG images exist within the same HTML
document.
If a valid prefix has been given, the root <svg> element will
be given an ID attribute with the prefix as its value.
addClasses
If TRUE, adds an SVG class attribute to all grobs and
viewports which holds the value of the class of the grob or
viewport. If the class attribute already exists (via
grid.garnish or grid.element), the
resulting SVG class attribute will be the union of the existing
class attribute and the grob/viewport classes.
indent
Determines whether the resulting SVG document will be exported with
indentation present.
Indentation makes the document more readable, but when indent
is set to FALSE, parsing the SVG in JavaScript is easier
because there are no empty text nodes.
htmlWrapper
If TRUE, saves a wrapping HTML file. This file contains a
snippet of HTML which links to the exported SVG file.
usePaths
If this parameter is set to vpPaths, then when writing out
viewports gridSVG will set the SVG element ID to the current
vpPath instead of the current viewport name.
If this parameter is set to gPaths, gridSVG will set the
names of grobs to be the current gPath instead of the current
grob name.
When none, viewports and grobs will not incorporate paths.
When both, viewports and grobs will both use paths.
uniqueNames
If TRUE, gridSVG will make an attempt to produce unique grob
names. Unique id attributes are required for valid SVG. It is
highly recommended that mapping information is used when this
parameter is TRUE.
annotate
If TRUE, an SVG metadata element will be introduced directly
below the root <svg> element. This element contains XML that
describes the information that gridSVG used to draw the image
(mostly arguments to grid.export). This output may be useful
for debugging purposes.
progress
If TRUE, messages will be displayed in the console that show
how quickly gridSVG is progressing when exporting an SVG image. This
is particularly useful when there are large images being exported so
we have a reasonable estimate of how long exporting will take.
compression
An integer between 0 and 9 indicating the level of (gzip)
compression applied to the SVG image when it is saved to a
file. Higher values of compression indicate smaller file
sizes at the expense of increased computation.
strict
A logical indicating whether checks should be made that all
attributes added to SVG elements are valid. If this is
TRUE and invalid attributes are detected, those
attributes are removed, with a warning.
rootAttrs
A named character vector containing attributes for the top-level
<svg> element.
xmldecl
This parameter sets the XML declaraction that will be applied to the
SVG document.
By default this parameter simply declares that the document is XML
version 1.0, along with the character encoding that was used to
export the SVG document.
If xmldecl is NULL, then no XML declaration is
printed. This may be useful when you want only the SVG document and
nothing more.
Details
The uniqueNames parameter is set to TRUE by default in
order to ensure that each SVG element ID is unique. This is a
requirement of XML (which SVG is based on). This differs from
usePaths because usePaths can still generate names that
are not unique (there are several ways for this to
happen). uniqueNames modifies grob and viewport names with a
numeric suffix to ensure uniqueness. When FALSE, only grob
names will be kept unmodified because modifying viewport names would
affect coordinate information.
Occasionally the XML package can report warnings, despite valid SVG
being produced. If spurious warnings are being produced, set
options(gridSVGWarnings = FALSE) to ignore them.
See the files in the directory gridSVG/tests for examples
of things that can be done. See the file gridSVG/doc/overview.tex
for limitations.
Value
When name has a valid filename the side effect is to produce an
SVG file of the specified name.
Optionally a JavaScript file containing coordinate transformation
information is also exported.
Optionally a JavaScript file containing name mapping information is
also exported.
Optionally a JavaScript file containing utility JavaScript functions
is also exported.
When name has a filename with zero characters, a named list is
returned with four elements. svg is the SVG root node (and all
its children, see the XML package for more information on how to use
this. coords contains the list of coordinate information for
exported viewports. mappings is a list containing information
on how names have been modified during the exporting process.
utils is a character vector containing JavaScript code to
manipulate gridSVG plots in the browser.
This list is always returned but when a valid filename is given, it is
returned invisibly.