Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-backgrounds.tex

raw
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: