\Header{trellis.device}{Initializing Trellis Displays}
\alias{canonical.theme}{trellis.device}
\keyword{dplot}{trellis.device}
\begin{Description}\relax
\code{trellis.device} initializes a Trellis display device with
appropriate settings of the graphics control parameter
\code{trellis.settings}.
\end{Description}
\begin{Usage}
\begin{verbatim}
trellis.device(device = getOption("device"),
               color = !(dev.name == "postscript"),
               theme = getOption("lattice.theme"),
               bg = NULL,
               new = TRUE,
               retain = FALSE,
               ...)
canonical.theme(name, color)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{device}] name of a function (possibly as a character string)
that initializes a device. Admissible values include "x11",
"windows", "mac", "postscript", "pdf", "png", etc.

\item[\code{color}] logical, whether the display should be color or black
and white. \code{FALSE} for postscript devices, \code{TRUE}
otherwise.

\item[\code{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 at
session startup, for example by setting \code{options(lattice.theme
      = "col.whitebg")}. If \code{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 \code{.Device}
inside the function to ascertain what device has been opened.

\item[\code{bg}] background color for the device.
\item[\code{new}] logical flag indicating whether a new device should be
started. If \code{FALSE},  the options for the current device are
changed to the defaults determined by the other arguments.

\item[\code{retain}] logical. If \code{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).

\item[\code{name}] name of the device for which the setting is required, as
returned by \code{.Device}

\item[\code{...}] additional parameters to be passed to the \code{device}
function, most commonly \code{file} for non-screen devices.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{trellis.device} calls the \code{device} function to start a
display, and sets an appropriate component of the variable
\code{lattice.theme} (in an unexported environment named
\code{.LatticeEnv}) to appropriate (device-specific) values.

The device specific settings are determined by \code{canonical.theme}
which returns a list (see below).

The settings can subsequently be handled by the interface functions
\code{trellis.par.get}, \code{trellis.par.set} and \code{lset}
\end{Details}
\begin{Value}
\code{canonical.theme} returns a list of components defining graphical
parameter settings for Lattice displays. It is used internally in
\code{trellis.device}, and can also be used as an argument to
\code{lset}, or even as \code{theme} in \code{trellis.device} to use
the defaults for another device.
\end{Value}
\begin{Author}\relax
Deepayan Sarkar \email{deepayan@stat.wisc.edu}
\end{Author}
\begin{SeeAlso}\relax
\code{\Link{trellis.par.set}}, \code{\Link{lset}}, 
\code{\Link{postscript}},\code{\Link{x11}}, \code{\Link{Lattice}}
\end{SeeAlso}

