summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex
diff options
context:
space:
mode:
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.tex465
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}
+