| 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{Using Paths} |
| 12 |
|
| 13 |
\subsection{Overview} |
| 14 |
|
| 15 |
Once a path has been constructed, it can be \emph{used} in different ways. For |
| 16 |
example, you can draw the path or fill it or use it for clipping. |
| 17 |
|
| 18 |
Numerous graph parameters influence how a path will be rendered. For example, |
| 19 |
when you draw a path, the line width is important as well as the dashing |
| 20 |
pattern. The options that govern how paths are rendered can all be set with |
| 21 |
commands starting with |\pgfset|. \emph{All options that influence how a path |
| 22 |
is rendered always influence the complete path.} Thus, it is not possible to |
| 23 |
draw part of a path using, say, a red color and drawing another part using a |
| 24 |
green color. To achieve such an effect, you must use two paths. |
| 25 |
|
| 26 |
In detail, paths can be used in the following ways: |
| 27 |
% |
| 28 |
\begin{enumerate} |
| 29 |
\item You can \emph{stroke} (also known as \emph{draw}) a path. |
| 30 |
\item You can add \emph{arrow tips} to a path. |
| 31 |
\item You can \emph{fill} a path with a uniform color. |
| 32 |
\item You can \emph{clip} subsequent renderings against the path. |
| 33 |
\item You can \emph{shade} a path. |
| 34 |
\item You can \emph{use the path as bounding box} for the whole picture. |
| 35 |
\end{enumerate} |
| 36 |
% |
| 37 |
You can also perform any combination of the above, though it makes no sense to |
| 38 |
fill and shade a path at the same time. |
| 39 |
|
| 40 |
To perform (a combination of) the first four actions, you can use the following |
| 41 |
command: |
| 42 |
% |
| 43 |
\begin{command}{\pgfusepath\marg{actions}} |
| 44 |
Applies the given \meta{actions} to the current path. Afterwards, the |
| 45 |
current path is (globally) empty. The following actions are possible: |
| 46 |
% |
| 47 |
\begin{itemize} |
| 48 |
\item \declare{|fill|} fills the path. See Section~\ref{section-fill} |
| 49 |
for further details. |
| 50 |
% |
| 51 |
\begin{codeexample}[] |
| 52 |
\begin{pgfpicture} |
| 53 |
\pgfpathmoveto{\pgfpointorigin} |
| 54 |
\pgfpathlineto{\pgfpoint{1cm}{1cm}} |
| 55 |
\pgfpathlineto{\pgfpoint{1cm}{0cm}} |
| 56 |
\pgfusepath{fill} |
| 57 |
\end{pgfpicture} |
| 58 |
\end{codeexample} |
| 59 |
% |
| 60 |
\item \declare{|stroke|} strokes the path. See |
| 61 |
Section~\ref{section-stroke} for further details. |
| 62 |
% |
| 63 |
\begin{codeexample}[] |
| 64 |
\begin{pgfpicture} |
| 65 |
\pgfpathmoveto{\pgfpointorigin} |
| 66 |
\pgfpathlineto{\pgfpoint{1cm}{1cm}} |
| 67 |
\pgfpathlineto{\pgfpoint{1cm}{0cm}} |
| 68 |
\pgfusepath{stroke} |
| 69 |
\end{pgfpicture} |
| 70 |
\end{codeexample} |
| 71 |
% |
| 72 |
\item \declare{|draw|} has the same effect as |stroke|. |
| 73 |
\item \declare{|clip|} clips all subsequent drawings against the path. |
| 74 |
Always suppresses arrow tips. See Section~\ref{section-clip} for |
| 75 |
further details. |
| 76 |
% |
| 77 |
\begin{codeexample}[] |
| 78 |
\begin{pgfpicture} |
| 79 |
\pgfpathmoveto{\pgfpointorigin} |
| 80 |
\pgfpathlineto{\pgfpoint{1cm}{1cm}} |
| 81 |
\pgfpathlineto{\pgfpoint{1cm}{0cm}} |
| 82 |
\pgfusepath{stroke,clip} |
| 83 |
\pgfpathcircle{\pgfpoint{1cm}{1cm}}{0.5cm} |
| 84 |
\pgfusepath{fill} |
| 85 |
\end{pgfpicture} |
| 86 |
\end{codeexample} |
| 87 |
% |
| 88 |
\item \declare{|discard|} discards the path, that is, it is not used at |
| 89 |
all. Giving this option (alone) has the same effect as giving an |
| 90 |
empty options list. |
| 91 |
\end{itemize} |
| 92 |
% |
| 93 |
When more than one of the first three actions are given, they are applied |
| 94 |
in the above ordering, regardless of their ordering in \meta{actions}. |
| 95 |
Thus, |{stroke,fill}| and |{fill,stroke}| have the same effect. |
| 96 |
\end{command} |
| 97 |
|
| 98 |
To shade a path, use the |\pgfshadepath| command, which is explained in |
| 99 |
Section~\ref{section-shadings}. |
| 100 |
|
| 101 |
|
| 102 |
\subsection{Stroking a Path} |
| 103 |
\label{section-stroke} |
| 104 |
|
| 105 |
When you use |\pgfusepath{stroke}| to stroke a path, several graphic parameters |
| 106 |
influence how the path is drawn. The commands for setting these parameters are |
| 107 |
explained in the following. |
| 108 |
|
| 109 |
Note that all graphic parameters apply to the path as a whole, never only to a |
| 110 |
part of it. |
| 111 |
|
| 112 |
All graphic parameters are local to the current |{pgfscope}|, but they persists |
| 113 |
past \TeX\ groups, \emph{except} for the interior rule (even-odd or nonzero) |
| 114 |
and the arrow tip kinds. The latter graphic parameters only persist till the |
| 115 |
end of the current \TeX\ group, but this may change in the future, so do not |
| 116 |
count on this. |
| 117 |
|
| 118 |
|
| 119 |
\subsubsection{Graphic Parameter: Line Width} |
| 120 |
|
| 121 |
\begin{command}{\pgfsetlinewidth\marg{line width}} |
| 122 |
This command sets the line width for subsequent strokes (in the current |
| 123 |
|pgfscope|). The line width is given as a normal \TeX\ dimension like |
| 124 |
|0.4pt| or |1mm|. |
| 125 |
% |
| 126 |
\begin{codeexample}[] |
| 127 |
\begin{pgfpicture} |
| 128 |
\pgfsetlinewidth{1mm} |
| 129 |
\pgfpathmoveto{\pgfpoint{0mm}{0mm}} |
| 130 |
\pgfpathlineto{\pgfpoint{2cm}{0mm}} |
| 131 |
\pgfusepath{stroke} |
| 132 |
\pgfsetlinewidth{2\pgflinewidth} % double in size |
| 133 |
\pgfpathmoveto{\pgfpoint{0mm}{5mm}} |
| 134 |
\pgfpathlineto{\pgfpoint{2cm}{5mm}} |
| 135 |
\pgfusepath{stroke} |
| 136 |
\end{pgfpicture} |
| 137 |
\end{codeexample} |
| 138 |
% |
| 139 |
\end{command} |
| 140 |
|
| 141 |
\begin{textoken}{\pgflinewidth} |
| 142 |
You can access the current line width via the \TeX\ dimension |
| 143 |
|\pgflinewidth|. It will be set to the correct line width, that is, even |
| 144 |
when a \TeX\ group closed, the value will be correct since it is set |
| 145 |
globally, but when a |{pgfscope}| closes, the value is set to the correct |
| 146 |
value it had before the scope. |
| 147 |
\end{textoken} |
| 148 |
|
| 149 |
|
| 150 |
\subsubsection{Graphic Parameter: Caps and Joins} |
| 151 |
|
| 152 |
\begin{command}{\pgfsetbuttcap} |
| 153 |
Sets the line cap to a butt cap. See Section~\ref{section-cap-joins} for an |
| 154 |
explanation of what this is. |
| 155 |
\end{command} |
| 156 |
% |
| 157 |
\begin{command}{\pgfsetroundcap} |
| 158 |
Sets the line cap to a round cap. See again Section~\ref{section-cap-joins}. |
| 159 |
\end{command} |
| 160 |
\begin{command}{\pgfsetrectcap} |
| 161 |
Sets the line cap to a square cap. See again Section~\ref{section-cap-joins}. |
| 162 |
\end{command} |
| 163 |
% |
| 164 |
\begin{command}{\pgfsetroundjoin} |
| 165 |
Sets the line join to a round join. See again Section~\ref{section-cap-joins}. |
| 166 |
\end{command} |
| 167 |
% |
| 168 |
\begin{command}{\pgfsetbeveljoin} |
| 169 |
Sets the line join to a bevel join. See again Section~\ref{section-cap-joins}. |
| 170 |
\end{command} |
| 171 |
% |
| 172 |
\begin{command}{\pgfsetmiterjoin} |
| 173 |
Sets the line join to a miter join. See again Section~\ref{section-cap-joins}. |
| 174 |
\end{command} |
| 175 |
% |
| 176 |
\begin{command}{\pgfsetmiterlimit\marg{miter limit factor}} |
| 177 |
Sets the miter limit to \meta{miter limit factor}. See again |
| 178 |
Section~\ref{section-cap-joins}. |
| 179 |
\end{command} |
| 180 |
|
| 181 |
|
| 182 |
\subsubsection{Graphic Parameter: Dashing} |
| 183 |
|
| 184 |
\begin{command}{\pgfsetdash\marg{list of even length of dimensions}\marg{phase}} |
| 185 |
Sets the dashing of a line. The first entry in the list specifies the |
| 186 |
length of the first solid part of the list. The second entry specifies the |
| 187 |
length of the following gap. Then comes the length of the second solid |
| 188 |
part, following by the length of the second gap, and so on. The |
| 189 |
\meta{phase} specifies where the first solid part starts relative to the |
| 190 |
beginning of the line. |
| 191 |
% |
| 192 |
\begin{codeexample}[] |
| 193 |
\begin{pgfpicture} |
| 194 |
\pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0cm} |
| 195 |
\pgfpathmoveto{\pgfpoint{0mm}{0mm}} |
| 196 |
\pgfpathlineto{\pgfpoint{2cm}{0mm}} |
| 197 |
\pgfusepath{stroke} |
| 198 |
\pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.1cm} |
| 199 |
\pgfpathmoveto{\pgfpoint{0mm}{1mm}} |
| 200 |
\pgfpathlineto{\pgfpoint{2cm}{1mm}} |
| 201 |
\pgfusepath{stroke} |
| 202 |
\pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.2cm} |
| 203 |
\pgfpathmoveto{\pgfpoint{0mm}{2mm}} |
| 204 |
\pgfpathlineto{\pgfpoint{2cm}{2mm}} |
| 205 |
\pgfusepath{stroke} |
| 206 |
\end{pgfpicture} |
| 207 |
\end{codeexample} |
| 208 |
|
| 209 |
Use |\pgfsetdash{}{0pt}| to get a solid dashing. |
| 210 |
\end{command} |
| 211 |
|
| 212 |
|
| 213 |
\subsubsection{Graphic Parameter: Stroke Color} |
| 214 |
|
| 215 |
\begin{command}{\pgfsetstrokecolor\marg{color}} |
| 216 |
Sets the color used for stroking lines to \meta{color}, where \meta{color} |
| 217 |
is a \LaTeX\ color like |red| or |black!20!red|. Unlike the |\color| |
| 218 |
command, the effect of this command lasts till the end of the current |
| 219 |
|{pgfscope}| and not till the end of the current \TeX\ group. |
| 220 |
|
| 221 |
The color used for stroking may be different from the color used for |
| 222 |
filling. However, a |\color| command will always ``immediately override'' |
| 223 |
any special settings for the stroke and fill colors. |
| 224 |
|
| 225 |
In plain \TeX, this command will also work, but the problem of |
| 226 |
\emph{defining} a color arises. After all, plain \TeX\ does not provide |
| 227 |
\LaTeX\ colors. For this reason, \pgfname\ implements a minimalistic |
| 228 |
``emulation'' of the |\definecolor|, |\colorlet|, and |\color| commands. |
| 229 |
Only gray-scale and rgb colors are supported. For most cases this turns out |
| 230 |
to be enough. |
| 231 |
% |
| 232 |
\begin{codeexample}[] |
| 233 |
\begin{pgfpicture} |
| 234 |
\pgfsetlinewidth{1pt} |
| 235 |
\color{red} |
| 236 |
\pgfpathcircle{\pgfpoint{0cm}{0cm}}{3mm} \pgfusepath{fill,stroke} |
| 237 |
\pgfsetstrokecolor{black} |
| 238 |
\pgfpathcircle{\pgfpoint{1cm}{0cm}}{3mm} \pgfusepath{fill,stroke} |
| 239 |
\color{red} |
| 240 |
\pgfpathcircle{\pgfpoint{2cm}{0cm}}{3mm} \pgfusepath{fill,stroke} |
| 241 |
\end{pgfpicture} |
| 242 |
\end{codeexample} |
| 243 |
% |
| 244 |
\end{command} |
| 245 |
|
| 246 |
\begin{command}{\pgfsetcolor\marg{color}} |
| 247 |
Sets both the stroke and fill color. The difference to the normal |\color| |
| 248 |
command is that the effect lasts till the end of the current |{pgfscope}|, |
| 249 |
not only till the end of the current \TeX\ group. |
| 250 |
\end{command} |
| 251 |
|
| 252 |
|
| 253 |
\subsubsection{Graphic Parameter: Stroke Opacity} |
| 254 |
|
| 255 |
You can set the stroke opacity using |\pgfsetstrokeopacity|. This command is |
| 256 |
described in Section~\ref{section-transparency}. |
| 257 |
|
| 258 |
|
| 259 |
\subsubsection{Inner Lines} |
| 260 |
|
| 261 |
When a path is stroked, it is possible to request that it is stroked twice, the |
| 262 |
second time with a different line width and a different color. This is a useful |
| 263 |
effect for creating ``double'' lines, for instance by setting the line width to |
| 264 |
2pt and stroking a black line and then setting the inner line width to 1pt and |
| 265 |
stroking a white line on the same path as the original path. This results in |
| 266 |
what looks like two lines, each of thickness 0.5pt, spaced 1pt apart. |
| 267 |
|
| 268 |
You may wonder why there is direct support for this ``double stroking'' in the |
| 269 |
basic layer. After all, this effect is easy to achieve ``by hand''. The main |
| 270 |
reason is that arrow tips must be treated in a special manner when such |
| 271 |
``double lines'' are present. First, the order of actions is important: First, |
| 272 |
the (thick) main line should be stroked, then the (thin) inner line, and only |
| 273 |
then should the arrow tip be drawn. Second, the way an arrow tip looks |
| 274 |
typically depends strongly on the width of the inner line, so the arrow tip |
| 275 |
code, which is part of the basic layer, needs access to the inner line |
| 276 |
thickness. |
| 277 |
|
| 278 |
Two commands are used to set the inner line width and color. |
| 279 |
|
| 280 |
\begin{command}{\pgfsetinnerlinewidth\marg{dimension}} |
| 281 |
This command sets the width of the inner line. Whenever a path is stroked |
| 282 |
(and only then), it will be stroked normally and, afterward, it is stroked |
| 283 |
once more with the color set to the inner line color and the line width set |
| 284 |
to \meta{dimension}. |
| 285 |
|
| 286 |
In case arrow tips are added to a path, the path is first stroked normally, |
| 287 |
then the inner line is stroked, and then the arrow tip is added. In case |
| 288 |
the main path is shortened because of the added arrow tip, this shortened |
| 289 |
path is double stroked, not the original path (which is exactly what you |
| 290 |
want). |
| 291 |
|
| 292 |
When the inner line width is set to 0pt, which is the default, no inner |
| 293 |
line is stroked at all (not even a line of width 0pt). So, in order to |
| 294 |
``switch off'' double stroking, set \meta{dimension} to~|0pt|. |
| 295 |
|
| 296 |
The setting of the inner line width is local to the current \TeX\ group and |
| 297 |
\emph{not} to the current \pgfname\ scope. |
| 298 |
|
| 299 |
Note that inner lines will \emph{not} be drawn for paths that are also used |
| 300 |
for clipping. However, this may change in the future, so you should not |
| 301 |
depend on this. |
| 302 |
% |
| 303 |
\begin{codeexample}[] |
| 304 |
\begin{pgfpicture} |
| 305 |
\pgfpathmoveto{\pgfpointorigin} |
| 306 |
\pgfpathlineto{\pgfpoint{1cm}{1cm}} |
| 307 |
\pgfpathlineto{\pgfpoint{1cm}{0cm}} |
| 308 |
\pgfsetlinewidth{2pt} |
| 309 |
\pgfsetinnerlinewidth{1pt} |
| 310 |
\pgfusepath{stroke} |
| 311 |
\end{pgfpicture} |
| 312 |
\end{codeexample} |
| 313 |
% |
| 314 |
\end{command} |
| 315 |
|
| 316 |
\begin{command}{\pgfsetinnerstrokecolor\marg{color}} |
| 317 |
This command sets the \meta{color} that is to be used when the inner line |
| 318 |
is stroked. The effect of this command is also local to the current \TeX\ |
| 319 |
group. |
| 320 |
% |
| 321 |
\begin{codeexample}[] |
| 322 |
\begin{pgfpicture} |
| 323 |
\pgfpathmoveto{\pgfpointorigin} |
| 324 |
\pgfpathlineto{\pgfpoint{1cm}{1cm}} |
| 325 |
\pgfpathlineto{\pgfpoint{1cm}{0cm}} |
| 326 |
\pgfsetlinewidth{2pt} |
| 327 |
\pgfsetinnerlinewidth{1pt} |
| 328 |
\pgfsetinnerstrokecolor{red!50} |
| 329 |
\pgfusepath{stroke} |
| 330 |
\end{pgfpicture} |
| 331 |
\end{codeexample} |
| 332 |
% |
| 333 |
\end{command} |
| 334 |
|
| 335 |
|
| 336 |
\subsection{Arrow Tips on a Path} |
| 337 |
\label{section-tips} |
| 338 |
|
| 339 |
After a path has been drawn, \pgfname\ can add arrow tips at the ends, |
| 340 |
depending on how the |tips| key is set, on whether |stroke| or |clip| are used |
| 341 |
and on whether the path contains closed subpaths. The exact rules when arrow |
| 342 |
tips are added are explained in Section~\ref{section-arrow-tips-where}. |
| 343 |
|
| 344 |
\begin{command}{\pgfsetarrowsstart\marg{start arrow tip specification}} |
| 345 |
Sets the arrow tip kind used at the start of a (possibly curved) path. The |
| 346 |
syntax of the \meta{start arrow specification} is detailed in |
| 347 |
Section~\ref{section-arrow-spec}. |
| 348 |
|
| 349 |
To ``clear'' the start arrow, say |\pgfsetarrowsstart{}|. |
| 350 |
% |
| 351 |
\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}] |
| 352 |
\begin{pgfpicture} |
| 353 |
\pgfsetarrowsstart{Latex[length=10pt]} |
| 354 |
\pgfpathmoveto{\pgfpointorigin} |
| 355 |
\pgfpathlineto{\pgfpoint{1cm}{0cm}} |
| 356 |
\pgfusepath{stroke} |
| 357 |
\pgfsetarrowsstart{Computer Modern Rightarrow} |
| 358 |
\pgfpathmoveto{\pgfpoint{0cm}{2mm}} |
| 359 |
\pgfpathlineto{\pgfpoint{1cm}{2mm}} |
| 360 |
\pgfusepath{stroke} |
| 361 |
\end{pgfpicture} |
| 362 |
\end{codeexample} |
| 363 |
|
| 364 |
The effect of this command persists only till the end of the current \TeX\ |
| 365 |
scope. |
| 366 |
\end{command} |
| 367 |
|
| 368 |
\begin{command}{\pgfsetarrowsend\marg{end arrow tip specification}} |
| 369 |
Sets the arrow tip kind used at the end of a path. |
| 370 |
% |
| 371 |
\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}] |
| 372 |
\begin{pgfpicture} |
| 373 |
\pgfsetarrowsstart{Latex[length=10pt]} |
| 374 |
\pgfsetarrowsend{Computer Modern Rightarrow} |
| 375 |
\pgfpathmoveto{\pgfpointorigin} |
| 376 |
\pgfpathlineto{\pgfpoint{1cm}{0cm}} |
| 377 |
\pgfusepath{stroke} |
| 378 |
\end{pgfpicture} |
| 379 |
\end{codeexample} |
| 380 |
% |
| 381 |
\end{command} |
| 382 |
|
| 383 |
\begin{command}{\pgfsetarrows\marg{argument}} |
| 384 |
The \meta{argument} can be of the form \meta{start arrow tip |
| 385 |
specification}|-|\meta{end arrow tip specification}. In this case, both the |
| 386 |
start and the end arrow specification are set: |
| 387 |
% |
| 388 |
\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}] |
| 389 |
\begin{pgfpicture} |
| 390 |
\pgfsetarrows{Latex[length=10pt]->>} |
| 391 |
\pgfpathmoveto{\pgfpointorigin} |
| 392 |
\pgfpathlineto{\pgfpoint{1cm}{0cm}} |
| 393 |
\pgfusepath{stroke} |
| 394 |
\end{pgfpicture} |
| 395 |
\end{codeexample} |
| 396 |
% |
| 397 |
Alternatively, \meta{argument} can be of the form |[|\meta{arrow keys}|]|. |
| 398 |
In this case, the \meta{arrow keys} will be set for all arrow tips in the |
| 399 |
current scope, see Section~\ref{section-arrow-scopes}. |
| 400 |
\end{command} |
| 401 |
|
| 402 |
\begin{command}{\pgfsetshortenstart\marg{dimension}} |
| 403 |
This command will shortened the start of every stroked path by the given |
| 404 |
dimension. This shortening is done in addition to automatic shortening done |
| 405 |
by a start arrow, but it can be used even if no start arrow is given. |
| 406 |
|
| 407 |
It is usually better to use the |sep| key with arrow tips. |
| 408 |
|
| 409 |
This command is useful if you wish arrows or lines to ``stop shortly |
| 410 |
before'' a given point. |
| 411 |
% |
| 412 |
\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}] |
| 413 |
\begin{pgfpicture} |
| 414 |
\pgfpathcircle{\pgfpointorigin}{5mm} |
| 415 |
\pgfusepath{stroke} |
| 416 |
\pgfsetarrows{Latex-} |
| 417 |
\pgfsetshortenstart{4pt} |
| 418 |
\pgfpathmoveto{\pgfpoint{5mm}{0cm}} % would be on the circle |
| 419 |
\pgfpathlineto{\pgfpoint{2cm}{0cm}} |
| 420 |
\pgfusepath{stroke} |
| 421 |
\end{pgfpicture} |
| 422 |
\end{codeexample} |
| 423 |
% |
| 424 |
\end{command} |
| 425 |
|
| 426 |
\begin{command}{\pgfsetshortenend\marg{dimension}} |
| 427 |
Works like |\pgfsetshortenstart|. |
| 428 |
\end{command} |
| 429 |
|
| 430 |
|
| 431 |
\subsection{Filling a Path} |
| 432 |
\label{section-fill} |
| 433 |
|
| 434 |
Filling a path means coloring every interior point of the path with the current |
| 435 |
fill color. It is not always obvious whether a point is ``inside'' a path when |
| 436 |
the path is self-intersecting and/or consists or multiple parts. In this case |
| 437 |
either the nonzero winding number rule or the even-odd crossing number rule is |
| 438 |
used to decide which points lie ``inside''. These rules are explained in |
| 439 |
Section~\ref{section-rules}. |
| 440 |
|
| 441 |
|
| 442 |
\subsubsection{Graphic Parameter: Interior Rule} |
| 443 |
|
| 444 |
You can set which rule is used using the following commands: |
| 445 |
|
| 446 |
\begin{command}{\pgfseteorule} |
| 447 |
Dictates that the even-odd rule is used in subsequent fillings in the |
| 448 |
current \emph{\TeX\ scope}. Thus, for once, the effect of this command does |
| 449 |
not persist past the current \TeX\ scope. |
| 450 |
% |
| 451 |
\begin{codeexample}[] |
| 452 |
\begin{pgfpicture} |
| 453 |
\pgfseteorule |
| 454 |
\pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} |
| 455 |
\pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} |
| 456 |
\pgfusepath{fill} |
| 457 |
\end{pgfpicture} |
| 458 |
\end{codeexample} |
| 459 |
% |
| 460 |
\end{command} |
| 461 |
|
| 462 |
\begin{command}{\pgfsetnonzerorule} |
| 463 |
Dictates that the nonzero winding number rule is used in subsequent |
| 464 |
fillings in the current \TeX\ scope. This is the default. |
| 465 |
% |
| 466 |
\begin{codeexample}[] |
| 467 |
\begin{pgfpicture} |
| 468 |
\pgfsetnonzerorule |
| 469 |
\pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} |
| 470 |
\pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} |
| 471 |
\pgfusepath{fill} |
| 472 |
\end{pgfpicture} |
| 473 |
\end{codeexample} |
| 474 |
% |
| 475 |
\end{command} |
| 476 |
|
| 477 |
|
| 478 |
\subsubsection{Graphic Parameter: Filling Color} |
| 479 |
|
| 480 |
\begin{command}{\pgfsetfillcolor\marg{color}} |
| 481 |
Sets the color used for filling paths to \meta{color}. Like the stroke |
| 482 |
color, the effect lasts only till the next use of |\color|. |
| 483 |
\end{command} |
| 484 |
|
| 485 |
|
| 486 |
\subsubsection{Graphic Parameter: Fill Opacity} |
| 487 |
|
| 488 |
You can set the fill opacity using |\pgfsetfillopacity|. This command is |
| 489 |
described in Section~\ref{section-transparency}. |
| 490 |
|
| 491 |
|
| 492 |
\subsection{Clipping a Path} |
| 493 |
\label{section-clip} |
| 494 |
|
| 495 |
When you add the |clip| option, the current path is used for clipping |
| 496 |
subsequent drawings. The same rule as for filling is used to decide whether a |
| 497 |
point is inside or outside the path, that is, either the even-odd rule or the |
| 498 |
nonzero rule. |
| 499 |
|
| 500 |
Clipping never enlarges the clipping area. Thus, when you clip against a |
| 501 |
certain path and then clip again against another path, you clip against the |
| 502 |
intersection of both. |
| 503 |
|
| 504 |
The only way to enlarge the clipping path is to end the |{pgfscope}| in which |
| 505 |
the clipping was done. At the end of a |{pgfscope}| the clipping path that was |
| 506 |
in force at the beginning of the scope is reinstalled. |
| 507 |
|
| 508 |
|
| 509 |
\subsection{Using a Path as a Bounding Box} |
| 510 |
\label{section-using-bb} |
| 511 |
|
| 512 |
When you add the |use as bounding box| option, the bounding box of the picture |
| 513 |
will be enlarged such that the path in encompassed, but any \emph{subsequent} |
| 514 |
paths of the current \TeX\ scope will not have any effect on the size of the |
| 515 |
bounding box. Typically, you use this command at the very beginning of a |
| 516 |
|{pgfpicture}| environment. Alternatively, you can use |\pgfresetboundingbox|, |
| 517 |
followed by |\pgfusepath{use as bounding box}| to overrule the picture's |
| 518 |
bounding box completely. |
| 519 |
% |
| 520 |
\begin{codeexample}[] |
| 521 |
Left |
| 522 |
\begin{pgfpicture} |
| 523 |
\pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} |
| 524 |
\pgfusepath{use as bounding box} % draws nothing |
| 525 |
|
| 526 |
\pgfpathcircle{\pgfpointorigin}{2ex} |
| 527 |
\pgfusepath{stroke} |
| 528 |
\end{pgfpicture} |
| 529 |
right. |
| 530 |
\end{codeexample} |