% 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: 
