% Copyright 2003 by Till Tantau . % % This program can be redistributed and/or modified under the terms % of the LaTeX Project Public License Distributed from CTAN % archives in directory macros/latex/base/lppl.txt. \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 protocoled 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 protocoled commands into the |.pdf| or |.dvi| file. Only those |\pgfsys@| commands can be protocolled that use the command |\pgfsysprotocol@literal| interally. 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: