dynTextGrob {sisal}

Create Text with Changing Size

Description

This function creates a text object. When drawn, its size changes automatically according to the space available.

Usage

dynTextGrob(label, x = 0.5, y = 0.5, width = 1, height = 1,
            default.units = "npc", just = c(0.5, 0.5),
            hjust = NULL, vjust = NULL, rot = 0, rotJust = TRUE,
            rotHjust = NULL, rotVjust = NULL, resize = TRUE,
            sizingWidth = NULL, sizingHeight = NULL,
            adjustJust = TRUE, takeMeasurements = FALSE,
            name = NULL, gp = gpar(), vp = NULL)

Arguments

label

a character or expression vector, or a list containing both character strings and mathematical expressions. These are the text items to be drawn.

x

a numeric vector or unit of x locations for the labels.

y

a numeric vector or unit of y locations for the labels.

width

the space available for the labels in the width direction of the viewport. Used for computing the fontsize.

height

the space available for the labels in the height direction of the viewport. Used for computing the fontsize.

default.units

default unit to use when dimensions or locations are unitless numbers. See unit.

just

a numeric or character vector with one or two elements for setting the same justification for all labels. See textGrob.

hjust

a numeric vector for setting horizontal justification of individual labels. If given, overrides just.

vjust

a numeric vector for setting vertical justification of individual labels. If given, overrides just.

rot

a numeric vector for setting the rotation angle of individual labels in degrees.

rotJust

a logical vector which affects the justification of individual labels. If an element is FALSE, the corresponding label is first justified according to hjust (reading direction) and vjust (the perpendicular direction), then rotated. This is the way a textGrob works. If an element is TRUE, the concept is: align the label with the other labels according to rotHjust (reading direction) and rotVjust (the perpendicular direction), then rotate, and finally justify in the width and height directions of the viewport with hjust and vjust, respectively.

rotHjust

a numeric vector or NULL. When the corresponding element of rotJust is TRUE, rotHjust sets the justification of a label in the reading direction. If NULL or an NA element is encountered, an automatic value will be computed based on rotation angle (rot) and justification along the viewport axes (just, hjust and vjust).

rotVjust

a numeric vector or NULL. Set the justification of labels perpendicular to the reading direction when rotJust is TRUE. See rotHjust.

resize

a logical flag. If TRUE (the default), the fontsize of the labels will be adjusted according to the space available. If FALSE, the size will remain constant, even if the graphical object is drawn in a viewport with a different setting for the "cex" graphical parameter.

sizingWidth

If resize is TRUE, a numeric value given here sets the width of the grob used when calculating fontsize at drawing time. If NULL (the default), the size is computed from the actual dimensions of the labels.

sizingHeight

See sizingWidth, only height instead of width.

adjustJust

A logical flag. If TRUE (the default), adjustments are made to the justification of the labels instead of passing the justification settings straight to the underlying textGrob(s). The justification of labels given in expression form will be unified with the justification of character labels, meaning that a setting of vjust = 0 will align the baselines of the labels and vjust = 1 will align the labels at lineheight, or at a multiple of lineheight in case of multiline character labels. The labels will also be shifted so that there is room for descenders.

takeMeasurements

A logical flag. If TRUE, only measurements of labels will be returned instead of a graphical object. An example of where this might be useful is when several labels should have the same fontsize but different graphical parameters such as color, or when the labels should be drawn in different viewports. See the source of sisalTable, particularly makeContent.sisalTable, for an example. If FALSE (the default) a graphical object will be returned.

name

a character string identifier for the graphical object returned by the function. If NULL (the default), a name will be assigned automatically.

gp

graphical parameters. See gpar.

vp

a "viewport" object, the name of a viewport object, a vpPath object pointing to a viewport or NULL (the default). If not NULL, this graphical object will be drawn in the given viewport. The name or the path must point to a descendant of the viewport that is current at drawing time. See current.vpPath, current.vpTree, downViewport and grid.draw.

Details

The number of labels created is the maximum of the lengths of x and y. Variables are recycled to that length if necessary.

All labels of one "dynText" grob have the same fontsize.

Value

If takeMeasurements is FALSE (the default), returns a grob of class "dynText". It can be drawn with grid.draw.

If takeMeasurements is TRUE, returns a list containing measurements of the labels.

Author(s)

Mikko Korpela

See Also

See function textGrob in package grid.

Examples

library(grid)
grid.newpage()
grid.draw(dynTextGrob("Hello", vjust = 0, y = 0))
grid.draw(dynTextGrob(list(expression(y==x^2),
                           "Hello,\ntry resizing me!"),
                      x = rep(1, 2), y = 1, rot = -45,
                      hjust = 1, vjust = 1,
                      rotHjust = c(0, 1), rotVjust = 1))