diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex | 465 |
1 files changed, 465 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex new file mode 100644 index 00000000000..f0e0f45c061 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex @@ -0,0 +1,465 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Using Paths} + +\subsection{Overview} + +Once a path has been constructed, it can be \emph{used} in different +ways. For example, you can draw the path or fill it or use it for +clipping. + +Numerous graph parameters influence how a path will be rendered. For +example, when you draw a path, the line width is important as well as +the dashing pattern. The options that govern how paths are rendered +can all be set with commands starting with |\pgfset|. \emph{All + options that influence how a path is rendered always influence the + complete path.} Thus, it is not possible to draw part of a path +using, say, a red color and drawing another part using a green +color. To achieve such an effect, you must use two paths. + +In detail, paths can be used in the following ways: + +\begin{enumerate} +\item + You can \emph{stroke} (also known as \emph{draw}) a path. +\item + You can \emph{fill} a path with a uniform color. +\item + You can \emph{clip} subsequent renderings against the path. +\item + You can \emph{shade} a path. +\item + You can \emph{use the path as bounding box} for the whole picture. +\end{enumerate} +You can also perform any combination of the above, though it makes no +sense to fill and shade a path at the same time. + +To perform (a combination of) the first three actions, you can use the +following command: +\begin{command}{\pgfusepath\marg{actions}} + Applies the given \meta{actions} to the current path. Afterwards, + the current path is (globally) empty. The following actions are + possible: + \begin{itemize} + \item \declare{|fill|} + fills the path. See Section~\ref{section-fill} for further details. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} + \item \declare{|stroke|} + strokes the path. See Section~\ref{section-stroke} for further details. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + \item \declare{|clip|} + clips all subsequent drawings against the path. See + Section~\ref{section-clip} for further details. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke,clip} + \pgfpathcircle{\pgfpoint{1cm}{1cm}}{0.5cm} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} + \item \declare{|discard|} + discards the path, that is, it is not used at all. Giving this + option (alone) has the same effect as giving an empty options + list. + \end{itemize} + When more than one of the first three actions are given, they are + applied in the above ordering, regardless of their ordering in + \meta{actions}. Thus, |{stroke,fill}| and |{fill,stroke}| have the + same effect. +\end{command} + +To shade a path, use the |\pgfshadepath| command, which is explained +in Section~\ref{section-shadings}. + + + +\subsection{Stroking a Path} +\label{section-stroke} + +When you use |\pgfusepath{stroke}| to stroke a path, several graphic +parameters influence how the path is drawn. The commands for setting +these parameters are explained in the following. + +Note that all graphic parameters apply to the path as a whole, never +only to a part of it. + +All graphic parameters are local to the current |{pgfscope}|, but they +persists past \TeX\ groups, \emph{except} for the interior rule +(even-odd or nonzero) and the arrow tip kinds. The latter graphic +parameters only persist till the end of the current \TeX\ group, but +this may change in the future, so do not count on this. + +\subsubsection{Graphic Parameter: Line Width} + +\begin{command}{\pgfsetlinewidth\marg{line width}} + This command sets the line width for subsequent strokes (in the + current |pgfscope|). The line width is given as a normal \TeX\ + dimension like |0.4pt| or |1mm|. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetlinewidth{1mm} + \pgfpathmoveto{\pgfpoint{0mm}{0mm}} + \pgfpathlineto{\pgfpoint{2cm}{0mm}} + \pgfusepath{stroke} + \pgfsetlinewidth{2\pgflinewidth} % double in size + \pgfpathmoveto{\pgfpoint{0mm}{5mm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{textoken}{\pgflinewidth} + You can access the current line width via the \TeX\ dimension + |\pgflinewidth|. It will be set to the correct line width, that is, + even when a \TeX\ group closed, the value will be correct since it + is set globally, but when a |{pgfscope}| closes, the value is set to + the correct value it had before the scope. +\end{textoken} + + +\subsubsection{Graphic Parameter: Caps and Joins} + +\begin{command}{\pgfsetbuttcap} + Sets the line cap to a butt cap. See Section~\ref{section-cap-joins} + for an explanation of what this is. +\end{command} +\begin{command}{\pgfsetroundcap} + Sets the line cap to a round cap. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetrectcap} + Sets the line cap to a square cap. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetroundjoin} + Sets the line join to a round join. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetbeveljoin} + Sets the line join to a bevel join. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetmiterjoin} + Sets the line join to a miter join. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetmiterlimit\marg{miter limit factor}} + Sets the miter limit to \meta{miter limit factor}. See again + Section~\ref{section-cap-joins}. +\end{command} + +\subsubsection{Graphic Parameter: Dashing} + +\begin{command}{\pgfsetdash\marg{list of even length of dimensions}\marg{phase}} + Sets the dashing of a line. The first entry in the list specifies + the length of the first solid part of the list. The second entry + specifies the length of the following gap. Then comes the length of + the second solid part, following by the length of the second gap, + and so on. The \meta{phase} specifies where the first solid part + starts relative to the beginning of the line. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0cm} + \pgfpathmoveto{\pgfpoint{0mm}{0mm}} + \pgfpathlineto{\pgfpoint{2cm}{0mm}} + \pgfusepath{stroke} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.1cm} + \pgfpathmoveto{\pgfpoint{0mm}{1mm}} + \pgfpathlineto{\pgfpoint{2cm}{1mm}} + \pgfusepath{stroke} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.2cm} + \pgfpathmoveto{\pgfpoint{0mm}{2mm}} + \pgfpathlineto{\pgfpoint{2cm}{2mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + Use |\pgfsetdash{}{0pt}| to get a solid dashing. +\end{command} + +\subsubsection{Graphic Parameter: Stroke Color} + +\begin{command}{\pgfsetstrokecolor\marg{color}} + Sets the color used for stroking lines to \meta{color}, where + \meta{color} is a \LaTeX\ color like |red| or |black!20!red|. Unlike + the |\color| command, the effect of this command lasts till the end + of the current |{pgfscope}| and not till the end of the current + \TeX\ group. + + The color used for stroking may be different from the color used for + filling. However, a |\color| command will always ``immediately + override'' any special settings for the stroke and fill colors. + + In plain \TeX, this command will also work, but the problem of + \emph{defining} a color arises. After all, plain \TeX\ does not + provide \LaTeX\ colors. For this reason, \pgfname\ implements a + minimalistic ``emulation'' of the |\definecolor|, |\colorlet|, and + |\color| commands. Only gray-scale and rgb colors are supported. For + most cases this turns out to be enough. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetlinewidth{1pt} + \color{red} + \pgfpathcircle{\pgfpoint{0cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \pgfsetstrokecolor{black} + \pgfpathcircle{\pgfpoint{1cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \color{red} + \pgfpathcircle{\pgfpoint{2cm}{0cm}}{3mm} \pgfusepath{fill,stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetcolor\marg{color}} + Sets both the stroke and fill color. The difference to the normal + |\color| command is that the effect lasts till the end of the + current |{pgfscope}|, not only till the end of the current \TeX\ + group. +\end{command} + + +\subsubsection{Graphic Parameter: Stroke Opacity} + +\begin{command}{\pgfsetstrokeopacity\marg{value}} + Sets the opacity of stroking operations. The \meta{value} should be + a number between |0| and |1|, where |1| means ``fully opaque'' and + |0| means ``fully transparent.'' A value like |0.5| will cause paths + to be stroked in a semitransparent way. + + \emph{Note:} For PostScript output, opacity is rendered correctly + only with the most recent versions of GhostScript. Printers and + other programs will ignore the opacity setting. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetlinewidth{5mm} + \color{red} + \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke} + \color{black} + \pgfsetstrokeopacity{0.5} + \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Graphic Parameter: Arrows} + +After a path has been drawn, \pgfname\ can add arrow tips at the +ends. Currently, it will only add arrows correctly at the end of paths +that consist of a single open part. For other paths, like closed paths +or path consisting of multiple parts, the result is not defined. + +\begin{command}{\pgfsetarrowsstart\marg{arrow kind}} + Sets the arrow tip kind used at the start of a (possibly curved) + path. When this option is used, the line will often be slightly + shortened to ensure that the tip of the arrow will exactly ``touch'' + the ``real'' start of the line. + + To ``clear'' the start arrow, say |\pgfsetarrowsstart{}|. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrowsstart{latex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \pgfsetarrowsstart{to} + \pgfpathmoveto{\pgfpoint{0cm}{2mm}} + \pgfpathlineto{\pgfpoint{1cm}{2mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + The effect of this command persists only till the end of the current + \TeX\ scope. + + The different possible arrow kinds are explained in + Section~\ref{section-arrows}. +\end{command} + +\begin{command}{\pgfsetarrowsend\marg{arrow kind}} + Sets the arrow tip kind used at the end of a path. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrowsstart{latex} + \pgfsetarrowsend{to} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetarrows{\texttt{\char`\{}}\meta{start kind}|-|\meta{end kind}{\texttt{\char`\}}}} + Sets the start arrow kind to \meta{start kind} and the end kind to + \meta{end kind}. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrows{latex-to} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetshortenstart\marg{dimension}} + This command will shortened the start of every stroked path by the + given dimension. This shortening is done in addition to automatic + shortening done by a start arrow, but it can be used even if no + start arrow is given. + + This command is useful if you wish arrows or lines to ``stop shortly + before'' a given point. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathcircle{\pgfpointorigin}{5mm} + \pgfusepath{stroke} + \pgfsetarrows{latex-} + \pgfsetshortenstart{4pt} + \pgfpathmoveto{\pgfpoint{5mm}{0cm}} % would be on the circle + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetshortenend\marg{dimension}} + Works like |\pgfsetshortenstart|. +\end{command} + + + +\subsection{Filling a Path} +\label{section-fill} + +Filling a path means coloring every interior point of the path with +the current fill color. It is not always obvious whether a point is +``inside'' a path when the path is self-intersecting and/or consists +or multiple parts. In this case either the nonzero winding number rule +or the even-odd crossing number rule is used to decide, which points +lie ``inside.'' These rules are explained in +Section~\ref{section-rules}. + +\subsubsection{Graphic Parameter: Interior Rule} + +You can set which rule is used using the following commands: + +\begin{command}{\pgfseteorule} + Dictates that the even-odd rule is used in subsequent fillings in + the current \emph{\TeX\ scope}. Thus, for once, the effect of this + command does not persist past the current \TeX\ scope. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfseteorule + \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} + \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetnonzerorule} + Dictates that the nonzero winding number rule is used in subsequent + fillings in the current \TeX\ scope. This is the default. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetnonzerorule + \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} + \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\subsubsection{Graphic Parameter: Filling Color} + +\begin{command}{\pgfsetfillcolor\marg{color}} + Sets the color used for filling paths to \meta{color}. Like the + stroke color, the effect lasts only till the next use of |\color|. +\end{command} + + +\subsubsection{Graphic Parameter: Fill Opacity} + +\begin{command}{\pgfsetfillopacity\marg{value}} + Sets the opacity of filling operations. As for stroking, the + \meta{value} should be a number between |0| and~|1|. + + The ``filling transparency'' will also be used for text and images. + +\begin{codeexample}[] +\begin{tikzpicture} + \pgfsetfillopacity{0.5} + \fill[red] (90:1cm) circle (11mm); + \fill[green] (210:1cm) circle (11mm); + \fill[blue] (-30:1cm) circle (11mm); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\subsection{Clipping a Path} +\label{section-clip} + +When you add the |clip| option, the current path is used for +clipping subsequent drawings. The same rule as for filling is used to +decide whether a point is inside or outside the path, that is, either +the even-odd rule or the nonzero rule. + +Clipping never enlarges the clipping area. Thus, when you clip against +a certain path and then clip again against another path, you clip +against the intersection of both. + +The only way to enlarge the clipping path is to end the |{pgfscope}| +in which the clipping was done. At the end of a |{pgfscope}| the +clipping path that was in force at the beginning of the scope is +reinstalled. + +\subsection{Using a Path as a Bounding Box} +\label{section-using-bb} + +When you add the |use as bounding box| option, the bounding box of the +picture will be enlarged such that the path in encompassed, but any +\emph{subsequent} paths of the current \TeX\ scope will not have any +effect on the size of the bounding box. Typically, you use this +command at the very beginning of a |{pgfpicture}| environment. + +\begin{codeexample}[] +Left +\begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} + \pgfusepath{use as bounding box} % draws nothing + + \pgfpathcircle{\pgfpointorigin}{2ex} + \pgfusepath{stroke} +\end{pgfpicture} +right. +\end{codeexample} + |