summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-library-backgrounds.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-backgrounds.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-library-backgrounds.tex283
1 files changed, 283 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-backgrounds.tex b/graphics/pgf/base/doc/pgfmanual-en-library-backgrounds.tex
new file mode 100644
index 0000000000..4d9d49e9cf
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-library-backgrounds.tex
@@ -0,0 +1,283 @@
+% Copyright 2019 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}
+
+The first use of this library is to make the following key available:
+%
+\begin{key}{/tikz/on background layer=\meta{options}}
+ This key can (only) be used with a |{scope}| or |\scoped|. It will cause
+ everything inside the scope to be typeset on a background layer.
+
+ The \meta{options} will be executed \emph{inside} background scope. This is
+ useful since \emph{other} options passed to the |{scope}| environment will
+ be executed \emph{before} the actual background material starts and, thus,
+ will have no effect on it.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
+\begin{tikzpicture}
+ % On main layer:
+ \fill[blue] (0,0) circle (1cm);
+
+ \begin{scope}[on background layer={color=yellow}]
+ \fill (-1,-1) rectangle (1,1);
+ \end{scope}
+
+ \begin{scope}[on background layer]
+ \fill[black] (-.8,-.8) rectangle (.8,.8);
+ \end{scope}
+
+ % On main layer again:
+ \fill[blue!50] (-.5,-1) rectangle (.5,1);
+\end{tikzpicture}
+\end{codeexample}
+
+ A scope with this option set should not be ``deeply nested'' inside the
+ picture since changes to the graphic state (like the color or the
+ transformation matrix) ``do not survive a layer switch'', see also
+ Section~\ref{section-layers} for details. In particular, setting, say, the
+ line width at the beginning of a picture will not have an effect on the
+ background picture.
+
+ For this reason, it may be useful to setup the following style:
+ %
+ \begin{stylekey}{/tikz/every on background layer}
+ This style is executed at the beginning of each background layer. If
+ you have a global setup in |every picture|, you should consider putting
+ that part of it that concerns the graphics state into this style.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
+\tikzset{
+ every picture/.style={line width=1ex},
+ every on background layer/.style={every picture}
+}
+\begin{tikzpicture}
+ \draw [->] (0,0) -- (2,1);
+
+ \scoped[on background layer]
+ \draw[red] (0,1) -- (2,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{stylekey}
+\end{key}
+
+When this package is loaded, the following styles become available:
+%
+\begin{stylekey}{/tikz/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}[preamble={\usetikzlibrary{backgrounds}}]
+\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{key}{/tikz/inner frame xsep=\meta{dimension} (initially 1ex)}
+ Sets the additional horizontal separator distance for the background
+ rectangle.
+ \end{key}
+ %
+ \begin{key}{/tikz/inner frame ysep=\meta{dimension} (initially 1ex)}
+ Same for the vertical separator distance.
+ \end{key}
+ %
+ \begin{key}{/tikz/inner frame sep=\meta{dimension}}
+ Sets the horizontal and vertical separator distances simultaneously.
+ \end{key}
+ %
+ The following two styles make setting the inner separator a bit easier to
+ remember:
+ %
+ \begin{stylekey}{/tikz/tight background}
+ Sets the inner frame separator to 0pt. The background rectangle will
+ have the size of the bounding box.
+ \end{stylekey}
+ %
+ \begin{stylekey}{/tikz/loose background}
+ Sets the inner frame separator to 2ex.
+ \end{stylekey}
+
+ You can influence how the background rectangle is rendered by setting the
+ following style:
+ %
+ \begin{stylekey}{/tikz/background rectangle (initially draw)}
+ This style dictates how the background rectangle is drawn or filled.
+ The default setting 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}[preamble={\usetikzlibrary{backgrounds}}]
+\begin{tikzpicture}
+ [background rectangle/.style=
+ {double,ultra thick,draw=red,top color=blue,rounded corners},
+ 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}[preamble={\usetikzlibrary{backgrounds}}]
+\begin{tikzpicture}
+ [background rectangle/.style=
+ {draw=blue!50,fill=blue!20,rounded corners=1ex},
+ show background rectangle]
+ \draw (0,0) ellipse (10mm and 5mm);
+\end{tikzpicture}
+\end{codeexample}
+ \end{stylekey}
+\end{stylekey}
+
+\begin{stylekey}{/tikz/framed}
+ This is a shorthand for |show background rectangle|.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/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}[preamble={\usetikzlibrary{backgrounds}}]
+\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{stylekey}{/tikz/background grid (initially draw,help lines)}
+ This style dictates how the background grid path is drawn.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
+\begin{tikzpicture}
+ [background grid/.style={thick,draw=red,step=.5cm},
+ show background grid]
+ \draw (0,0) ellipse (10mm and 5mm);
+\end{tikzpicture}
+\end{codeexample}
+ \end{stylekey}
+ %
+ This option can be combined with the |framed| option (use the |framed|
+ option first):
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
+\tikzset{background grid/.style={thick,draw=red,step=.5cm},
+ background rectangle/.style={rounded corners,fill=yellow}}
+\begin{tikzpicture}[framed,gridded]
+ \draw (0,0) ellipse (10mm and 5mm);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{stylekey}
+
+\begin{stylekey}{/tikz/gridded}
+ This is a shorthand for |show background grid|.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/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}[preamble={\usetikzlibrary{backgrounds}}]
+\begin{tikzpicture}[
+ background rectangle/.style={fill=yellow},
+ 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{key}{/tikz/outer frame xsep=\meta{dimension} (initially 0pt)}
+ The \meta{dimension} is added at the left and right side of the line.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
+\begin{tikzpicture}
+ [background rectangle/.style={fill=yellow},
+ framed,
+ show background top,
+ outer frame xsep=1ex]
+ \draw (0,0) ellipse (10mm and 5mm);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/tikz/outer frame ysep=\meta{dimension} (initially 0pt)}
+ This option does not apply to the top line, but to the left and right
+ lines, see below.
+ \end{key}
+ %
+ \begin{key}{/tikz/outer frame sep=\meta{dimension}}
+ Sets both the $x$- and $y$-separation.
+ \end{key}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
+\begin{tikzpicture}
+ [background rectangle={fill=blue!20},
+ 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}
+ %
+ You can influence how the line is drawn grid by setting the following
+ style:
+ %
+ \begin{stylekey}{/tikz/background top (initially draw)}
+\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
+\tikzset{background rectangle/.style={fill=blue!20},
+ background top/.style={draw=blue!50,line width=1ex}}
+\begin{tikzpicture}[framed,show background top]
+ \draw (0,0) ellipse (10mm and 5mm);
+\end{tikzpicture}
+\end{codeexample}
+ \end{stylekey}
+\end{stylekey}
+
+\begin{stylekey}{/tikz/show background bottom}
+ Works like the style for the top line.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/show background left}
+ Works similarly.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/show background right}
+ Works similarly.
+\end{stylekey}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual-pdftex-version"
+%%% End: