summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex
Initial commit
Diffstat (limited to 'graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex')
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex694
1 files changed, 694 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex
new file mode 100644
index 0000000000..cf20bc8476
--- /dev/null
+++ b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex
@@ -0,0 +1,694 @@
+% 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{Constant Plot Handlers}
+
+There are several plot handlers which produce piecewise constant interpolations
+between successive points:
+
+\begin{command}{\pgfplothandlerconstantlineto}
+ This handler works like the line-to plot handler, only it will produce a
+ connected, piecewise constant path to connect the points.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerconstantlineto
+ \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}{\pgfplothandlerconstantlinetomarkright}
+ A variant of |\pgfplothandlerconstantlineto| which places its mark on the
+ right line ends.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerconstantlinetomarkright
+ \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}{\pgfplothandlerconstantlinetomarkmid}
+ A variant of |\pgfplothandlerconstantlineto| which places its mark on the
+ center of the line.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerconstantlinetomarkmid
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+ %
+ The plot handler always connects two data points by a horizontal line
+ starting from the previous data points, followed by a vertical line in the
+ middle between the two data points, followed by a horizontal line between
+ the middle and the current data point. This results in a symmetric constant
+ plot handler for constant mesh width.
+\end{command}
+
+\begin{command}{\pgfplothandlerjumpmarkleft}
+ This handler works like the line-to plot handler, only it will produce a
+ non-connected, piecewise constant path to connect the points. If there are
+ any plot marks, they will be placed on the left open pieces.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerjumpmarkleft
+ \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}{\pgfplothandlerjumpmarkright}
+ This handler works like the line-to plot handler, only it will produce a
+ non-connected, piecewise constant path to connect the points. If there are
+ any plot marks, they will be placed on the right open pieces.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerjumpmarkright
+ \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}{\pgfplothandlerjumpmarkmid}
+ This handler works like the |\pgfplothandlerconstantlinetomarkmid|, but it
+ will produce a non-connected, piecewise constant path to connect the
+ points. If there are any plot marks, they will be placed in the center of
+ the horizontal line segment..
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerjumpmarkmid
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+ %
+ See |\pgfplothandlerconstantlinetomarkmid| for details.
+\end{command}
+
+
+\subsection{Comb Plot Handlers}
+
+There are three ``comb'' plot handlers. Their 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}
+
+\pgfname\ bar or comb plots usually draw something from zero to the current
+plot's coordinate. The ``zero'' offset can be changed using an input stream
+which returns the desired offset successively for each processed coordinate.
+
+There are two such streams, which can be configured independently. The first
+one returns ``zeros'' for coordinate~$x$, the second one returns ``zeros'' for
+coordinate~$y$. They are used as follows.
+%
+\begin{codeexample}[code only]
+\pgfplotxzerolevelstreamstart
+\pgfplotxzerolevelstreamnext % assigns \pgf@x
+\pgfplotxzerolevelstreamnext
+\pgfplotxzerolevelstreamnext
+\pgfplotxzerolevelstreamend
+\end{codeexample}
+%
+\begin{codeexample}[code only]
+\pgfplotyzerolevelstreamstart
+\pgfplotyzerolevelstreamnext % assigns \pgf@x
+\pgfplotyzerolevelstreamend
+\end{codeexample}
+%
+Different zero level streams can be implemented by overwriting these macros.
+
+\begin{command}{\pgfplotxzerolevelstreamconstant\marg{dimension}}
+ This zero level stream always returns \marg{dimension} instead of $x=0$pt.
+
+ It is used for |xcomb| and |xbar|.
+\end{command}
+
+\begin{command}{\pgfplotyzerolevelstreamconstant\marg{dimension}}
+ This zero level stream always returns \marg{dimension} instead of $y=0$pt.
+
+ It is used for |ycomb| and |ybar|.
+\end{command}
+
+
+\subsection{Bar Plot Handlers}
+\label{section-plotlib-bar-handlers}
+
+While comb plot handlers produce a line-to operation to generate combs, bar
+plot handlers employ rectangular shapes, allowing filled bars (or pattern
+bars).
+
+\begin{command}{\pgfplothandlerybar}
+ This handler converts each point in the plot stream into a rectangle from
+ the $x$-axis to the point's coordinate. The rectangle is placed centered at
+ the $x$-axis.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerybar
+ \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}{\pgfplothandlerxbar}
+ This handler converts each point in the plot stream into a rectangle from
+ the $y$-axis to the point's coordinate. The rectangle is placed centered at
+ the $y$-axis.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
+ \pgfplothandlerxbar
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{command}
+
+\label{key-bar-width}%
+\begin{key}{/pgf/bar width=\marg{dimension} (initially 10pt)}
+\keyalias{tikz}
+ Sets the width of |\pgfplothandlerxbar| and |\pgfplothandlerybar| to
+ \marg{dimension}. The argument \marg{dimension} will be evaluated using the
+ math parser.
+\end{key}
+
+\label{key-bar-shift}%
+\begin{key}{/pgf/bar shift=\marg{dimension} (initially 0pt)}
+\keyalias{tikz}
+ Sets a shift used by |\pgfplothandlerxbar| and |\pgfplothandlerybar| to
+ \marg{dimension}. It has the same effect as |xshift|, but it applies only
+ to those bar plots. The argument \marg{dimension} will be evaluated using
+ the math parser.
+\end{key}
+
+\begin{command}{\pgfplotbarwidth}
+ Expands to the value of |/pgf/bar width|.
+\end{command}
+
+\begin{command}{\pgfplothandlerybarinterval}
+ This handler is a variant of |\pgfplothandlerybar| which works with
+ intervals instead of points.
+
+ Bars are drawn between successive input coordinates and the width is
+ determined relatively to the interval length.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[gray] (0,2) node {$x_1$} (1,1) node {$x_2$} (2,.5) node {$x_3$} (4,0.7) node {$x_4$};
+ \pgfplothandlerybarinterval
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{2cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}}
+ \pgfplotstreamend
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+
+ In more detail, if $(x_i,y_i)$ and $(x_{i+1},y_{i+1})$ denote successive
+ input coordinates, the bar will be placed above the interval
+ $[x_i,x_{i+1}]$, centered at
+ %
+ \[ x_i + \text{\meta{bar interval shift}} \cdot (x_{i+1} - x_i) \]
+ %
+ with width
+ %
+ \[ \text{\meta{bar interval width}} \cdot (x_{i+1} - x_i). \]
+ %
+ Here, \meta{bar interval shift} and \meta{bar interval width} denote the
+ current values of the associated options.
+
+ If you have $N+1$ input points, you will get $N$ bars (one for each
+ interval). The $y$~value of the last point will be ignored.
+\end{command}
+
+\begin{command}{\pgfplothandlerxbarinterval}
+ As |\pgfplothandlerybarinterval|, this handler provides bar plots with
+ relative bar sizes and offsets, one bar for each $y$~coordinate interval.
+\end{command}
+
+\label{key-bar-interval-shift}%
+\begin{key}{/pgf/bar interval shift=\marg{factor} (initially 0.5)}
+\keyalias{tikz}
+ Sets the \emph{relative} shift of |\pgfplothandlerxbarinterval| and
+ |\pgfplothandlerybarinterval| to \meta{factor}. As
+ |/pgf/bar interval width|, the argument is relative to the interval length
+ of the input coordinates.
+
+ The argument \marg{scale} will be evaluated using the math parser.
+\end{key}
+
+\label{key-bar-interval-width}%
+\begin{key}{/pgf/bar interval width=\marg{scale} (initially 1)}
+\keyalias{tikz}
+ Sets the \emph{relative} width of |\pgfplothandlerxbarinterval| and
+ |\pgfplothandlerybarinterval| to \marg{scale}. The argument is relative to
+ $(x_{i+1} - x_i)$ for $y$~bar plots and relative to $(y_{i+1}-y_i)$ for
+ $x$~bar plots.
+
+ The argument \marg{scale} will be evaluated using the math parser.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}[bar interval width=0.5]
+ \draw[gray]
+ (0,3) -- (0,-0.1)
+ (1,3) -- (1,-0.1)
+ (2,3) -- (2,-0.1)
+ (4,3) -- (4,-0.1);
+ \pgfplothandlerybarinterval
+ \begin{scope}[bar interval shift=0.25,fill=blue]
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{2cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
+ \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}}
+ \pgfplotstreamend
+ \pgfusepath{fill}
+ \end{scope}
+ \begin{scope}[bar interval shift=0.75,fill=red]
+ \pgfplotstreamstart
+ \pgfplotstreampoint{\pgfpoint{0cm}{3cm}}
+ \pgfplotstreampoint{\pgfpoint{1cm}{0.2cm}}
+ \pgfplotstreampoint{\pgfpoint{2cm}{0.7cm}}
+ \pgfplotstreampoint{\pgfpoint{4cm}{0.2cm}}
+ \pgfplotstreamend
+ \pgfusepath{fill}
+ \end{scope}
+\end{tikzpicture}
+\end{codeexample}
+ %
+ Please note that bars are always centered, so we have to use shifts $0.25$
+ and $0.75$ instead of $0$ and $0.5$.
+\end{key}
+
+
+\subsection{Gapped Plot Handlers}
+\label{section-plot-gapped}
+
+\begin{command}{\pgfplothandlergaplineto}
+ This handler will connect the points of the plots by straight line
+ segments. However, at the start and the end of the lines there will be a
+ small gap, given by the following key:
+ %
+ \begin{key}{/pgf/gap around stream point=\meta{dimension} (initially 1.5pt)}
+ The \meta{dimension} by which the lines between consecutive stream
+ points are shortened at the beginning and end.
+ \end{key}
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \pgfplothandlergaplineto
+ \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}{\pgfplothandlergapcycle}
+ Works like |\pgfplothandlergaplineto|, but the last point is connected to
+ the first in the same fashion:
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \pgfplothandlergapcycle
+ \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 set up 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 have been previously 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: