% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.



\section{Background Library}

\label{section-tikz-backgrounds}

\begin{tikzlibrary}{backgrounds}
  This library defines ``backgrounds'' for pictures. This does not
  refer to background pictures, but rather to frames drawn around and
  behind pictures. For example, this package allows you to just add
  the |framed| option to a picture to get a rectangular box around
  your picture or |gridded| to put a grid behind your picture.
\end{tikzlibrary}

When this package is loaded, the following styles become available:
\begin{itemize}
  \itemstyle{show background rectangle}
  This style causes a rectangle to be drawn behind your graphic. This
  style option must be given to the |{tikzpicture}| environment or to
  the |\tikz| command.
\begin{codeexample}[]
\begin{tikzpicture}[show background rectangle]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
  The size of the background rectangle is determined as follows:
  We start with the bounding box of the picture. Then, a certain
  separator distance is added on the sides. This distance can be
  different for the $x$- and $y$-directions and can be set using the
  following options:
  \begin{itemize}
    \itemoption{inner frame xsep}|=|\meta{dimension}
    Sets the additional horizontal separator distance for the
    background rectangle. The default is |1ex|.
    \itemoption{inner frame ysep}|=|\meta{dimension}
    Same for the vertical separator distance.
    \itemoption{inner frame sep}|=|\meta{dimension}
    sets the horizontal and vertical separator distances
    simultaneously. 
  \end{itemize}
  The following two styles make setting the inner separator a bit
  easier to remember:
  \begin{itemize}
    \itemstyle{tight background} Sets the inner frame separator to
    0pt. The background rectangle will have the size of the bounding
    box. 
    \itemstyle{loose background} Sets the inner frame separator to 2ex.
  \end{itemize}
    
  You can influence how the background rectangle is rendered by setting
  the following style:
  \begin{itemize}
    \itemstyle{background rectangle}
    This style dictates how the background rectangle is drawn or
    filled. By default this style is set to |draw|, which causes the
    path of the background rectangle to be drawn in the usual
    way. Setting this style to, say, |fill=blue!20| causes a light
    blue background to be added to the picture. You can also use more
    fancy settings as shown in the following example:
\begin{codeexample}[]
\tikzstyle{background rectangle}=
  [double,ultra thick,draw=red,top color=blue,rounded corners]      
\begin{tikzpicture}[show background rectangle]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
    Naturally, no one in their right mind would use the above, but
    here is a nice background: 
\begin{codeexample}[]
\tikzstyle{background rectangle}=
  [draw=blue!50,fill=blue!20,rounded corners=1ex]      
\begin{tikzpicture}[show background rectangle]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
\end{itemize}
  \itemstyle{framed}
  This is a shorthand for |show background rectangle|.
  \itemstyle{show background grid}
  This style behaves similarly to the |show background rectangle|
  style, but it will not use a rectangle path, but a grid. The lower
  left and upper right corner of the grid is computed in the same way
  as for the background rectangle:
\begin{codeexample}[]
\begin{tikzpicture}[show background grid]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
  You can influence the background grid by setting
  the following style:
  \begin{itemize}
    \itemstyle{background grid}
    This style dictates how the background grid path is drawn. The
    default is |draw,help lines|. 
\begin{codeexample}[]
\tikzstyle{background grid}=[thick,draw=red,step=.5cm]
\begin{tikzpicture}[show background grid]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
  This option can be combined with the |framed| option (use the
  |framed| option first):
\begin{codeexample}[]
\tikzstyle{background grid}=[thick,draw=red,step=.5cm]
\tikzstyle{background rectangle}=[rounded corners,fill=yellow]
\begin{tikzpicture}[framed,gridded]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
  \itemstyle{gridded}
  This is a shorthand for |show background grid|.
  \end{itemize}
  \itemstyle{show background top}
  This style causes a single line to be drawn at the top of the
  background rectangle. Normally, the line coincides exactly with the
  top line of the background rectangle:
\begin{codeexample}[]
\tikzstyle{background rectangle}=[fill=yellow]    
\begin{tikzpicture}[framed,show background top]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
  The following option allows you to lengthen (or shorten) the line:
  \begin{itemize}
    \itemoption{outer frame xsep}|=|\meta{dimension}
    The \meta{dimension} is added at the left and right side of the
    line. 
\begin{codeexample}[]
\tikzstyle{background rectangle}=[fill=yellow]    
\begin{tikzpicture}
    [framed,show background top,outer frame xsep=1ex]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
    \itemoption{outer frame ysep}|=|\meta{dimension}
    This option does not apply to the top line, but to the left and
    right lines, see below.
    \itemoption{outer frame sep}|=|\meta{dimension}
    Sets both the $x$- and $y$-separation.
\begin{codeexample}[]
\tikzstyle{background rectangle}=[fill=blue!20]    
\begin{tikzpicture}
  [outer frame sep=1ex,%
   show background top,%
   show background bottom,%
   show background left,%
   show background right]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
  \end{itemize}
  You can influence how the line is drawn grid by setting
  the following style:
  \begin{itemize}
    \itemstyle{background top}
    Default is |draw|.
\begin{codeexample}[]
\tikzstyle{background rectangle}=[fill=blue!20]    
\tikzstyle{background top}=[draw=blue!50,line width=1ex]
\begin{tikzpicture}[framed,show background top]
  \draw (0,0) ellipse (10mm and 5mm);
\end{tikzpicture}
\end{codeexample}
  \end{itemize}
  \itemstyle{show background bottom}
  works like the style for the top line.
  \itemstyle{show background left}
  works like the style for the top line.
  \itemstyle{show background right}
  works like the style for the top line.
\end{itemize}



%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "pgfmanual-pdftex-version"
%%% End: 
