trellis.par.get           package:lattice           R Documentation

Graphical Parameters for Trellis Displays

Description:

     Functions used to query, display and modify graphical parameters
     for fine control of Trellis displays.  Modifications are made to
     the settings for the currently active device only.

Usage:

     trellis.par.set(name, value, ..., theme, warn = TRUE, strict = FALSE)
     trellis.par.get(name = NULL)
     show.settings(x = NULL)

Arguments:

    name: character giving the name of a component. If unspecified,
          'names(trellis.par.get())' returns a list containing all the
          current settings (this can be used to get the valid values
          for 'name') 

   value: a list giving the desired value of the component. Components
          that are already defined as part of the current settings but
          are not mentioned in 'value' will remain unchanged. 

   theme: a list decribing how to change the settings, similar to what
          is returned by 'trellis.par.get()'.  This is purely for
          convenience, allowing multiple calls to 'trellis.par.set' to
          be condensed into one.  The name of each component must be a
          valid 'name' as described above, with the corresponding value
          a valid 'value' as described above.

          As in 'trellis.device', 'theme' can also be a function that
          produces such a list when called.  The function name can be
          supplied as a quoted string. 

     ...: Multiple settings can be specified in 'name = value' form.
          Equivalent to calling with 'theme = list(...)' 

    warn: logical, indicating whether a warning should be issued when
          'trellis.par.get' is called when no graphics device is open 

  strict: logical, indicating whether the 'value' should be interpreted
          strictly.  Usually, assignment of value to the corresponding
          named component is fuzzy in the sense that sub-components
          that are absent from 'value' but not currently 'NULL' are
          retained.  By specifying 'strict = TRUE', the assignment will
          be exact. 

       x: optional list of components that change the settings (any
          valid value of 'theme').  These are used to modify the
          current settings (obtained by 'trellis.par.get') before they
          are displayed. 

Details:

     The various graphical parameters (color, line type, background
     etc) that control the look and feel of Trellis displays are highly
     customizable. Also, R can produce graphics on a number of devices,
     and it is expected that a different set of parameters would be
     more suited to different devices. These parameters are stored
     internally in a variable named 'lattice.theme', which is a list
     whose components define settings for particular devices. The
     components are idenified by the name of the device they represent
     (as obtained by '.Device'), and are created as and when new
     devices are opened for the first time using 'trellis.device' (or
     Lattice plots are drawn on a device for the first time in that
     session).

     The initial settings for each device defaults to values
     appropriate for that device. In practice, this boils down to three
     distinct settings, one for screen devices like 'x11' and
     'windows', one for black and white plots (mostly useful for
     'postscript') and one for color printers (color 'postcript',
     'pdf').

     Once a device is open, its settings can be modified. When another
     instance of the same device is opened later using
     'trellis.device', the settings for that device are reset to its
     defaults, unless otherwise specified in the call to
     'trellis.device'. But settings for different devices are treated
     separately, i.e., opening a postscript device will not alter the
     x11 settings, which will remain in effect whenever an x11 device
     is active.

     The functions 'trellis.par.*' are meant to be interfaces to the
     global settings. They always apply on the settings for the
     currently ACTIVE device.

     'trellis.par.get', called without any arguments, returns the full
     list of settings for the active device. With the 'name' argument
     present, it returns that component only. 'trellis.par.get' sets
     the value of the 'name' component of the current active device
     settings to 'value'.

     'trellis.par.get' is usually used inside trellis functions to get
     graphical parameters before plotting. Modifications by users via
     'trellis.par.set' is traditionally done as follows:

     'add.line <- trellis.par.get("add.line")'

     'add.line$col <- "red"'

     'trellis.par.set("add.line", add.line)'

     More convenient (but not S compatible) ways to do this are

     'trellis.par.set(list(add.line = list(col = "red")))'

     and

     'trellis.par.set(add.line = list(col = "red"))'

     The actual list of the components in 'trellis.settings' has not
     been finalized, so I'm not attempting to list them here. The
     current value can be obtained by 'print(trellis.par.get())'. Most
     names should be self-explanatory.

     'show.settings' provides a graphical display summarizing some of
     the values in the current settings.

Value:

     'trellis.par.get' returns a list giving parameters for that
     component. If 'name' is missing, it returns the full list.

Note:

     In some ways, 'trellis.par.get' and 'trellis.par.set' together are
     a replacement for the 'par' function used in traditional R
     graphics.  In particular, changing 'par' settings has little (if
     any) effect on lattice output.  Since lattice plots are
     implemented using Grid graphics, its parameter system _does_ have
     an effect unless overridden by a suitable lattice parameter
     setting. Such parameters can be specified as part of a lattice
     theme by including them in the 'grid.pars' component (see 'gpar'
     for a list of valid parameter names).

     One of the uses of 'par' is to set 'par(ask = TRUE)' making R wait
     for user input before starting a new graphics page.  For Grid
     graphics, this is done using 'grid.prompt'.  Lattice has no
     separate interface for this, and the user must call 'grid.prompt'
     directly.  If the grid package is not attached (lattice itself
     only loads the grid namespace), this may be done using
     'grid::grid.prompt(TRUE)'.

Author(s):

     Deepayan Sarkar Deepayan.Sarkar@R-project.org

See Also:

     'trellis.device', 'Lattice', 'grid.prompt', 'gpar'

Examples:

     show.settings()

