diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-shadows.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-library-shadows.tex | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-shadows.tex b/graphics/pgf/base/doc/pgfmanual-en-library-shadows.tex new file mode 100644 index 0000000000..9d1ae581d5 --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-library-shadows.tex @@ -0,0 +1,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: |