summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex319
1 files changed, 319 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex
new file mode 100644
index 00000000000..efe70ab6975
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex
@@ -0,0 +1,319 @@
+% Copyright 2006 by Till Tantau
+%
+% This file may be distributed and/or modified
+%
+% 1. under the LaTeX Project Public License and/or
+% 2. under the GNU Free Documentation License.
+%
+% See the file doc/generic/pgf/licenses/LICENSE for more details.
+
+
+\section{Plot Handler Library}
+\label{section-library-plothandlers}
+
+\begin{pgflibrary}{plothandlers}
+ This library packages defines additional plot handlers, see
+ Section~\ref{section-plot-handlers} for an introduction to plot
+ handlers. The additional handlers are described in the following.
+
+ This library is loaded automatically by \tikzname.
+\end{pgflibrary}
+
+
+\subsection{Curve Plot Handlers}
+
+\begin{command}{\pgfplothandlercurveto}
+ This handler will issue a |\pgfpathcurveto| command for each point of
+ the plot, \emph{except} possibly for the first. As for the line-to
+ handler, what happens with the first point can be specified using
+ |\pgfsetmovetofirstplotpoint| or |\pgfsetlinetofirstplotpoint|.
+
+ Obviously, the |\pgfpathcurveto| command needs, in addition to the
+ points on the path, some control points. These are generated
+ automatically using a somewhat ``dumb'' algorithm: Suppose you have
+ three points $x$, $y$, and $z$ on the curve such that $y$ is between
+ $x$ and $z$:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlercurveto
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+
+ In order to determine the control points of the curve at the point
+ $y$, the handler computes the vector $z-x$ and scales it by the
+ tension factor (see below). Let us call the resulting vector
+ $s$. Then $y+s$ and $y-s$ will be the control points around $y$. The
+ first control point at the beginning of the curve will be the
+ beginning itself, once more; likewise the last control point is the
+ end itself.
+\end{command}
+
+\begin{command}{\pgfsetplottension\marg{value}}
+ Sets the factor used by the curve plot handlers to determine the
+ distance of the control points from the points they control. The
+ higher the curvature of the curve points, the higher this value
+ should be. A value of $1$ will cause four points at quarter
+ positions of a circle to be connected using a circle. The default is
+ $0.5$.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfsetplottension{0.75}
+ \pgfplothandlercurveto
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+
+\begin{command}{\pgfplothandlerclosedcurve}
+ This handler works like the curve-to plot handler, only it will
+ add a new part to the current path that is a closed curve through
+ the plot points.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerclosedcurve
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+
+\subsection{Comb Plot Handlers}
+
+There are three ``comb'' plot handlers. There name stems from the fact
+that the plots they produce look like ``combs'' (more or less).
+
+\begin{command}{\pgfplothandlerxcomb}
+ This handler converts each point in the plot stream into a line from
+ the $y$-axis to the point's coordinate, resulting in a ``horizontal
+ comb.''
+
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerxcomb
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+
+\begin{command}{\pgfplothandlerycomb}
+ This handler converts each point in the plot stream into a line from
+ the $x$-axis to the point's coordinate, resulting in a ``vertical
+ comb.''
+
+ This handler is useful for creating ``bar diagrams.''
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerycomb
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+\begin{command}{\pgfplothandlerpolarcomb}
+ This handler converts each point in the plot stream into a line from
+ the origin to the point's coordinate.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerpolarcomb
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+\subsection{Mark Plot Handler}
+
+\label{section-plot-marks}
+
+\begin{command}{\pgfplothandlermark\marg{mark code}}
+ This command will execute the \meta{mark code} for some points of the
+ plot, but each time the coordinate transformation matrix will be
+ setup such that the origin is at the position of the point to be
+ plotted. This way, if the \meta{mark code} draws a little circle
+ around the origin, little circles will be drawn at some point of the
+ plot.
+
+ By default, a mark is drawn at all points of the plot. However, two
+ parameters $r$ and $p$ influence this. First, only every $r$th mark
+ is drawn. Second, the first mark drawn is the $p$th. These
+ parameters can be influenced using the commands below.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlermark{\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}}
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+
+ Typically, the \meta{code} will be |\pgfuseplotmark{|\meta{plot mark
+ name}|}|, where \meta{plot mark name} is the name of a
+ predefined plot mark.
+\end{command}
+
+\begin{command}{\pgfsetplotmarkrepeat\marg{repeat}}
+ Sets the $r$ parameter to \meta{repeat}, that is, only every $r$th
+ mark will be drawn.
+\end{command}
+
+\begin{command}{\pgfsetplotmarkphase\marg{phase}}
+ Sets the $p$ parameter to \meta{phase}, that is, the first mark to
+ be drawn is the $p$th, followed by the $(p+r)$th, then the
+ $(p+2r)$th, and so on.
+\end{command}
+
+\begin{command}{\pgfplothandlermarklisted\marg{mark code}\marg{index list}}
+ This command works similar to the previous one. However, marks will
+ only be placed at those indices in the given \meta{index list}. The
+ syntax for the list is the same as for the |\foreach| statement. For
+ example, if you provide the list |1,3,...,25|, a mark will be placed
+ only at every second point. Similarly, |1,2,4,8,16,32| yields marks
+ only at those points that are powers of two.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlermarklisted
+ {\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}}
+ {1,3}
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+\begin{command}{\pgfuseplotmark\marg{plot mark name}}
+ Draws the given \meta{plot mark name} at the origin. The \meta{plot
+ mark name} must previously have been declared using
+ |\pgfdeclareplotmark|.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlermark{\pgfuseplotmark{pentagon}}
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}}
+ Declares a plot mark for later used with the |\pgfuseplotmark|
+ command.
+
+\begin{codeexample}[]
+\pgfdeclareplotmark{my plot mark}
+ {\pgfpathcircle{\pgfpoint{0cm}{1ex}}{1ex}\pgfusepathqstroke}
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlermark{\pgfuseplotmark{my plot mark}}
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+
+\begin{command}{\pgfsetplotmarksize\marg{dimension}}
+ This command sets the \TeX\ dimension |\pgfplotmarksize| to
+ \meta{dimension}. This dimension is a ``recommendation'' for plot
+ mark code at which size the plot mark should be drawn; plot mark
+ code may choose to ignore this \meta{dimension} altogether. For
+ circles, \meta{dimension} should be the radius, for other shapes it
+ should be about half the width/height.
+
+ The predefined plot marks all take this dimension into account.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfsetplotmarksize{1ex}
+ \pgfplothandlermark{\pgfuseplotmark{*}}
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+\begin{textoken}{\pgfplotmarksize}
+ A \TeX\ dimension that is a ``recommendation'' for the size of plot
+ marks.
+\end{textoken}
+
+The following plot marks are predefined (the filling color has been
+set to yellow):
+
+\medskip
+\begin{tabular}{lc}
+ \plotmarkentry{*}
+ \plotmarkentry{x}
+ \plotmarkentry{+}
+\end{tabular}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual-pdftex-version"
+%%% End: