| 1 |
% Copyright 2019 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Background Library} |
| 12 |
\label{section-tikz-backgrounds} |
| 13 |
|
| 14 |
\begin{tikzlibrary}{backgrounds} |
| 15 |
This library defines ``backgrounds'' for pictures. This does not refer to |
| 16 |
background pictures, but rather to frames drawn around and behind pictures. |
| 17 |
For example, this package allows you to just add the |framed| option to a |
| 18 |
picture to get a rectangular box around your picture or |gridded| to put a |
| 19 |
grid behind your picture. |
| 20 |
\end{tikzlibrary} |
| 21 |
|
| 22 |
The first use of this library is to make the following key available: |
| 23 |
% |
| 24 |
\begin{key}{/tikz/on background layer=\meta{options}} |
| 25 |
This key can (only) be used with a |{scope}| or |\scoped|. It will cause |
| 26 |
everything inside the scope to be typeset on a background layer. |
| 27 |
|
| 28 |
The \meta{options} will be executed \emph{inside} background scope. This is |
| 29 |
useful since \emph{other} options passed to the |{scope}| environment will |
| 30 |
be executed \emph{before} the actual background material starts and, thus, |
| 31 |
will have no effect on it. |
| 32 |
% |
| 33 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 34 |
\begin{tikzpicture} |
| 35 |
% On main layer: |
| 36 |
\fill[blue] (0,0) circle (1cm); |
| 37 |
|
| 38 |
\begin{scope}[on background layer={color=yellow}] |
| 39 |
\fill (-1,-1) rectangle (1,1); |
| 40 |
\end{scope} |
| 41 |
|
| 42 |
\begin{scope}[on background layer] |
| 43 |
\fill[black] (-.8,-.8) rectangle (.8,.8); |
| 44 |
\end{scope} |
| 45 |
|
| 46 |
% On main layer again: |
| 47 |
\fill[blue!50] (-.5,-1) rectangle (.5,1); |
| 48 |
\end{tikzpicture} |
| 49 |
\end{codeexample} |
| 50 |
|
| 51 |
A scope with this option set should not be ``deeply nested'' inside the |
| 52 |
picture since changes to the graphic state (like the color or the |
| 53 |
transformation matrix) ``do not survive a layer switch'', see also |
| 54 |
Section~\ref{section-layers} for details. In particular, setting, say, the |
| 55 |
line width at the beginning of a picture will not have an effect on the |
| 56 |
background picture. |
| 57 |
|
| 58 |
For this reason, it may be useful to setup the following style: |
| 59 |
% |
| 60 |
\begin{stylekey}{/tikz/every on background layer} |
| 61 |
This style is executed at the beginning of each background layer. If |
| 62 |
you have a global setup in |every picture|, you should consider putting |
| 63 |
that part of it that concerns the graphics state into this style. |
| 64 |
% |
| 65 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 66 |
\tikzset{ |
| 67 |
every picture/.style={line width=1ex}, |
| 68 |
every on background layer/.style={every picture} |
| 69 |
} |
| 70 |
\begin{tikzpicture} |
| 71 |
\draw [->] (0,0) -- (2,1); |
| 72 |
|
| 73 |
\scoped[on background layer] |
| 74 |
\draw[red] (0,1) -- (2,0); |
| 75 |
\end{tikzpicture} |
| 76 |
\end{codeexample} |
| 77 |
\end{stylekey} |
| 78 |
\end{key} |
| 79 |
|
| 80 |
When this package is loaded, the following styles become available: |
| 81 |
% |
| 82 |
\begin{stylekey}{/tikz/show background rectangle} |
| 83 |
This style causes a rectangle to be drawn behind your graphic. This style |
| 84 |
option must be given to the |{tikzpicture}| environment or to the |\tikz| |
| 85 |
command. |
| 86 |
% |
| 87 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 88 |
\begin{tikzpicture}[show background rectangle] |
| 89 |
\draw (0,0) ellipse (10mm and 5mm); |
| 90 |
\end{tikzpicture} |
| 91 |
\end{codeexample} |
| 92 |
% |
| 93 |
The size of the background rectangle is determined as follows: We start |
| 94 |
with the bounding box of the picture. Then, a certain separator distance is |
| 95 |
added on the sides. This distance can be different for the $x$- and |
| 96 |
$y$-directions and can be set using the following options: |
| 97 |
% |
| 98 |
\begin{key}{/tikz/inner frame xsep=\meta{dimension} (initially 1ex)} |
| 99 |
Sets the additional horizontal separator distance for the background |
| 100 |
rectangle. |
| 101 |
\end{key} |
| 102 |
% |
| 103 |
\begin{key}{/tikz/inner frame ysep=\meta{dimension} (initially 1ex)} |
| 104 |
Same for the vertical separator distance. |
| 105 |
\end{key} |
| 106 |
% |
| 107 |
\begin{key}{/tikz/inner frame sep=\meta{dimension}} |
| 108 |
Sets the horizontal and vertical separator distances simultaneously. |
| 109 |
\end{key} |
| 110 |
% |
| 111 |
The following two styles make setting the inner separator a bit easier to |
| 112 |
remember: |
| 113 |
% |
| 114 |
\begin{stylekey}{/tikz/tight background} |
| 115 |
Sets the inner frame separator to 0pt. The background rectangle will |
| 116 |
have the size of the bounding box. |
| 117 |
\end{stylekey} |
| 118 |
% |
| 119 |
\begin{stylekey}{/tikz/loose background} |
| 120 |
Sets the inner frame separator to 2ex. |
| 121 |
\end{stylekey} |
| 122 |
|
| 123 |
You can influence how the background rectangle is rendered by setting the |
| 124 |
following style: |
| 125 |
% |
| 126 |
\begin{stylekey}{/tikz/background rectangle (initially draw)} |
| 127 |
This style dictates how the background rectangle is drawn or filled. |
| 128 |
The default setting causes the path of the background rectangle to be |
| 129 |
drawn in the usual way. Setting this style to, say, |fill=blue!20| |
| 130 |
causes a light blue background to be added to the picture. You can also |
| 131 |
use more fancy settings as shown in the following example: |
| 132 |
% |
| 133 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 134 |
\begin{tikzpicture} |
| 135 |
[background rectangle/.style= |
| 136 |
{double,ultra thick,draw=red,top color=blue,rounded corners}, |
| 137 |
show background rectangle] |
| 138 |
\draw (0,0) ellipse (10mm and 5mm); |
| 139 |
\end{tikzpicture} |
| 140 |
\end{codeexample} |
| 141 |
% |
| 142 |
Naturally, no one in their right mind would use the above, but here is |
| 143 |
a nice background: |
| 144 |
% |
| 145 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 146 |
\begin{tikzpicture} |
| 147 |
[background rectangle/.style= |
| 148 |
{draw=blue!50,fill=blue!20,rounded corners=1ex}, |
| 149 |
show background rectangle] |
| 150 |
\draw (0,0) ellipse (10mm and 5mm); |
| 151 |
\end{tikzpicture} |
| 152 |
\end{codeexample} |
| 153 |
\end{stylekey} |
| 154 |
\end{stylekey} |
| 155 |
|
| 156 |
\begin{stylekey}{/tikz/framed} |
| 157 |
This is a shorthand for |show background rectangle|. |
| 158 |
\end{stylekey} |
| 159 |
|
| 160 |
\begin{stylekey}{/tikz/show background grid} |
| 161 |
This style behaves similarly to the |show background rectangle| style, but |
| 162 |
it will not use a rectangle path, but a grid. The lower left and upper |
| 163 |
right corner of the grid is computed in the same way as for the background |
| 164 |
rectangle: |
| 165 |
% |
| 166 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 167 |
\begin{tikzpicture}[show background grid] |
| 168 |
\draw (0,0) ellipse (10mm and 5mm); |
| 169 |
\end{tikzpicture} |
| 170 |
\end{codeexample} |
| 171 |
% |
| 172 |
You can influence the background grid by setting the following style: |
| 173 |
% |
| 174 |
\begin{stylekey}{/tikz/background grid (initially draw,help lines)} |
| 175 |
This style dictates how the background grid path is drawn. |
| 176 |
% |
| 177 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 178 |
\begin{tikzpicture} |
| 179 |
[background grid/.style={thick,draw=red,step=.5cm}, |
| 180 |
show background grid] |
| 181 |
\draw (0,0) ellipse (10mm and 5mm); |
| 182 |
\end{tikzpicture} |
| 183 |
\end{codeexample} |
| 184 |
\end{stylekey} |
| 185 |
% |
| 186 |
This option can be combined with the |framed| option (use the |framed| |
| 187 |
option first): |
| 188 |
% |
| 189 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 190 |
\tikzset{background grid/.style={thick,draw=red,step=.5cm}, |
| 191 |
background rectangle/.style={rounded corners,fill=yellow}} |
| 192 |
\begin{tikzpicture}[framed,gridded] |
| 193 |
\draw (0,0) ellipse (10mm and 5mm); |
| 194 |
\end{tikzpicture} |
| 195 |
\end{codeexample} |
| 196 |
% |
| 197 |
\end{stylekey} |
| 198 |
|
| 199 |
\begin{stylekey}{/tikz/gridded} |
| 200 |
This is a shorthand for |show background grid|. |
| 201 |
\end{stylekey} |
| 202 |
|
| 203 |
\begin{stylekey}{/tikz/show background top} |
| 204 |
This style causes a single line to be drawn at the top of the background |
| 205 |
rectangle. Normally, the line coincides exactly with the top line of the |
| 206 |
background rectangle: |
| 207 |
% |
| 208 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 209 |
\begin{tikzpicture}[ |
| 210 |
background rectangle/.style={fill=yellow}, |
| 211 |
framed,show background top] |
| 212 |
\draw (0,0) ellipse (10mm and 5mm); |
| 213 |
\end{tikzpicture} |
| 214 |
\end{codeexample} |
| 215 |
% |
| 216 |
The following option allows you to lengthen (or shorten) the line: |
| 217 |
% |
| 218 |
\begin{key}{/tikz/outer frame xsep=\meta{dimension} (initially 0pt)} |
| 219 |
The \meta{dimension} is added at the left and right side of the line. |
| 220 |
% |
| 221 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 222 |
\begin{tikzpicture} |
| 223 |
[background rectangle/.style={fill=yellow}, |
| 224 |
framed, |
| 225 |
show background top, |
| 226 |
outer frame xsep=1ex] |
| 227 |
\draw (0,0) ellipse (10mm and 5mm); |
| 228 |
\end{tikzpicture} |
| 229 |
\end{codeexample} |
| 230 |
\end{key} |
| 231 |
% |
| 232 |
\begin{key}{/tikz/outer frame ysep=\meta{dimension} (initially 0pt)} |
| 233 |
This option does not apply to the top line, but to the left and right |
| 234 |
lines, see below. |
| 235 |
\end{key} |
| 236 |
% |
| 237 |
\begin{key}{/tikz/outer frame sep=\meta{dimension}} |
| 238 |
Sets both the $x$- and $y$-separation. |
| 239 |
\end{key} |
| 240 |
% |
| 241 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 242 |
\begin{tikzpicture} |
| 243 |
[background rectangle={fill=blue!20}, |
| 244 |
outer frame sep=1ex,% |
| 245 |
show background top,% |
| 246 |
show background bottom,% |
| 247 |
show background left,% |
| 248 |
show background right] |
| 249 |
\draw (0,0) ellipse (10mm and 5mm); |
| 250 |
\end{tikzpicture} |
| 251 |
\end{codeexample} |
| 252 |
% |
| 253 |
You can influence how the line is drawn grid by setting the following |
| 254 |
style: |
| 255 |
% |
| 256 |
\begin{stylekey}{/tikz/background top (initially draw)} |
| 257 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 258 |
\tikzset{background rectangle/.style={fill=blue!20}, |
| 259 |
background top/.style={draw=blue!50,line width=1ex}} |
| 260 |
\begin{tikzpicture}[framed,show background top] |
| 261 |
\draw (0,0) ellipse (10mm and 5mm); |
| 262 |
\end{tikzpicture} |
| 263 |
\end{codeexample} |
| 264 |
\end{stylekey} |
| 265 |
\end{stylekey} |
| 266 |
|
| 267 |
\begin{stylekey}{/tikz/show background bottom} |
| 268 |
Works like the style for the top line. |
| 269 |
\end{stylekey} |
| 270 |
|
| 271 |
\begin{stylekey}{/tikz/show background left} |
| 272 |
Works similarly. |
| 273 |
\end{stylekey} |
| 274 |
|
| 275 |
\begin{stylekey}{/tikz/show background right} |
| 276 |
Works similarly. |
| 277 |
\end{stylekey} |
| 278 |
|
| 279 |
|
| 280 |
%%% Local Variables: |
| 281 |
%%% mode: latex |
| 282 |
%%% TeX-master: "pgfmanual-pdftex-version" |
| 283 |
%%% End: |