summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex633
1 files changed, 311 insertions, 322 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
index 61e627f8304..4e4bac2faf0 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
@@ -9,70 +9,59 @@
\section{Creating Plots}
-
\label{section-plots}
This section describes the |plot| module.
\begin{pgfmodule}{plot}
- This module provides a set of commands that are intended to make it
- reasonably easy to plot functions using \pgfname. It is loaded
- automatically by |pgf|, but you can load it manually if you have
- only included |pgfcore|.
+ This module provides a set of commands that are intended to make it
+ reasonably easy to plot functions using \pgfname. It is loaded
+ automatically by |pgf|, but you can load it manually if you have only
+ included |pgfcore|.
\end{pgfmodule}
\subsection{Overview}
-There are different reasons for using \pgfname\ for creating plots
-rather than some more powerful program such as \textsc{gnuplot} or
-\textsc{mathematica}, as discussed in
-Section~\ref{section-why-pgname-for-plots}. So, let us assume that --
-for whatever reason -- you wish to use \pgfname\ for generating a plot.
-
-\pgfname\ (conceptually) uses a two-stage process for generating
-plots. First, a \emph{plot stream} must be produced. This stream
-consists (more or less) of a large number of coordinates. Second a
-\emph{plot handler} is applied to the stream. A plot handler ``does
-something'' with the stream. The standard handler will issue
-line-to operations to the coordinates in the stream. However, a
-handler might also try to issue appropriate curve-to operations in
-order to smooth the curve. A handler may even do something else
-entirely, like writing each coordinate to another stream, thereby
-duplicating the original stream.
+There are different reasons for using \pgfname\ for creating plots rather than
+some more powerful program such as \textsc{gnuplot} or \textsc{mathematica}, as
+discussed in Section~\ref{section-why-pgname-for-plots}. So, let us assume that
+-- for whatever reason -- you wish to use \pgfname\ for generating a plot.
-Both for the creation of streams and the handling of streams different
-sets of commands exist. The commands for creating streams start with
-|\pgfplotstream|, the commands for setting the handler start with
-|\pgfplothandler|.
+\pgfname\ (conceptually) uses a two-stage process for generating plots. First,
+a \emph{plot stream} must be produced. This stream consists (more or less) of a
+large number of coordinates. Second a \emph{plot handler} is applied to the
+stream. A plot handler ``does something'' with the stream. The standard handler
+will issue line-to operations to the coordinates in the stream. However, a
+handler might also try to issue appropriate curve-to operations in order to
+smooth the curve. A handler may even do something else entirely, like writing
+each coordinate to another stream, thereby duplicating the original stream.
+Both for the creation of streams and the handling of streams different sets of
+commands exist. The commands for creating streams start with |\pgfplotstream|,
+the commands for setting the handler start with |\pgfplothandler|.
\subsection{Generating Plot Streams}
\subsubsection{Basic Building Blocks of Plot Streams}
-A \emph{plot stream} is a (long) sequence of the following
-commands:
+A \emph{plot stream} is a (long) sequence of the following commands:
+%
\begin{enumerate}
-\item
- |\pgfplotstreamstart|,
-\item
- |\pgfplotstreampoint|,
-\item
- |\pgfplotstreampointoutlier|,
-\item
- |\pgfplotstreampointundefined|,
-\item
- |\pgfplotstreamnewdataset|,
-\item
- |\pgfplotstreamspecial|, and
-\item
- |\pgfplotstreamend|.
+ \item |\pgfplotstreamstart|,
+ \item |\pgfplotstreampoint|,
+ \item |\pgfplotstreampointoutlier|,
+ \item |\pgfplotstreampointundefined|,
+ \item |\pgfplotstreamnewdataset|,
+ \item |\pgfplotstreamspecial|, and
+ \item |\pgfplotstreamend|.
\end{enumerate}
-Between calls of these commands arbitrary other code may be
-called. Obviously, the stream should start with the first command and
-end with the last command. Here is an example of a plot stream:
+%
+Between calls of these commands arbitrary other code may be called. Obviously,
+the stream should start with the first command and end with the last command.
+Here is an example of a plot stream:
+%
\begin{codeexample}[code only]
\pgfplotstreamstart
\pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
@@ -84,151 +73,151 @@ end with the last command. Here is an example of a plot stream:
\pgfplotstreamend
\end{codeexample}
-Streams are \emph{global}, meaning that they are not influenced by
-\TeX\ groups.
+Streams are \emph{global}, meaning that they are not influenced by \TeX\
+groups.
\begin{command}{\pgfplotstreamstart}
- This command signals that a plot stream starts. The effect of this
- command is to call the internal command |\pgf@plotstreamstart|,
- which is set by the current plot handler to do whatever needs to be
- done at the beginning of the plot. It will also reset the
- meaning of the internal commands like |\pgf@plotstreampoint| to the
- initial setting for the plot handler (what this means will be
- explained in a moment).
+ This command signals that a plot stream starts. The effect of this command
+ is to call the internal command |\pgf@plotstreamstart|, which is set by the
+ current plot handler to do whatever needs to be done at the beginning of
+ the plot. It will also reset the meaning of the internal commands like
+ |\pgf@plotstreampoint| to the initial setting for the plot handler (what
+ this means will be explained in a moment).
\end{command}
\begin{command}{\pgfplotstreampoint\marg{point}}
- This command adds a \meta{point} to the current plot stream. The
- effect of this command is to call the internal command |\pgf@plotstreampoint|,
- which is also set by the current plot handler. This command should
- now ``handle'' the point in some sensible way. For example, a
- line-to command might be issued for the point.
-
- When a plot handler is installed, it will setup the internal command
- |\pgf@plotstreampoint| in some way. It is permissible to change the
- meaning of this internal command during a stream. For instance, a
- handler might setup |\pgf@plotstreampoint| in some sensible way for
- the first point and then redefine it so that subsequent points are
- handled in some other way.
-
- As mentioned earlier, the |\pgfplotstreamstart| will always reset
- the definition of the internal command to the initial meaning it had
- when the handler was installed. This is true for the other commands
- mentioned in the following.
+ This command adds a \meta{point} to the current plot stream. The effect of
+ this command is to call the internal command |\pgf@plotstreampoint|, which
+ is also set by the current plot handler. This command should now ``handle''
+ the point in some sensible way. For example, a line-to command might be
+ issued for the point.
+
+ When a plot handler is installed, it will setup the internal command
+ |\pgf@plotstreampoint| in some way. It is permissible to change the meaning
+ of this internal command during a stream. For instance, a handler might
+ setup |\pgf@plotstreampoint| in some sensible way for the first point and
+ then redefine it so that subsequent points are handled in some other way.
+
+ As mentioned earlier, the |\pgfplotstreamstart| will always reset the
+ definition of the internal command to the initial meaning it had when the
+ handler was installed. This is true for the other commands mentioned in the
+ following.
\end{command}
\begin{command}{\pgfplotstreampointoutlier\marg{point}}
- An \emph{outlier} is a point that is ``out of bounds'' in some
- way. For instance, it might have very large coordinates or the
- coordinates might just be outside some specified
- range. Nevertheless, an outlier is still a well-defined point. This
- command is issued, for instance, by \textsc{gnuplot} when a value is
- outside the specified range.
-
- You can configure how outliers are treated using the following key:
- \begin{key}{/pgf/handle outlier points in plots=\meta{how}
- (initially jump)}
+ An \emph{outlier} is a point that is ``out of bounds'' in some way. For
+ instance, it might have very large coordinates or the coordinates might
+ just be outside some specified range. Nevertheless, an outlier is still a
+ well-defined point. This command is issued, for instance, by
+ \textsc{gnuplot} when a value is outside the specified range.
+
+ You can configure how outliers are treated using the following key:
+ %
+ \begin{key}{/pgf/handle outlier points in plots=\meta{how} (initially jump)}
\keyalias{tikz}
- You can set \meta{how} to one of the following values:
- \begin{itemize}
- \item |plot| This will cause the outlier to be drawn normally,
- just as if |\pgfplotstreampoint| had been used rather than this
- command.
- \item |ignore| The outlier will be completely ignored, just as if
- the command had not been used at all.
- \item |jump| This causes the internal macro |\pgf@plotstreamjump|
- to be called. A ``jump'' in a stream is a position where a
- ``gap'' is introduced. For instance, a simple line-to plot
- handler will stop the current subpath at a jump position and
- begin with a move-to operation at the next normal point of the
- stream.
-
- The net effect of this setting is that at outlier points plots
- get interrupted and ``restarted'' when the points are no longer
- outliers. This is usually the behaviour you will be looking for.
- \end{itemize}
- \end{key}
+ You can set \meta{how} to one of the following values:
+ %
+ \begin{itemize}
+ \item |plot| This will cause the outlier to be drawn normally, just
+ as if |\pgfplotstreampoint| had been used rather than this
+ command.
+ \item |ignore| The outlier will be completely ignored, just as if
+ the command had not been used at all.
+ \item |jump| This causes the internal macro |\pgf@plotstreamjump|
+ to be called. A ``jump'' in a stream is a position where a
+ ``gap'' is introduced. For instance, a simple line-to plot
+ handler will stop the current subpath at a jump position and
+ begin with a move-to operation at the next normal point of the
+ stream.
+
+ The net effect of this setting is that at outlier points plots
+ get interrupted and ``restarted'' when the points are no longer
+ outliers. This is usually the behaviour you will be looking
+ for.
+ \end{itemize}
+ \end{key}
\end{command}
\begin{command}{\pgfplotstreampointundefined}
- This command indicated that the stream contains an ``undefined''
- point like a point where some coordinate results for a division by
- zero. Such a point cannot be plotted, which is why it is not given
- as a parameter. However, such a point \emph{can} result in a jump in
- the plot, depending on the setting of the following key:
- \begin{key}{/pgf/handle undefined points in plots=\meta{how}
- (initially jump)}
+ This command indicated that the stream contains an ``undefined'' point like
+ a point where some coordinate results for a division by zero. Such a point
+ cannot be plotted, which is why it is not given as a parameter. However,
+ such a point \emph{can} result in a jump in the plot, depending on the
+ setting of the following key:
+ %
+ \begin{key}{/pgf/handle undefined points in plots=\meta{how} (initially jump)}
\keyalias{tikz}
- You can set \meta{how} to one of the following values:
- \begin{itemize}
- \item |ignore| The undefined point will be completely ignored, just as if
- the command had not been used at all.
- \item |jump| This causes the internal macro |\pgf@plotstreamjump|
- to be called.
- \end{itemize}
- \end{key}
+ You can set \meta{how} to one of the following values:
+ %
+ \begin{itemize}
+ \item |ignore| The undefined point will be completely ignored, just
+ as if the command had not been used at all.
+ \item |jump| This causes the internal macro |\pgf@plotstreamjump|
+ to be called.
+ \end{itemize}
+ \end{key}
\end{command}
\begin{command}{\pgfplotstreamnewdataset}
- This command indicated that in the stream a ``new data set'' starts.
- So, the stream does not end, but there is a logical break in the
- data. For example, when a table is read from a file, empty lines are
- interpreted as indicating new data sets. What happens when a new
- data set is encountered is governed by the following key:
- \begin{key}{/pgf/handle new data sets in plots=\meta{how}
- (initially jump)}
+ This command indicated that in the stream a ``new data set'' starts. So,
+ the stream does not end, but there is a logical break in the data. For
+ example, when a table is read from a file, empty lines are interpreted as
+ indicating new data sets. What happens when a new data set is encountered
+ is governed by the following key:
+ %
+ \begin{key}{/pgf/handle new data sets in plots=\meta{how} (initially jump)}
\keyalias{tikz}
- You can set \meta{how} to one of the following values:
- \begin{itemize}
- \item |ignore| The command will be completely ignored, just as if
- the command had not been used at all.
- \item |jump| This causes the internal macro |\pgf@plotstreamjump|
- to be called.
- \end{itemize}
- \end{key}
+ You can set \meta{how} to one of the following values:
+ %
+ \begin{itemize}
+ \item |ignore| The command will be completely ignored, just as if
+ the command had not been used at all.
+ \item |jump| This causes the internal macro |\pgf@plotstreamjump|
+ to be called.
+ \end{itemize}
+ \end{key}
\end{command}
\begin{command}{\pgfplotstreamspecial\marg{text}}
- This command causes |\pgf@plotstreamspecial| to be called with
- \meta{text} as its parameter. This allows handler-specific
- information to be passed to the handler. All normal handlers ignore
- this command.
+ This command causes |\pgf@plotstreamspecial| to be called with \meta{text}
+ as its parameter. This allows handler-specific information to be passed to
+ the handler. All normal handlers ignore this command.
\end{command}
\begin{command}{\pgfplotstreamend}
- This command signals that a plot stream ends. It calls
- |\pgf@plotstreamend|, which should now do any necessary ``cleanup.''
+ This command signals that a plot stream ends. It calls
+ |\pgf@plotstreamend|, which should now do any necessary ``cleanup''.
\end{command}
-Note that plot streams are not buffered, that is, the different points
-are handled immediately. However, using the recording handler, it is
-possible to record a stream.
+Note that plot streams are not buffered, that is, the different points are
+handled immediately. However, using the recording handler, it is possible to
+record a stream.
\subsubsection{Commands That Generate Plot Streams}
\label{section-plot-jumps}
-Plot streams can be created ``by hand'' as in the earlier
-example. However, most of the time the coordinates will be produced
-internally by some command. For example, the |\pgfplotxyfile| reads a
-file and converts it into a plot stream.
+Plot streams can be created ``by hand'' as in the earlier example. However,
+most of the time the coordinates will be produced internally by some command.
+For example, the |\pgfplotxyfile| reads a file and converts it into a plot
+stream.
\begin{command}{\pgfplotxyfile\marg{filename}}
- This command will try to open the file \meta{filename}. If this
- succeeds, it will convert the file contents into a plot stream as
- follows: A |\pgfplotstreamstart| is issued. Then, for each nonempty
- line a |\pgfplotstreamnewdataset| is produced. Other lines in the
- file should start with two numbers separated by a space, such as
- |0.1 1| or |100 -.3|. The numbers may be followed by some text,
- which will be ignore \emph{except} if it is exactly ``|u|'' or
- ``|o|''. For ``|u|'', the point is considered to be undefined and
- |\pgfplotstreampointundefined| is called. For ``|o|'', the point is
- considered to be an outlier and |\pgfplotstreampointoutlier| is
- called. Otherwise, each pair \meta{x} and \meta{y} of numbers is
- converted into one plot stream point in the xy-coordinate
- system. Thus, a line like
+ This command will try to open the file \meta{filename}. If this succeeds,
+ it will convert the file contents into a plot stream as follows: A
+ |\pgfplotstreamstart| is issued. Then, for each empty line a
+ |\pgfplotstreamnewdataset| is produced. Other lines in the file should
+ start with two numbers separated by a space, such as |0.1 1| or |100 -.3|.
+ The numbers may be followed by some text, which will be ignore
+ \emph{except} if it is exactly ``|u|'' or ``|o|''. For ``|u|'' the point
+ is considered to be undefined and |\pgfplotstreampointundefined| is called.
+ For ``|o|'' the point is considered to be an outlier and
+ |\pgfplotstreampointoutlier| is called. Otherwise, each pair \meta{x} and
+ \meta{y} of numbers is converted into one plot stream point in the
+ $xy$-coordinate system. Thus, a line like
+ %
\begin{codeexample}[code only, tikz syntax=false]
-0 Nan u
+0 Nan u
1 1 some text
2 4
3 9
@@ -236,7 +225,9 @@ file and converts it into a plot stream.
4 16 o
5 25 oo
\end{codeexample}
- is turned into
+ %
+ is turned into
+ %
\begin{codeexample}[code only]
\pgfplotstreamstart
\pgfplotstreampointundefined
@@ -248,22 +239,22 @@ file and converts it into a plot stream.
\pgfplotstreampoint{\pgfpointxy{5}{25}}
\pgfplotstreamend
\end{codeexample}
- (Note that the last line is not an outlier because |oo| is not the
- same as |o|).
+ %
+ (Note that the last line is not an outlier because |oo| is not the same as
+ |o|).
- The two characters |%| and |#| are also allowed in a file and they
- are both treated as comment characters. Thus, a line starting with
- either of them is treated as empty.
+ The two characters |%| and |#| are also allowed in a file and they are both
+ treated as comment characters. Thus, a line starting with either of them is
+ treated as empty.
- When the file has been read completely, |\pgfplotstreamend| is
- called.
+ When the file has been read completely, |\pgfplotstreamend| is called.
\end{command}
-
\begin{command}{\pgfplotxyzfile\marg{filename}}
- This command works like |\pgfplotxyfile|, only \emph{three} numbers
- are expected on each non-empty line. They are converted into points
- in the xyz-coordinate system. Consider, the following file:
+ This command works like |\pgfplotxyfile|, only \emph{three} numbers are
+ expected on each non-empty line. They are converted into points in the
+ $xyz$-coordinate system. Consider, the following file:
+ %
\begin{codeexample}[code only, tikz syntax=false]
% Some comments
# more comments
@@ -271,7 +262,9 @@ file and converts it into a plot stream.
2 -.2 2 o
2 -5 2 third entry
\end{codeexample}
- It is turned into the following stream:
+ %
+ It is turned into the following stream:
+ %
\begin{codeexample}[code only]
\pgfplotstreamstart
\pgfplotstreamnewdataset
@@ -281,22 +274,20 @@ file and converts it into a plot stream.
\pgfplotstreampoint{\pgfpointxyz{2}{-5}{2}}
\pgfplotstreamend
\end{codeexample}
+ %
\end{command}
-Currently, there is no command that can decide automatically whether
-the xy-coordinate system should be used or whether the xyz-system
-should be used. However, it would not be terribly difficult to write a
-``smart file reader'' that parses coordinate files a bit more
-intelligently.
-
+Currently, there is no command that can decide automatically whether the
+$xy$-coordinate system should be used or whether the $xyz$-system should be
+used. However, it would not be terribly difficult to write a ``smart file
+reader'' that parses coordinate files a bit more intelligently.
\begin{command}{\pgfplotfunction\marg{variable}\marg{sample list}\marg{point}}
- This command will produce coordinates by iterating the
- \meta{variable} over all values in \meta{sample list}, which should
- be a list in the |\foreach| syntax. For each value of
- \meta{variable}, the \meta{point} is evaluated and the resulting
- coordinate is inserted into the plot stream.
-
+ This command will produce coordinates by iterating the \meta{variable} over
+ all values in \meta{sample list}, which should be a list in the |\foreach|
+ syntax. For each value of \meta{variable}, the \meta{point} is evaluated
+ and the resulting coordinate is inserted into the plot stream.
+ %
\begin{codeexample}[]
\begin{tikzpicture}[x=3.8cm/360]
\pgfplothandlerlineto
@@ -313,40 +304,38 @@ intelligently.
\end{tikzpicture}
\end{codeexample}
- Be warned that if the expressions that need to evaluated for each
- point are complex, then this command can be very slow.
+ Be warned that if the expressions that need to evaluated for each point are
+ complex, then this command can be very slow.
\end{command}
-
-
\begin{command}{\pgfplotgnuplot\oarg{prefix}\marg{function}}
- This command will ``try'' to call the \textsc{gnuplot} program to
- generate the coordinates of the \meta{function}. In detail, the
- following happens:
+ This command will ``try'' to call the \textsc{gnuplot} program to generate
+ the coordinates of the \meta{function}. In detail, the following happens:
- This command works with two files: \meta{prefix}|.gnuplot| and
- \meta{prefix}|.table|. If the optional argument \meta{prefix} is
- not given, it is set to |\jobname|.
+ This command works with two files: \meta{prefix}|.gnuplot| and
+ \meta{prefix}|.table|. If the optional argument \meta{prefix} is not
+ given, it is set to |\jobname|.
- Let us start with the situation where none of these files
- exists. Then \pgfname\ will first generate the file
- \meta{prefix}|.gnuplot|. In this file it writes
+ Let us start with the situation where none of these files exists. Then
+ \pgfname\ will first generate the file \meta{prefix}|.gnuplot|. In this
+ file it writes
+ %
\begin{codeexample}[code only, tikz syntax=false]
set terminal table; set output "#1.table"; set format "%.5f"
\end{codeexample}
- where |#1| is replaced by \meta{prefix}. Then, in a second line, it
- writes the text \meta{function}.
-
- Next, \pgfname\ will try to invoke the program |gnuplot| with the
- argument \meta{prefix}|.gnuplot|. This call may or may not succeed,
- depending on whether the |\write18| mechanism (also known as
- shell escape) is switched on and whether the |gnuplot| program is
- available.
-
- Assuming that the call succeeded, the next step is to invoke
- |\pgfplotxyfile| on the file \meta{prefix}|.table|; which is exactly
- the file that has just been created by |gnuplot|.
-
+ %
+ where |#1| is replaced by \meta{prefix}. Then, in a second line, it writes
+ the text \meta{function}.
+
+ Next, \pgfname\ will try to invoke the program |gnuplot| with the argument
+ \meta{prefix}|.gnuplot|. This call may or may not succeed, depending on
+ whether the |\write18| mechanism (also known as shell escape) is switched
+ on and whether the |gnuplot| program is available.
+
+ Assuming that the call succeeded, the next step is to invoke
+ |\pgfplotxyfile| on the file \meta{prefix}|.table|; which is exactly the
+ file that has just been created by |gnuplot|.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,-1) grid (4,1);
@@ -356,59 +345,53 @@ set terminal table; set output "#1.table"; set format "%.5f"
\end{tikzpicture}
\end{codeexample}
- The more difficult situation arises when the |.gnuplot| file exists,
- which will be the case on the second run of \TeX\ on the \TeX\
- file. In this case \pgfname\ will read this file and check whether
- it contains exactly what \pgfname\ ``would have written'' into
- this file. If this is not the case, the file contents is overwritten
- with what ``should be there'' and, as above, |gnuplot| is invoked to
- generate a new |.table| file. However, if the file contents is ``as
- expected,'' the external |gnuplot| program is \emph{not}
- called. Instead, the \meta{prefix}|.table| file is immediately
- read.
-
- As explained in Section~\ref{section-tikz-gnuplot}, the net effect
- of the above mechanism is that |gnuplot| is called as seldom as
- possible and that when you pass along the |.gnuplot| and |.table|
- files with your |.tex| file to someone else, that person can
- \TeX\ the |.tex| file without having |gnuplot| installed and without
- having the |\write18| mechanism switched on.
-
- \begin{key}{/pgf/plot/gnuplot call=\meta{gnuplot invocation} (initially gnuplot)}
- This key can be used to change the way gnuplot is called.
-
- Some portable Mik\TeX{} distribution needs something like the
- following.
-
+ The more difficult situation arises when the |.gnuplot| file exists, which
+ will be the case on the second run of \TeX\ on the \TeX\ file. In this case
+ \pgfname\ will read this file and check whether it contains exactly what
+ \pgfname\ ``would have written'' into this file. If this is not the case,
+ the file contents is overwritten with what ``should be there'' and, as
+ above, |gnuplot| is invoked to generate a new |.table| file. However, if
+ the file contents is ``as expected'', the external |gnuplot| program is
+ \emph{not} called. Instead, the \meta{prefix}|.table| file is immediately
+ read.
+
+ As explained in Section~\ref{section-tikz-gnuplot}, the net effect of the
+ above mechanism is that |gnuplot| is called as seldom as possible and that
+ when you pass along the |.gnuplot| and |.table| files with your |.tex| file
+ to someone else, that person can \TeX\ the |.tex| file without having
+ |gnuplot| installed and without having the |\write18| mechanism switched
+ on.
+
+ \begin{key}{/pgf/plot/gnuplot call=\meta{gnuplot invocation} (initially gnuplot)}
+ This key can be used to change the way gnuplot is called.
+
+ Some portable MiK\TeX{} distribution needs something like the
+ following.
+ %
\begin{codeexample}[code only]
\pgfkeys{/pgf/plot/gnuplot call="/Programs/gnuplot/binary/gnuplot"}
\end{codeexample}
-
- \end{key}
+ \end{key}
\end{command}
-
\subsection{Plot Handlers}
-
\label{section-plot-handlers}
-A \emph{plot handler} determines what ``should be done'' with a
-plot stream. You must set the plot handler before the stream starts.
-The following commands install the most basic plot handlers; more plot
-handlers are defined in the file |pgflibraryplothandlers|, which is
-documented in Section~\ref{section-library-plothandlers}.
+A \emph{plot handler} determines what ``should be done'' with a plot stream.
+You must set the plot handler before the stream starts. The following commands
+install the most basic plot handlers; more plot handlers are defined in the
+file |pgflibraryplothandlers|, which is documented in
+Section~\ref{section-library-plothandlers}.
-All plot handlers work by setting or redefining the following three
-macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and
-|\pgf@plotstreamend|.
+All plot handlers work by setting or redefining the following three macros:
+|\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and |\pgf@plotstreamend|.
\begin{command}{\pgfplothandlerlineto}
- This handler will issue a |\pgfpathlineto| command for each point of
- the plot, \emph{except} possibly for the first. What happens with
- the first point can be specified using the two commands described
- below.
-
+ This handler will issue a |\pgfpathlineto| command for each point of the
+ plot, \emph{except} possibly for the first. What happens with the first
+ point can be specified using the two commands described below.
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfpathmoveto{\pgfpointorigin}
@@ -422,20 +405,20 @@ macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and
\pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfsetmovetofirstplotpoint}
- Specifies that the line-to plot handler (and also some other plot
- handlers) should issue a move-to command for the
- first point of the plot instead of a line-to. This will start a new
- part of the current path, which is not always, but often,
- desirable. This is the default.
+ Specifies that the line-to plot handler (and also some other plot handlers)
+ should issue a move-to command for the first point of the plot instead of a
+ line-to. This will start a new part of the current path, which is not
+ always, but often, desirable. This is the default.
\end{command}
\begin{command}{\pgfsetlinetofirstplotpoint}
- Specifies that plot handlers should issue a line-to command for the
- first point of the plot.
-
+ Specifies that plot handlers should issue a line-to command for the first
+ point of the plot.
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfpathmoveto{\pgfpointorigin}
@@ -450,25 +433,25 @@ macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and
\pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfplothandlerpolygon}
- This handler works like the line-to plot handler, only the line is
- closed at the end using |\pgfpathclose|, resulting in a polygon.
+ This handler works like the line-to plot handler, only the line is closed
+ at the end using |\pgfpathclose|, resulting in a polygon.
\end{command}
\begin{command}{\pgfplothandlerdiscard}
- This handler will simply throw away the stream.
+ This handler will simply throw away the stream.
\end{command}
\begin{command}{\pgfplothandlerrecord\marg{macro}}
- When this handler is installed, each time a plot stream command is
- called, this command will be appended to \meta{macro}. Thus, at
- the end of the stream, \meta{macro} will contain all the
- commands that were issued on the stream. You can then install
- another handler and invoke \meta{macro} to ``replay'' the stream
- (possibly many times).
-
+ When this handler is installed, each time a plot stream command is called,
+ this command will be appended to \meta{macro}. Thus, at the end of the
+ stream, \meta{macro} will contain all the commands that were issued on the
+ stream. You can then install another handler and invoke \meta{macro} to
+ ``replay'' the stream (possibly many times).
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfplothandlerrecord{\mystream}
@@ -485,19 +468,20 @@ macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and
\pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
+ %
\end{command}
-
\subsection{Defining New Plot Handlers}
You can define new plot handlers using the following command:
\begin{command}{\pgfdeclareplothandler\marg{macro}\marg{arguments}\marg{configuration}}
- This command creates a new plot handler that can subsequently be
- called using the macro \meta{macro}. This macro take the arguments
- given in \meta{arguments}, which can be a list like |#1#2| if
- \meta{macro} should be invoked with two arguments. Here is a typical example:
+ This command creates a new plot handler that can subsequently be called
+ using the macro \meta{macro}. This macro take the arguments given in
+ \meta{arguments}, which can be a list like |#1#2| if \meta{macro} should be
+ invoked with two arguments. Here is a typical example:
+ %
\begin{codeexample}[code only]
\pgfdeclareplothandler{\myhandler}{#1}{...}
...
@@ -507,33 +491,36 @@ You can define new plot handlers using the following command:
\pgfplotstreamend
\end{codeexample}
- The \meta{configuration} is used to define the behaviour of the
- handler. It is a list of key--value pairs, where the following keys
- are allowed:
- \begin{itemize}
- \item |start=|\meta{code}. The \meta{code} will be executed whenever
- |\pgfplotstreamstart| is used while the handler \meta{macro} is
- selected. Inside the \meta{code}, you can use |#1|, |#2|, and so
- on to refer to the parameters that were given to \meta{macro}:
+ The \meta{configuration} is used to define the behaviour of the handler. It
+ is a list of key--value pairs, where the following keys are allowed:
+ %
+ \begin{itemize}
+ \item |start=|\meta{code}. The \meta{code} will be executed whenever
+ |\pgfplotstreamstart| is used while the handler \meta{macro} is
+ selected. Inside the \meta{code}, you can use |#1|, |#2|, and so on
+ to refer to the parameters that were given to \meta{macro}:
+ %
\begin{codeexample}[width=6cm]
\pgfdeclareplothandler{\myhandler}{#1}{
start = Hi #1.,
end = Bye #1.,
}
\myhandler{foo}
-\pgfplotstreamstart
+\pgfplotstreamstart
\pgfplotstreamend
\myhandler{bar}
-\pgfplotstreamstart
+\pgfplotstreamstart
\pgfplotstreamend
\end{codeexample}
- \item |end=|\meta{code} Works just like |start|.
- \item |point=|\meta{code}. The \meta{code} will be executed whenever
- |\pgfplotstreampoint| is used while the handler \meta{macro} is in
- force. Inside the \meta{code}, you can use |#1|, |#2|, and so on
- to refer to the arguments give to \meta{macro}, while you can use
- |##1| to refer to the argument given to |\pgfplotstreampoint|
- itself (this will be the coordinate).
+ %
+ \item |end=|\meta{code} Works just like |start|.
+ \item |point=|\meta{code}. The \meta{code} will be executed whenever
+ |\pgfplotstreampoint| is used while the handler \meta{macro} is in
+ force. Inside the \meta{code}, you can use |#1|, |#2|, and so on to
+ refer to the arguments give to \meta{macro}, while you can use
+ |##1| to refer to the argument given to |\pgfplotstreampoint|
+ itself (this will be the coordinate).
+ %
\begin{codeexample}[]
\pgfdeclareplothandler{\myhandler}{#1}{
point=\pgfpathcircle{##1}{#1} % ##1 is the coordinate,
@@ -556,40 +543,42 @@ You can define new plot handlers using the following command:
\pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
- The \meta{code} will also be called for
- |\pgfplotstreampointoutlier| when this command has been configured
- to |plot| the outliers.
- \item |jump=|\meta{code} The \meta{code} will be called whenever a
- jump has been requested indirectly via an outlier point, and
- undefined point, or a new data set (for each of which the command
- needs to be configured to |jump|). As always, inside the
- \meta{code} you can access |#1| and so on.
- \item |special=|\meta{code} Causes \meta{code} to be executed
- whenever |\pgfplotstreamspecial|\marg{something} is used. Inside
- the \meta{code}, you can access \meta{something} via |##1| and the
- parameters of \meta{macro} as |#1|, |#2|, and so on.
- \end{itemize}
-
- In addition to the above keys, there exist also ``code macro
- versions'' of them:
- \begin{itemize}
- \item |point macro=|\meta{some macro}. Causes |\pgfplotstreampoint|
- to call \meta{some macro} directly (actually,
- |\pgf@plotstreampoint| is set to be equal to \meta{some
- macro}). Inside the \meta{some macro} you can use |#1| to access
- the coordinate passed to |\pgfplotstreampoint| and you can no
- longer access the parameters passed to the original call to
- \meta{macro} that installed the handler. So, \meta{some macro}
- must take exactly one argument, namely |#1|.
- \item |special macro=|\meta{some macro}. As |point macro|, only for
- specials.
- \item |start macro=|\meta{some macro}. Causes \meta{some macro} to
- be executed at the start. This macro, like the below ones, may not
- take any parameters and will not have access to the parameters
- passed to the original \meta{macro}.
- \item |end macro=|\meta{some macro}. As above.
- \item |jump macro=|\meta{some macro}. As above.
- \end{itemize}
+ %
+ The \meta{code} will also be called for
+ |\pgfplotstreampointoutlier| when this command has been configured
+ to |plot| the outliers.
+ \item |jump=|\meta{code} The \meta{code} will be called whenever a jump
+ has been requested indirectly via an outlier point, and undefined
+ point, or a new data set (for each of which the command needs to be
+ configured to |jump|). As always, inside the \meta{code} you can
+ access |#1| and so on.
+ \item |special=|\meta{code} Causes \meta{code} to be executed whenever
+ |\pgfplotstreamspecial|\marg{something} is used. Inside the
+ \meta{code}, you can access \meta{something} via |##1| and the
+ parameters of \meta{macro} as |#1|, |#2|, and so on.
+ \end{itemize}
+
+ In addition to the above keys, there exist also ``code macro versions'' of
+ them:
+ %
+ \begin{itemize}
+ \item |point macro=|\meta{some macro}. Causes |\pgfplotstreampoint| to
+ call \meta{some macro} directly (actually, |\pgf@plotstreampoint|
+ is set to be equal to \meta{some macro}). Inside the \meta{some
+ macro} you can use |#1| to access the coordinate passed to
+ |\pgfplotstreampoint| and you can no longer access the parameters
+ passed to the original call to \meta{macro} that installed the
+ handler. So, \meta{some macro} must take exactly one argument,
+ namely |#1|.
+ \item |special macro=|\meta{some macro}. As |point macro|, only for
+ specials.
+ \item |start macro=|\meta{some macro}. Causes \meta{some macro} to be
+ executed at the start. This macro, like the below ones, may not
+ take any parameters and will not have access to the parameters
+ passed to the original \meta{macro}.
+ \item |end macro=|\meta{some macro}. As above.
+ \item |jump macro=|\meta{some macro}. As above.
+ \end{itemize}
\end{command}