31 Quick Commands

This section explains the “quick” commands of PGF. These commands are executed more quickly than the normal commands of PGF, 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.

31.1 Quick Path Construction Commands

The difference between the quick and the normal path commands is that the quick path commands

do not keep track of the bounding boxes,
do not allow you to arc corners,
do not apply coordinate transformations.

However, they do use the soft-path subsystem (see Section 34 for details), which allows you to mix quick and normal path commands arbitrarily.

All quick path construction commands start with \pgfpathq.

\pgfpathqmoveto{<x dimension>}{<y dimension>}

Either starts a path or starts a new part of a path at the coordinate (<x dimension>,<y dimension>). The coordinate is not transformed by the current coordinate transformation matrix. However, any low-level transformations apply.

\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}

\pgfpathqlineto{<x dimension>}{<y dimension>}: The quick version of the line-to operation.

\pgfpathqcurveto{<s_x¹>}{<s_y¹>}{<s_x²>}{<s_y²>}{<t_x>}{<t_y>}

The quick version of the curve-to operation. The first support point is (s_x¹,s_y¹), the second support point is (s_x²,s_y²), and the target is (t_x,t_y).

\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgfpathqmoveto{0pt}{0pt}
  \pgfpathqcurveto{1cm}{1cm}{2cm}{1cm}{3cm}{0cm}
  \pgfusepath{stroke}
\end{tikzpicture}

\pgfpathqcircle{<radius>}

Adds a radius around the origin of the given <radius>. This command is orders of magnitude faster than \pgfcircle{\pgfpointorigin}{<radius>}.

\begin{tikzpicture}
  \draw[help lines] (0,0) grid (1,1);
  \pgfpathqcircle{10pt}
  \pgfsetfillcolor{examplefill}
  \pgfusepath{stroke,fill}
\end{tikzpicture}

31.2 Quick Path Usage Commands

The quick path usage commands perform similar tasks as \pgfusepath, but they

do not add arrows,
do not modify the path in any way, in particular,
ends are not shortened,
corners are not replaced by arcs.

Note that you 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.

\pgfusepathqstroke

Strokes the path without further ado. No arrows are drawn, no corners are arced.

\begin{pgfpicture}
\pgfpathqcircle{5pt}
\pgfusepathqstroke
\end{pgfpicture}

\pgfusepathqfill: Fills the path without further ado.

\pgfusepathqfillstroke: Fills and then strokes the path without further ado.

\pgfusepathqclip: Clips all subsequent drawings against the current path. The path is not processed.

31.3 Quick Text Box Commands

\pgfqbox{<box number>}: This command inserts a TEX box into a {pgfpicture} by “escaping” to TEX, inserting the box number <box number> at the origin, and then returning to the typesetting the picture.

\pgfqboxsynced{<box number>}

This command works similarly to the \pgfqbox command. However, before inserting the text in <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 <box number> is translated where it should), but the method used by \pgfqboxsynced ensures that hyperlinks are placed correctly. Note that scaling and rotation will not (cannot, even) apply to hyperlinks.

[prev] [prev-tail] [front] [up]