R: Create a definition of a fill pattern.

Pattern Fills {gridSVG} | R Documentation

## 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`

[Package gridSVG version 1.6-0 Index]