Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-plot-handlers.tex

raw
1 % Copyright 2018 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Plot Handler Library}
12 \label{section-library-plothandlers}
13
14 \begin{pgflibrary}{plothandlers}
15 This library packages defines additional plot handlers, see
16 Section~\ref{section-plot-handlers} for an introduction to plot handlers.
17 The additional handlers are described in the following.
18
19 This library is loaded automatically by \tikzname.
20 \end{pgflibrary}
21
22
23 \subsection{Curve Plot Handlers}
24
25 \begin{command}{\pgfplothandlercurveto}
26 This handler will issue a |\pgfpathcurveto| command for each point of the
27 plot, \emph{except} possibly for the first. As for the line-to handler,
28 what happens with the first point can be specified using
29 |\pgfsetmovetofirstplotpoint| or |\pgfsetlinetofirstplotpoint|.
30
31 Obviously, the |\pgfpathcurveto| command needs, in addition to the points
32 on the path, some control points. These are generated automatically using a
33 somewhat ``dumb'' algorithm: Suppose you have three points $x$, $y$, and
34 $z$ on the curve such that $y$ is between $x$ and $z$:
35 %
36 \begin{codeexample}[]
37 \begin{tikzpicture}
38 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
39 \pgfplothandlercurveto
40 \pgfplotstreamstart
41 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
42 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
43 \pgfplotstreampoint{\pgfpoint{2cm}{.5cm}}
44 \pgfplotstreamend
45 \pgfusepath{stroke}
46 \end{tikzpicture}
47 \end{codeexample}
48
49 In order to determine the control points of the curve at the point $y$, the
50 handler computes the vector $z-x$ and scales it by the tension factor (see
51 below). Let us call the resulting vector $s$. Then $y+s$ and $y-s$ will be
52 the control points around $y$. The first control point at the beginning of
53 the curve will be the beginning itself, once more; likewise the last
54 control point is the end itself.
55 \end{command}
56
57 \begin{command}{\pgfsetplottension\marg{value}}
58 Sets the factor used by the curve plot handlers to determine the distance
59 of the control points from the points they control. The higher the
60 curvature of the curve points, the higher this value should be. A value of
61 $1$ will cause four points at quarter positions of a circle to be connected
62 using a circle. The default is $0.5$.
63 %
64 \begin{codeexample}[]
65 \begin{tikzpicture}
66 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
67 \pgfsetplottension{0.75}
68 \pgfplothandlercurveto
69 \pgfplotstreamstart
70 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
71 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
72 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
73 \pgfplotstreamend
74 \pgfusepath{stroke}
75 \end{tikzpicture}
76 \end{codeexample}
77 %
78 \end{command}
79
80 \begin{command}{\pgfplothandlerclosedcurve}
81 This handler works like the curve-to plot handler, only it will add a new
82 part to the current path that is a closed curve through the plot points.
83 %
84 \begin{codeexample}[]
85 \begin{tikzpicture}
86 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
87 \pgfplothandlerclosedcurve
88 \pgfplotstreamstart
89 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
90 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
91 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
92 \pgfplotstreamend
93 \pgfusepath{stroke}
94 \end{tikzpicture}
95 \end{codeexample}
96 %
97 \end{command}
98
99
100 \subsection{Constant Plot Handlers}
101
102 There are several plot handlers which produce piecewise constant interpolations
103 between successive points:
104
105 \begin{command}{\pgfplothandlerconstantlineto}
106 This handler works like the line-to plot handler, only it will produce a
107 connected, piecewise constant path to connect the points.
108 %
109 \begin{codeexample}[]
110 \begin{tikzpicture}
111 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
112 \pgfplothandlerconstantlineto
113 \pgfplotstreamstart
114 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
115 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
116 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
117 \pgfplotstreamend
118 \pgfusepath{stroke}
119 \end{tikzpicture}
120 \end{codeexample}
121 %
122 \end{command}
123
124 \begin{command}{\pgfplothandlerconstantlinetomarkright}
125 A variant of |\pgfplothandlerconstantlineto| which places its mark on the
126 right line ends.
127 %
128 \begin{codeexample}[]
129 \begin{tikzpicture}
130 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
131 \pgfplothandlerconstantlinetomarkright
132 \pgfplotstreamstart
133 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
134 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
135 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
136 \pgfplotstreamend
137 \pgfusepath{stroke}
138 \end{tikzpicture}
139 \end{codeexample}
140 %
141 \end{command}
142
143 \begin{command}{\pgfplothandlerconstantlinetomarkmid}
144 A variant of |\pgfplothandlerconstantlineto| which places its mark on the
145 center of the line.
146 %
147 \begin{codeexample}[]
148 \begin{tikzpicture}
149 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
150 \pgfplothandlerconstantlinetomarkmid
151 \pgfplotstreamstart
152 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
153 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
154 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
155 \pgfplotstreamend
156 \pgfusepath{stroke}
157 \end{tikzpicture}
158 \end{codeexample}
159 %
160 The plot handler always connects two data points by a horizontal line
161 starting from the previous data points, followed by a vertical line in the
162 middle between the two data points, followed by a horizontal line between
163 the middle and the current data point. This results in a symmetric constant
164 plot handler for constant mesh width.
165 \end{command}
166
167 \begin{command}{\pgfplothandlerjumpmarkleft}
168 This handler works like the line-to plot handler, only it will produce a
169 non-connected, piecewise constant path to connect the points. If there are
170 any plot marks, they will be placed on the left open pieces.
171 %
172 \begin{codeexample}[]
173 \begin{tikzpicture}
174 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
175 \pgfplothandlerjumpmarkleft
176 \pgfplotstreamstart
177 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
178 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
179 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
180 \pgfplotstreamend
181 \pgfusepath{stroke}
182 \end{tikzpicture}
183 \end{codeexample}
184 %
185 \end{command}
186
187 \begin{command}{\pgfplothandlerjumpmarkright}
188 This handler works like the line-to plot handler, only it will produce a
189 non-connected, piecewise constant path to connect the points. If there are
190 any plot marks, they will be placed on the right open pieces.
191 %
192 \begin{codeexample}[]
193 \begin{tikzpicture}
194 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
195 \pgfplothandlerjumpmarkright
196 \pgfplotstreamstart
197 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
198 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
199 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
200 \pgfplotstreamend
201 \pgfusepath{stroke}
202 \end{tikzpicture}
203 \end{codeexample}
204 %
205 \end{command}
206
207 \begin{command}{\pgfplothandlerjumpmarkmid}
208 This handler works like the |\pgfplothandlerconstantlinetomarkmid|, but it
209 will produce a non-connected, piecewise constant path to connect the
210 points. If there are any plot marks, they will be placed in the center of
211 the horizontal line segment..
212 %
213 \begin{codeexample}[]
214 \begin{tikzpicture}
215 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
216 \pgfplothandlerjumpmarkmid
217 \pgfplotstreamstart
218 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
219 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
220 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
221 \pgfplotstreamend
222 \pgfusepath{stroke}
223 \end{tikzpicture}
224 \end{codeexample}
225 %
226 See |\pgfplothandlerconstantlinetomarkmid| for details.
227 \end{command}
228
229
230 \subsection{Comb Plot Handlers}
231
232 There are three ``comb'' plot handlers. Their name stems from the fact that the
233 plots they produce look like ``combs'' (more or less).
234
235 \begin{command}{\pgfplothandlerxcomb}
236 This handler converts each point in the plot stream into a line from the
237 $y$-axis to the point's coordinate, resulting in a ``horizontal comb''.
238 %
239 \begin{codeexample}[]
240 \begin{tikzpicture}
241 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
242 \pgfplothandlerxcomb
243 \pgfplotstreamstart
244 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
245 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
246 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
247 \pgfplotstreamend
248 \pgfusepath{stroke}
249 \end{tikzpicture}
250 \end{codeexample}
251 %
252 \end{command}
253
254 \begin{command}{\pgfplothandlerycomb}
255 This handler converts each point in the plot stream into a line from the
256 $x$-axis to the point's coordinate, resulting in a ``vertical comb''.
257
258 This handler is useful for creating ``bar diagrams''.
259 %
260 \begin{codeexample}[]
261 \begin{tikzpicture}
262 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
263 \pgfplothandlerycomb
264 \pgfplotstreamstart
265 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
266 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
267 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
268 \pgfplotstreamend
269 \pgfusepath{stroke}
270 \end{tikzpicture}
271 \end{codeexample}
272 %
273 \end{command}
274
275 \begin{command}{\pgfplothandlerpolarcomb}
276 This handler converts each point in the plot stream into a line from the
277 origin to the point's coordinate.
278 %
279 \begin{codeexample}[]
280 \begin{tikzpicture}
281 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
282 \pgfplothandlerpolarcomb
283 \pgfplotstreamstart
284 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
285 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
286 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
287 \pgfplotstreamend
288 \pgfusepath{stroke}
289 \end{tikzpicture}
290 \end{codeexample}
291 %
292 \end{command}
293
294 \pgfname\ bar or comb plots usually draw something from zero to the current
295 plot's coordinate. The ``zero'' offset can be changed using an input stream
296 which returns the desired offset successively for each processed coordinate.
297
298 There are two such streams, which can be configured independently. The first
299 one returns ``zeros'' for coordinate~$x$, the second one returns ``zeros'' for
300 coordinate~$y$. They are used as follows.
301 %
302 \begin{codeexample}[code only]
303 \pgfplotxzerolevelstreamstart
304 \pgfplotxzerolevelstreamnext % assigns \pgf@x
305 \pgfplotxzerolevelstreamnext
306 \pgfplotxzerolevelstreamnext
307 \pgfplotxzerolevelstreamend
308 \end{codeexample}
309 %
310 \begin{codeexample}[code only]
311 \pgfplotyzerolevelstreamstart
312 \pgfplotyzerolevelstreamnext % assigns \pgf@x
313 \pgfplotyzerolevelstreamend
314 \end{codeexample}
315 %
316 Different zero level streams can be implemented by overwriting these macros.
317
318 \begin{command}{\pgfplotxzerolevelstreamconstant\marg{dimension}}
319 This zero level stream always returns \marg{dimension} instead of $x=0$pt.
320
321 It is used for |xcomb| and |xbar|.
322 \end{command}
323
324 \begin{command}{\pgfplotyzerolevelstreamconstant\marg{dimension}}
325 This zero level stream always returns \marg{dimension} instead of $y=0$pt.
326
327 It is used for |ycomb| and |ybar|.
328 \end{command}
329
330
331 \subsection{Bar Plot Handlers}
332 \label{section-plotlib-bar-handlers}
333
334 While comb plot handlers produce a line-to operation to generate combs, bar
335 plot handlers employ rectangular shapes, allowing filled bars (or pattern
336 bars).
337
338 \begin{command}{\pgfplothandlerybar}
339 This handler converts each point in the plot stream into a rectangle from
340 the $x$-axis to the point's coordinate. The rectangle is placed centered at
341 the $x$-axis.
342 %
343 \begin{codeexample}[]
344 \begin{tikzpicture}
345 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
346 \pgfplothandlerybar
347 \pgfplotstreamstart
348 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
349 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
350 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
351 \pgfplotstreamend
352 \pgfusepath{stroke}
353 \end{tikzpicture}
354 \end{codeexample}
355 %
356 \end{command}
357
358 \begin{command}{\pgfplothandlerxbar}
359 This handler converts each point in the plot stream into a rectangle from
360 the $y$-axis to the point's coordinate. The rectangle is placed centered at
361 the $y$-axis.
362 %
363 \begin{codeexample}[]
364 \begin{tikzpicture}
365 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
366 \pgfplothandlerxbar
367 \pgfplotstreamstart
368 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
369 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
370 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
371 \pgfplotstreamend
372 \pgfusepath{stroke}
373 \end{tikzpicture}
374 \end{codeexample}
375 %
376 \end{command}
377
378 \label{key-bar-width}%
379 \begin{key}{/pgf/bar width=\marg{dimension} (initially 10pt)}
380 \keyalias{tikz}
381 Sets the width of |\pgfplothandlerxbar| and |\pgfplothandlerybar| to
382 \marg{dimension}. The argument \marg{dimension} will be evaluated using the
383 math parser.
384 \end{key}
385
386 \label{key-bar-shift}%
387 \begin{key}{/pgf/bar shift=\marg{dimension} (initially 0pt)}
388 \keyalias{tikz}
389 Sets a shift used by |\pgfplothandlerxbar| and |\pgfplothandlerybar| to
390 \marg{dimension}. It has the same effect as |xshift|, but it applies only
391 to those bar plots. The argument \marg{dimension} will be evaluated using
392 the math parser.
393 \end{key}
394
395 \begin{command}{\pgfplotbarwidth}
396 Expands to the value of |/pgf/bar width|.
397 \end{command}
398
399 \begin{command}{\pgfplothandlerybarinterval}
400 This handler is a variant of |\pgfplothandlerybar| which works with
401 intervals instead of points.
402
403 Bars are drawn between successive input coordinates and the width is
404 determined relatively to the interval length.
405 %
406 \begin{codeexample}[]
407 \begin{tikzpicture}
408 \draw[gray] (0,2) node {$x_1$} (1,1) node {$x_2$} (2,.5) node {$x_3$} (4,0.7) node {$x_4$};
409 \pgfplothandlerybarinterval
410 \pgfplotstreamstart
411 \pgfplotstreampoint{\pgfpoint{0cm}{2cm}}
412 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
413 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
414 \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}}
415 \pgfplotstreamend
416 \pgfusepath{stroke}
417 \end{tikzpicture}
418 \end{codeexample}
419
420 In more detail, if $(x_i,y_i)$ and $(x_{i+1},y_{i+1})$ denote successive
421 input coordinates, the bar will be placed above the interval
422 $[x_i,x_{i+1}]$, centered at
423 %
424 \[ x_i + \text{\meta{bar interval shift}} \cdot (x_{i+1} - x_i) \]
425 %
426 with width
427 %
428 \[ \text{\meta{bar interval width}} \cdot (x_{i+1} - x_i). \]
429 %
430 Here, \meta{bar interval shift} and \meta{bar interval width} denote the
431 current values of the associated options.
432
433 If you have $N+1$ input points, you will get $N$ bars (one for each
434 interval). The $y$~value of the last point will be ignored.
435 \end{command}
436
437 \begin{command}{\pgfplothandlerxbarinterval}
438 As |\pgfplothandlerybarinterval|, this handler provides bar plots with
439 relative bar sizes and offsets, one bar for each $y$~coordinate interval.
440 \end{command}
441
442 \begin{key}{/pgf/bar interval shift=\marg{factor} (initially 0.5)}
443 \label{key-bar-interval-shift}%
444 \keyalias{tikz}
445 Sets the \emph{relative} shift of |\pgfplothandlerxbarinterval| and
446 |\pgfplothandlerybarinterval| to \meta{factor}. As
447 |/pgf/bar interval width|, the argument is relative to the interval length
448 of the input coordinates.
449
450 The argument \marg{scale} will be evaluated using the math parser.
451 \end{key}
452
453 \begin{key}{/pgf/bar interval width=\marg{scale} (initially 1)}
454 \label{key-bar-interval-width}%
455 \keyalias{tikz}
456 Sets the \emph{relative} width of |\pgfplothandlerxbarinterval| and
457 |\pgfplothandlerybarinterval| to \marg{scale}. The argument is relative to
458 $(x_{i+1} - x_i)$ for $y$~bar plots and relative to $(y_{i+1}-y_i)$ for
459 $x$~bar plots.
460
461 The argument \marg{scale} will be evaluated using the math parser.
462 %
463 \begin{codeexample}[]
464 \begin{tikzpicture}[bar interval width=0.5]
465 \draw[gray]
466 (0,3) -- (0,-0.1)
467 (1,3) -- (1,-0.1)
468 (2,3) -- (2,-0.1)
469 (4,3) -- (4,-0.1);
470 \pgfplothandlerybarinterval
471 \begin{scope}[bar interval shift=0.25,fill=blue]
472 \pgfplotstreamstart
473 \pgfplotstreampoint{\pgfpoint{0cm}{2cm}}
474 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
475 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
476 \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}}
477 \pgfplotstreamend
478 \pgfusepath{fill}
479 \end{scope}
480 \begin{scope}[bar interval shift=0.75,fill=red]
481 \pgfplotstreamstart
482 \pgfplotstreampoint{\pgfpoint{0cm}{3cm}}
483 \pgfplotstreampoint{\pgfpoint{1cm}{0.2cm}}
484 \pgfplotstreampoint{\pgfpoint{2cm}{0.7cm}}
485 \pgfplotstreampoint{\pgfpoint{4cm}{0.2cm}}
486 \pgfplotstreamend
487 \pgfusepath{fill}
488 \end{scope}
489 \end{tikzpicture}
490 \end{codeexample}
491 %
492 Please note that bars are always centered, so we have to use shifts $0.25$
493 and $0.75$ instead of $0$ and $0.5$.
494 \end{key}
495
496
497 \subsection{Gapped Plot Handlers}
498 \label{section-plot-gapped}
499
500 \begin{command}{\pgfplothandlergaplineto}
501 This handler will connect the points of the plots by straight line
502 segments. However, at the start and the end of the lines there will be a
503 small gap, given by the following key:
504 %
505 \begin{key}{/pgf/gap around stream point=\meta{dimension} (initially 1.5pt)}
506 The \meta{dimension} by which the lines between consecutive stream
507 points are shortened at the beginning and end.
508 \end{key}
509 %
510 \begin{codeexample}[]
511 \begin{tikzpicture}
512 \pgfplothandlergaplineto
513 \pgfplotstreamstart
514 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
515 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
516 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
517 \pgfplotstreamend
518 \pgfusepath{stroke}
519 \end{tikzpicture}
520 \end{codeexample}
521 %
522 \end{command}
523
524 \begin{command}{\pgfplothandlergapcycle}
525 Works like |\pgfplothandlergaplineto|, but the last point is connected to
526 the first in the same fashion:
527 %
528 \begin{codeexample}[]
529 \begin{tikzpicture}
530 \pgfplothandlergapcycle
531 \pgfplotstreamstart
532 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
533 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
534 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
535 \pgfplotstreamend
536 \pgfusepath{stroke}
537 \end{tikzpicture}
538 \end{codeexample}
539 %
540 \end{command}
541
542
543 \subsection{Mark Plot Handler}
544 \label{section-plot-marks}
545
546 \begin{command}{\pgfplothandlermark\marg{mark code}}
547 This command will execute the \meta{mark code} for some points of the plot,
548 but each time the coordinate transformation matrix will be set up such that
549 the origin is at the position of the point to be plotted. This way, if the
550 \meta{mark code} draws a little circle around the origin, little circles
551 will be drawn at some point of the plot.
552
553 By default, a mark is drawn at all points of the plot. However, two
554 parameters $r$ and $p$ influence this. First, only every $r$th mark is
555 drawn. Second, the first mark drawn is the $p$th. These parameters can be
556 influenced using the commands below.
557 %
558 \begin{codeexample}[]
559 \begin{tikzpicture}
560 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
561 \pgfplothandlermark{\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}}
562 \pgfplotstreamstart
563 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
564 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
565 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
566 \pgfplotstreamend
567 \pgfusepath{stroke}
568 \end{tikzpicture}
569 \end{codeexample}
570
571 Typically, the \meta{code} will be |\pgfuseplotmark{|\meta{plot mark
572 name}|}|, where \meta{plot mark name} is the name of a predefined plot
573 mark.
574 \end{command}
575
576 \begin{command}{\pgfsetplotmarkrepeat\marg{repeat}}
577 Sets the $r$ parameter to \meta{repeat}, that is, only every $r$th mark
578 will be drawn.
579 \end{command}
580
581 \begin{command}{\pgfsetplotmarkphase\marg{phase}}
582 Sets the $p$ parameter to \meta{phase}, that is, the first mark to be drawn
583 is the $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so on.
584 \end{command}
585
586 \begin{command}{\pgfplothandlermarklisted\marg{mark code}\marg{index list}}
587 This command works similar to the previous one. However, marks will only be
588 placed at those indices in the given \meta{index list}. The syntax for the
589 list is the same as for the |\foreach| statement. For example, if you
590 provide the list |1,3,...,25|, a mark will be placed only at every second
591 point. Similarly, |1,2,4,8,16,32| yields marks only at those points that
592 are powers of two.
593 %
594 \begin{codeexample}[]
595 \begin{tikzpicture}
596 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
597 \pgfplothandlermarklisted
598 {\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}}
599 {1,3}
600 \pgfplotstreamstart
601 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
602 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
603 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
604 \pgfplotstreamend
605 \pgfusepath{stroke}
606 \end{tikzpicture}
607 \end{codeexample}
608 %
609 \end{command}
610
611 \begin{command}{\pgfuseplotmark\marg{plot mark name}}
612 Draws the given \meta{plot mark name} at the origin. The \meta{plot mark
613 name} must have been previously declared using |\pgfdeclareplotmark|.
614 %
615 \begin{codeexample}[]
616 \begin{tikzpicture}
617 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
618 \pgfplothandlermark{\pgfuseplotmark{pentagon}}
619 \pgfplotstreamstart
620 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
621 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
622 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
623 \pgfplotstreamend
624 \pgfusepath{stroke}
625 \end{tikzpicture}
626 \end{codeexample}
627 %
628 \end{command}
629
630 \begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}}
631 Declares a plot mark for later used with the |\pgfuseplotmark| command.
632 %
633 \begin{codeexample}[]
634 \pgfdeclareplotmark{my plot mark}
635 {\pgfpathcircle{\pgfpoint{0cm}{1ex}}{1ex}\pgfusepathqstroke}
636 \begin{tikzpicture}
637 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
638 \pgfplothandlermark{\pgfuseplotmark{my plot mark}}
639 \pgfplotstreamstart
640 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
641 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
642 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
643 \pgfplotstreamend
644 \pgfusepath{stroke}
645 \end{tikzpicture}
646 \end{codeexample}
647 %
648 \end{command}
649
650 \begin{command}{\pgfsetplotmarksize\marg{dimension}}
651 This command sets the \TeX\ dimension |\pgfplotmarksize| to
652 \meta{dimension}. This dimension is a ``recommendation'' for plot mark code
653 at which size the plot mark should be drawn; plot mark code may choose to
654 ignore this \meta{dimension} altogether. For circles, \meta{dimension}
655 should be the radius, for other shapes it should be about half the
656 width/height.
657
658 The predefined plot marks all take this dimension into account.
659 %
660 \begin{codeexample}[]
661 \begin{tikzpicture}
662 \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
663 \pgfsetplotmarksize{1ex}
664 \pgfplothandlermark{\pgfuseplotmark{*}}
665 \pgfplotstreamstart
666 \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
667 \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
668 \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
669 \pgfplotstreamend
670 \pgfusepath{stroke}
671 \end{tikzpicture}
672 \end{codeexample}
673 %
674 \end{command}
675
676 \begin{textoken}{\pgfplotmarksize}
677 A \TeX\ dimension that is a ``recommendation'' for the size of plot marks.
678 \end{textoken}
679
680 The following plot marks are predefined (the filling color has been set to
681 yellow):
682
683 \medskip
684 \begin{tabular}{lc}
685 \plotmarkentry{*}
686 \plotmarkentry{x}
687 \plotmarkentry{+}
688 \end{tabular}
689
690
691 %%% Local Variables:
692 %%% mode: latex
693 %%% TeX-master: "pgfmanual-pdftex-version"
694 %%% End: