summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-library-backgrounds.tex
blob: 4d9d49e9cf0c2aafb84b40951a3d6751e3f446be (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
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: