summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex563
1 files changed, 339 insertions, 224 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex
index c4c8cb13ed2..50aa70a3af2 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex
@@ -9,6 +9,8 @@
\section{Actions on Paths}
+\subsection{Overview}
+
Once a path has been constructed, different things can be done with
it. It can be drawn (or stroked) with a ``pen,'' it can be filled with
a color or shading, it can be used for clipping subsequent drawing, it
@@ -96,8 +98,7 @@ abbreviations:
The most unspecific option for setting colors is the following:
-\begin{itemize}
- \itemoption{color}|=|\meta{color name}%
+\begin{key}{/tikz/color=\meta{color name}}
\indexoption{color option}%
This option sets the color that is used for fill, drawing, and text
inside the current scope. Any special settings for filling colors or
@@ -137,7 +138,7 @@ The most unspecific option for setting colors is the following:
\TeX\ group. |\aftergroup|-hackery is used to restore the color
after the group.
\end{itemize}
-\end{itemize}
+\end{key}
As pointed out above, the |color=| option applies to ``everything''
(except to shadings), which is not always what you want. Because of
@@ -150,8 +151,7 @@ where the path action they influence is described.
\subsection{Drawing a Path}
You can draw a path using the following option:
-\begin{itemize}
- \itemoption{draw}\opt{|=|\meta{color}}
+\begin{key}{/tikz/draw=\meta{color} (default \normalfont is scope's color setting)}
Causes the path to be drawn. ``Drawing'' (also known as
``stroking'') can be thought of as picking up a pen and moving it
along the path, thereby leaving ``ink'' on the canvas.
@@ -182,7 +182,8 @@ You can draw a path using the following option:
\path[draw=red] (0,0) -- (1,1) -- (2,1) circle (10pt);
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
+
The following subsections list the different options that influence
how a path is drawn. All of these options only have an effect if the
@@ -192,100 +193,104 @@ how a path is drawn. All of these options only have an effect if the
\label{section-cap-joins}
-\begin{itemize}
- \itemoption{line width}|=|\meta{dimension}
- Specifies the line width. Note the space. Default: |0.4pt|.
+\begin{key}{/tikz/line width=\meta{dimension} (initially 0.4pt)}
+ Specifies the line width. Note the space.
\begin{codeexample}[]
\tikz \draw[line width=5pt] (0,0) -- (1cm,1.5ex);
\end{codeexample}
-\end{itemize}
+\end{key}
There are a number of predefined styles that provide more ``natural''
ways of setting the line width. You can also redefine these
-styles. Remember that you can leave out the |style=| when setting a
-style.
+styles.
-\begin{itemize}
- \itemstyle{ultra thin}
+\begin{stylekey}{/tikz/ultra thin}
Sets the line width to 0.1pt.
\begin{codeexample}[]
\tikz \draw[ultra thin] (0,0) -- (1cm,1.5ex);
\end{codeexample}
+\end{stylekey}
- \itemstyle{very thin}
+\begin{stylekey}{/tikz/very thin}
Sets the line width to 0.2pt.
\begin{codeexample}[]
\tikz \draw[very thin] (0,0) -- (1cm,1.5ex);
\end{codeexample}
+\end{stylekey}
- \itemstyle{thin}
+\begin{stylekey}{/tikz/thin}
Sets the line width to 0.4pt.
\begin{codeexample}[]
\tikz \draw[thin] (0,0) -- (1cm,1.5ex);
\end{codeexample}
+\end{stylekey}
- \itemstyle{semithick}
+\begin{stylekey}{/tikz/semithick}
Sets the line width to 0.6pt.
\begin{codeexample}[]
\tikz \draw[semithick] (0,0) -- (1cm,1.5ex);
\end{codeexample}
+\end{stylekey}
- \itemstyle{thick}
+\begin{stylekey}{/tikz/thick}
Sets the line width to 0.8pt.
\begin{codeexample}[]
\tikz \draw[thick] (0,0) -- (1cm,1.5ex);
\end{codeexample}
+\end{stylekey}
- \itemstyle{very thick}
+\begin{stylekey}{/tikz/very thick}
Sets the line width to 1.2pt.
\begin{codeexample}[]
\tikz \draw[very thick] (0,0) -- (1cm,1.5ex);
\end{codeexample}
+\end{stylekey}
- \itemstyle{ultra thick}
+\begin{stylekey}{/tikz/ultra thick}
Sets the line width to 1.6pt.
\begin{codeexample}[]
\tikz \draw[ultra thick] (0,0) -- (1cm,1.5ex);
\end{codeexample}
-\end{itemize}
+\end{stylekey}
-\begin{itemize}
- \itemoption{cap}|=|\meta{type}
+
+\begin{key}{/tikz/line cap=\meta{type} (initially butt)}
Specifies how lines ``end.'' Permissible \meta{type} are |round|,
- |rect|, and |butt| (default). They have the following effects:
+ |rect|, and |butt|. They have the following effects:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{scope}[line width=10pt]
- \draw[cap=rect] (0,0 ) -- (1,0);
- \draw[cap=butt] (0,.5) -- (1,.5);
- \draw[cap=round] (0,1 ) -- (1,1);
+ \draw[line cap=rect] (0,0 ) -- (1,0);
+ \draw[line cap=butt] (0,.5) -- (1,.5);
+ \draw[line cap=round] (0,1 ) -- (1,1);
\end{scope}
\draw[white,line width=1pt]
(0,0 ) -- (1,0) (0,.5) -- (1,.5) (0,1 ) -- (1,1);
\end{tikzpicture}
\end{codeexample}
+\end{key}
- \itemoption{join}|=|\meta{type}
+\begin{key}{/tikz/line join=\meta{type} (initially miter)}
Specifies how lines ``join.'' Permissible \meta{type} are |round|,
- |bevel|, and |miter| (default). They have the following effects:
+ |bevel|, and |miter|. They have the following effects:
\begin{codeexample}[]
\begin{tikzpicture}[line width=10pt]
- \draw[join=round] (0,0) -- ++(.5,1) -- ++(.5,-1);
- \draw[join=bevel] (1.25,0) -- ++(.5,1) -- ++(.5,-1);
- \draw[join=miter] (2.5,0) -- ++(.5,1) -- ++(.5,-1);
+ \draw[line join=round] (0,0) -- ++(.5,1) -- ++(.5,-1);
+ \draw[line join=bevel] (1.25,0) -- ++(.5,1) -- ++(.5,-1);
+ \draw[line join=miter] (2.5,0) -- ++(.5,1) -- ++(.5,-1);
\useasboundingbox (0,1.5); % make bounding box bigger
\end{tikzpicture}
\end{codeexample}
- \itemoption{miter limit}|=|\meta{factor}
- When you use the miter join and there is a very sharp corner (a
- small angle), the miter join may protrude very far over the actual
- joining point. In this case, if it were to protrude by
- more than \meta{factor} times the line width, the miter join is
- replaced by a bevel join. Default value is |10|.
+ \begin{key}{/tikz/miter limit=\meta{factor} (initially 10)}
+ When you use the miter join and there is a very sharp corner (a
+ small angle), the miter join may protrude very far over the actual
+ joining point. In this case, if it were to protrude by
+ more than \meta{factor} times the line width, the miter join is
+ replaced by a bevel join.
\begin{codeexample}[]
\begin{tikzpicture}[line width=5pt]
@@ -294,14 +299,15 @@ style.
\useasboundingbox (14,0); % make bounding box bigger
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+ \end{key}
+\end{key}
\subsubsection{Graphic Parameters: Dash Pattern}
-\begin{itemize}
- \itemoption{dash pattern}|=|\meta{dash pattern}
+\begin{key}{/tikz/dash pattern=\meta{dash pattern}}
Sets the dashing pattern. The syntax is the same as in
- \textsc{metafont}. For example |on 2pt off 3pt on 4pt off 4pt| means ``draw
+ \textsc{metafont}. For example following pattern
+ |on 2pt off 3pt on 4pt off 4pt| means ``draw
2pt, then leave out 3pt, then draw 4pt once more, then leave out 4pt
again, repeat''.
@@ -310,8 +316,9 @@ style.
\draw (0pt,0pt) -- (3.5cm,0pt);
\end{tikzpicture}
\end{codeexample}
+\end{key}
- \itemoption{dash phase}|=|\meta{dash phase}
+\begin{key}{/tikz/dash phase=\meta{dash phase} (initially 0pt)}
Shifts the start of the dash pattern by \meta{phase}.
\begin{codeexample}[]
@@ -320,61 +327,66 @@ style.
\draw[dash phase=10pt] (0pt,0pt) -- (3.5cm,0pt);
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
As for the line thickness, some predefined styles allow you to set the
dashing conveniently.
-\begin{itemize}
-\itemstyle{solid}
+\begin{stylekey}{/tikz/solid}
Shorthand for setting a solid line as ``dash pattern.'' This is the default.
\begin{codeexample}[]
\tikz \draw[solid] (0pt,0pt) -- (50pt,0pt);
\end{codeexample}
+\end{stylekey}
- \itemstyle{dotted}
+\begin{stylekey}{/tikz/dotted}
Shorthand for setting a dotted dash pattern.
\begin{codeexample}[]
\tikz \draw[dotted] (0pt,0pt) -- (50pt,0pt);
\end{codeexample}
+\end{stylekey}
- \itemstyle{densely dotted}
+\begin{stylekey}{/tikz/densely dotted}
Shorthand for setting a densely dotted dash pattern.
\begin{codeexample}[]
\tikz \draw[densely dotted] (0pt,0pt) -- (50pt,0pt);
\end{codeexample}
+\end{stylekey}
- \itemstyle{loosely dotted}
+\begin{stylekey}{/tikz/loosely dotted}
Shorthand for setting a loosely dotted dash pattern.
\begin{codeexample}[]
\tikz \draw[loosely dotted] (0pt,0pt) -- (50pt,0pt);
\end{codeexample}
+\end{stylekey}
- \itemstyle{dashed}
+\begin{stylekey}{/tikz/dashed}
Shorthand for setting a dashed dash pattern.
\begin{codeexample}[]
\tikz \draw[dashed] (0pt,0pt) -- (50pt,0pt);
\end{codeexample}
+\end{stylekey}
- \itemstyle{densely dashed}
+\begin{stylekey}{/tikz/densely dashed}
Shorthand for setting a densely dashed dash pattern.
\begin{codeexample}[]
\tikz \draw[densely dashed] (0pt,0pt) -- (50pt,0pt);
\end{codeexample}
+\end{stylekey}
- \itemstyle{loosely dashed}
+\begin{stylekey}{/tikz/loosely dashed}
Shorthand for setting a loosely dashed dash pattern.
\begin{codeexample}[]
\tikz \draw[loosely dashed] (0pt,0pt) -- (50pt,0pt);
\end{codeexample}
-\end{itemize}
+\end{stylekey}
\subsubsection{Graphic Parameters: Draw Opacity}
@@ -382,90 +394,8 @@ dashing conveniently.
When a line is drawn, it will normally ``obscure'' everything behind
it as if you has used perfectly opaque ink. It is also possible to ask
\tikzname\ to use an ink that is a little bit (or a big bit)
-transparent. To do so, use the following option:
-
-\begin{itemize}
- \itemoption{draw opacity}|=|\meta{value}
- This option sets ``how transparent'' lines should be. A value of |1|
- means ``fully opaque'' or ``not transparent at all,'' a value of |0|
- means ``fully transparent'' or ``invisible.'' A value of |0.5|
- yields lines that are semitransparent.
-
- Note that when you use PostScript as your output format,
- this option works only with recent versions of GhostScript.
-
-\begin{codeexample}[]
-\begin{tikzpicture}[line width=1ex]
- \draw (0,0) -- (3,1);
- \filldraw [fill=examplefill,draw opacity=0.5] (1,0) rectangle (2,1);
-\end{tikzpicture}
-\end{codeexample}
-\end{itemize}
-
-Note that the |draw opacity| options only sets the opacity of drawn
-lines. The opacity of fillings is set using the option
-|fill opacity| (documented in Section~\ref{section-fill-opacity}. The
-option |opacity| sets both at the same time.
-
-\begin{itemize}
- \itemoption{opacity}|=|\meta{value}
- Sets both the drawing and filling opacity to \meta{value}.
-
- The following predefined styles make it easier to use this option:
- \begin{itemize}
- \itemstyle{transparent}
- Makes everything totally transparent and, hence, invisible.
-
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[transparent,red] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \itemstyle{ultra nearly transparent}
- Makes everything, well, ultra nearly transparent.
-
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[ultra nearly transparent] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \itemstyle{very nearly transparent}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[very nearly transparent] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \itemstyle{nearly transparent}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[nearly transparent] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \itemstyle{semitransparent}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[semitransparent] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \itemstyle{nearly opaque}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[nearly opaque] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \itemstyle{very nearly opaque}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[very nearly opaque] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \itemstyle{ultra nearly opaque}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[ultra nearly opaque] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \itemstyle{opaque}
- This yields completely opaque drawings, which is the default.
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[opaque] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{itemize}
-\end{itemize}
-
+transparent using the |draw opacity| option. This is explained in
+Section~\ref{section-tikz-transparency} on transparency in more detail.
@@ -477,8 +407,7 @@ the path consists of several segments, only the last segment gets
arrow tips. The behavior for paths that are closed is not specified
and may change in the future.
-\begin{itemize}
-\itemoption{arrows}\opt{|=|\meta{start arrow kind}|-|\meta{end arrow kind}}
+\begin{key}{/tikz/arrows=\meta{start arrow kind}|-|\meta{end arrow kind}}
This option sets the start and end arrow tips (an empty value as in |->|
indicates that no arrow tip should be drawn at the start).%
\indexoption{arrows}
@@ -515,8 +444,9 @@ and may change in the future.
\useasboundingbox (-.1,-.1) rectangle (3.1,1.1); % make bounding box bigger
\end{tikzpicture}
\end{codeexample}
+\end{key}
- \itemoption{>}|=|\meta{end arrow kind}
+\begin{key}{/tikz/>=\meta{end arrow kind}}
This option can be used to redefine the ``standard'' arrow tip |>|. The
idea is that different people have different ideas what arrow tip kind
should normally be used. I prefer the arrow tip of \TeX's |\to| command
@@ -539,7 +469,7 @@ and may change in the future.
\begin{tikzpicture}[scale=2]
\begin{scope}[>=latex]
\draw[->] (0pt,6ex) -- (1cm,6ex);
- \draw[>->>] (0pt,5ex) -- (1cm,5ex);
+ \draw[>->>] (0pt,5ex) -- (1cm,5ex);
\draw[|<->|] (0pt,4ex) -- (1cm,4ex);
\end{scope}
\begin{scope}[>=diamond]
@@ -548,9 +478,11 @@ and may change in the future.
\draw[|<->|] (0pt,0ex) -- (1cm,0ex);
\end{scope}
\end{tikzpicture}
-\end{codeexample}
+\end{codeexample}
+% <<
+\end{key}
- \itemoption{shorten >}|=|\meta{dimension}
+\begin{key}{/tikz/shorten >=\meta{dimension} (initially 0pt)}
This option will shorten the end of lines by the given
\meta{dimension}. If you specify an arrow tip, lines are already
shortened a bit such that the arrow tip touches the specified endpoint
@@ -575,17 +507,18 @@ and may change in the future.
\draw[-to,shorten >=10pt,gray] (0,0) -- (3,0);
\end{tikzpicture}
\end{codeexample}
+\end{key}
+
- \itemoption{shorten <}|=|\meta{dimension} works like |shorten >|,
- but for the start.
-\end{itemize}
+\begin{key}{/tikz/shorten <=\meta{dimension}}
+ Works like |shorten >|, but for the start.
+\end{key}
\subsubsection{Graphic Parameters: Double Lines and Bordered Lines}
-\begin{itemize}
- \itemoption{double}\opt{|=|\meta{core color}}
+\begin{key}{/tikz/double=\meta{core color} (default white)}
This option causes ``two'' lines to be drawn instead of a single
one. However, this is not what really happens. In reality, the path
is drawn twice. First, with the normal drawing color, secondly with
@@ -608,10 +541,11 @@ and may change in the future.
\draw[draw=white,double=red,very thick] (0,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
+\end{key}
- \itemoption{double distance}|=|\meta{dimension}
- Sets the distance the ``two'' lines are spaced apart (default is
- 0.6pt). In reality, this is the thickness of the line that is used
+\begin{key}{/tikz/double distance=\meta{dimension} (initially 0.6pt)}
+ Sets the distance the ``two'' lines are spaced apart. In reality,
+ this is the thickness of the line that is used
to draw the path for the second time. The thickness of the
\emph{first} time the path is drawn is twice the normal line width
plus the given \meta{dimension}. As a side-effect, this option
@@ -624,7 +558,7 @@ and may change in the future.
\draw[thin,double distance=2pt] (2,0) arc (180:90:1cm);
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
@@ -635,8 +569,7 @@ and may change in the future.
\subsection{Filling a Path}
\label{section-rules}
To fill a path, use the following option:
-\begin{itemize}
- \itemoption{fill}\opt{|=|\meta{color}}
+\begin{key}{/tikz/fill=\meta{color} (default \normalfont is scope's color setting)}
This option causes the path to be filled. All unclosed parts of the
path are first closed, if necessary. Then, the area enclosed by the
path is filled with the current filling color, which is either the
@@ -676,7 +609,7 @@ To fill a path, use the following option:
\filldraw (8,0) -- (9,1) -- (10,0) circle (.5cm);
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
@@ -703,8 +636,7 @@ pattern. For complicated case, it may be easier to use two nested
|\foreach| statements to simulate a pattern, but patterns are rendered
\emph{much} more quickly than simulated ones.
-\begin{itemize}
- \itemoption{pattern}\opt{|=|\meta{name}}
+\begin{key}{/tikz/pattern=\meta{name} (default \normalfont is scope's pattern)}
This option causes the path to be filled with a pattern. If the
\meta{name} is given, this pattern is used, otherwise the pattern
set in the enclosing scope is used. As for the |draw| and |fill|
@@ -713,7 +645,7 @@ pattern. For complicated case, it may be easier to use two nested
The pattern works like a fill color. In particular, setting a new
fill color will fill the path with a solid color once more.
- Strangely, no \meta{name}s are permissible by default. You neet to
+ Strangely, no \meta{name}s are permissible by default. You need to
load for instance |pgflibrarypatterns|, see
Section~\ref{section-library-patterns}, to install predefined
patterns.
@@ -724,8 +656,9 @@ pattern. For complicated case, it may be easier to use two nested
\draw[pattern=fivepointed stars] (0,0) rectangle (3,1);
\end{tikzpicture}
\end{codeexample}
+\end{key}
- \itemoption{pattern color}|=|\meta{color}
+\begin{key}{/tikz/pattern color=\meta{color}}
This option is used to set the color to be used for form-only
patterns. This option has no effect on inherently colored patterns.
@@ -743,15 +676,14 @@ pattern. For complicated case, it may be easier to use two nested
\pattern[pattern color=white,pattern=bricks] \mypath;
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
\subsubsection{Graphic Parameters: Interior Rules}
The following two options can be used to decide how interior points
should be determined:
-\begin{itemize}
- \itemoption{nonzero rule}
+\begin{key}{/tikz/nonzero rule}
If this rule is used (which is the default), the following method is
used to determine whether a given point is ``inside'' the path: From
the point, shoot a ray in some direction towards infinity (the
@@ -791,8 +723,9 @@ should be determined:
\end{scope}
\end{tikzpicture}
\end{codeexample}
+\end{key}
-\itemoption{even odd rule}
+\begin{key}{/tikz/even odd rule}
This option causes a different method to be used for determining the
inside and outside of paths. While it is less flexible, it turns out
to be more intuitive.
@@ -811,7 +744,7 @@ should be determined:
\draw[->] (0.5,0.5) -- +(0,1) [above] node{crossings: $1+1 = 2$};
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
@@ -819,33 +752,8 @@ should be determined:
\label{section-fill-opacity}
Analogously to the |draw opacity|, you can also set the filling
-opacity:
-
-\begin{itemize}
- \itemoption{fill opacity}|=|\meta{value}
- This option sets the opacity of fillings. In addition to filling
- operations, this opacity also applies to text and images.
-
- Note, again, that when you use PostScript as your output format,
- this option works only with recent versions of GhostScript.
-
-\begin{codeexample}[]
-\begin{tikzpicture}[thick,fill opacity=0.5]
- \filldraw[fill=red] (0:1cm) circle (12mm);
- \filldraw[fill=green] (120:1cm) circle (12mm);
- \filldraw[fill=blue] (-120:1cm) circle (12mm);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \fill[red] (0,0) rectangle (3,2);
-
- \node at (0,0) {\huge A};
- \node[fill opacity=0.5] at (3,2) {\huge B};
-\end{tikzpicture}
-\end{codeexample}
-\end{itemize}
+opacity. Please see Section~\ref{section-tikz-transparency} for more
+details.
\subsection{Shading a Path}
@@ -854,8 +762,7 @@ You can shade a path using the |shade| option. A shading is like a
filling, only the shading changes its color smoothly from one color to
another.
-\begin{itemize}
- \itemoption{shade}
+\begin{key}{/tikz/shade}
Causes the path to be shaded using the currently selected shading
(more on this later). If this option is used together with the
|draw| option, then the path is first shaded, then drawn.
@@ -870,7 +777,7 @@ another.
\begin{codeexample}[]
\tikz \shadedraw (0,0) circle (1ex);
\end{codeexample}
-\end{itemize}
+\end{key}
For some shadings it is not really clear how they can ``fill'' the
path. For example, the |ball| shading normally looks like this: \tikz
@@ -896,8 +803,7 @@ option. Note that this does \emph{not} change the shading color, only
the way the colors sweep. For changing the colors, other options are
needed, which are explained below.
-\begin{itemize}
- \itemoption{shading}|=|\meta{name}
+\begin{key}{/tikz/shading=\meta{name}}
This selects a shading named \meta{name}. The following shadings are
predefined:
\begin{itemize}
@@ -937,16 +843,17 @@ needed, which are explained below.
\tikz \shadedraw [shading=ball] (0,0) circle (.5cm);
\end{codeexample}
\end{itemize}
- \itemoption{shading angle}|=|\meta{degrees}
- This option rotates the shading (not the path!) by the given
- angle. For example, we can turn a top-to-bottom axis shading into a
- left-to-right shading by rotating it by $90^\circ$.
+
+ \begin{key}{/tikz/shading angle=\meta{degrees} (initially 0)}
+ This option rotates the shading (not the path!) by the given
+ angle. For example, we can turn a top-to-bottom axis shading into a
+ left-to-right shading by rotating it by $90^\circ$.
\begin{codeexample}[]
\tikz \shadedraw [shading=axis,shading angle=90] (0,0) rectangle (1,1);
\end{codeexample}
-\end{itemize}
-
+ \end{key}
+\end{key}
You can also define new shading types yourself. However, for this, you
need to use the basic layer directly, which is, well, more basic and
@@ -961,8 +868,7 @@ The following options can be used to change the colors used for
shadings. When one of these options is given, the |shade| option is
automatically selected and also the ``right'' shading.
-\begin{itemize}
- \itemoption{top color}|=|\meta{color}
+\begin{key}{/tikz/top color=\meta{color}}
This option prescribes the color to be used at the top in an |axis|
shading. When this option is given, several things happen:
\begin{enumerate}
@@ -981,11 +887,13 @@ automatically selected and also the ``right'' shading.
\begin{codeexample}[]
\tikz \draw[top color=red] (0,0) rectangle (2,1);
\end{codeexample}
-
- \itemoption{bottom color}|=|\meta{color}
+\end{key}
+
+\begin{key}{/tikz/bottom color=\meta{color}}
This option works like |top color|, only for the bottom color.
-
- \itemoption{middle color}|=|\meta{color}
+\end{key}
+
+\begin{key}{/tikz/middle color=\meta{color}}
This option specifies the color for the middle of an axis
shading. It also sets the |shade| and |shading=axis| options, but it
does not change the rotation angle.
@@ -998,15 +906,18 @@ automatically selected and also the ``right'' shading.
\tikz \draw[top color=white,bottom color=black,middle color=red]
(0,0) rectangle (2,1);
\end{codeexample}
+\end{key}
- \itemoption{left color}|=|\meta{color}
+\begin{key}{/tikz/left color=\meta{color}}
This option does exactly the same as |top color|, except that the
shading angle is set to $90^\circ$.
+\end{key}
- \itemoption{right color}|=|\meta{color}
+\begin{key}{/tikz/right color=\meta{color}}
Works like |left color|.
+\end{key}
- \itemoption{inner color}|=|\meta{color}
+\begin{key}{/tikz/inner color=\meta{color}}
This option sets the color used at the center of a |radial|
shading. When this option is used, the |shade| and |shading=radial|
options are set.
@@ -1014,8 +925,9 @@ automatically selected and also the ``right'' shading.
\begin{codeexample}[]
\tikz \draw[inner color=red] (0,0) rectangle (2,1);
\end{codeexample}
+\end{key}
- \itemoption{outer color}|=|\meta{color}
+\begin{key}{/tikz/outer color=\meta{color}}
This option sets the color used at the border and outside of a
|radial| shading.
@@ -1023,8 +935,10 @@ automatically selected and also the ``right'' shading.
\tikz \draw[outer color=red,inner color=white]
(0,0) rectangle (2,1);
\end{codeexample}
+\end{key}
+
- \itemoption{ball color}|=|\meta{color}
+\begin{key}{/tikz/ball color=\meta{color}}
This option sets the color used for the ball shading. It sets the
|shade| and |shading=ball| options. Note that the ball will never
``completely'' have the color \meta{color}. At its ``highlight'' spot
@@ -1039,8 +953,7 @@ automatically selected and also the ``right'' shading.
\shade[ball color=black] (2,0) circle (2ex);
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
-
+\end{key}
@@ -1054,8 +967,7 @@ actually a little large.'' For this you can use the option
|use as bounding box| or the command |\useasboundingbox|, which is just
a shorthand for |\path[use as bounding box]|.
-\begin{itemize}
- \itemoption{use as bounding box}
+\begin{key}{/tikz/use as bounding box}
Normally, when this option is given on a path, the bounding box of
the present path is used to determine the size of the picture and
the size of all \emph{subsequent} paths are
@@ -1093,7 +1005,7 @@ right of picture.
Note: If this option is used on a path inside a \TeX\ group (scope),
the effect ``lasts'' only till the end of the scope. Again, this
behavior is the same as for clipping.
-\end{itemize}
+\end{key}
There is a node that allows you to get the size of the current
bounding box. The |current bounding box| node has the |rectangle|
@@ -1121,14 +1033,24 @@ hape and the size of the bounding box of the current path.
+\subsection{Clipping and Fading (Soft Clipping)}
+\emph{Clipping path} means that all painting on the page is restricted
+to a certain area. This area need not be rectangular, rather an
+arbitrary path can be used to specify this area. The |clip| option,
+explained below, is used to specify the region that is to be used for
+clipping.
-\subsection{Using a Path For Clipping}
+A \emph{fading} (a term that I propose, fadings are commonly known
+as soft masks, transparency masks, opacity masks or soft clips) is
+similar to clipping, but a fading allows parts of the picture to be
+only ``half clipped.'' This means that a fading can specify that newly
+painted pixels should be partly transparent. The specification
+and handling of fadings is a bit complex and it is detailed in
+Section~\ref{section-tikz-transparency}, which is devoted to
+transparency in general.
-To use a path for clipping, use the |clip| option.
-
-\begin{itemize}
- \itemoption{clip}
+\begin{key}{/tikz/clip}
This option causes all subsequent drawings to be clipped against the
current path and the size of subsequent paths will not be important
for the picture size. If you clip against a self-intersecting path,
@@ -1190,4 +1112,197 @@ To use a path for clipping, use the |clip| option.
\pdf\ specification. You do not want to know the details. It is best
simply not to specify any options for these
commands.
-\end{itemize}
+\end{key}
+
+
+
+\subsection{Doing Multiple Actions on a Path}
+
+If more than one of the basic actions like drawing, clipping and
+filling are requested, they are automatically applied in a sensible
+order: First, a path is filled, then drawn, and then clipped (although
+it took Apple two mayor revisions of their operating system to get
+this right\dots). Sometimes, however, you need finer control over what
+is done with a path. For instance, you might wish to first fill a path
+with a color, then repaint the path with a pattern and then repaint it
+with yet another pattern. In such cases you can use the following two
+options:
+
+\begin{key}{/tikz/preactions=\meta{options}}
+ This option can be given to a |\path| command (or to derived
+ commands like |\draw| which internally call |\path|). Similarly to
+ options like |draw|, this option only has an effect when given to a
+ |\path| or as part of the options of a |node|; as an option to a
+ |{scope}| it has no effect.
+
+ When this option is used on a |\path|, the effect is the following:
+ When the path has been completely constructed and is about to be
+ used, a scope is created. Inside this scope, the path is used but
+ not with the original path options, but with \meta{options}
+ instead. Then, the path is used in the usual manner. In other words,
+ the path is used twice: Once with \meta{options} in force and then
+ again with the normal path options in force.
+
+ Here is an example in which the path consists of a rectangle. The
+ main action is to draw this path in red (which is why we see a red
+ rectangle). However, the preaction is to draw the path in blue,
+ which is why we see a blue rectangle behind the red rectangle.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (3,2);
+
+ \draw
+ [preaction={draw,line width=4mm,blue}]
+ [line width=2mm,red] (0,0) rectangle (2,2);
+\end{tikzpicture}
+\end{codeexample}
+
+ Note that when the preactions are preformed, then the path is
+ already ``finished.'' In particular, applying a coordinate
+ transformation to the path has no effect. By comparison, applying a
+ canvas transformation does have an effect. Let us use this to add a
+ ``shadow'' to a path. For this, we use the preaction to fill the
+ path in gray, shifted a bit to the right and down:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (3,2);
+ \draw
+ [preaction={fill=black,opacity=.5,
+ transform canvas={xshift=1mm,yshift=-1mm}}]
+ [fill=red] (0,0) rectangle (1,2)
+ (1,2) circle (5mm);
+\end{tikzpicture}
+\end{codeexample}
+
+ Naturally, you would normally create a style |shadow| that contains
+ the above code. The shadow library, see
+ Section~\ref{section-libs-shadows}, contains predefined shadows of
+ this kind.
+
+ It is possible to use the |preaction| option multiple times. In this
+ case, for each use of the |preaction| option, the path is used again
+ (thus, the \meta{options} do not accumulate in a single usage of the
+ path). The path is used in the order of |preaction| options given.
+
+ In the following example, we use one |preaction| to add a shadow and
+ another to provide a shading, while the main action is to use a
+ pattern.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (3,2);
+ \draw [pattern=fivepointed stars]
+ [preaction={fill=black,opacity=.5,
+ transform canvas={xshift=1mm,yshift=-1mm}}]
+ [preaction={top color=blue,bottom color=white}]
+ (0,0) rectangle (1,2)
+ (1,2) circle (5mm);
+\end{tikzpicture}
+\end{codeexample}
+
+ A complicated application is shown in the following example, where
+ the path is used several times with different fadings and shadings
+ to create a special visual effect:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ [
+ % Define an interesting style
+ button/.style={
+ % First preaction: Fuzzy shadow
+ preaction={fill=black,path fading=circle with fuzzy edge 20 percent,
+ opacity=.5,transform canvas={xshift=1mm,yshift=-1mm}},
+ % Second preaction: Background pattern
+ preaction={pattern=#1,
+ path fading=circle with fuzzy edge 15 percent},
+ % Third preaction: Make background shiny
+ preaction={top color=white,
+ bottom color=black!50,
+ shading angle=45,
+ path fading=circle with fuzzy edge 15 percent,
+ opacity=0.2},
+ % Fourth preaction: Make edge especially shiny
+ preaction={path fading=fuzzy ring 15 percent,
+ top color=black!5,
+ bottom color=black!80,
+ shading angle=45},
+ inner sep=2ex
+ },
+ button/.default=horizontal lines light blue,
+ circle
+ ]
+
+ \draw [help lines] (0,0) grid (4,3);
+
+ \node [button] at (2.2,1) {\Huge Big};
+ \node [button=crosshatch dots light steel blue,
+ text=white] at (1,1.5) {Small};
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+\begin{key}{/tikz/postaction=\meta{options}}
+ The postactions work in the same way as the preactions, only they
+ are applied \emph{after} the main action has been taken. Like
+ preactions, multiple |postaction| options may be given to a |\path|
+ command, in which case the path is reused several times, each time
+ with a different set of options in force.
+
+ If both pre- and postactions are specified, then the preactions are
+ taken first, then the main action, and then the post actions.
+
+ In the first example, we use a postaction to draw the path, after it
+ has already been drawn:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (3,2);
+
+ \draw
+ [postaction={draw,line width=2mm,blue}]
+ [line width=4mm,red,fill=white] (0,0) rectangle (2,2);
+\end{tikzpicture}
+\end{codeexample}
+
+ In another example, we use a postaction to ``colorzie'' a path:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (3,2);
+ \draw
+ [postaction={path fading=south,fill=white}]
+ [postaction={path fading=south,fading angle=45,fill=blue,opacity=.5}]
+ [left color=black,right color=red,draw=white,line width=2mm]
+ (0,0) rectangle (1,2)
+ (1,2) circle (5mm);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+
+
+\subsection{Decorating and Morphing a Path}
+
+Before a path is used, it is possible to first ``decorate'' and/or
+``morph'' it. Morphing means that the path is replaced by another path
+that slightly varied. Such morphings are a special case
+of the more general ``decorations'' described in detail in
+Section~\ref{section-tikz-decorations}. For instance, in the following
+example the path is drawn twice: Once normally and then in a morphed
+(=decorated) manner.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw (0,0) rectangle (3,2);
+ \draw [red, decorate, decoration=zigzag]
+ (0,0) rectangle (3,2);
+\end{tikzpicture}
+\end{codeexample}
+
+Naturally, we could have combined this into a single command using
+pre- or postaction. It is also possible to deform shapes:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node [circular drop shadow={shadow scale=1.05},minimum size=3.13cm,
+ decorate, decoration=zigzag,
+ fill=blue!20,draw,thick,circle] {Hello!};
+\end{tikzpicture}
+\end{codeexample}
+