summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadows.tex
blob: 9d1ae581d5487d0e4edb7e42a8e9d0f4d6370895 (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
284
285
286
287
288
289
290
291
% Copyright 2019 by Till Tantau and Mark Wibrow
%
% 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{Shadows Library}
\label{section-libs-shadows}

\begin{tikzlibrary}{shadows}
    This library defines styles that help adding a (partly) transparent shadow
    to a path or node.
\end{tikzlibrary}


\subsection{Overview}

A \emph{shadow} is usually a black or gray area that is drawn behind a path or
a node, thereby adding visual depth to a picture. The |shadows| library defines
options that make it easy to add shadows to paths. Internally, these options
are based on using the |preaction| option to use a path twice: Once for drawing
the shadow (slightly shifted) and once for actually using the path.

Note that you can only add shadows to \emph{paths}, not to whole scopes.

In addition to the general |shadow| option, there exist special options like
|circular shadow|. These can only (sensibly) be used with a special kind of
path (for |circular shadow|, a circle) and, thus, they are not as general. The
advantage is, however, that they are more visually pleasing since these shadows
blend smoothly with the background. Note that these special shadows use
fadings, which few printers will support.


\subsection{The General Shadow Option}

The shadows are internally created by using a single option called
|general shadow|. The different options like |drop shadow| or |copy shadow|
only differ in the commands that they preset.

You will not need to use this option directly under normal circumstances.

\begin{key}{/tikz/general shadow=\meta{shadow options} (default \normalfont empty)}
    This option should be given to a |\path| or a |node|. It has the following
    effect: Before the path is used normally, it is used once with the
    \meta{shadow options} in force. Furthermore, when the path is ``preused''
    in this way, it is shifted and scaled a little bit.

    In detail, the following happens: A |preaction| is used to paint the path
    in a special manner before it is actually painted. This ``special'' manner
    is as follows: The options in \meta{shadow options} are used for painting
    this path. Typically, the \meta{shadow options} will contain options like
    |fill=black| to create, say, a black shadow. Furthermore, after the
    \meta{shadow options} have been set up, the following extra canvas
    transformations are applied to the path: It is scaled by |shadow scale|
    (with the origin of scaling at the path's center) and it is shifted by
    |shadow xshift| and |shadow yshift|.

    Note that since scaling and shifting is done using canvas transformations,
    shadows are not taken into account when the picture's bounding box is
    computed.
    %
\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\tikz [even odd rule]
  \draw [general shadow={fill=red}] (0,0) circle (.5) (0.5,0) circle (.5);
\end{codeexample}

    \begin{key}{/tikz/shadow scale=\meta{factor} (initially 1)}
        Shadows are scaled by \meta{factor}.
        %
\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\tikz [even odd rule]
  \draw [general shadow={fill=red,shadow scale=1.25}]
    (0,0) circle (.5) (0.5,0) circle (.5);
\end{codeexample}
    \end{key}
    %
    \begin{key}{/tikz/shadow xshift=\meta{dimension} (initially 0pt)}
        Shadows are shifted horizontally by \meta{dimension}.
        %
\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\tikz [even odd rule]
  \draw [general shadow={fill=red,shadow xshift=-5pt}]
    (0,0) circle (.5) (0.5,0) circle (.5);
\end{codeexample}
    \end{key}
    %
    \begin{key}{/tikz/shadow yshift=\meta{dimension} (initially 0pt)}
        Shadows are shifted vertically by \meta{dimension}.
    \end{key}
\end{key}


\subsection{Shadows for Arbitrary Paths and Shapes}

\subsubsection{Drop Shadows}

\begin{key}{/tikz/drop shadow=\meta{shadow options} (default \normalfont empty)}
    This option adds a drop shadow to a |\path| or a |node|. It uses the
    |general shadow| and passes the \meta{shadow options} to it, plus, before
    them, the following extra options:
    %
\begin{codeexample}[code only]
  shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex,
  opacity=.5, fill=black!50, every shadow
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\tikz [even odd rule]
  \filldraw [drop shadow,fill=white] (0,0) circle (.5) (0.5,0) circle (.5);
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
\begin{tikzpicture}
  \foreach \i in {1,...,4}
    \node[starburst,drop shadow,fill=white,draw] at (0,\i) {Burst \i};
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);
  \filldraw [drop shadow={opacity=1},fill=white]
    (1,2)  circle (.5) (1.5,2)  circle (.5);

  \filldraw [drop shadow={opacity=0.25},fill=white]
    (1,.5) circle (.5) (1.5,.5) circle (.5);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{stylekey}{/tikz/every shadow (initially \normalfont empty)}
    This style is executed in addition to any \meta{shadow options} for each
    shadow. Use this style to reconfigure the way shadows are drawn.
    %
\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\begin{tikzpicture}[every shadow/.style={opacity=.8,fill=blue!50!black}]
  \filldraw [drop shadow,fill=white] (0,0) circle (.5) (0.5,0) circle (.5);
\end{tikzpicture}
\end{codeexample}
    %
\end{stylekey}


\subsubsection{Copy Shadows}

A \emph{copy shadow} is not really a shadow. Rather, it looks like another copy
of the path drawn behind the path and a little bit offset. This creates the
visual impression of having multiple copies of the path/object present.

\begin{key}{/tikz/copy shadow=\meta{shadow options} (default \normalfont empty)}
    This shadow installs the following default options:
    %
\begin{codeexample}[code only]
  shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex, every shadow
\end{codeexample}
    %
    Furthermore, the options |fill=|\meta{fill color} and |draw=|\meta{draw
    color} are also set, where the \meta{fill color} and \meta{draw color} are
    the fill and draw colors used for the main path.
    %
\begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
\begin{tikzpicture}
  \node [copy shadow,fill=blue!20,draw=blue,thick] {Hello World!};

  \node at (0,-1) [copy shadow={shadow xshift=1ex,shadow yshift=1ex},
                   fill=blue!20,draw=blue,thick]
    {Hello World!};

  \node at (0,-2) [copy shadow={opacity=.5},tape,
                   fill=blue!20,draw=blue,thick]
    {Hello World!};

  % We have to repeat the left color since shadings are not
  % automatically applied to shadows
  \node at (0,-3) [copy shadow={left color=blue!50},
                   left color=blue!50,draw=blue,thick]
    {Hello World!};
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/double copy shadow=\meta{shadow options} (default \normalfont empty)}
    This shadow works like a |copy shadow|, only the shadow is added twice, the
    second time with the double |xshift| and |yshift|.
    %
\begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
\begin{tikzpicture}
  \node [double copy shadow,fill=blue!20,draw=blue,thick] {Hello World!};

  \node at (0,-1) [double copy shadow={shadow xshift=1ex,shadow yshift=1ex},
                   fill=blue!20,draw=blue,thick]
    {Hello World!};

  \node at (0,-2) [double copy shadow={opacity=.5},tape,
                   fill=blue!20,draw=blue,thick]
    {Hello World!};

  \node at (0,-3) [double copy shadow={left color=blue!50},
                   left color=blue!50,draw=blue,thick]
    {Hello World!};
\end{tikzpicture}
\end{codeexample}
    %
\end{key}


\subsection{Shadows for Special Paths and Nodes}

The shadows in this section should normally be added only to paths that have a
special shape. They will look strange with other shapes.

\begin{key}{/tikz/circular drop shadow=\meta{shadow options}}
    This shadow works like a drop shadow, only it adds a circular fading to the
    shadow. This means that the shadow will fade out at the border. The
    following options are preset for this shadow:
    %
\begin{codeexample}[code only]
  shadow scale=1.1, shadow xshift=.3ex, shadow yshift=-.3ex,
  fill=black, path fading={circle with fuzzy edge 15 percent},
  every shadow,
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\begin{tikzpicture}
  \foreach \i in {1,...,8}
    \node[circle,circular drop shadow,draw=blue,fill=blue!20,thick]
      at (\i*45:1) {Circle \i};
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/circular glow=\meta{shadow options}}
    This shadow works much like the |circular shadow|, only it is not shifted.
    This creates a visual effect of a ``glow'' behind the circle. The following
    options are preset for this shadow:
    %
\begin{codeexample}[code only]
  shadow scale=1.25, shadow xshift=0pt, shadow yshift=0pt,
  fill=black, path fading={circle with fuzzy edge 15 percent},
  every shadow,
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\begin{tikzpicture}
  \foreach \i in {1,...,8}
  \node[circle,circular glow,fill=red!20,draw=red,thick]
    at (\i*45:1) {Circle \i};
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\begin{tikzpicture}
  \foreach \i in {1,...,8}
  \node[circle,circular glow={fill=white},fill=red!20,draw=red,thick]
    at (\i*45:1) {Circle \i};
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\begin{tikzpicture}
  \foreach \i in {1,...,8}
  \node[circle,circular glow={fill=green},fill=black,text=green!50!black]
    at (\i*45:1) {Circle \i};
\end{tikzpicture}
\end{codeexample}
    %
    An especially interesting effect can be achieved by only using the glow and
    not filling the path:
    %
\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
\begin{tikzpicture}
  \foreach \i in {1,...,8}
  \node[circle,circular glow={fill=red!\i0}]
    at (\i*45:1) {Circle \i};
\end{tikzpicture}
\end{codeexample}
    %
\end{key}


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual-pdftex-version"
%%% End: