trellis.device            package:lattice            R Documentation

_I_n_i_t_i_a_l_i_z_i_n_g _T_r_e_l_l_i_s _D_i_s_p_l_a_y_s

_D_e_s_c_r_i_p_t_i_o_n:

     'trellis.device' initializes a Trellis display device with
     appropriate settings of the graphics control parameters.

_U_s_a_g_e:

     trellis.device(device = getOption("device"),
                    color = !(dev.name == "postscript"),
                    theme = lattice.getOption("default.theme"),
                    new = TRUE,
                    retain = FALSE,
                    ...)
     canonical.theme(name, color)
     col.whitebg()

_A_r_g_u_m_e_n_t_s:

  device: name of a function (possibly as a character string) that
          initializes a device. Admissible values include "x11",
          "windows", "mac", "postscript", "pdf", "png", etc. 

   color: logical, whether the display should be color or black and
          white. 'FALSE' for postscript devices, 'TRUE' otherwise. 

   theme: list of components that change the settings of the device
          opened, or, a function that when called produces such a list.
          The function name can be supplied as a quoted string.

          A possible use of this argument is to change the default
          settings by  specifying 'lattice.options(default.theme =
          "col.whitebg")'.  For back-compatibility, this is initially
          (when lattice is loaded) set to 'options(lattice.theme)'.

          If 'theme' is a function, it will not be supplied any
          arguments, however, it is guaranteed that a device will
          already be open when it is called, so one may use '.Device'
          inside the function to ascertain what device has been opened. 

     new: logical flag indicating whether a new device should be
          started. If 'FALSE',  the options for the current device are
          changed to the defaults determined by the other arguments. 

  retain: logical. If 'TRUE' and a setting for this device already
          exists, then that is used instead of the defaults for this
          device. By default, pre-existing settings are overwritten
          (and lost). 

    name: name of the device for which the setting is required, as
          returned by '.Device' 

     ...: additional parameters to be passed to the 'device' function,
          most commonly 'file' for non-screen devices. 

_D_e_t_a_i_l_s:

     'trellis.device' calls the 'device' function to start a display,
     and sets an appropriate component of the variable 'lattice.theme'
     (in an unexported environment named '.LatticeEnv') to appropriate
     (device-specific) values.  The device specific settings are
     determined by 'canonical.theme' which returns a list (see below). 
     The settings can subsequently be handled by the interface
     functions 'trellis.par.get' and  'trellis.par.set'.

     'col.whitebg' returns a similar (but smaller) list that is
     suitable as the 'theme' argument to 'trellis.device' and
     'trellis.par.set'.  It contains settings values which provide
     colors suitable for plotting on a white background.  Note that the
     name 'col.whitebg' is somewhat a misnomer, since it actually sets
     the background to transparent rather than white.

_V_a_l_u_e:

     'canonical.theme' returns a list of components defining graphical
     parameter settings for Lattice displays. It is used internally in
     'trellis.device', and can also be used as the 'theme' argument to
     'trellis.par.set', or even as 'theme' in 'trellis.device' to use
     the defaults for another device.

     'col.whitebg' returns a similar but smaller list.

_N_o_t_e:

     Trellis Graphics is designed to have a different look and feel on
     different devices.  In particular, the default settings for
     'screen' devices are not at all suitable for printing.

     One technique often used to create printable graphs is through use
     of 'dev.print' and related functions (typically via a GUI menu). 
     Unfortunately, this only copies the display already created, and
     hence retains the settings used therein, instead of settings
     suitable for the target device.

     The recommended workaround for this is to re-print the trellis
     object after explicitly starting the new device.  The last printed
     trellis object is typically stored in memory, and it is possible
     to retrieve it using 'trellis.last.object'.

     The other option (relevant especially if the trellis plot is
     enhanced interactively after plotting) is to start the initial
     (screen) device with the settings suitable for the eventual target
     (print) device. For instance, a 'windows' device can be opened
     with 'pdf' settings with

     'trellis.device(windows, theme = canonical.theme("pdf"))'

     Note that earlier versions of 'trellis.device' had a 'bg' argument
     to set the background color, but this is no longer supported. If
     supplied, the 'bg' argument will be passed on to the device
     function; however, this will have no effect on the Trellis
     settings. It is rarely meaningful to change the background alone,
     and if you feel the need to change the background, consider using
     the 'theme' argument.

_A_u_t_h_o_r(_s):

     Deepayan Sarkar Deepayan.Sarkar@R-project.org

_S_e_e _A_l_s_o:

     'trellis.par.set', 'postscript', 'pdf', 'x11', 'Lattice'

