R: Reorder the children of a gTree

grid.reorder {grid} | R Documentation

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

`gPath` | A gPath object specifying a gTree within the current scene.
`x` | A gTree object to be modified.
`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).
`back` | Controls what happens when the `order` does not specify all children of the gTree (see Details).
`grep` | Should the `gPath` be treated as a regular expression?
`redraw` | Should the modified scene be redrawn?

### Details

In the simplest case, `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 `order` does not specify all children of the gTree then, by default, the children specified by `order` are drawn first and then all remaining children are drawn. If `back=FALSE` then the children not specified in `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 `order` argument is 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 `grid.grab()` to create a gTree and then reorder (and redraw) that gTree.

### Value

`grid.reorder()` is called for its side-effect of modifying the current scene. `reorderGrob()` returns the modified gTree.

### 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 `grid.reorder()`, the modification will not be performed. If this happens with `reorderGrob()` it should be possible simply to restore the original order.

### Author(s)

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)

[Package grid version 3.5.1 Index]