1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
|
% 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{The Protocol Subsystem}
\label{section-protocols}
\makeatletter
This section describes commands for \emph{protocolling} literal text
created by \pgfname. The idea is that some literal text, like the string
of commands used to draw an arrow head, will be used over and over
again in a picture. It is then much more efficient to compute the
necessary literal text just once and to quickly insert it ``in a
single sweep.''
When protocolling is ``switched on,'' there is a ``current protocol''
to which literal text gets appended. Once all commands that needed to
be protocolled have been issued, the protocol can be obtained and
stored using |\pgfsysprotocol@getcurrentprotocol|. At any point, the
current protocol can be changed using a corresponding setting
command. Finally, |\pgfsysprotocol@invokecurrentprotocol| is used to
insert the protocolled commands into the |.pdf| or |.dvi| file.
Only those |\pgfsys@| commands can be protocolled that use the
command |\pgfsysprotocol@literal| internally. For example, the
definition of |\pgfsys@moveto| in |pgfsys-common-pdf.def| is
\begin{codeexample}[code only]
\def\pgfsys@moveto#1#2{\pgfsysprotocol@literal{#1 #2 m}}
\end{codeexample}
All ``normal'' system-level commands can be protocolled. However,
commands for creating or invoking shadings, images, or whole pictures
require special |\special|'s and cannot be protocolled.
\begin{command}{\pgfsysprotocol@literalbuffered\marg{literal text}}
Adds the \meta{literal text} to the current protocol, after it has
been ``|\edef|ed.'' This command will always protocol.
\end{command}
\begin{command}{\pgfsysprotocol@literal\marg{literal text}}
First calls |\pgfsysprotocol@literalbuffered| on \meta{literal
text}. Then, if protocolling is currently switched off, the
\meta{literal text} is passed on to |\pgfsys@invoke|.
\end{command}
\begin{command}{\pgfsysprotocol@bufferedtrue}
Turns on protocolling. All subsequent calls of
|\pgfsysprotocol@literal| will append their argument to the current
protocol.
\end{command}
\begin{command}{\pgfsysprotocol@bufferedfalse}
Turns off protocolling. Subsequent calls of
|\pgfsysprotocol@literal| directly insert their argument into the
current |.pdf| or |.ps|.
Note that if the current protocol is not empty when protocolling is
switched off, the next call to |\pgfsysprotocol@literal| will first
flush the current protocol, that is, insert it into the file.
\end{command}
\begin{command}{\pgfsysprotocol@getcurrentprotocol\marg{macro name}}
Stores the current protocol in \meta{macro name} for later use.
\end{command}
\begin{command}{\pgfsysprotocol@setcurrentprotocol\marg{macro name}}
Sets the current protocol to \meta{macro name}.
\end{command}
\begin{command}{\pgfsysprotocol@invokecurrentprotocol}
Inserts the text stored in the current protocol into the |.pdf| or
|.dvi| file. This does \emph{not} change the current protocol.
\end{command}
\begin{command}{\pgfsysprotocol@flushcurrentprotocol}
First inserts the current protocol, then sets the current protocol
to the empty string.
\end{command}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End:
|
