| % File src/library/grid/man/grid.reorder.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2007 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{grid.reorder} |
| \alias{grid.reorder} |
| \alias{reorderGrob} |
| \title{ Reorder the children of a gTree } |
| \description{ |
| Change the order in which the children of a gTree get drawn. |
| } |
| \usage{ |
| grid.reorder(gPath, order, back=TRUE, grep=FALSE, redraw=TRUE) |
| reorderGrob(x, order, back=TRUE) |
| } |
| \arguments{ |
| \item{gPath}{A gPath object specifying a gTree within the current |
| scene.} |
| \item{x}{A gTree object to be modified.} |
| \item{order}{A character vector or a numeric vector that specifies |
| the new drawing order for the children of the gTree. May not refer |
| to all children of the gTree (see Details).} |
| \item{back}{Controls what happens when the \code{order} does not |
| specify all children of the gTree (see Details).} |
| \item{grep}{Should the \code{gPath} be treated as a regular expression?} |
| \item{redraw}{Should the modified scene be redrawn?} |
| } |
| \details{ |
| In the simplest case, \code{order} specifies a new ordering for all of |
| the children of the gTree. The children may be specified either by |
| name or by existing numerical order. |
| |
| If the \code{order} does not |
| specify all children of the gTree then, by default, the children |
| specified by \code{order} are drawn first and then all remaining |
| children are drawn. If \code{back=FALSE} then the children not |
| specified in \code{order} are drawn first, followed by the specified |
| children. This makes it easy to specify a send-to-back or |
| bring-to-front reordering. The \code{order} argument is \emph{always} |
| in back-to-front order. |
| |
| It is not possible to reorder the grid display list (the top-level |
| grobs in the current scene) because the display list is a mixture of |
| grobs and viewports (so it is not clear what reordering even means and |
| it would be too easy to end up with a scene that would not draw). |
| If you want to reorder the grid display list, try \code{grid.grab()} |
| to create a gTree and then reorder (and redraw) that gTree. |
| } |
| \section{Warning}{ |
| This function may return a gTree that will not draw. For example, a |
| gTree has two children, A and B (in that order), |
| and the width of child B depends on the width of child A (e.g., a box |
| around a piece of text). Switching the order so that B is drawn |
| before A will not allow B to be drawn. If this happens with |
| \code{grid.reorder()}, the modification will not be performed. If |
| this happens with \code{reorderGrob()} it should be possible simply to |
| restore the original order. |
| } |
| \value{ |
| \code{grid.reorder()} is called for its side-effect of modifying the |
| current scene. |
| \code{reorderGrob()} returns the modified gTree. |
| } |
| \author{ Paul Murrell } |
| \examples{ |
| # gTree with two children, "red-rect" and "blue-rect" (in that order) |
| gt <- gTree(children=gList( |
| rectGrob(gp=gpar(col=NA, fill="red"), |
| width=.8, height=.2, name="red-rect"), |
| rectGrob(gp=gpar(col=NA, fill="blue"), |
| width=.2, height=.8, name="blue-rect")), |
| name="gt") |
| grid.newpage() |
| grid.draw(gt) |
| # Spec entire order as numeric (blue-rect, red-rect) |
| grid.reorder("gt", 2:1) |
| # Spec entire order as character |
| grid.reorder("gt", c("red-rect", "blue-rect")) |
| # Only spec the one I want behind as character |
| grid.reorder("gt", "blue-rect") |
| # Only spec the one I want in front as character |
| grid.reorder("gt", "blue-rect", back=FALSE) |
| } |
| \keyword{ dplot } |