| 1 |
% Copyright 2019 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{Quick Commands} |
| 12 |
|
| 13 |
This section explains the ``quick'' commands of \pgfname. These commands are |
| 14 |
executed more quickly than the normal commands of \pgfname, but offer less |
| 15 |
functionality. You should use these commands only if you either have a very |
| 16 |
large number of commands that need to be processed or if you expect your |
| 17 |
commands to be executed very often. |
| 18 |
|
| 19 |
|
| 20 |
\subsection{Quick Coordinate Commands} |
| 21 |
|
| 22 |
\begin{command}{\pgfqpoint\marg{x}\marg{y}} |
| 23 |
This command does the same as |\pgfpoint|, but \meta{x} and \meta{y} must |
| 24 |
be simple dimensions like |1pt| or |1cm|. Things like |2ex| or |2cm+1pt| |
| 25 |
are not allowed. |
| 26 |
\end{command} |
| 27 |
|
| 28 |
\begin{command}{\pgfqpointxy\marg{$s_x$}\marg{$s_y$}} |
| 29 |
This command does the same as |\pgfpointxy|, but \meta{$s_x$} and |
| 30 |
\meta{$s_y$} must be simple numbers without unit, like |1.234| or |5.0|. |
| 31 |
Mathematical expressions or units are not allowed. |
| 32 |
\end{command} |
| 33 |
|
| 34 |
\begin{command}{\pgfqpointxyz\marg{$s_x$}\marg{$s_y$}\marg{$s_z$}} |
| 35 |
As |\pgfqpointxy|, but for three-dimensional coordinates. Any argument |
| 36 |
needs to be a number without unit. |
| 37 |
\end{command} |
| 38 |
|
| 39 |
\begin{command}{\pgfqpointscale\marg{factor}\marg{coordinate}} |
| 40 |
As |\pgfpointscale|, but \marg{factor} must be a simple number without |
| 41 |
unit, as for the other ``quick'' commands. |
| 42 |
\end{command} |
| 43 |
|
| 44 |
|
| 45 |
\subsection{Quick Path Construction Commands} |
| 46 |
|
| 47 |
The difference between the quick and the normal path commands is that the quick |
| 48 |
path commands |
| 49 |
% |
| 50 |
\begin{itemize} |
| 51 |
\item do not keep track of the bounding boxes, |
| 52 |
\item do not allow you to arc corners, |
| 53 |
\item do not apply coordinate transformations. |
| 54 |
\end{itemize} |
| 55 |
|
| 56 |
However, they do use the soft-path subsystem (see |
| 57 |
Section~\ref{section-soft-paths} for details), which allows you to mix quick |
| 58 |
and normal path commands arbitrarily. |
| 59 |
|
| 60 |
All quick path construction commands start with |\pgfpathq|. |
| 61 |
|
| 62 |
\begin{command}{\pgfpathqmoveto\marg{x dimension}\marg{y dimension}} |
| 63 |
Either starts a path or starts a new part of a path at the coordinate |
| 64 |
$(\meta{x dimension},\meta{y dimension})$. The coordinate is \emph{not} |
| 65 |
transformed by the current coordinate transformation matrix. However, any |
| 66 |
low-level transformations apply. |
| 67 |
% |
| 68 |
\begin{codeexample}[] |
| 69 |
\begin{tikzpicture} |
| 70 |
\draw[help lines] (0,0) grid (3,2); |
| 71 |
\pgftransformxshift{1cm} |
| 72 |
\pgfpathqmoveto{0pt}{0pt} % not transformed |
| 73 |
\pgfpathqlineto{1cm}{1cm} % not transformed |
| 74 |
\pgfpathlineto{\pgfpoint{2cm}{0cm}} |
| 75 |
\pgfusepath{stroke} |
| 76 |
\end{tikzpicture} |
| 77 |
\end{codeexample} |
| 78 |
% |
| 79 |
\end{command} |
| 80 |
|
| 81 |
\begin{command}{\pgfpathqlineto\marg{x dimension}\marg{y dimension}} |
| 82 |
The quick version of the line-to operation. |
| 83 |
\end{command} |
| 84 |
|
| 85 |
\begin{command}{\pgfpathqcurveto\marg{$s^1_x$}\marg{$s^1_y$}\marg{$s^2_x$}\marg{$s^2_y$}\marg{$t_x$}\marg{$t_y$}} |
| 86 |
The quick version of the curve-to operation. The first support point is |
| 87 |
$(s^1_x,s^1_y)$, the second support point is $(s^2_x,s^2_y)$, and the |
| 88 |
target is $(t_x,t_y)$. |
| 89 |
% |
| 90 |
\begin{codeexample}[] |
| 91 |
\begin{tikzpicture} |
| 92 |
\draw[help lines] (0,0) grid (3,2); |
| 93 |
\pgfpathqmoveto{0pt}{0pt} |
| 94 |
\pgfpathqcurveto{1cm}{1cm}{2cm}{1cm}{3cm}{0cm} |
| 95 |
\pgfusepath{stroke} |
| 96 |
\end{tikzpicture} |
| 97 |
\end{codeexample} |
| 98 |
% |
| 99 |
\end{command} |
| 100 |
|
| 101 |
\begin{command}{\pgfpathqcircle\marg{radius}} |
| 102 |
Adds a radius around the origin of the given \meta{radius}. This command is |
| 103 |
orders of magnitude faster than |\pgfpathcircle{\pgfpointorigin}{|\meta{radius}|}|. |
| 104 |
% |
| 105 |
\begin{codeexample}[] |
| 106 |
\colorlet{examplefill}{yellow!80!black} |
| 107 |
\begin{tikzpicture} |
| 108 |
\draw[help lines] (0,0) grid (1,1); |
| 109 |
\pgfpathqcircle{10pt} |
| 110 |
\pgfsetfillcolor{examplefill} |
| 111 |
\pgfusepath{stroke,fill} |
| 112 |
\end{tikzpicture} |
| 113 |
\end{codeexample} |
| 114 |
% |
| 115 |
\end{command} |
| 116 |
|
| 117 |
|
| 118 |
\subsection{Quick Path Usage Commands} |
| 119 |
|
| 120 |
The quick path usage commands perform similar tasks as |\pgfusepath|, but they |
| 121 |
% |
| 122 |
\begin{itemize} |
| 123 |
\item do not add arrows, |
| 124 |
\item do not modify the path in any way, in particular, |
| 125 |
\item ends are not shortened, |
| 126 |
\item corners are not replaced by arcs. |
| 127 |
\end{itemize} |
| 128 |
|
| 129 |
Note that you \emph{have to} use the quick versions in the code of arrow tip |
| 130 |
definitions since, inside these definition, you obviously do not want arrows to |
| 131 |
be drawn. |
| 132 |
|
| 133 |
\begin{command}{\pgfusepathqstroke} |
| 134 |
Strokes the path without further ado. No arrows are drawn, no corners are |
| 135 |
arced. |
| 136 |
% |
| 137 |
\begin{codeexample}[] |
| 138 |
\begin{pgfpicture} |
| 139 |
\pgfpathqcircle{5pt} |
| 140 |
\pgfusepathqstroke |
| 141 |
\end{pgfpicture} |
| 142 |
\end{codeexample} |
| 143 |
% |
| 144 |
\end{command} |
| 145 |
|
| 146 |
\begin{command}{\pgfusepathqfill} |
| 147 |
Fills the path without further ado. |
| 148 |
\end{command} |
| 149 |
|
| 150 |
\begin{command}{\pgfusepathqfillstroke} |
| 151 |
Fills and then strokes the path without further ado. |
| 152 |
\end{command} |
| 153 |
|
| 154 |
\begin{command}{\pgfusepathqclip} |
| 155 |
Clips all subsequent drawings against the current path. The path is not |
| 156 |
processed. |
| 157 |
\end{command} |
| 158 |
|
| 159 |
|
| 160 |
\subsection{Quick Text Box Commands} |
| 161 |
|
| 162 |
\begin{command}{\pgfqbox\marg{box number}} |
| 163 |
This command inserts a \TeX\ box into a |{pgfpicture}| by ``escaping'' to |
| 164 |
\TeX, inserting the box number \meta{box number} at the origin, and then |
| 165 |
returning to the typesetting the picture. |
| 166 |
\end{command} |
| 167 |
|
| 168 |
\begin{command}{\pgfqboxsynced\marg{box number}} |
| 169 |
This command works similarly to the |\pgfqbox| command. However, before |
| 170 |
inserting the text in \meta{box number}, the current coordinate |
| 171 |
transformation matrix is applied to the current canvas transformation |
| 172 |
matrix (is it ``synced'' with this matrix, hence the name). |
| 173 |
|
| 174 |
Thus, this command basically has the same effect as if you first called |
| 175 |
|\pgflowlevelsynccm| followed by |\pgfqbox|. However, this command will use |
| 176 |
|\hskip| and |\raise| commands for the ``translational part'' of the |
| 177 |
coordinate transformation matrix, instead of adding the translational part |
| 178 |
to the current canvas transformation matrix directly. Both methods have the |
| 179 |
same effect (box \meta{box number} is translated to where it should be), |
| 180 |
but the method used by |\pgfqboxsynced| ensures that hyperlinks are placed |
| 181 |
correctly. Note that scaling and rotation will not (cannot, even) apply to |
| 182 |
hyperlinks. |
| 183 |
\end{command} |
| 184 |
|
| 185 |
|
| 186 |
%%% Local Variables: |
| 187 |
%%% mode: latex |
| 188 |
%%% TeX-master: "pgfmanual" |
| 189 |
%%% End: |