unit                  package:grid                  R Documentation

Function to Create a Unit Object

Description:

     This function creates a unit object - a vector of unit values. A
     unit value is typically just a single numeric value with an
     associated unit.

Usage:

     unit(x, units, data=NULL)

Arguments:

       x: A numeric vector.

   units: A character vector specifying the units for the corresponding
          numeric values.

    data: This argument is used to supply extra information for special
          'unit' types.

Details:

     Unit objects allow the user to specify locations and dimensions in
     a large number of different coordinate systems.  All drawing
     occurs relative to a viewport and the 'units' specifies what
     coordinate system to use within that viewport.

     Possible 'units' (coordinate systems) are:

     '"npc"' Normalised Parent Coordinates (the default). The origin of
          the viewport is (0, 0) and the viewport has a width and
          height of 1 unit.  For example, (0.5, 0.5) is the centre of
          the viewport.

     '"cm"' Centimetres.

     '"inches"' Inches.  1 in = 2.54 cm.

     '"mm"' Millimetres.  10 mm = 1 cm.

     '"points"' Points.  72.27 pt = 1 in.

     '"picas"' Picas.  1 pc = 12 pt.

     '"bigpts"' Big Points.  72 bp = 1 in.

     '"dida"' Dida. 1157 dd = 1238 pt.

     '"cicero"' Cicero.  1 cc = 12 dd.

     '"scaledpts"' Scaled Points.  65536 sp = 1 pt.

     '"lines"' Lines of text.  Locations and dimensions are in terms of
          multiples of the default text size of the viewport (as
          specified by the viewport's 'fontsize' and 'lineheight').

     '"char"' Multiples of nominal font height of the viewport (as
          specified by the viewport's 'fontsize').

     '"native"' Locations and dimensions are relative to the viewport's
          'xscale' and 'yscale'.

     '"snpc"' Square Normalised Parent Coordinates. Same as Normalised
          Parent Coordinates, except gives the same answer for
          horizontal and vertical locations/dimensions.  It uses the
          _lesser_ of npc-width and npc-height.  This is useful for
          making things which are a proportion of the viewport, but
          have to be square  (or have a fixed aspect ratio).

     '"strwidth"' Multiples of the width of the string specified in the
          'data' argument.  The font size is determined by the
          pointsize of the viewport.

     '"strheight"' Multiples of the height of the string specified in
          the 'data' argument.  The font size is determined by the
          pointsize of the viewport.

     '"grobwidth"' Multiples of the width of the grob specified in the
          'data' argument.

     '"grobheight"' Multiples of the height of the grob specified in
          the 'data' argument.

     A special 'units' value of '"null"' is also allowed, but only
     makes sense when used in specifying widths of columns or heights
     of rows in grid layouts (see 'grid.layout').

     The 'data' argument must be a list when the 'unit.length()' is
     greater than 1.  For example, 'unit(rep(1, 3), c("npc",
     "strwidth", "inches"), data=list(NULL, "my string", NULL))'.

     It is possible to subset unit objects in the normal way (e.g.,
     'unit(1:5, "npc")[2:4]'), but a special function 'unit.c' is
     provided for combining unit objects.

     Certain arithmetic and summary operations are defined for unit
     objects.  In particular, it is possible to add and subtract unit
     objects (e.g., 'unit(1, "npc") - unit(1, "inches")'), and to
     specify the minimum or maximum of a list of unit objects (e.g.,
     'min(unit(0.5, "npc"), unit(1, "inches"))').

Value:

     An object of class '"unit"'.

WARNING:

     There is a special function 'unit.c' for concatenating several
     unit objects.

     The 'c' function will not give the right answer.

     There used to be '"mylines"', '"mychar"', '"mystrwidth"',
     '"mystrheight"' units.  These will still be accepted, but work
     exactly the same as '"lines"', '"char"', '"strwidth"',
     '"strheight"'.

Author(s):

     Paul Murrell

See Also:

     'unit.c'

Examples:

     unit(1, "npc")
     unit(1:3/4, "npc")
     unit(1:3/4, "npc") + unit(1, "inches")
     min(unit(0.5, "npc"), unit(1, "inches"))
     unit.c(unit(0.5, "npc"), unit(2, "inches") + unit(1:3/4, "npc"),
            unit(1, "strwidth", "hi there"))

