1% File src/library/grid/man/grid.edit.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.edit}
7\alias{grid.edit}
8\alias{grid.gedit}
9\alias{editGrob}
10\title{Edit the Description of a Grid Graphical Object}
11\description{
12  Changes the value of one of the slots of a grob
13 and redraws the grob.
14}
15\usage{
16grid.edit(gPath, ..., strict = FALSE, grep = FALSE,
17          global = FALSE, allDevices = FALSE, redraw = TRUE)
18
19grid.gedit(..., grep = TRUE, global = TRUE)
20
21editGrob(grob, gPath = NULL, ..., strict = FALSE, grep = FALSE,
22         global = FALSE, warn = TRUE)
23}
24\arguments{
25  \item{grob}{A grob object.}
26  \item{\dots}{Zero or more named arguments specifying new slot values.}
27  \item{gPath}{ A gPath object. For \code{grid.edit} this
28    specifies a grob on the display list.  For \code{editGrob} this
29    specifies a descendant of the specified grob. }
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{editGrob} copies the specified grob and returns a modified
53  grob.
54
55  \code{grid.edit} 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  Both functions call \code{editDetails} to allow a grob to perform
60  custom actions and \code{validDetails} to check that the modified grob
61  is still coherent.
62
63  \code{grid.gedit} (\code{g} for global) is just a convenience wrapper for
64  \code{grid.edit} with different defaults.
65}
66\value{
67  \code{editGrob} returns a grob object;  \code{grid.edit} returns \code{NULL}.
68}
69\author{Paul Murrell}
70\seealso{
71  \code{\link{grob}}, \code{\link{getGrob}},
72  \code{\link{addGrob}}, \code{\link{removeGrob}}.
73}
74\examples{
75grid.newpage()
76grid.xaxis(name = "xa", vp = viewport(width=.5, height=.5))
77grid.edit("xa", gp = gpar(col="red"))
78# won't work because no ticks (at is NULL)
79try(grid.edit(gPath("xa", "ticks"), gp = gpar(col="green")))
80grid.edit("xa", at = 1:4/5)
81# Now it should work
82try(grid.edit(gPath("xa", "ticks"), gp = gpar(col="green")))
83}
84\keyword{dplot}
85