Pattern Fills {gridSVG}

Create a definition of a fill pattern.

Description

A feature of SVG is that elements can be filled with a pattern that is defined somewhere in the document. The purpose of these functions is to create the definition of a fill pattern so that it can be referred to by grobs drawn by gridSVG.

Usage

pattern(grob,
        x = unit(0, "npc"), y = unit(0, "npc"),
        width = unit(0.1, "npc"), height = unit(0.1, "npc"),
        default.units = "npc",
        just = "centre", hjust = NULL, vjust = NULL,
        dev.width = 7, dev.height = 7)
registerPatternFill(label, pattern = NULL, ...)
registerPatternFillRef(label, refLabel, pattern = NULL, ...)

Arguments

label

A character identifier for the definition.

refLabel

A character identifier referring to an existing pattern definition that has been created by registerPatternFill.

pattern

A pattern object created by pattern.

grob

A grid grob or tree of grobs.

x

A numeric vector or unit object specifying x-location.

y

A numeric vector or unit object specifying y-location.

width

A numeric vector or unit object specifying width.

height

A numeric vector or unit object specifying height.

just

The justification of the pattern relative to its (x, y) location. If there are two values, the first value specifies horizontal justification and the second value specifies vertical justification. Possible string values are: "left", "right", "centre", "center", "bottom", and "top". For numeric values, 0 means left alignment and 1 means right alignment.

hjust

A numeric vector specifying horizontal justification. If specified, overrides the just setting.

vjust

A numeric vector specifying vertical justification. If specified, overrides the just setting.

default.units

A string indicating the default units to use if x, y, width, or height are only given as numeric vectors.

dev.width, dev.height

The width and height of the fill pattern's graphics region in inches. The default values are 7.

...

Arguments to be be passed onto pattern.

Details

The pattern fill is drawn off-screen on a new device. The size of this device is determined by dev.width and dev.height. The grob and vp that have been given are then drawn within this device. This is relevant for determining what the pattern definition looks like.

The previous arguments do not determine the size of the pattern as it is being used (i.e. how big each "tile" is). This is set by the x, y, width, height arguments. The values of these arguments are relative to the current viewport as this function is being called. From then on, the definition of the location and size of the pattern are fixed.

In summary, the pattern function defines what a pattern looks like, along with how big each tile is (and its position).

To avoid repetition of pattern definitions, use registerPatternFillRef to reuse an existing pattern definition (referred to by refLabel). This means that a pattern "tile" can now be reused, repositioned and rescaled without having to describe how it needs to be drawn.

In general use, first create a pattern object, then either give a label to the definition (for grobs to use), or alternatively simply pass on the pattern object to grid.patternFill.

Value

A pattern object for pattern, none otherwise.

Author(s)

Simon Potter

See Also

grid.patternFill