diff options
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.tex | 1231 |
1 files changed, 652 insertions, 579 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 bb201599575..cad08b6b71b 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 @@ -7,45 +7,45 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. + \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 -can be used to specify the extend of the picture---or any -combination of these actions at the same time. - -To decide what is to be done with a path, two methods can be -used. First, you can use a special-purpose command like |\draw| to -indicate that the path should be drawn. However, commands like |\draw| -and |\fill| are just abbreviations for special cases of the more -general method: Here, the |\path| command is used to specify the -path. Then, options encountered on the path indicate what should be +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 can be used to specify the +extend of the picture -- or any combination of these actions at the same time. + +To decide what is to be done with a path, two methods can be used. First, you +can use a special-purpose command like |\draw| to indicate that the path should +be drawn. However, commands like |\draw| and |\fill| are just abbreviations for +special cases of the more general method: Here, the |\path| command is used to +specify the path. Then, options encountered on the path indicate what should be done with the path. -For example, |\path (0,0) circle (1cm);| means ``This is a path -consisting of a circle around the origin. Do not do anything with it -(throw it away).'' However, if the option |draw| is encountered -anywhere on the path, the circle will be drawn. ``Anywhere'' is any -point on the path where an option can be given, which is everywhere -where a path command like |circle (1cm)| or |rectangle (1,1)| or even -just |(0,0)| would also be allowed. Thus, the following commands all -draw the same circle: +For example, |\path (0,0) circle (1cm);| means: ``This is a path consisting of +a circle around the origin. Do not do anything with it (throw it away).'' +However, if the option |draw| is encountered anywhere on the path, the circle +will be drawn. ``Anywhere'' is any point on the path where an option can be +given, which is everywhere where a path command like |circle (1cm)| or +|rectangle (1,1)| or even just |(0,0)| would also be allowed. Thus, the +following commands all draw the same circle: +% \begin{codeexample}[code only] \path [draw] (0,0) circle (1cm); \path (0,0) [draw] circle (1cm); \path (0,0) circle (1cm) [draw]; \end{codeexample} -Finally, |\draw (0,0) circle (1cm);| also draws a path, because -|\draw| is an abbreviation for |\path [draw]| and thus the command -expands to the first line of the above example. +% +Finally, |\draw (0,0) circle (1cm);| also draws a path, because |\draw| is an +abbreviation for |\path [draw]| and thus the command expands to the first line +of the above example. -Similarly, |\fill| is an abbreviation for |\path[fill]| and -|\filldraw| is an abbreviation for the command -|\path[fill,draw]|. Since options accumulate, the following commands -all have the same effect: +Similarly, |\fill| is an abbreviation for |\path[fill]| and |\filldraw| is an +abbreviation for the command |\path[fill,draw]|. Since options accumulate, the +following commands all have the same effect: +% \begin{codeexample}[code only] \path [draw,fill] (0,0) circle (1cm); \path [draw] [fill] (0,0) circle (1cm); @@ -55,229 +55,246 @@ all have the same effect: \filldraw (0,0) circle (1cm); \end{codeexample} -In the following subsection the different actions that -can be performed on a path are explained. The following commands are abbreviations for -certain sets of actions, but for many useful combinations there are no -abbreviations: +In the following subsection the different actions that can be performed on a +path are explained. The following commands are abbreviations for certain sets +of actions, but for many useful combinations there are no abbreviations: \begin{command}{\draw} - Inside |{tikzpicture}| this is an abbreviation for |\path[draw]|. + Inside |{tikzpicture}| this is an abbreviation for |\path[draw]|. \end{command} \begin{command}{\fill} - Inside |{tikzpicture}| this is an abbreviation for |\path[fill]|. + Inside |{tikzpicture}| this is an abbreviation for |\path[fill]|. \end{command} \begin{command}{\filldraw} - Inside |{tikzpicture}| this is an abbreviation for |\path[fill,draw]|. + Inside |{tikzpicture}| this is an abbreviation for |\path[fill,draw]|. \end{command} \begin{command}{\pattern} - Inside |{tikzpicture}| this is an abbreviation for |\path[pattern]|. + Inside |{tikzpicture}| this is an abbreviation for |\path[pattern]|. \end{command} \begin{command}{\shade} - Inside |{tikzpicture}| this is an abbreviation for |\path[shade]|. + Inside |{tikzpicture}| this is an abbreviation for |\path[shade]|. \end{command} \begin{command}{\shadedraw} - Inside |{tikzpicture}| this is an abbreviation for |\path[shade,draw]|. + Inside |{tikzpicture}| this is an abbreviation for |\path[shade,draw]|. \end{command} \begin{command}{\clip} - Inside |{tikzpicture}| this is an abbreviation for |\path[clip]|. + Inside |{tikzpicture}| this is an abbreviation for |\path[clip]|. \end{command} \begin{command}{\useasboundingbox} - Inside |{tikzpicture}| this is an abbreviation for |\path[use as bounding box]|. + Inside |{tikzpicture}| this is an abbreviation for |\path[use as bounding box]|. \end{command} - \subsection{Specifying a Color} The most unspecific option for setting colors is the following: - +% \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 - drawing colors are immediately ``overruled'' by this option. - - The \meta{color name} is the name of a previously defined color. For - \LaTeX\ users, this is just a normal ``\LaTeX-color'' and the - |xcolor| extensions are allowed. Here is an example: + \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 drawing + colors are immediately ``overruled'' by this option. + The \meta{color name} is the name of a previously defined color. For + \LaTeX\ users, this is just a normal ``\LaTeX-color'' and the |xcolor| + extensions are allowed. Here is an example: + % \begin{codeexample}[] \tikz \fill[color=red!20] (0,0) circle (1ex); \end{codeexample} - It is possible to ``leave out'' the |color=| part and you can also - write: + It is possible to ``leave out'' the |color=| part and you can also write: + % \begin{codeexample}[] \tikz \fill[red!20] (0,0) circle (1ex); \end{codeexample} - What happens is that every option that \tikzname\ does not know, like - |red!20|, gets a ``second chance'' as a color name. - - For plain \TeX\ users, it is not so easy to specify colors since - plain \TeX\ has no ``standardized'' color naming - mechanism. Because of this, \pgfname\ emulates the |xcolor| package, - though the emulation is \emph{extremely basic} (more precisely, what - I could hack together in two hours or so). The emulation allows you - to do the following: - \begin{itemize} - \item Specify a new color using |\definecolor|. Only the two color - models |gray| and |rgb| are supported\footnote{Con\TeX t users should be aware that \texttt{\textbackslash definecolor} has a different meaning in Con\TeX t. There is a low-level equivalent named \texttt{\textbackslash pgfutil@definecolor} which can be used instead.}.% - \example |\definecolor{orange}{rgb}{1,0.5,0}| - \item Use |\colorlet| to define a new color based on an old - one. Here, the |!| mechanism is supported, though only ``once'' - (use multiple |\colorlet| for more fancy colors). - \example |\colorlet{lightgray}{black!25}| - \item Use |\color|\marg{color name} to set the color in the current - \TeX\ group. |\aftergroup|-hackery is used to restore the color - after the group. - \end{itemize} + % + What happens is that every option that \tikzname\ does not know, like + |red!20|, gets a ``second chance'' as a color name. + + For plain \TeX\ users, it is not so easy to specify colors since plain + \TeX\ has no ``standardized'' color naming mechanism. Because of this, + \pgfname\ emulates the |xcolor| package, though the emulation is + \emph{extremely basic} (more precisely, what I could hack together in two + hours or so). The emulation allows you to do the following: + % + \begin{itemize} + \item Specify a new color using |\definecolor|. Only the two color + models |gray| and |rgb| are supported\footnote{Con\TeX t users + should be aware that \texttt{\textbackslash definecolor} has a + different meaning in Con\TeX t. There is a low-level equivalent + named \texttt{\textbackslash pgfutil@definecolor} which can be + used instead.}. + % + \example |\definecolor{orange}{rgb}{1,0.5,0}| + \item Use |\colorlet| to define a new color based on an old one. + Here, the |!| mechanism is supported, though only ``once'' (use + multiple |\colorlet| for more fancy colors). + % + \example |\colorlet{lightgray}{black!25}| + \item Use |\color|\marg{color name} to set the color in the current + \TeX\ group. |\aftergroup|-hackery is used to restore the color + after the group. + \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 -this, there are several more specialized color options. For example, -the |draw=| option sets the color used for drawing, but does not -modify the color used for filling. These color options are documented -where the path action they influence is described. +As pointed out above, the |color=| option applies to ``everything'' (except to +shadings), which is not always what you want. Because of this, there are +several more specialized color options. For example, the |draw=| option sets +the color used for drawing, but does not modify the color used for filling. +These color options are documented where the path action they influence is +described. \subsection{Drawing a Path} You can draw a path using the following option: +% \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. - - There are numerous parameters that influence how a line is drawn, - like the thickness or the dash pattern. These options are explained - below. - - If the optional \meta{color} argument is given, drawing is done - using the given \meta{color}. This color can be different from the - current filling color, which allows you to draw and fill a path with - different colors. If no \meta{color} argument is given, the last - usage of the |color=| option is used. - - If the special color name |none| is given, this option causes - drawing to be ``switched off.'' This is useful if a style has - previously switched on drawing and you locally wish to undo this - effect. - - Although this option is normally used on paths to indicate that the - path should be drawn, it also makes sense to use the option with a - |{scope}| or |{tikzpicture}| environment. However, this will - \emph{not} cause all paths to be drawn. Instead, this just sets the - \meta{color} to be used for drawing paths inside the environment. - + 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. + + There are numerous parameters that influence how a line is drawn, like the + thickness or the dash pattern. These options are explained below. + + If the optional \meta{color} argument is given, drawing is done using the + given \meta{color}. This color can be different from the current filling + color, which allows you to draw and fill a path with different colors. If + no \meta{color} argument is given, the last usage of the |color=| option is + used. + + If the special color name |none| is given, this option causes drawing to be + ``switched off''. This is useful if a style has previously switched on + drawing and you locally wish to undo this effect. + + Although this option is normally used on paths to indicate that the path + should be drawn, it also makes sense to use the option with a |{scope}| or + |{tikzpicture}| environment. However, this will \emph{not} cause all paths + to be drawn. Instead, this just sets the \meta{color} to be used for + drawing paths inside the environment. + % \begin{codeexample}[] \begin{tikzpicture} \path[draw=red] (0,0) -- (1,1) -- (2,1) circle (10pt); \end{tikzpicture} \end{codeexample} + % \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 |draw| option is +given (directly or indirectly). -The following subsections list the different options that influence -how a path is drawn. All of these options only have an effect if the -|draw| option is given (directly or indirectly). \subsubsection{Graphic Parameters: Line Width, Line Cap, and Line Join} - \label{section-cap-joins} \begin{key}{/tikz/line width=\meta{dimension} (initially 0.4pt)} - Specifies the line width. Note the space. - + Specifies the line width. Note the space. + % \begin{codeexample}[] \tikz \draw[line width=5pt] (0,0) -- (1cm,1.5ex); \end{codeexample} + % \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. +There are a number of predefined styles that provide more ``natural'' ways of +setting the line width. You can also redefine these styles. \begin{stylekey}{/tikz/ultra thin} - Sets the line width to 0.1pt. + Sets the line width to 0.1pt. + % \begin{codeexample}[] \tikz \draw[ultra thin] (0,0) -- (1cm,1.5ex); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/very thin} - Sets the line width to 0.2pt. + Sets the line width to 0.2pt. + % \begin{codeexample}[] \tikz \draw[very thin] (0,0) -- (1cm,1.5ex); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/thin} - Sets the line width to 0.4pt. + Sets the line width to 0.4pt. + % \begin{codeexample}[] \tikz \draw[thin] (0,0) -- (1cm,1.5ex); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/semithick} - Sets the line width to 0.6pt. + Sets the line width to 0.6pt. + % \begin{codeexample}[] \tikz \draw[semithick] (0,0) -- (1cm,1.5ex); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/thick} - Sets the line width to 0.8pt. + Sets the line width to 0.8pt. + % \begin{codeexample}[] \tikz \draw[thick] (0,0) -- (1cm,1.5ex); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/very thick} - Sets the line width to 1.2pt. + Sets the line width to 1.2pt. + % \begin{codeexample}[] \tikz \draw[very thick] (0,0) -- (1cm,1.5ex); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/ultra thick} - Sets the line width to 1.6pt. + Sets the line width to 1.6pt. + % \begin{codeexample}[] \tikz \draw[ultra thick] (0,0) -- (1cm,1.5ex); \end{codeexample} + % \end{stylekey} - -\label{section-line-cap} - + \label{section-line-cap} \begin{key}{/tikz/line cap=\meta{type} (initially butt)} - Specifies how lines ``end.'' Permissible \meta{type} are |round|, - |rect|, and |butt|. They have the following effects: - + Specifies how lines ``end''. Permissible \meta{type} are |round|, |rect|, + and |butt|. They have the following effects: + % \begin{codeexample}[] \begin{tikzpicture} \begin{scope}[line width=10pt] - \draw[line cap=rect] (0,0 ) -- (1,0); - \draw[line cap=butt] (0,.5) -- (1,.5); - \draw[line cap=round] (0,1 ) -- (1,1); + \draw[line cap=round] (0,1 ) -- +(1,0); + \draw[line cap=butt] (0,.5) -- +(1,0); + \draw[line cap=rect] (0,0 ) -- +(1,0); \end{scope} \draw[white,line width=1pt] - (0,0 ) -- (1,0) (0,.5) -- (1,.5) (0,1 ) -- (1,1); + (0,0 ) -- +(1,0) (0,.5) -- +(1,0) (0,1 ) -- +(1,0); \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/line join=\meta{type} (initially miter)} - Specifies how lines ``join.'' Permissible \meta{type} are |round|, - |bevel|, and |miter|. They have the following effects: - + Specifies how lines ``join''. Permissible \meta{type} are |round|, |bevel|, + and |miter|. They have the following effects: + % \begin{codeexample}[] \begin{tikzpicture}[line width=10pt] \draw[line join=round] (0,0) -- ++(.5,1) -- ++(.5,-1); @@ -287,13 +304,12 @@ styles. \end{tikzpicture} \end{codeexample} - \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{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] \draw (0,0) -- ++(5,.5) -- ++(-5,.5); @@ -301,191 +317,214 @@ styles. \useasboundingbox (14,0); % make bounding box bigger \end{tikzpicture} \end{codeexample} - \end{key} + \end{key} \end{key} + \subsubsection{Graphic Parameters: 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 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''. - + Sets the dashing pattern. The syntax is the same as in \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''. + % \begin{codeexample}[] \begin{tikzpicture}[dash pattern=on 2pt off 3pt on 4pt off 4pt] \draw (0pt,0pt) -- (3.5cm,0pt); \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/dash phase=\meta{dash phase} (initially 0pt)} - Shifts the start of the dash pattern by \meta{phase}. - + Shifts the start of the dash pattern by \meta{phase}. + % \begin{codeexample}[] \begin{tikzpicture}[dash pattern=on 20pt off 10pt] \draw[dash phase=0pt] (0pt,3pt) -- (3.5cm,3pt); \draw[dash phase=10pt] (0pt,0pt) -- (3.5cm,0pt); \end{tikzpicture} \end{codeexample} + % \end{key} -As for the line thickness, some predefined styles allow you to set the -dashing conveniently. +\begin{key}{/tikz/dash=\meta{dash pattern}|phase|\meta{dash phase}} + Sets the dashing pattern and phase at the same time. + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw [dash=on 20pt off 10pt phase 0pt] (0pt,3pt) -- (3.5cm,3pt); + \draw [dash=on 20pt off 10pt phase 10pt] (0pt,0pt) -- (3.5cm,0pt); +\end{tikzpicture} +\end{codeexample} + % +\end{key} -\begin{stylekey}{/tikz/solid} - Shorthand for setting a solid line as ``dash pattern.'' This is the default. +As for the line thickness, some predefined styles allow you to set the dashing +conveniently. +\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} \begin{stylekey}{/tikz/dotted} - Shorthand for setting a dotted dash pattern. - + Shorthand for setting a dotted dash pattern. + % \begin{codeexample}[] \tikz \draw[dotted] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/densely dotted} - Shorthand for setting a densely dotted dash pattern. - + Shorthand for setting a densely dotted dash pattern. + % \begin{codeexample}[] \tikz \draw[densely dotted] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/loosely dotted} - Shorthand for setting a loosely dotted dash pattern. - + Shorthand for setting a loosely dotted dash pattern. + % \begin{codeexample}[] \tikz \draw[loosely dotted] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/dashed} - Shorthand for setting a dashed dash pattern. - + Shorthand for setting a dashed dash pattern. + % \begin{codeexample}[] \tikz \draw[dashed] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/densely dashed} - Shorthand for setting a densely dashed dash pattern. - + Shorthand for setting a densely dashed dash pattern. + % \begin{codeexample}[] \tikz \draw[densely dashed] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/loosely dashed} - Shorthand for setting a loosely dashed dash pattern. - + Shorthand for setting a loosely dashed dash pattern. + % \begin{codeexample}[] \tikz \draw[loosely dashed] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} - \begin{stylekey}{/tikz/dash dot} - Shorthand for setting a dashed and dotted dash pattern. - + Shorthand for setting a dashed and dotted dash pattern. + % \begin{codeexample}[] \tikz \draw[dash dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/densely dash dot} - Shorthand for setting a densely dashed and dotted dash pattern. - + Shorthand for setting a densely dashed and dotted dash pattern. + % \begin{codeexample}[] \tikz \draw[densely dash dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/loosely dash dot} - Shorthand for setting a loosely dashed and dotted dash pattern. - + Shorthand for setting a loosely dashed and dotted dash pattern. + % \begin{codeexample}[] \tikz \draw[loosely dash dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} - \begin{stylekey}{/tikz/dash dot dot} - Shorthand for setting a dashed and dotted dash pattern with more dots. - + Shorthand for setting a dashed and dotted dash pattern with more dots. + % \begin{codeexample}[] \tikz \draw[dash dot dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/densely dash dot dot} - Shorthand for setting a densely dashed and dotted dash pattern with more dots. - + Shorthand for setting a densely dashed and dotted dash pattern with more dots. + % \begin{codeexample}[] \tikz \draw[densely dash dot dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/loosely dash dot dot} - Shorthand for setting a loosely dashed and dotted dash pattern with more dots. - + Shorthand for setting a loosely dashed and dotted dash pattern with more dots. + % \begin{codeexample}[] \tikz \draw[loosely dash dot dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} + % \end{stylekey} \subsubsection{Graphic Parameters: Draw Opacity} -When a line is drawn, it will normally ``obscure'' everything behind -it as if you had 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 using the |draw opacity| option. This is explained in -Section~\ref{section-tikz-transparency} on transparency in more detail. - +When a line is drawn, it will normally ``obscure'' everything behind it as if +you had 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 using the |draw opacity| +option. This is explained in Section~\ref{section-tikz-transparency} on +transparency in more detail. \subsubsection{Graphic Parameters: Double Lines and Bordered Lines} \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 - the \meta{core color}, which is normally |white|. Upon the second - drawing, the line width is reduced. The net effect is that it - appears as if two lines had been drawn and this works well even with - complicated, curved paths: - + 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 the \meta{core + color}, which is normally |white|. Upon the second drawing, the line width + is reduced. The net effect is that it appears as if two lines had been + drawn and this works well even with complicated, curved paths: + % \begin{codeexample}[] \tikz \draw[double] plot[smooth cycle] coordinates{(0,0) (1,1) (1,0) (0,1)}; \end{codeexample} - You can also use the doubling option to create an effect in which a - line seems to have a certain ``border'': - + You can also use the doubling option to create an effect in which a line + seems to have a certain ``border'': + % \begin{codeexample}[] \begin{tikzpicture} \draw (0,0) -- (1,1); \draw[draw=white,double=red,very thick] (0,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{key} \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 - ``selects'' the |double| option. - + 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 ``selects'' the |double| option. + % \begin{codeexample}[] \begin{tikzpicture} \draw[very thick,double] (0,0) arc (180:90:1cm); @@ -493,77 +532,82 @@ Section~\ref{section-tikz-transparency} on transparency in more detail. \draw[thin,double distance=2pt] (2,0) arc (180:90:1cm); \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/double distance between line centers=\meta{dimension}} - This option works like |double distance|, only the distance is not - the distance between (inner) borders of the two main lines, but - between their centers. Thus, the thickness the - \emph{first} time the path is drawn is the normal line width - plus the given \meta{dimension}, while the line width of the - \emph{second} line that is drawn is \meta{dimension} minus the - normal line width. As a side-effect, this option ``selects'' the - |double| option. - + This option works like |double distance|, only the distance is not the + distance between (inner) borders of the two main lines, but between their + centers. Thus, the thickness the \emph{first} time the path is drawn is the + normal line width plus the given \meta{dimension}, while the line width of + the \emph{second} line that is drawn is \meta{dimension} minus the normal + line width. As a side-effect, this option ``selects'' the |double| option. + % \begin{codeexample}[] \begin{tikzpicture}[double distance between line centers=3pt] \foreach \lw in {0.5,1,1.5,2,2.5} \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0); \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture}[double distance=3pt] \foreach \lw in {0.5,1,1.5,2,2.5} \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0); \end{tikzpicture} \end{codeexample} + % \end{key} \begin{stylekey}{/tikz/double equal sign distance} - This style selects a double line distance such that it corresponds - to the distance of the two lines in an equal sign. + This style selects a double line distance such that it corresponds to the + distance of the two lines in an equal sign. + % \begin{codeexample}[] \Huge $=\implies$\tikz[baseline,double equal sign distance] \draw[double,thick,-implies](0,0.55ex) --++(3ex,0); \end{codeexample} + % \begin{codeexample}[] \normalsize $=\implies$\tikz[baseline,double equal sign distance] \draw[double,-implies](0,0.6ex) --++(3ex,0); \end{codeexample} + % \begin{codeexample}[] \tiny $=\implies$\tikz[baseline,double equal sign distance] \draw[double,very thin,-implies](0,0.5ex) -- ++(3ex,0); \end{codeexample} + % \end{stylekey} - \subsection{Adding Arrow Tips to a Path} \label{section-arrow-tip-action} -In different situations, \tikzname\ will add arrow tips to the end of -a path. For this to happen, a number of different things need to be -specified: - +In different situations, \tikzname\ will add arrow tips to the end of a path. +For this to happen, a number of different things need to be specified: +% \begin{enumerate} -\item You must have used the |arrows| key, explained in detail in - Section~\ref{section-tikz-arrows}, to setup which kinds of arrow - tips you would like. -\item The path may not be closed (like a circle or a rectangle) and, - if it consists of several subpath, further restrictions apply as - explained in Section~\ref{section-tikz-arrows}. -\item The |tips| key must be set to an appropriate value, see - Section~\ref{section-tikz-arrows} once more. + \item You must have used the |arrows| key, explained in detail in + Section~\ref{section-tikz-arrows}, to setup which kinds of arrow tips + you would like. + \item The path may not be closed (like a circle or a rectangle) and, if + it consists of several subpath, further restrictions apply as + explained in Section~\ref{section-tikz-arrows}. + \item The |tips| key must be set to an appropriate value, see + Section~\ref{section-tikz-arrows} once more. \end{enumerate} -For the current section on paths, it is only important that when you -add the |tips| option to a path that is not drawn, arrow tips will -still be added at the beginning and at the end of the current -path. This is true even when ``only'' arrow tips get drawn for a path -without drawing the path itself. Here is an example: +For the current section on paths, it is only important that when you add the +|tips| option to a path that is not drawn, arrow tips will still be added at +the beginning and at the end of the current path. This is true even when +``only'' arrow tips get drawn for a path without drawing the path itself. Here +is an example: +% \begin{codeexample}[width=2cm] \tikz \path[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0); \end{codeexample} +% \begin{codeexample}[width=2cm] \tikz \draw[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0); \end{codeexample} @@ -571,21 +615,22 @@ without drawing the path itself. Here is an example: \subsection{Filling a Path} \label{section-rules} + To fill a path, use the following option: +% \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 - last color set using the general |color=| option or the optional - color \meta{color}. For self-intersection paths and for paths - consisting of several closed areas, the ``enclosed area'' is - somewhat complicated to define and two different definitions exist, - namely the nonzero winding number rule and the even odd rule, see - the explanation of these options, below. - - Just as for the |draw| option, setting \meta{color} to |none| - disables filling locally. - + 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 last color set + using the general |color=| option or the optional color \meta{color}. For + self-intersection paths and for paths consisting of several closed areas, + the ``enclosed area'' is somewhat complicated to define and two different + definitions exist, namely the nonzero winding number rule and the even odd + rule, see the explanation of these options, below. + + Just as for the |draw| option, setting \meta{color} to |none| disables + filling locally. + % \begin{codeexample}[] \begin{tikzpicture} \fill (0,0) -- (1,1) -- (2,1); @@ -595,15 +640,15 @@ To fill a path, use the following option: \end{tikzpicture} \end{codeexample} - If the |fill| option is used together with the |draw| option (either - because both are given as options or because a |\filldraw| command - is used), the path is filled \emph{first}, then the path is drawn - \emph{second}. This is especially useful if different colors are - selected for drawing and for filling. Even if the same color is - used, there is a difference between this command and a plain - |fill|: A ``filldrawn'' area will be slightly larger than a filled - area because of the thickness of the ``pen.'' - + If the |fill| option is used together with the |draw| option (either + because both are given as options or because a |\filldraw| command is + used), the path is filled \emph{first}, then the path is drawn + \emph{second}. This is especially useful if different colors are selected + for drawing and for filling. Even if the same color is used, there is a + difference between this command and a plain |fill|: A ``filldrawn'' area + will be slightly larger than a filled area because of the thickness of the + ``pen''. + % \begin{codeexample}[] \begin{tikzpicture}[fill=yellow!80!black,line width=5pt] \filldraw (0,0) -- (1,1) -- (2,1); @@ -612,59 +657,57 @@ To fill a path, use the following option: \filldraw (8,0) -- (9,1) -- (10,0) circle (.5cm); \end{tikzpicture} \end{codeexample} + % \end{key} - \subsubsection{Graphic Parameters: Fill Pattern} - \label{section-fill-pattern} -Instead of filling a path with a single solid color, it is also -possible to fill it with a \emph{tiling pattern}. Imagine a small tile -that contains a simple picture like a star. Then these tiles are -(conceptually) repeated infinitely in all directions, but clipped -against the path. - -Tiling patterns come in two variants: \emph{inherently - colored patterns} and \emph{form-only patterns}. An inherently colored -pattern is, say, a red star with a black border and will always look -like this. A form-only pattern may have a different color each time -it is used, only the form of the pattern will stay the same. As such, -form-only patterns do not have any colors of their own, but when it -is used the current \emph{pattern color} is used as its color. - -Patterns are not overly flexible. In particular, it is not possible to -change the size or orientation of a pattern without declaring a new -pattern. For complicated cases, 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{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| - options, setting \meta{name} to |none| disables filling locally. +Instead of filling a path with a single solid color, it is also possible to +fill it with a \emph{tiling pattern}. Imagine a small tile that contains a +simple picture like a star. Then these tiles are (conceptually) repeated +infinitely in all directions, but clipped against the path. + +Tiling patterns come in two variants: \emph{inherently colored patterns} and +\emph{form-only patterns}. An inherently colored pattern is, say, a red star +with a black border and will always look like this. A form-only pattern may +have a different color each time it is used, only the form of the pattern will +stay the same. As such, form-only patterns do not have any colors of their own, +but when it is used the current \emph{pattern color} is used as its color. - The pattern works like a fill color. In particular, setting a new - fill color will fill the path with a solid color once more. +Patterns are not overly flexible. In particular, it is not possible to change +the size or orientation of a pattern without declaring a new pattern. For +complicated cases, 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. - Strangely, no \meta{name}s are permissible by default. You need to - load for instance the |patterns| library, see - Section~\ref{section-library-patterns}, to install predefined - patterns. +\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| options, setting \meta{name} to + |none| disables filling locally. + + 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 need to load for + instance the |patterns| library, see + Section~\ref{section-library-patterns}, to install predefined patterns. + % \begin{codeexample}[] \begin{tikzpicture} \draw[pattern=dots] (0,0) circle (1cm); \draw[pattern=fivepointed stars] (0,0) rectangle (3,1); \end{tikzpicture} \end{codeexample} + % \end{key} \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. - + This option is used to set the color to be used for form-only patterns. + This option has no effect on inherently colored patterns. + % \begin{codeexample}[] \begin{tikzpicture} \draw[pattern color=red,pattern=fivepointed stars] (0,0) circle (1cm); @@ -679,26 +722,27 @@ pattern. For complicated cases, it may be easier to use two nested \pattern[pattern color=white,pattern=bricks] \mypath; \end{tikzpicture} \end{codeexample} + % \end{key} \subsubsection{Graphic Parameters: Interior Rules} -The following two options can be used to decide how interior points -should be determined: +The following two options can be used to decide how interior points should be +determined: +% \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 - direction is chosen such that no strange borderline cases - occur). Then the ray may hit the path. Whenever it hits the path, we - increase or decrease a counter, which is initially zero. If the ray - hits the path as the path goes ``from left to right'' (relative to - the ray), the counter is increased, otherwise it is decreased. Then, - at the end, we check whether the counter is nonzero (hence the - name). If so, the point is deemed to lie ``inside,'' otherwise it is - ``outside.'' Sounds complicated? It is. - + 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 direction is chosen + such that no strange borderline cases occur). Then the ray may hit the + path. Whenever it hits the path, we increase or decrease a counter, which + is initially zero. If the ray hits the path as the path goes ``from left to + right'' (relative to the ray), the counter is increased, otherwise it is + decreased. Then, at the end, we check whether the counter is nonzero (hence + the name). If so, the point is deemed to lie ``inside'', otherwise it is + ``outside''. Sounds complicated? It is. + % \begin{codeexample}[] \begin{tikzpicture} \filldraw[fill=yellow!80!black] @@ -726,20 +770,21 @@ should be determined: \end{scope} \end{tikzpicture} \end{codeexample} + % \end{key} \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. - - With this method, we also shoot rays from the point for which we - wish to determine whether it is inside or outside the filling - area. However, this time we only count how often we ``hit'' the path - and declare the point to be ``inside'' if the number of hits is odd. + 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. - Using the even-odd rule, it is easy to ``drill holes'' into a path. + With this method, we also shoot rays from the point for which we wish to + determine whether it is inside or outside the filling area. However, this + time we only count how often we ``hit'' the path and declare the point to + be ``inside'' if the number of hits is odd. + Using the even-odd rule, it is easy to ``drill holes'' into a path. + % \begin{codeexample}[] \begin{tikzpicture} \filldraw[fill=yellow!80!black,even odd rule] @@ -747,57 +792,58 @@ should be determined: \draw[->] (0.5,0.5) -- +(0,1) [above] node{crossings: $1+1 = 2$}; \end{tikzpicture} \end{codeexample} + % \end{key} - \subsubsection{Graphic Parameters: Fill Opacity} - \label{section-fill-opacity} -Analogously to the |draw opacity|, you can also set the fill opacity. Please see Section~\ref{section-tikz-transparency} for more -details. + +Analogously to the |draw opacity|, you can also set the fill opacity. Please +see Section~\ref{section-tikz-transparency} for more details. \subsection{Generalized Filling: Using Arbitrary Pictures to Fill a Path} -Sometimes you wish to ``fill'' a path with something even more -complicated than a pattern, let alone a single color. For instance, -you might wish to use an image to fill the path or some other, -complicated drawing. In principle, this effect can be achieved -by first using the path for clipping and then, subsequently, drawing -the desired image or picture. However, there is an option that makes -this process much easier: +Sometimes you wish to ``fill'' a path with something even more complicated than +a pattern, let alone a single color. For instance, you might wish to use an +image to fill the path or some other, complicated drawing. In principle, this +effect can be achieved by first using the path for clipping and then, +subsequently, drawing the desired image or picture. However, there is an option +that makes this process much easier: \begin{key}{/tikz/path picture=\meta{code}} - When this option is given on a path and when the \meta{code} is not - empty, the following happens: After all other ``filling'' operations - are done with the path, which are caused by the options |fill|, - |pattern| and |shade|, a local scope is opened and the path is - temporarily installed as a clipping path. Then, the \meta{code} is - executed, which can now draw something. Then, the local scope ends - and, possibly, the path is stroked, provided the |draw| option has - been given. - - As with other keys like |fill| or |draw| this option needs to be given on a path, setting the |path picture| outside a path has no effect (the path picture is cleared at the beginning of each path). - - The \meta{code} can be any normal \tikzname\ code like |\draw ...| - or |\node ...|. As always, when you include an external graphic, you need to put it inside a |\node|. - - Note that no special actions are taken to transform the origin in - any way. This means that the coordinate |(0,0)| is still where is - was when the path was being constructed and not -- as one might - expect -- at the lower left corner of the path. However, you can use - the following special node to access the size of the path: - \begin{predefinednode}{path picture bounding box} - This node is of shape |rectangle|. Its size and position are those - of |current path bounding box| just before the \meta{code} - of the path picture started to be executed. The \meta{code} can - construct its own paths, so accessing the - |current path bounding box| inside the \meta{code} yields the - bounding box of any path that is currently being constructed - inside the \meta{code}. - \end{predefinednode} - + When this option is given on a path and when the \meta{code} is not empty, + the following happens: After all other ``filling'' operations are done with + the path, which are caused by the options |fill|, |pattern| and |shade|, a + local scope is opened and the path is temporarily installed as a clipping + path. Then, the \meta{code} is executed, which can now draw something. + Then, the local scope ends and, possibly, the path is stroked, provided the + |draw| option has been given. + + As with other keys like |fill| or |draw| this option needs to be given on a + path, setting the |path picture| outside a path has no effect (the path + picture is cleared at the beginning of each path). + + The \meta{code} can be any normal \tikzname\ code like |\draw ...| or + |\node ...|. As always, when you include an external graphic, you need to + put it inside a |\node|. + + Note that no special actions are taken to transform the origin in any way. + This means that the coordinate |(0,0)| is still where is was when the path + was being constructed and not -- as one might expect -- at the lower left + corner of the path. However, you can use the following special node to + access the size of the path: + % + \begin{predefinednode}{path picture bounding box} + This node is of shape |rectangle|. Its size and position are those of + |current path bounding box| just before the \meta{code} of the path + picture started to be executed. The \meta{code} can construct its own + paths, so accessing the |current path bounding box| inside the + \meta{code} yields the bounding box of any path that is currently being + constructed inside the \meta{code}. + \end{predefinednode} + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); @@ -839,23 +885,23 @@ this process much easier: \end{tikzpicture} \end{codeexample} + % \end{key} \subsection{Shading a Path} -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. +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{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. - - It is not an error to use this option together with the |fill| - option, but it makes no sense. + 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. + It is not an error to use this option together with the |fill| option, but + it makes no sense. + % \begin{codeexample}[] \tikz \shade (0,0) circle (1ex); \end{codeexample} @@ -863,98 +909,95 @@ another. \begin{codeexample}[] \tikz \shadedraw (0,0) circle (1ex); \end{codeexample} + % \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 -\shade[shading=ball] (0,0) circle (0.75ex);. How is this supposed to +For some shadings it is not really clear how they can ``fill'' the path. For +example, the |ball| shading normally looks like this: +\tikz \shade[shading=ball] (0,0) circle (0.75ex);. How is this supposed to shade a rectangle? Or a triangle? -To solve this problem, the predefined shadings like |ball| or |axis| -fill a large rectangle completely in a sensible way. Then, when the -shading is used to ``shade'' a path, what actually happens is that the -path is temporarily used for clipping and then the rectangular shading -is drawn, scaled and shifted such that all parts of the path are -filled. - -The default shading is a smooth transition from gray -to white and from top to bottom. However, other shadings are also -possible, for example a shading that will sweep a color from the -center to the corners outward. To choose the shading, you can use the -|shading=| option, which will also automatically invoke the |shade| -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. +To solve this problem, the predefined shadings like |ball| or |axis| fill a +large rectangle completely in a sensible way. Then, when the shading is used to +``shade'' a path, what actually happens is that the path is temporarily used +for clipping and then the rectangular shading is drawn, scaled and shifted such +that all parts of the path are filled. + +The default shading is a smooth transition from gray to white and from top to +bottom. However, other shadings are also possible, for example a shading that +will sweep a color from the center to the corners outward. To choose the +shading, you can use the |shading=| option, which will also automatically +invoke the |shade| 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{key}{/tikz/shading=\meta{name}} - This selects a shading named \meta{name}. The following shadings are - predefined: |axis|, |radial|, and |ball|. + This selects a shading named \meta{name}. The following shadings are + predefined: |axis|, |radial|, and |ball|. + % \begin{codeexample}[] \tikz \shadedraw [shading=axis] (0,0) rectangle (1,1); \tikz \shadedraw [shading=radial] (0,0) rectangle (1,1); \tikz \shadedraw [shading=ball] (0,0) circle (.5cm); \end{codeexample} - The shadings as well as additional shadings are described in more - detail in Section~\ref{section-library-shadings}. + The shadings as well as additional shadings are described in more detail in + Section~\ref{section-library-shadings}. - To change the color of a shading, special options are needed like - |left color|, which sets the color of an axis shading from left to - right. These options implicitly also select the correct shading type, - see the following example + To change the color of a shading, special options are needed like + |left color|, which sets the color of an axis shading from left to right. + These options implicitly also select the correct shading type, see the + following example + % \begin{codeexample}[] \tikz \shadedraw [left color=red,right color=blue] (0,0) rectangle (1,1); \end{codeexample} - For a complete list of the possible options see - Section~\ref{section-library-shadings} once more. - - \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$. + For a complete list of the possible options see + Section~\ref{section-library-shadings} once more. + \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{key} + \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 -harder to use. Details on how to create a shading appropriate for -filling paths are given in Section~\ref{section-shading-a-path}. - +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 harder to use. +Details on how to create a shading appropriate for filling paths are given in +Section~\ref{section-shading-a-path}. \subsection{Establishing a Bounding Box} -\pgfname\ is reasonably good at keeping track of the size of your picture -and reserving just the right amount of space for it in the main -document. However, in some cases you may want to say things like -``do not count this for the picture size'' or ``the picture is -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]|. +\pgfname\ is reasonably good at keeping track of the size of your picture and +reserving just the right amount of space for it in the main document. However, +in some cases you may want to say things like ``do not count this for the +picture size'' or ``the picture is 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{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 - ignored. However, if there were previous path operations that have - already established a larger bounding box, it will not be made - smaller by this operation (consider the |\pgfresetboundingbox| command - to reset the previous bounding box). - - In a sense, |use as bounding box| has the same effect as clipping - all subsequent drawing against the current path---without actually - doing the clipping, only making \pgfname\ treat everything as if it - were clipped. + 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 ignored. However, if there were previous + path operations that have already established a larger bounding box, it + will not be made smaller by this operation (consider the + |\pgfresetboundingbox| command to reset the previous bounding box). - The first application of this option is to have a |{tikzpicture}| - overlap with the main text: + In a sense, |use as bounding box| has the same effect as clipping all + subsequent drawing against the current path -- without actually doing the + clipping, only making \pgfname\ treat everything as if it were clipped. + The first application of this option is to have a |{tikzpicture}| overlap + with the main text: + % \begin{codeexample}[] Left of picture\begin{tikzpicture} \draw[use as bounding box] (2,0) rectangle (3,1); @@ -962,9 +1005,9 @@ Left of picture\begin{tikzpicture} \end{tikzpicture}right of picture. \end{codeexample} - In a second application this option can be used to get better - control over the white space around the picture: - + In a second application this option can be used to get better control over + the white space around the picture: + % \begin{codeexample}[] Left of picture \begin{tikzpicture} @@ -974,23 +1017,21 @@ Left of picture right of picture. \end{codeexample} - Note: If this option is used on a path inside a \TeX\ group (scope), - the effect ``lasts'' only until the end of the scope. Again, this - behavior is the same as for clipping. - + Note: If this option is used on a path inside a \TeX\ group (scope), the + effect ``lasts'' only until the end of the scope. Again, this behavior is + the same as for clipping. - Consider using |\useasboundingbox| together with |\pgfresetboundingbox| in order to replace the bounding box with a new one. + Consider using |\useasboundingbox| together with |\pgfresetboundingbox| in + order to replace the bounding box with a new one. \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| -shape and its size is always the size of the current -bounding box. - -Similarly, the |current path bounding box| node has the |rectangle| -shape and the size of the bounding box of the current path. - +There is a node that allows you to get the size of the current bounding box. +The |current bounding box| node has the |rectangle| shape and its size is +always the size of the current bounding box. +Similarly, the |current path bounding box| node has the |rectangle| shape and +the size of the bounding box of the current path. +% \begin{codeexample}[] \begin{tikzpicture} \draw[red] (0,0) circle (2pt); @@ -1006,104 +1047,136 @@ shape and the size of the bounding box of the current path. \end{tikzpicture} \end{codeexample} - -Occasionally, you may want to align multiple |tikzpicture| environments horizontally and/or vertically at some prescribed position. The vertical alignment can be realized by means of the |baseline| option since \TeX\ supports the concept of box depth natively. For horizontal alignment, things are slightly more involved. The following approach is realized by means of negative |\hspace|s before and/or after the picture, thereby removing parts of the picture. However, the actual amount of negative horizontal space is provided by means of image coordinates using the |trim left| and |trim right| keys: +Occasionally, you may want to align multiple |tikzpicture| environments +horizontally and/or vertically at some prescribed position. The vertical +alignment can be realized by means of the |baseline| option since \TeX\ +supports the concept of box depth natively. For horizontal alignment, things +are slightly more involved. The following approach is realized by means of +negative |\hspace|s before and/or after the picture, thereby removing parts of +the picture. However, the actual amount of negative horizontal space is +provided by means of image coordinates using the |trim left| and |trim right| +keys: \begin{key}{/tikz/trim left=\meta{dimension or coordinate or \texttt{default}} (default 0pt)} - The |trim left| key tells \pgfname\space to discard everything which is left of the provided \meta{dimension or coordinate}. Here, \meta{dimension} is a single $x$ coordinate of the picture and \meta{coordinate} is a point with $x$ and $y$ coordinates (but only its $x$ coordinate will be used). The effect is the same as if you issue |\hspace{-s}| where |s| is the difference of the picture's bounding box lower left $x$ coordinate and the $x$ coordinate specified as \meta{dimension or coordinate}: + The |trim left| key tells \pgfname\space to discard everything which is + left of the provided \meta{dimension or coordinate}. Here, \meta{dimension} + is a single $x$ coordinate of the picture and \meta{coordinate} is a point + with $x$ and $y$ coordinates (but only its $x$ coordinate will be used). + The effect is the same as if you issue |\hspace{-s}| where |s| is the + difference of the picture's bounding box lower left $x$ coordinate and the + $x$ coordinate specified as \meta{dimension or coordinate}: + % \begin{codeexample}[] Text before image.% - \begin{tikzpicture}[trim left] - \draw (-1,-1) grid (3,2); - \fill (0,0) circle (5pt); - \end{tikzpicture}% + \begin{tikzpicture}[trim left] + \draw (-1,-1) grid (3,2); + \fill (0,0) circle (5pt); + \end{tikzpicture}% Text after image. \end{codeexample} - Since |trim left| uses the default |trim left=0pt|, everything left of $x=0$ is removed from the bounding box. + % + Since |trim left| uses the default |trim left=0pt|, everything left of + $x=0$ is removed from the bounding box. - The following example has once the relative long label $-1$ and once the shorter label $1$. Horizontal alignment is established with |trim left|: + The following example has once the relative long label $-1$ and once the + shorter label $1$. Horizontal alignment is established with |trim left|: + % \begin{codeexample}[pre={\vbox\bgroup\hsize=5cm},post=\egroup,width=8cm] \begin{tikzpicture} - \draw (0,1) -- (0,0) -- (1,1) -- cycle; - \fill (0,0) circle (2pt); - \node[left] at (0,0) {$-1$}; + \draw (0,1) -- (0,0) -- (1,1) -- cycle; + \fill (0,0) circle (2pt); + \node[left] at (0,0) {$-1$}; \end{tikzpicture} \par \begin{tikzpicture} - \draw (0,1) -- (0,0) -- (1,1) -- cycle; - \fill (0,0) circle (2pt); - \node[left] at (0,0) {$1$}; + \draw (0,1) -- (0,0) -- (1,1) -- cycle; + \fill (0,0) circle (2pt); + \node[left] at (0,0) {$1$}; \end{tikzpicture} \par \begin{tikzpicture}[trim left] - \draw (0,1) -- (0,0) -- (1,1) -- cycle; - \fill (0,0) circle (2pt); - \node[left] at (0,0) {$-1$}; + \draw (0,1) -- (0,0) -- (1,1) -- cycle; + \fill (0,0) circle (2pt); + \node[left] at (0,0) {$-1$}; \end{tikzpicture} \par \begin{tikzpicture}[trim left] - \draw (0,1) -- (0,0) -- (1,1) -- cycle; - \fill (0,0) circle (2pt); - \node[left] at (0,0) {$1$}; + \draw (0,1) -- (0,0) -- (1,1) -- cycle; + \fill (0,0) circle (2pt); + \node[left] at (0,0) {$1$}; \end{tikzpicture} \end{codeexample} - - Use |trim left=default| to reset the value. + + Use |trim left=default| to reset the value. \end{key} \begin{key}{/tikz/trim right=\meta{dimension or coordinate or \texttt{default}}} - This key is similar to |trim left|: it discards everything which is right of the provided \meta{dimension or coordinate}. As for |trim left|, \meta{dimension} denotes a single $x$ coordinate of the picture and \meta{coordinate} a coordinate with $x$ and $y$ value (although only its $x$ component will be used). + This key is similar to |trim left|: it discards everything which is right + of the provided \meta{dimension or coordinate}. As for |trim left|, + \meta{dimension} denotes a single $x$ coordinate of the picture and + \meta{coordinate} a coordinate with $x$ and $y$ value (although only its + $x$ component will be used). - We use the same example from above and add |trim right|: + We use the same example from above and add |trim right|: + % \begin{codeexample}[] Text before image.% - \begin{tikzpicture}[trim left, trim right=2cm, baseline] - \draw (-1,-1) grid (3,2); - \fill (0,0) circle (5pt); - \end{tikzpicture}% + \begin{tikzpicture}[trim left, trim right=2cm, baseline] + \draw (-1,-1) grid (3,2); + \fill (0,0) circle (5pt); + \end{tikzpicture}% Text after image. \end{codeexample} - In addition to |trim left=0pt|, we also discard everything which is right of $x$|=2cm|. Furthermore, the |baseline| key supports vertical alignment as well (using the $y$|=0cm| baseline). + % + In addition to |trim left=0pt|, we also discard everything which is right + of $x$|=2cm|. Furthermore, the |baseline| key supports vertical alignment + as well (using the $y$|=0cm| baseline). - Use |trim right=default| to reset the value. + Use |trim right=default| to reset the value. \end{key} -Note that |baseline|, |trim left| and |trim right| are currently the \emph{only} supported way of truncated bounding boxes which are compatible with image externalization (see the |external| library for details). +Note that |baseline|, |trim left| and |trim right| are currently the +\emph{only} supported way of truncated bounding boxes which are compatible with +image externalization (see the |external| library for details). \begin{key}{/pgf/trim lowlevel=\mchoice{true,false} (initially false)} - This affects only the basic level image externalization: the initial configuration |trim lowlevel=false| stores the normal image, without trimming, and the trimming into a separate file. This allows reduced bounding boxes without clipping the rest away. The |trim lowlevel=true| information causes the image externalization to store the trimmed image, possibly resulting in clipping. + This affects only the basic level image externalization: the initial + configuration |trim lowlevel=false| stores the normal image, without + trimming, and the trimming into a separate file. This allows reduced + bounding boxes without clipping the rest away. The |trim lowlevel=true| + information causes the image externalization to store the trimmed image, + possibly resulting in clipping. \end{key} + \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. - -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 +\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. + +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. \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, - the even-odd rule or the nonzero winding number rule is used to - determine whether a point is inside or outside the clipping region. - - The clipping path is a graphic state parameter, so it will be reset - at the end of the current scope. Multiple clippings accumulate, that - is, clipping is always done against the intersection of all clipping - areas that have been specified inside the current scopes. The only - way of enlarging the clipping area is to end a |{scope}|. - + 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, the even-odd + rule or the nonzero winding number rule is used to determine whether a + point is inside or outside the clipping region. + + The clipping path is a graphic state parameter, so it will be reset at the + end of the current scope. Multiple clippings accumulate, that is, clipping + is always done against the intersection of all clipping areas that have + been specified inside the current scopes. The only way of enlarging the + clipping area is to end a |{scope}|. + % \begin{codeexample}[] \begin{tikzpicture} \draw[clip] (0,0) circle (1cm); @@ -1111,12 +1184,12 @@ transparency in general. \end{tikzpicture} \end{codeexample} - It is usually a \emph{very} good idea to apply the |clip| option only - to the first path command in a scope. - - If you ``only wish to clip'' and do not wish to draw anything, you can - use the |\clip| command, which is a shorthand for |\path[clip]|. + It is usually a \emph{very} good idea to apply the |clip| option only to + the first path command in a scope. + If you ``only wish to clip'' and do not wish to draw anything, you can use + the |\clip| command, which is a shorthand for |\path[clip]|. + % \begin{codeexample}[] \begin{tikzpicture} \clip (0,0) circle (1cm); @@ -1124,9 +1197,9 @@ transparency in general. \end{tikzpicture} \end{codeexample} - To keep clipping local, use |{scope}| environments as in the - following example: - + To keep clipping local, use |{scope}| environments as in the following + example: + % \begin{codeexample}[] \begin{tikzpicture} \draw (0,0) -- ( 0:1cm); @@ -1146,48 +1219,45 @@ transparency in general. \end{tikzpicture} \end{codeexample} - There is a slightly annoying catch: You cannot specify certain graphic - options for the command used for clipping. For example, in the above - code we could not have moved the |fill=red| to the |\fill| - command. The reasons for this have to do with the internals of the - \pdf\ specification. You do not want to know the details. It is best - simply not to specify any options for these - commands. + There is a slightly annoying catch: You cannot specify certain graphic + options for the command used for clipping. For example, in the above code + we could not have moved the |fill=red| to the |\fill| command. The reasons + for this have to do with the internals of the \pdf\ specification. You do + not want to know the details. It is best simply not to specify any options + for these commands. \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: +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/preaction=\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. + 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); @@ -1198,13 +1268,13 @@ options: \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: - + 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); @@ -1216,19 +1286,18 @@ options: \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. + 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. + 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. + 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); @@ -1241,9 +1310,10 @@ options: \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: + 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} [ @@ -1279,20 +1349,22 @@ options: 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. + 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. + 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: + 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); @@ -1303,8 +1375,8 @@ options: \end{tikzpicture} \end{codeexample} - In another example, we use a postaction to ``colorize'' a path: - + In another example, we use a postaction to ``colorize'' a path: + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -1316,19 +1388,19 @@ options: (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 is 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. +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 is 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); @@ -1337,8 +1409,9 @@ example the path is drawn twice: Once normally and then in a morphed \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: +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, |