% File src/library/grid/man/drawDetails.Rd
% Part of the R package, http://www.R-project.org
% Copyright 1995-2007 R Core Development Team
% Distributed under GPL 2 or later

\name{drawDetails}
\alias{drawDetails}
\alias{preDrawDetails}
\alias{postDrawDetails}
\alias{draw.details}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{ Customising grid Drawing }
\description{
  These generic hook functions are called whenever a grid grob is drawn.
  They provide an opportunity for customising the drawing of a
  new class derived from grob (or gTree).
}
\usage{
drawDetails(x, recording)
draw.details(x, recording)
preDrawDetails(x)
postDrawDetails(x)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{x}{ A grid grob. }
  \item{recording}{ A logical value indicating whether a grob
  is being added to the display list or redrawn from the display list. }
}
\details{
  These functions are called by the \code{grid.draw} methods for grobs
  and gTrees.
  
  \code{preDrawDetails} is called first during the drawing of a grob.
  This is where any additional viewports should be pushed (see,
  for example, \code{grid:::preDrawDetails.frame}).  Note that
  the default behaviour for grobs is to push any viewports in the
  \code{vp} slot, and for gTrees is to also push and up any viewports in the
  \code{childrenvp} slot so there is typically nothing to do here.
  
  \code{drawDetails} is called next and is where any additional
  calculations and graphical output should occur (see, for example,
  \code{grid:::drawDetails.xaxis}.  Note that the default behaviour
  for gTrees is to draw all grobs in the \code{children} slot
  so there is typically nothing to do here.

  \code{postDrawDetails} is called last and should reverse anything
  done in \code{preDrawDetails} (i.e., pop or up any viewports that were
  pushed;  again, see,
  for example, \code{grid:::postDrawDetails.frame}).  Note that the
  default behaviour for grobs is to pop any viewports that were pushed
  so there is typically nothing to do here.

  Note that \code{preDrawDetails} and \code{postDrawDetails} are
  also called in the calculation of \code{"grobwidth"} and
  \code{"grobheight"} units.
}
\value{
  None of these functions are expected to return a value.
}
\author{ Paul Murrell }
\seealso{ \code{\link{grid.draw}} }
\keyword{ dplot }% at least one, from doc/KEYWORDS
