grid.ls                 package:grid                 R Documentation

_L_i_s_t _t_h_e _n_a_m_e_s _o_f _g_r_o_b_s _o_r _v_i_e_w_p_o_r_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     Returns a listing of the names of grobs or viewports.

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

_U_s_a_g_e:

     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, ...) 

_A_r_g_u_m_e_n_t_s:

       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
          'grid.ls'.

   grobs: A logical value indicating whether to list grobs.

viewports: A logical value indicating whether to list viewports.

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

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

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

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

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

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

  gvpSep: The string used to separate viewport paths from grob paths.

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

     ...: Arguments passed to the 'print' function.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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 heiararchical object (list of lists),
     but it does contain more detailed information so may be of use for
     more advanced customisations.

_A_u_t_h_o_r(_s):

     Paul Murrell

_S_e_e _A_l_s_o:

     'grob' 'viewport'

_E_x_a_m_p_l_e_s:

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