grid.pack                package:grid                R Documentation

Pack an Object within a Frame

Description:

     This functions, together with 'grid.frame' and 'frameGrob' are
     part of a GUI-builder-like interface to constructing graphical
     images. The idea is that you create a frame with 'grid.frame' or
     'frameGrob' then use this functions to pack objects into the
     frame.

Usage:

     grid.pack(gPath, grob, redraw = TRUE, side = NULL,
               row = NULL, row.before = NULL, row.after = NULL,
               col = NULL, col.before = NULL, col.after = NULL,
               width = NULL, height = NULL,
               force.width = FALSE, force.height = FALSE, border = NULL,
               dynamic = FALSE)

     packGrob(frame, grob, side = NULL,
               row = NULL, row.before = NULL, row.after = NULL,
               col = NULL, col.before = NULL, col.after = NULL,
               width = NULL, height = NULL,
               force.width = FALSE, force.height = FALSE, border = NULL,
               dynamic = FALSE)

Arguments:

   gPath: A gPath object, which specifies a frame on the display list.

   frame: An object of class 'frame', typically the output from a call
          to 'grid.frame'. 

    grob: An object of class 'grob'.  The object to be packed. 

  redraw: A boolean indicating whether the output should be updated. 

    side: One of '"left"', '"top"', '"right"', '"bottom"' to indicate
          which side to pack the object on. 

     row: Which row to add the object to.  Must be between 1 and
          the-number-of-rows-currently-in-the-frame + 1, or 'NULL' in
          which case the object occupies all rows. 

row.before: Add the object to a new row just before this row. 

row.after: Add the object to a new row just after this row. 

     col: Which col to add the object to.  Must be between 1 and
          the-number-of-cols-currently-in-the-frame + 1, or 'NULL' in
          which case the object occupies all cols.  

col.before: Add the object to a new col just before this col.

col.after: Add the object to a new col just after this col. 

   width: Specifies the width of the column that the object is added to
          (rather than allowing the width to be taken from the object). 

  height: Specifies the height of the row that the object is added to
          (rather than allowing the height to be taken from the
          object). 

force.width: A logical value indicating whether the width of the column
          that the grob is being packed into should be EITHER the width
          specified in the call to 'grid.pack' OR the maximum of that
          width and the pre-existing width. 

force.height: A logical value indicating whether the height of the
          column that the grob is being packed into should be EITHER
          the height specified in the call to 'grid.pack' OR the
          maximum of that height and the pre-existing height. 

  border: A 'unit' object of length 4 indicating the borders around the
          object. 

 dynamic: If the width/height is taken from the grob being packed, this
          boolean flag indicates whether the grobwidth/height unit
          refers directly to the grob, or uses a gPath to the grob. In
          the latter case, changes to the grob will trigger a
          recalculation of the width/height.

Details:

     'packGrob' modifies the given frame grob and returns the modified
     frame grob.

     'grid.pack' destructively modifies a frame grob on the display
     list (and redraws the display list if 'redraw' is 'TRUE').

     These are (meant to be) very flexible functions.  There are many
     different ways to specify where the new object is to be added
     relative to the objects already in the frame.  The function checks
     that the specification is not self-contradictory.

     NOTE that the width/height of the row/col that the object is added
     to is taken from the object itself unless the 'width'/'height' is
     specified.

Value:

     'packGrob' returns a frame grob, but 'grid.pack' returns 'NULL'.

Author(s):

     Paul Murrell

See Also:

     'grid.frame', 'grid.place', 'grid.edit', and 'gPath'.

