Grid Viewports             package:grid             R Documentation

_C_r_e_a_t_e _a _G_r_i_d _V_i_e_w_p_o_r_t

_D_e_s_c_r_i_p_t_i_o_n:

     These functions create viewports, which describe a rectangular
     regions on a graphics device and define a number of coordinate
     systems within those regions.

_U_s_a_g_e:

     viewport(x = unit(0.5, "npc"), y = unit(0.5, "npc"),
              width = unit(1, "npc"), height = unit(1, "npc"),
              default.units = "npc", just = "centre", 
              gp = gpar(), clip = "inherit",
              xscale = c(0, 1), yscale = c(0, 1),
              angle = 0,
              layout = NULL, layout.pos.row = NULL, layout.pos.col = NULL,
              name=NULL)
     vpList(...)
     vpStack(...)
     vpTree(parent, children)

_A_r_g_u_m_e_n_t_s:

       x: A numeric vector or unit object specifying x-location.

       y: A numeric vector or unit object specifying y-location.

   width: A numeric vector or unit object specifying width.

  height: A numeric vector or unit object specifying height.

default.units: A string indicating the default units to use if 'x',
          'y', 'width', or 'height' are only given as numeric vectors.

    just: A string vector specifying the justification of the viewport
          relative to its (x, y) location.  If there are two values,
          the first value specifes horizontal justification and the
          second value specifies vertical justification.  Possible
          values are: '"left"', '"right"', '"centre"', '"center"',
          '"bottom"', and '"top"'.

      gp: An object of class 'gpar', typically the output from a call
          to the function 'gpar'.  This is basically a list of
          graphical parameter settings.

    clip: One of '"on"', '"inherit"', or '"off"', indicating whether to
          clip to the extent of this viewport, inherit the clipping
          region from the parent viewport, or turn clipping off
          altogether. For back-compatibility, a logical value of 'TRUE'
          corresponds to '"on"' and 'FALSE' corresponds to '"inherit"'.

  xscale: A numeric vector of length two indicating the minimum and
          maximum on the x-scale.

  yscale: A numeric vector of length two indicating the minimum and
          maximum on the y-scale.

   angle: A numeric value indicating the angle of rotation of the
          viewport.  Positive values indicate the amount of rotation,
          in degrees, anitclockwise from the positive x-axis.

  layout: A Grid layout object which splits the viewport into
          subregions.

layout.pos.row: A numeric vector giving the rows occupied by this
          viewport in its parent's layout.

layout.pos.col: A numeric vector giving the columns occupied by this
          viewport in its parent's layout.

    name: A character value to uniquely identify the viewport once it
          has been pushed onto the viewport tree.  

     ...: Any number of grid viewport objects.

  parent: A grid viewport object.

children: A vpList object.

_D_e_t_a_i_l_s:

     The location and size of a viewport are relative to the coordinate
     systems defined by the viewport's parent (either a graphical
     device or another viewport).  The location and size can be
     specified in a very flexible way by specifying them with unit
     objects. When specifying the location of a viewport, specifying
     both 'layout.pos.row' and 'layout.pos.col' as 'NULL' indicates
     that the viewport ignores its parent's layout and specifies its
     own location and size (via its 'locn').  If only one of
     'layout.pos.row' and 'layout.pos.col' is 'NULL', this means occupy
     ALL of the appropriate row(s)/column(s).  For example,
     'layout.pos.row = 1' and 'layout.pos.col = NULL' means occupy all
     of row 1.  Specifying non-'NULL' values for both 'layout.pos.row'
     and 'layout.pos.col' means occupy the intersection of the
     appropriate rows and columns.  If a vector of length two is
     specified for 'layout.pos.row' or 'layout.pos.col', this indicates
     a range of rows or columns to occupy.  For example,
     'layout.pos.row = c(1, 3)' and 'layout.pos.col = c(2, 4)' means
     occupy cells in the intersection of rows 1, 2, and 3, and columns,
     2, 3, and 4.

     Clipping obeys only the most recent viewport clip setting. For
     example, if you clip to viewport1, then clip to viewport2, the
     clipping region is determined wholly by viewport2, the size and
     shape of viewport1 is irrelevant (until viewport2 is popped of
     course).

     If a viewport is rotated (because of its own 'angle' setting or
     because it is within another viewport which is rotated) then the
     'clip' flag is ignored.

     Viewport names need not be unique.  When pushed, viewports sharing
     the same parent must have unique names, which means that if you
     push a viewport with the same name as an existing viewport, the
     existing viewport will be replaced in the viewport tree. A
     viewport name can be any valid R symbol name, but grid uses the
     reserved name '"ROOT"' for the top-level viewport.  Also, when
     specifying a viewport name in 'downViewport' and 'seekViewport',
     it is possible to provide a viewport path, which consists of
     several names concatenated using the separator  (currently '::'). 
     Consequently, it is not advisable to use this separator in
     viewport names.

     The viewports in a 'vpList' are pushed in parallel.  The viewports
     in a 'vpStack' are pushed in series.  When a 'vpTree' is pushed,
     the parent is pushed first, then the children are pushed in
     parallel.

_V_a_l_u_e:

     An R object of class 'viewport'.

_A_u_t_h_o_r(_s):

     Paul Murrell

_S_e_e _A_l_s_o:

     Grid, 'pushViewport', 'popViewport', 'downViewport',
     'seekViewport', 'upViewport', 'unit', 'grid.layout',
     'grid.show.layout'.

_E_x_a_m_p_l_e_s:

     # Diagram of a sample viewport
     grid.show.viewport(viewport(x=0.6, y=0.6,
                        w=unit(1, "inches"), h=unit(1, "inches")))
     # Demonstrate viewport clipping
     clip.demo <- function(i, j, clip1, clip2) {
       pushViewport(viewport(layout.pos.col=i,
                              layout.pos.row=j))
       pushViewport(viewport(width=0.6, height=0.6, clip=clip1))
       grid.rect(gp=gpar(fill="white"))
       grid.circle(r=0.55, gp=gpar(col="red", fill="pink"))
       popViewport()
       pushViewport(viewport(width=0.6, height=0.6, clip=clip2))
       grid.polygon(x=c(0.5, 1.1, 0.6, 1.1, 0.5, -0.1, 0.4, -0.1),
                    y=c(0.6, 1.1, 0.5, -0.1, 0.4, -0.1, 0.5, 1.1),
                    gp=gpar(col="blue", fill="light blue"))
       popViewport(2)
     }

     grid.newpage()
     grid.rect(gp=gpar(fill="grey"))
     pushViewport(viewport(layout=grid.layout(2, 2)))
     clip.demo(1, 1, FALSE, FALSE)
     clip.demo(1, 2, TRUE, FALSE)
     clip.demo(2, 1, FALSE, TRUE)
     clip.demo(2, 2, TRUE, TRUE)
     popViewport()
     # Demonstrate turning clipping off
     grid.newpage()
     pushViewport(viewport(w=.5, h=.5, clip="on"))
     grid.rect()
     grid.circle(r=.6, gp=gpar(lwd=10))
     pushViewport(viewport(clip="inherit"))
     grid.circle(r=.6, gp=gpar(lwd=5, col="grey"))
     pushViewport(viewport(clip="off"))
     grid.circle(r=.6)
     popViewport(3)
     # Demonstrate vpList, vpStack, and vpTree
     grid.newpage()
     tree <- vpTree(viewport(w=0.8, h=0.8, name="A"),
                    vpList(vpStack(viewport(x=0.1, y=0.1, w=0.5, h=0.5,
                                            just=c("left", "bottom"), name="B"),
                                   viewport(x=0.1, y=0.1, w=0.5, h=0.5, 
                                            just=c("left", "bottom"), name="C"),
                                   viewport(x=0.1, y=0.1, w=0.5, h=0.5, 
                                            just=c("left", "bottom"), name="D")),
                           viewport(x=0.5, w=0.4, h=0.9,
                                    just="left", name="E")))
     pushViewport(tree)
     for (i in LETTERS[1:5]) {
       seekViewport(i)
       grid.rect()
       grid.text(current.vpTree(FALSE),
                 x=unit(1, "mm"), y=unit(1, "npc") - unit(1, "mm"),
                 just=c("left", "top"),
                 gp=gpar(fontsize=8))
     }

