{grid}R Documentation

List the names of grobs or viewports


Return a listing of the names of grobs or viewports.

This is a generic function with methods for grobs (including gTrees) and viewports (including vpTrees).

Usage, grobs=TRUE, viewports=FALSE, fullNames=FALSE,
        recursive=TRUE, print=TRUE, flatten=TRUE, ...)

nestedListing(x, gindent="  ", vpindent=gindent)
pathListing(x, gvpSep=" | ", gAlign=TRUE)
grobPathListing(x, ...)



A grob or viewport or NULL. If NULL, the current grid display list is listed.

For print functions, this should be the result of a call to


A logical value indicating whether to list grobs.


A logical value indicating whether to list viewports.


A logical value indicating whether to embellish object names with information about the object type.


A logical value indicating whether recursive structures should also list their children.


A logical indicating whether to print the listing or a function that will print the listing.


A logical value indicating whether to flatten the listing. Otherwise a more complex hierarchical object is produced.


The indent used to show nesting in the output for grobs.


The indent used to show nesting in the output for viewports.


The string used to separate viewport paths from grob paths.


Logical indicating whether to align the left hand edge of all grob paths.


Arguments passed to the print function.


If the argument x is NULL, the current contents of the grid display list are listed (both viewports and grobs). In other words, all objects representing the current scene are listed.

Otherwise, x should be a grob or a viewport.

The default behaviour of this function is to print information about the grobs in the current scene. It is also possible to add information about the viewports in the scene. By default, the listing is recursive, so all children of gTrees and all nested viewports are reported.

The format of the information can be controlled via the print argument, which can be given a function to perform the formatting. The nestedListing function produces a line per grob or viewport, with indenting used to show nesting. The pathListing function produces a line per grob or viewport, with viewport paths and grob paths used to show nesting. The grobPathListing is a simple derivation that only shows lines for grobs. The user can define new functions.


The result of this function is either a "gridFlatListing" object (if flatten is TRUE) or a "gridListing" object.

The former is a simple (flat) list of vectors. This is convenient, for example, for working programmatically with the list of grob and viewport names, or for writing a new display function for the listing.

The latter is a more complex hierarchical object (list of lists), but it does contain more detailed information so may be of use for more advanced customisations.


Paul Murrell

See Also

grob viewport


# A gTree, called "parent", with childrenvp vpTree (vp2 within vp1)
# and child grob, called "child", with vp vpPath (down to vp2)
sampleGTree <- gTree(name="parent",
                     children=gList(grob(name="child", vp="vp1::vp2")),
# Show viewports too, viewports=TRUE)
# Only show viewports, viewports=TRUE, grobs=FALSE)
# Alternate displays
# nested listing, custom indent, viewports=TRUE, print=nestedListing, gindent="--")
# path listing, viewports=TRUE, print=pathListing)
# path listing, without grobs aligned, viewports=TRUE, print=pathListing, gAlign=FALSE)
# grob path listing, viewports=TRUE, print=grobPathListing)
# path listing, grobs only, print=pathListing)
# path listing, viewports only, viewports=TRUE, grobs=FALSE, print=pathListing)
# raw flat listing
str(, viewports=TRUE, print=FALSE))

[Package grid version 4.4.0 Index]