Debian Codegraph @

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

raw
1 % Copyright 2019 by Till Tantau and Mark Wibrow
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{Shadows Library}
12 \label{section-libs-shadows}
13
14 \begin{tikzlibrary}{shadows}
15 This library defines styles that help adding a (partly) transparent shadow
16 to a path or node.
17 \end{tikzlibrary}
18
19
20 \subsection{Overview}
21
22 A \emph{shadow} is usually a black or gray area that is drawn behind a path or
23 a node, thereby adding visual depth to a picture. The |shadows| library defines
24 options that make it easy to add shadows to paths. Internally, these options
25 are based on using the |preaction| option to use a path twice: Once for drawing
26 the shadow (slightly shifted) and once for actually using the path.
27
28 Note that you can only add shadows to \emph{paths}, not to whole scopes.
29
30 In addition to the general |shadow| option, there exist special options like
31 |circular shadow|. These can only (sensibly) be used with a special kind of
32 path (for |circular shadow|, a circle) and, thus, they are not as general. The
33 advantage is, however, that they are more visually pleasing since these shadows
34 blend smoothly with the background. Note that these special shadows use
35 fadings, which few printers will support.
36
37
38 \subsection{The General Shadow Option}
39
40 The shadows are internally created by using a single option called
41 |general shadow|. The different options like |drop shadow| or |copy shadow|
42 only differ in the commands that they preset.
43
44 You will not need to use this option directly under normal circumstances.
45
46 \begin{key}{/tikz/general shadow=\meta{shadow options} (default \normalfont empty)}
47 This option should be given to a |\path| or a |node|. It has the following
48 effect: Before the path is used normally, it is used once with the
49 \meta{shadow options} in force. Furthermore, when the path is ``preused''
50 in this way, it is shifted and scaled a little bit.
51
52 In detail, the following happens: A |preaction| is used to paint the path
53 in a special manner before it is actually painted. This ``special'' manner
54 is as follows: The options in \meta{shadow options} are used for painting
55 this path. Typically, the \meta{shadow options} will contain options like
56 |fill=black| to create, say, a black shadow. Furthermore, after the
57 \meta{shadow options} have been set up, the following extra canvas
58 transformations are applied to the path: It is scaled by |shadow scale|
59 (with the origin of scaling at the path's center) and it is shifted by
60 |shadow xshift| and |shadow yshift|.
61
62 Note that since scaling and shifting is done using canvas transformations,
63 shadows are not taken into account when the picture's bounding box is
64 computed.
65 %
66 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
67 \tikz [even odd rule]
68 \draw [general shadow={fill=red}] (0,0) circle (.5) (0.5,0) circle (.5);
69 \end{codeexample}
70
71 \begin{key}{/tikz/shadow scale=\meta{factor} (initially 1)}
72 Shadows are scaled by \meta{factor}.
73 %
74 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
75 \tikz [even odd rule]
76 \draw [general shadow={fill=red,shadow scale=1.25}]
77 (0,0) circle (.5) (0.5,0) circle (.5);
78 \end{codeexample}
79 \end{key}
80 %
81 \begin{key}{/tikz/shadow xshift=\meta{dimension} (initially 0pt)}
82 Shadows are shifted horizontally by \meta{dimension}.
83 %
84 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
85 \tikz [even odd rule]
86 \draw [general shadow={fill=red,shadow xshift=-5pt}]
87 (0,0) circle (.5) (0.5,0) circle (.5);
88 \end{codeexample}
89 \end{key}
90 %
91 \begin{key}{/tikz/shadow yshift=\meta{dimension} (initially 0pt)}
92 Shadows are shifted vertically by \meta{dimension}.
93 \end{key}
94 \end{key}
95
96
97 \subsection{Shadows for Arbitrary Paths and Shapes}
98
99 \subsubsection{Drop Shadows}
100
101 \begin{key}{/tikz/drop shadow=\meta{shadow options} (default \normalfont empty)}
102 This option adds a drop shadow to a |\path| or a |node|. It uses the
103 |general shadow| and passes the \meta{shadow options} to it, plus, before
104 them, the following extra options:
105 %
106 \begin{codeexample}[code only]
107 shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex,
108 opacity=.5, fill=black!50, every shadow
109 \end{codeexample}
110
111 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
112 \tikz [even odd rule]
113 \filldraw [drop shadow,fill=white] (0,0) circle (.5) (0.5,0) circle (.5);
114 \end{codeexample}
115
116 \begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
117 \begin{tikzpicture}
118 \foreach \i in {1,...,4}
119 \node[starburst,drop shadow,fill=white,draw] at (0,\i) {Burst \i};
120 \end{tikzpicture}
121 \end{codeexample}
122
123 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
124 \begin{tikzpicture}
125 \draw [help lines] (0,0) grid (3,2);
126 \filldraw [drop shadow={opacity=1},fill=white]
127 (1,2) circle (.5) (1.5,2) circle (.5);
128
129 \filldraw [drop shadow={opacity=0.25},fill=white]
130 (1,.5) circle (.5) (1.5,.5) circle (.5);
131 \end{tikzpicture}
132 \end{codeexample}
133 %
134 \end{key}
135
136 \begin{stylekey}{/tikz/every shadow (initially \normalfont empty)}
137 This style is executed in addition to any \meta{shadow options} for each
138 shadow. Use this style to reconfigure the way shadows are drawn.
139 %
140 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
141 \begin{tikzpicture}[every shadow/.style={opacity=.8,fill=blue!50!black}]
142 \filldraw [drop shadow,fill=white] (0,0) circle (.5) (0.5,0) circle (.5);
143 \end{tikzpicture}
144 \end{codeexample}
145 %
146 \end{stylekey}
147
148
149 \subsubsection{Copy Shadows}
150
151 A \emph{copy shadow} is not really a shadow. Rather, it looks like another copy
152 of the path drawn behind the path and a little bit offset. This creates the
153 visual impression of having multiple copies of the path/object present.
154
155 \begin{key}{/tikz/copy shadow=\meta{shadow options} (default \normalfont empty)}
156 This shadow installs the following default options:
157 %
158 \begin{codeexample}[code only]
159 shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex, every shadow
160 \end{codeexample}
161 %
162 Furthermore, the options |fill=|\meta{fill color} and |draw=|\meta{draw
163 color} are also set, where the \meta{fill color} and \meta{draw color} are
164 the fill and draw colors used for the main path.
165 %
166 \begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
167 \begin{tikzpicture}
168 \node [copy shadow,fill=blue!20,draw=blue,thick] {Hello World!};
169
170 \node at (0,-1) [copy shadow={shadow xshift=1ex,shadow yshift=1ex},
171 fill=blue!20,draw=blue,thick]
172 {Hello World!};
173
174 \node at (0,-2) [copy shadow={opacity=.5},tape,
175 fill=blue!20,draw=blue,thick]
176 {Hello World!};
177
178 % We have to repeat the left color since shadings are not
179 % automatically applied to shadows
180 \node at (0,-3) [copy shadow={left color=blue!50},
181 left color=blue!50,draw=blue,thick]
182 {Hello World!};
183 \end{tikzpicture}
184 \end{codeexample}
185 %
186 \end{key}
187
188 \begin{key}{/tikz/double copy shadow=\meta{shadow options} (default \normalfont empty)}
189 This shadow works like a |copy shadow|, only the shadow is added twice, the
190 second time with the double |xshift| and |yshift|.
191 %
192 \begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
193 \begin{tikzpicture}
194 \node [double copy shadow,fill=blue!20,draw=blue,thick] {Hello World!};
195
196 \node at (0,-1) [double copy shadow={shadow xshift=1ex,shadow yshift=1ex},
197 fill=blue!20,draw=blue,thick]
198 {Hello World!};
199
200 \node at (0,-2) [double copy shadow={opacity=.5},tape,
201 fill=blue!20,draw=blue,thick]
202 {Hello World!};
203
204 \node at (0,-3) [double copy shadow={left color=blue!50},
205 left color=blue!50,draw=blue,thick]
206 {Hello World!};
207 \end{tikzpicture}
208 \end{codeexample}
209 %
210 \end{key}
211
212
213 \subsection{Shadows for Special Paths and Nodes}
214
215 The shadows in this section should normally be added only to paths that have a
216 special shape. They will look strange with other shapes.
217
218 \begin{key}{/tikz/circular drop shadow=\meta{shadow options}}
219 This shadow works like a drop shadow, only it adds a circular fading to the
220 shadow. This means that the shadow will fade out at the border. The
221 following options are preset for this shadow:
222 %
223 \begin{codeexample}[code only]
224 shadow scale=1.1, shadow xshift=.3ex, shadow yshift=-.3ex,
225 fill=black, path fading={circle with fuzzy edge 15 percent},
226 every shadow,
227 \end{codeexample}
228
229 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
230 \begin{tikzpicture}
231 \foreach \i in {1,...,8}
232 \node[circle,circular drop shadow,draw=blue,fill=blue!20,thick]
233 at (\i*45:1) {Circle \i};
234 \end{tikzpicture}
235 \end{codeexample}
236 %
237 \end{key}
238
239 \begin{key}{/tikz/circular glow=\meta{shadow options}}
240 This shadow works much like the |circular shadow|, only it is not shifted.
241 This creates a visual effect of a ``glow'' behind the circle. The following
242 options are preset for this shadow:
243 %
244 \begin{codeexample}[code only]
245 shadow scale=1.25, shadow xshift=0pt, shadow yshift=0pt,
246 fill=black, path fading={circle with fuzzy edge 15 percent},
247 every shadow,
248 \end{codeexample}
249
250 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
251 \begin{tikzpicture}
252 \foreach \i in {1,...,8}
253 \node[circle,circular glow,fill=red!20,draw=red,thick]
254 at (\i*45:1) {Circle \i};
255 \end{tikzpicture}
256 \end{codeexample}
257
258 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
259 \begin{tikzpicture}
260 \foreach \i in {1,...,8}
261 \node[circle,circular glow={fill=white},fill=red!20,draw=red,thick]
262 at (\i*45:1) {Circle \i};
263 \end{tikzpicture}
264 \end{codeexample}
265
266 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
267 \begin{tikzpicture}
268 \foreach \i in {1,...,8}
269 \node[circle,circular glow={fill=green},fill=black,text=green!50!black]
270 at (\i*45:1) {Circle \i};
271 \end{tikzpicture}
272 \end{codeexample}
273 %
274 An especially interesting effect can be achieved by only using the glow and
275 not filling the path:
276 %
277 \begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
278 \begin{tikzpicture}
279 \foreach \i in {1,...,8}
280 \node[circle,circular glow={fill=red!\i0}]
281 at (\i*45:1) {Circle \i};
282 \end{tikzpicture}
283 \end{codeexample}
284 %
285 \end{key}
286
287
288 %%% Local Variables:
289 %%% mode: latex
290 %%% TeX-master: "pgfmanual-pdftex-version"
291 %%% End: