1% File src/library/grid/man/grid.add.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2007 R Core Team
4% Distributed under GPL 2 or later
5
6\name{grid.add}
7\alias{grid.add}
8\alias{addGrob}
9\alias{setChildren}
10\title{Add a Grid Graphical Object}
11\description{
12  Add a grob to a gTree or a descendant of a gTree.
13}
14\usage{
15grid.add(gPath, child, strict = FALSE, grep = FALSE,
16         global = FALSE, allDevices = FALSE, redraw = TRUE)
17
18addGrob(gTree, child, gPath = NULL, strict = FALSE, grep = FALSE,
19        global = FALSE, warn = TRUE)
20
21setChildren(x, children)
22}
23\arguments{
24  \item{gTree, x}{A gTree object.}
25  \item{gPath}{ A gPath object. For \code{grid.add} this
26    specifies a gTree on the display list.  For \code{addGrob} this
27    specifies a descendant of the specified gTree. }
28  \item{child}{ A grob object. }
29  \item{children}{ A gList object. }
30  \item{strict}{ A boolean indicating whether the gPath must be
31    matched exactly. }
32  \item{grep}{A boolean indicating whether the \code{gPath} should
33    be treated as a regular expression.  Values are recycled across
34    elements of the \code{gPath} (e.g., \code{c(TRUE, FALSE)} means
35    that every odd element of the \code{gPath} will be treated as
36    a regular expression).
37  }
38  \item{global}{ A boolean indicating whether the function should affect
39    just the first match of the \code{gPath}, or whether all matches
40    should be affected.
41  }
42  \item{warn}{A logical to indicate whether failing to find the
43    specified gPath should trigger an error.  }
44  \item{allDevices}{ A boolean indicating whether all open devices
45    should
46    be searched for matches, or just the current device.
47    NOT YET IMPLEMENTED.
48  }
49  \item{redraw}{A logical value to indicate whether to redraw the grob. }
50}
51\details{
52  \code{addGrob} copies the specified grob and returns a modified
53  grob.
54
55  \code{grid.add} destructively modifies a grob on the display list.
56  If \code{redraw}
57  is \code{TRUE} it then redraws everything to reflect the change.
58
59  \code{setChildren} is a basic function for setting all children
60  of a gTree at once (instead of repeated calls to \code{addGrob}).
61}
62\value{
63  \code{addGrob} returns a grob object;  \code{grid.add} returns \code{NULL}.
64}
65\author{Paul Murrell}
66\seealso{
67  \code{\link{grob}}, \code{\link{getGrob}},
68  \code{\link{addGrob}}, \code{\link{removeGrob}}.
69}
70\keyword{dplot}
71