summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex
blob: c7f762bef6c4bf843003788bfa3eb4332094b83f (plain)
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
% 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{Quick Commands}

This section explains the ``quick'' commands of \pgfname. These
commands are executed more quickly than the normal commands of
\pgfname, but offer less functionality. You should use these commands
only if you either have a very large number of commands that need to
be processed or if you expect your commands to be executed very often.


\subsection{Quick Coordinate Commands}

\begin{command}{\pgfqpoint\marg{x}\marg{y}}
  This command does the same as |\pgfpoint|, but \meta{x} and \meta{y}
  must be simple dimensions like |1pt| or |1cm|. Things like |2ex| or
  |2cm+1pt| are not allowed.
\end{command}

\begin{command}{\pgfqpointxy\marg{$s_x$}\marg{$s_y$}}
  This command does the same as |\pgfpointxy|, but \meta{$s_x$} and \meta{$s_y$}
  must be simple numbers without unit, like |1.234| or |5.0|. Mathematical expressions or units are not allowed.
\end{command}

\begin{command}{\pgfqpointxyz\marg{$s_x$}\marg{$s_y$}\marg{$s_z$}}
  As |\pgfqpointxy|, but for three-dimensional coordinates. Any argument needs to be a number without unit.
\end{command}

\begin{command}{\pgfqpointscale\marg{factor}\marg{coordinate}}
	As |\pgfpointscale|, but \marg{factor} must be a simple number without unit, as for the other ``quick'' commands.
\end{command}

\subsection{Quick Path Construction Commands}

The difference between the quick and the normal path commands is that
the quick path commands
\begin{itemize}
\item
  do not keep track of the bounding boxes,
\item
  do not allow you to arc corners,
\item
  do not apply coordinate transformations.
\end{itemize}

However, they do use the soft-path subsystem (see
Section~\ref{section-soft-paths} for details), which allows you to mix
quick and normal path commands arbitrarily.

All quick path construction commands start with |\pgfpathq|.

\begin{command}{\pgfpathqmoveto\marg{x dimension}\marg{y dimension}}
  Either starts a path or starts a new part of a path at the coordinate
  $(\meta{x dimension},\meta{y dimension})$. The coordinate is
  \emph{not} transformed by the current coordinate transformation
  matrix. However, any low-level transformations apply.

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgftransformxshift{1cm}
  \pgfpathqmoveto{0pt}{0pt} % not transformed
  \pgfpathqlineto{1cm}{1cm} % not transformed
  \pgfpathlineto{\pgfpoint{2cm}{0cm}}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfpathqlineto\marg{x dimension}\marg{y dimension}}
  The quick version of the line-to operation.
\end{command}

\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$}}
  The quick version of the curve-to operation. The first support point
  is $(s^1_x,s^1_y)$, the second support point is  $(s^2_x,s^2_y)$,
  and the target is $(t_x,t_y)$.
 
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgfpathqmoveto{0pt}{0pt}
  \pgfpathqcurveto{1cm}{1cm}{2cm}{1cm}{3cm}{0cm}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfpathqcircle\marg{radius}}
  Adds a radius around the origin of the given \meta{radius}. This
  command is orders of magnitude faster than
  |\pgfcircle{\pgfpointorigin}{|\meta{radius}|}|. 
 
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (1,1);
  \pgfpathqcircle{10pt}
  \pgfsetfillcolor{examplefill}
  \pgfusepath{stroke,fill}
\end{tikzpicture}
\end{codeexample}
\end{command}



\subsection{Quick Path Usage Commands}

The quick path usage commands perform similar tasks as |\pgfusepath|,
but they
\begin{itemize}
\item
  do not add arrows,
\item
  do not modify the path in any way, in particular,
\item
  ends are not shortened,
\item
  corners are not replaced by arcs.
\end{itemize}

Note that you \emph{have to} use the quick versions in the code of
arrow tip definitions since, inside these definition, you obviously do
not want arrows to be drawn.

\begin{command}{\pgfusepathqstroke}
  Strokes the path without further ado. No arrows are drawn, no
  corners are arced.

\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathqcircle{5pt}
  \pgfusepathqstroke
\end{pgfpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfusepathqfill}
  Fills the path without further ado.
\end{command}

\begin{command}{\pgfusepathqfillstroke}
  Fills and then strokes the path without further ado.
\end{command}

\begin{command}{\pgfusepathqclip}
  Clips all subsequent drawings against the current path. The path is
  not processed.
\end{command}


\subsection{Quick Text Box Commands}

\begin{command}{\pgfqbox\marg{box number}}
  This command inserts a \TeX\ box into a |{pgfpicture}| by
  ``escaping'' to \TeX, inserting the box number \meta{box number} at
  the origin, and then returning to the typesetting the picture.
\end{command}

\begin{command}{\pgfqboxsynced\marg{box number}}
  This command works similarly to the |\pgfqbox| command. However,
  before inserting the text in \meta{box number}, the current
  coordinate transformation matrix is applied to the current canvas
  transformation matrix (is it ``synced'' with this matrix, hence the
  name).

  Thus, this command basically has the same effect as if you first
  called |\pgflowlevelsynccm| followed by |\pgfqbox|. However, this
  command will use |\hskip| and |\raise| commands for the
  ``translational part'' of the coordinate transformation matrix,
  instead of adding the translational part to the current
  canvas transformation matrix directly. Both methods have the same
  effect (box \meta{box number} is translated to where it should be), but
  the method used by |\pgfqboxsynced| ensures that hyperlinks are
  placed correctly. Note that scaling and rotation will not (cannot,
  even) apply to hyperlinks.
\end{command}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End: