grid.clip                package:grid                R Documentation

Set the Clipping Region

Description:

     These functions set the clipping region within the current
     viewport _without_ altering the current coordinate system.

Usage:

     grid.clip(...)
     clipGrob(x = unit(0.5, "npc"), y = unit(0.5, "npc"),
              width = unit(1, "npc"), height = unit(1, "npc"),
              just = "centre", hjust = NULL, vjust = NULL, 
              default.units = "npc", name = NULL, vp = NULL)

Arguments:

       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.

    just: The justification of the clip rectangle 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 string values
          are: '"left"', '"right"', '"centre"', '"center"', '"bottom"',
          and '"top"'.  For numeric values, 0 means left alignment and
          1 means right alignment. 

   hjust: A numeric vector specifying horizontal justification. If
          specified, overrides the 'just' setting.

   vjust: A numeric vector specifying vertical justification. If
          specified, overrides the 'just' setting.

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

    name: A character identifier. 

      vp: A Grid viewport object (or NULL).

     ...: Arguments passed to 'clipGrob'.

Details:

     Both functions create a clip rectangle (a graphical object
     describing a clip rectangle), but only 'grid.clip' enforces the
     clipping.

     Pushing or popping a viewport _always_ overrides the clip region
     set by a clip grob, regardless of whether that viewport explicitly
     enforces a clipping region.

Value:

     'clipGrob' returns a clip grob.

Author(s):

     Paul Murrell

See Also:

     Grid, 'viewport'

Examples:

     # draw across entire viewport, but clipped
     grid.clip(x = 0.3, width = 0.1)
     grid.lines(gp=gpar(col="green", lwd=5))
     # draw across entire viewport, but clipped (in different place)
     grid.clip(x = 0.7, width = 0.1)
     grid.lines(gp=gpar(col="red", lwd=5))
     # Viewport sets new clip region
     pushViewport(viewport(width=0.5, height=0.5, clip=TRUE))
     grid.lines(gp=gpar(col="grey", lwd=3))
     # Return to original viewport;  get 
     # clip region from previous grid.clip()
     # (NOT from previous viewport clip region)
     popViewport()
     grid.lines(gp=gpar(col="black"))

