Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-quick.tex

raw
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: