grid.grab                package:grid                R Documentation

_G_r_a_b _t_h_e _c_u_r_r_e_n_t _g_r_i_d _o_u_t_p_u_t

_D_e_s_c_r_i_p_t_i_o_n:

     Creates a gTree object from the current grid display list or from
     a scene generated by user-specified code.

_U_s_a_g_e:

     grid.grab(warn = 2, wrap = FALSE, ...)
     grid.grabExpr(expr, warn = 2, wrap = FALSE, ...)

_A_r_g_u_m_e_n_t_s:

    expr: An expression to be evaluated.  Typically, some calls to grid
          drawing functions. 

    warn: An integer specifying the amount of warnings to emit.  0
          means no warnings, 1 means warn when it is certain that the
          grab will not faithfully represent the original scene. 2
          means warn if there's any possibility that the grab will not
          faithfully represent the original scene. 

    wrap: A logical indicating how the output should be captured. If
          'TRUE', each non-grob element on the display list is captured
          by wrapping it in a grob.   

     ...: arguments passed to gTree, for example, a name and/or class
          for the gTree that is created.

_D_e_t_a_i_l_s:

     There are four ways to capture grid output as a gTree.

     There are two functions for capturing output: use 'grid.grab' to
     capture an existing drawing and 'grid.grabExpr' to capture the
     output from an expression (without drawing anything).

     For each of these functions, the output can be captured in two
     ways.  One way tries to be clever and make a gTree with a
     childrenvp slot containing all viewports on the display list
     (including those that are popped) and every grob on the display
     list as a child of the new gTree;  each child has a vpPath in the
     vp slot so that it is drawn in the appropriate viewport. In other
     words, the gTree contains all elements on the display list, but in
     a slightly altered form.

     The other way, 'wrap=TRUE', is to create a grob for every element
     on the display list (and make all of those grobs children of the
     gTree).

     The first approach creates a more compact and elegant gTree, which
     is more flexible to work with, but is not guaranteed to faithfully
     replicate all possible grid output.  The second approach is more
     brute force, and harder to work with, but should always faithfully
     replicate the original output.

_V_a_l_u_e:

     A gTree object.

_S_e_e _A_l_s_o:

     'gTree'

_E_x_a_m_p_l_e_s:

     pushViewport(viewport(w=.5, h=.5))
     grid.rect()
     grid.points(stats::runif(10), stats::runif(10))
     popViewport()
     grab <- grid.grab()
     grid.newpage()
     grid.draw(grab)