% File src/library/grid/man/grid.ls.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2013 R Core Team
% Distributed under GPL 2 or later

\name{grid.ls}
\alias{grid.ls}
\alias{nestedListing}
\alias{pathListing}
\alias{grobPathListing}
\title{ List the names of grobs or viewports }
\description{
  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{
grid.ls(x=NULL, grobs=TRUE, viewports=FALSE, fullNames=FALSE,
        recursive=TRUE, print=TRUE, flatten=TRUE, ...)

nestedListing(x, gindent="  ", vpindent=gindent)
pathListing(x, gvpSep=" | ", gAlign=TRUE)
grobPathListing(x, ...)
}
\arguments{
  \item{x}{A grob or viewport or \code{NULL}.  If \code{NULL}, the current
    grid display list is listed.

    For print functions, this should be the result of a call to
    \code{grid.ls}.}
  \item{grobs}{A logical value indicating whether to list grobs.}
  \item{viewports}{A logical value indicating whether to list
    viewports.}
  \item{fullNames}{A logical value indicating whether to embellish
    object names with information about the object type.}
  \item{recursive}{A logical value indicating whether recursive
    structures should also list their children.}
  \item{print}{A logical indicating whether to print the listing
    or a function that will print the listing.}
  \item{flatten}{A logical value indicating whether to flatten
    the listing.  Otherwise a more complex hierarchical object is
    produced.}
  \item{gindent}{The indent used to show nesting in the output for
    grobs.}
  \item{vpindent}{The indent used to show nesting in the output for
    viewports.}
  \item{gvpSep}{The string used to separate viewport paths from grob
    paths.}
  \item{gAlign}{Logical indicating whether to align the left hand
    edge of all grob paths.}
  \item{...}{Arguments passed to the \code{print} function.}
}
\details{
  If the argument \code{x} is \code{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, \code{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 \code{print}
  argument, which can be given a function to perform the formatting.
  The \code{nestedListing} function produces a line per grob or
  viewport, with indenting used to show nesting.  The \code{pathListing}
  function produces a line per grob or viewport, with viewport paths
  and grob paths used to show nesting.  The \code{grobPathListing}
  is a simple derivation that only shows lines for grobs.  The user
  can define new functions.
}
\value{
  The result of this function is either a \code{"gridFlatListing"}
  object (if \code{flatten} is \code{TRUE}) or a \code{"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.
}
\seealso{
  \code{\link{grob}}
  \code{\link{viewport}}
}
\author{ Paul Murrell }
\examples{
# 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")),
                     childrenvp=vpTree(parent=viewport(name="vp1"),
                                       children=vpList(viewport(name="vp2"))))
grid.ls(sampleGTree)
# Show viewports too
grid.ls(sampleGTree, view=TRUE)
# Only show viewports
grid.ls(sampleGTree, view=TRUE, grob=FALSE)
# Alternate displays
# nested listing, custom indent
grid.ls(sampleGTree, view=TRUE, print=nestedListing, gindent="--")
# path listing
grid.ls(sampleGTree, view=TRUE, print=pathListing)
# path listing, without grobs aligned
grid.ls(sampleGTree, view=TRUE, print=pathListing, gAlign=FALSE)
# grob path listing
grid.ls(sampleGTree, view=TRUE, print=grobPathListing)
# path listing, grobs only
grid.ls(sampleGTree, print=pathListing)
# path listing, viewports only
grid.ls(sampleGTree, view=TRUE, grob=FALSE, print=pathListing)
# raw flat listing
str(grid.ls(sampleGTree, view=TRUE, print=FALSE))
}
\keyword{ dplot }