| 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{Pics: Small Pictures on Paths} |
| 12 |
\label{section-pics} |
| 13 |
|
| 14 |
\subsection{Overview} |
| 15 |
|
| 16 |
A ``pic'' is a ``short picture'' (hence the short name\dots) that can be |
| 17 |
inserted anywhere in \tikzname\ picture where you could also insert a node. |
| 18 |
Similarly to nodes, pics have a ``shape'' (called \emph{type} to avoid |
| 19 |
confusion) that someone has defined. Each time a pic of a specified type is |
| 20 |
used, the type's code is executed, resulting in some drawings to be added to |
| 21 |
the current picture. The syntax for adding nodes and adding pics to a picture |
| 22 |
are also very similar. The core difference is that pics are typically more |
| 23 |
complex than nodes and may consist of a whole bunch of nodes themselves |
| 24 |
together with complex paths joining them. |
| 25 |
|
| 26 |
As a very simple example, suppose we want to define a pic type |seagull| that |
| 27 |
just draw ``two bumps''. The code for this definition is quite easy: |
| 28 |
% |
| 29 |
\begin{codeexample}[code only] |
| 30 |
\tikzset{ |
| 31 |
seagull/.pic={ |
| 32 |
% Code for a "seagull". Do you see it?... |
| 33 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 34 |
} |
| 35 |
} |
| 36 |
\end{codeexample} |
| 37 |
|
| 38 |
The first line just tells \TeX\ that you set some \tikzname\ options for the |
| 39 |
current scope (which is the whole document); you could put |seagull/.pic=...| |
| 40 |
anywhere else where \tikzname\ options are allowed (which is just about |
| 41 |
anywhere). We have now defined a |seagull| pic type and can use it as follows: |
| 42 |
% |
| 43 |
\tikzset{ |
| 44 |
seagull/.pic={ |
| 45 |
% Code for a "seagull". Do you see it?... |
| 46 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 47 |
} |
| 48 |
} |
| 49 |
\begin{codeexample}[ |
| 50 |
pre={\tikzset{ |
| 51 |
seagull/.pic={ |
| 52 |
% Code for a "seagull". Do you see it?... |
| 53 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 54 |
}, |
| 55 |
}}] |
| 56 |
\tikz \fill [fill=blue!20] |
| 57 |
(1,1) |
| 58 |
-- (2,2) pic {seagull} |
| 59 |
-- (3,2) pic {seagull} |
| 60 |
-- (3,1) pic [rotate=30] {seagull} |
| 61 |
-- (2,1) pic [red] {seagull}; |
| 62 |
\end{codeexample} |
| 63 |
|
| 64 |
As can be see, defining new types of pics is much easier than defining new |
| 65 |
shapes for nodes; but see Section~\ref{section-new-pic-types} for the fine |
| 66 |
details. |
| 67 |
|
| 68 |
Since defining new pics types is easier than defining new node shapes and since |
| 69 |
using pics is as easy as using nodes, why should you use nodes at all? There |
| 70 |
are chiefly two reasons: |
| 71 |
% |
| 72 |
\begin{enumerate} |
| 73 |
\item Unlike nodes, pics cannot be referenced later on. You \emph{can} |
| 74 |
reference nodes that are inside a pic, but not ``the pic itself''. In |
| 75 |
particular, you cannot draw lines between pics the way you can draw |
| 76 |
them between nodes. In general, whenever it makes sense that some |
| 77 |
drawing could conceivably be connected to other node-like-things, then |
| 78 |
a node is better than a pic. |
| 79 |
\item If pics are used to emulate the full power of a node (which is |
| 80 |
possible, in principle), they will be slower to construct and take up |
| 81 |
more memory than a node achieving the same effect. |
| 82 |
\end{enumerate} |
| 83 |
|
| 84 |
Despite these drawbacks, pics are an excellent choice for creating highly |
| 85 |
configurable reusable pieces of drawings that can be inserted into larger |
| 86 |
contexts. |
| 87 |
|
| 88 |
|
| 89 |
\subsection{The Pic Syntax} |
| 90 |
|
| 91 |
\begin{command}{\pic} |
| 92 |
Inside |{tikzpicture}| this is an abbreviation for |\path pic|. |
| 93 |
\end{command} |
| 94 |
|
| 95 |
The syntax for adding a pic to a picture is very similar to the syntax used for |
| 96 |
nodes (indeed, internally the same parser code is used). The main difference is |
| 97 |
that instead of a node contents you provide the picture's type between the |
| 98 |
braces: |
| 99 |
|
| 100 |
\begin{pathoperation}{pic}{ |
| 101 |
\opt{\meta{foreach statements}} |
| 102 |
\opt{|[|\meta{options}|]|} |
| 103 |
\opt{|(|\meta{prefix}|)|} |
| 104 |
\opt{|at(|\meta{coordinate}|)|} |
| 105 |
\opt{|:|\meta{animation attribute}|=|\marg{options}} |
| 106 |
\opt{\marg{pic type}}% |
| 107 |
} |
| 108 |
Adds a pic to the current \tikzname\ picture of the specified \meta{pic |
| 109 |
type}. The effect is, basically, that some code associated with the |
| 110 |
\meta{pic type} is executed (how this works, exactly, is explained later). |
| 111 |
This code can consist of arbitrary \tikzname\ code. As for nodes, the |
| 112 |
current path will not be modified by this path command, all drawings |
| 113 |
produced by the code are ``external'' to the path the same way neither a |
| 114 |
node nor its border are part of the path on which they are specified. |
| 115 |
|
| 116 |
Just like the |node| command, this path operation is somewhat complex and |
| 117 |
we go over it step by step. |
| 118 |
|
| 119 |
\medskip |
| 120 |
\textbf{Order of the parts of the specification.} |
| 121 |
Just like for nodes, everything between ``|pic|'' and the opening brace of |
| 122 |
the \meta{pic type} is optional and can be given in any order. If there are |
| 123 |
\meta{foreach statements}, they must come first, directly following |
| 124 |
``|pic|''. As for nodes, the ``end'' of the pic specification is normally |
| 125 |
detected by the presence of the opening brace. You can, however, use the |
| 126 |
|pic type| option to specify the pic type as an option. |
| 127 |
|
| 128 |
\begin{key}{/tikz/pic type=\meta{pic type}} |
| 129 |
This key sets the pic type of the current~|pic|. When this option is |
| 130 |
used inside an option block of a |pic|, the parsing of the |pic| ends |
| 131 |
immediately and no pic type in braces is expected. (In other words, |
| 132 |
this option behaves exactly like the |node contents| option and, |
| 133 |
indeed, the two are interchangeable.) |
| 134 |
% |
| 135 |
\begin{codeexample}[ |
| 136 |
pre={\tikzset{ |
| 137 |
seagull/.pic={ |
| 138 |
% Code for a "seagull". Do you see it?... |
| 139 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 140 |
}, |
| 141 |
}}] |
| 142 |
\tikz { |
| 143 |
\path (0,0) pic [pic type = seagull] |
| 144 |
(1,0) pic {seagull}; |
| 145 |
} |
| 146 |
\end{codeexample} |
| 147 |
\end{key} |
| 148 |
|
| 149 |
\medskip |
| 150 |
\textbf{The location of a pic.} |
| 151 |
Just like nodes, pics are placed at the last position mentioned on the path |
| 152 |
or, when |at| is used, at a specified position. ``Placing'' a pic somewhere |
| 153 |
actually means that the coordinate system is translated (shifted) to this |
| 154 |
last position. This means that inside of the pic type's code any mentioning |
| 155 |
of the origin refers to the last position used on the path or to the |
| 156 |
specified |at|. |
| 157 |
% |
| 158 |
\begin{codeexample}[ |
| 159 |
pre={\tikzset{ |
| 160 |
seagull/.pic={ |
| 161 |
% Code for a "seagull". Do you see it?... |
| 162 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 163 |
}, |
| 164 |
}}] |
| 165 |
\tikz { % different ways of placing pics |
| 166 |
\draw [help lines] (0,0) grid (3,2); |
| 167 |
\pic at (1,0) {seagull}; |
| 168 |
\path (2,1) pic {seagull}; |
| 169 |
\pic [at={(3,2)}] {seagull}; |
| 170 |
} |
| 171 |
\end{codeexample} |
| 172 |
|
| 173 |
As for nodes, except for the described shifting, the coordinate system of a |
| 174 |
pic is reset prior to executing the pic type's code. This can be changed |
| 175 |
using the |transform shape| option, which has the same effect as for nodes: |
| 176 |
The ``outer'' transformation gets applied to the node: |
| 177 |
% |
| 178 |
\begin{codeexample}[ |
| 179 |
pre={\tikzset{ |
| 180 |
seagull/.pic={ |
| 181 |
% Code for a "seagull". Do you see it?... |
| 182 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 183 |
}, |
| 184 |
}}] |
| 185 |
\tikz [scale=2] { |
| 186 |
\pic at (0,0) {seagull}; |
| 187 |
\pic at (1,0) [transform shape] {seagull}; |
| 188 |
} |
| 189 |
\end{codeexample} |
| 190 |
|
| 191 |
When the \meta{options} contain transformation commands like |scale| or |
| 192 |
|rotate|, these transformations always apply to the pic: |
| 193 |
% |
| 194 |
\begin{codeexample}[ |
| 195 |
pre={\tikzset{ |
| 196 |
seagull/.pic={ |
| 197 |
% Code for a "seagull". Do you see it?... |
| 198 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 199 |
}, |
| 200 |
}}] |
| 201 |
\tikz [rotate=30] { |
| 202 |
\pic at (0,0) {seagull}; |
| 203 |
\pic at (1,0) [rotate=90] {seagull}; |
| 204 |
} |
| 205 |
\end{codeexample} |
| 206 |
|
| 207 |
Just like nodes, pics can also be positioned implicitly and, somewhat |
| 208 |
unsurprisingly, the same rules concerning positioning and sloping apply: |
| 209 |
% |
| 210 |
\begin{codeexample}[ |
| 211 |
pre={\tikzset{ |
| 212 |
seagull/.pic={ |
| 213 |
% Code for a "seagull". Do you see it?... |
| 214 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 215 |
}, |
| 216 |
}}] |
| 217 |
\tikz \draw |
| 218 |
(0,0) to [bend left] |
| 219 |
pic [near start] {seagull} |
| 220 |
pic {seagull} |
| 221 |
pic [sloped, near end] {seagull} (4,0); |
| 222 |
\end{codeexample} |
| 223 |
|
| 224 |
\medskip |
| 225 |
\textbf{The options of a node.} |
| 226 |
As always, any given \meta{options} apply only to the pic and have no |
| 227 |
effect outside. As for nodes, most ``outside'' options also apply to the |
| 228 |
pics, but not the ``action'' options like |draw| or |fill|. These must be |
| 229 |
given in the \meta{options} of the pic. |
| 230 |
|
| 231 |
\medskip |
| 232 |
\textbf{The code of a pic.} |
| 233 |
As stated earlier, the main job of a pic is to execute some code in a scope |
| 234 |
that is shifted according to the last point on the path or to the |at| |
| 235 |
position specified in the pic. It was also claimed that this code is |
| 236 |
specified by the \meta{pic type}. However, this specification is somewhat |
| 237 |
indirect. What really happens is the following: When a |pic| is |
| 238 |
encountered, the current path is suspended and a new internal scope is |
| 239 |
started. The \meta{options} are executed and also the \meta{pic type} (as |
| 240 |
explained in a moment). After all this is done, the code stored in the |
| 241 |
following key gets executed: |
| 242 |
|
| 243 |
\begin{key}{/tikz/pics/code=\meta{code}} |
| 244 |
This key stores the \meta{code} that should be drawn in the current |
| 245 |
pic. Normally, setting this key is done by the \meta{pic type}, but you |
| 246 |
can also set it in the \meta{options} and leave the \meta{pic type} |
| 247 |
empty: |
| 248 |
% |
| 249 |
\begin{codeexample}[] |
| 250 |
\tikz \pic [pics/code={\draw (-3mm,0) to[bend left] (0,0) |
| 251 |
to[bend left] (3mm,0);}] |
| 252 |
{}; % no pic type specified |
| 253 |
\end{codeexample} |
| 254 |
\end{key} |
| 255 |
|
| 256 |
Now, how does the \meta{pic type} set |pics/code|? It turns out that the |
| 257 |
\meta{pic type} is actually just a list of keys that are executed with the |
| 258 |
prefix |/tikz/pics/|. In the above examples, this ``list of keys'' just |
| 259 |
consisted of the single key ``|seagull|'' that did not take any arguments, |
| 260 |
but, in principle, you could provide any arbitrary text understood by |
| 261 |
|\pgfkeys| here. This means that when we write |pic{seagull}|, \tikzname\ |
| 262 |
will execute the key |/tikz/pics/seagull|. It turns out, see |
| 263 |
Section~\ref{section-new-pic-types}, that this key is just a style set to |
| 264 |
|code={\draw(-3mm,0)...;}|. Thus, |pic{seagull}| will cause the |pics/code| |
| 265 |
key to be set to the text needed to draw the |
| 266 |
seagull. |
| 267 |
|
| 268 |
Indeed, you can also use the \meta{pic type} simply to set the |code| of |
| 269 |
the pic. This is useful for cases when you have some code that you ``just |
| 270 |
want to execute, but do not want to define a new pic type''. Here is a |
| 271 |
typical example where we use pics to add some markings to a path: |
| 272 |
% |
| 273 |
\begin{codeexample}[] |
| 274 |
\tikz \draw (0,0) .. controls(1,0) and (2,1) .. (3,1) |
| 275 |
foreach \t in {0, 0.125, ..., 1} { |
| 276 |
pic [pos=\t] {code={\draw circle [radius=2pt];}} |
| 277 |
}; |
| 278 |
\end{codeexample} |
| 279 |
|
| 280 |
In our seagull example, we always explicitly used |\draw| to draw the |
| 281 |
seagull. This implies that when a user writes something |
| 282 |
|pic[fill]{seagull}| in the hope of having a ``filled'' seagull, nothing |
| 283 |
special will happen: The |\draw| inside the pic explicitly states that the |
| 284 |
path should be drawn, not filled, and the fact that in the surrounding |
| 285 |
scope the |fill| option is set has no effect. The following key can be used |
| 286 |
to change this: |
| 287 |
% |
| 288 |
\begin{key}{/tikz/pic actions} |
| 289 |
This key is a style that can be used (only) inside the code of a pic. |
| 290 |
There, it will set the ``action'' keys set inside the \meta{options} of |
| 291 |
the pic (``actions'' are drawing, filling, shading, and clipping or any |
| 292 |
combination thereof). |
| 293 |
|
| 294 |
To see how this key works, let us define the following pic: |
| 295 |
% |
| 296 |
\begin{codeexample}[code only] |
| 297 |
\tikzset{ |
| 298 |
my pic/.pic = { |
| 299 |
\path [pic actions] (0,0) circle[radius=3mm]; |
| 300 |
\draw (-3mm,-3mm) rectangle (3mm,3mm); |
| 301 |
} |
| 302 |
} |
| 303 |
\end{codeexample} |
| 304 |
% |
| 305 |
In the code, whether or not the circle gets drawn/filled/shaded |
| 306 |
depends on which options where given to the |pic| command when it |
| 307 |
is used. In contrast, the rectangle will always (just) be drawn. |
| 308 |
% |
| 309 |
\tikzset{ |
| 310 |
my pic/.pic = { |
| 311 |
\path [pic actions] (0,0) circle[radius=3mm]; |
| 312 |
\draw (-3mm,-3mm) rectangle (3mm,3mm); |
| 313 |
} |
| 314 |
} |
| 315 |
\begin{codeexample}[ |
| 316 |
width=6cm, |
| 317 |
pre={\tikzset{ |
| 318 |
my pic/.pic = { |
| 319 |
\path [pic actions] (0,0) circle[radius=3mm]; |
| 320 |
\draw (-3mm,-3mm) rectangle (3mm,3mm); |
| 321 |
} |
| 322 |
}}] |
| 323 |
\tikz \pic {my pic}; \space |
| 324 |
\tikz \pic [red] {my pic}; \space |
| 325 |
\tikz \pic [draw] {my pic}; \space |
| 326 |
\tikz \pic [draw=red] {my pic}; \space |
| 327 |
\tikz \pic [draw, shading=ball] {my pic}; \space |
| 328 |
\tikz \pic [fill=red!50] {my pic}; |
| 329 |
\end{codeexample} |
| 330 |
\end{key} |
| 331 |
|
| 332 |
\medskip |
| 333 |
\textbf{Code executed behind or in front of the path.} |
| 334 |
As for nodes, a pic can be ``behind'' the current path or ``in front of |
| 335 |
it'' and, just as for nodes, the two options |behind path| and |
| 336 |
|in front of path| are used to specify which is meant. In detail, if |node| |
| 337 |
and |pic| are both used repeatedly on a path, in the resulting picture we |
| 338 |
first see all nodes and pics with the |behind path| option set in the order |
| 339 |
they appear on the path (nodes and pics are interchangeable in this |
| 340 |
regard), then comes the path, and then come all nodes and pics that are in |
| 341 |
front of the path in the order they appeared. |
| 342 |
% |
| 343 |
\begin{codeexample}[ |
| 344 |
pre={\tikzset{ |
| 345 |
seagull/.pic={ |
| 346 |
% Code for a "seagull". Do you see it?... |
| 347 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 348 |
}, |
| 349 |
}}] |
| 350 |
\tikz \fill [fill=blue!20] |
| 351 |
(1,1) |
| 352 |
-- (2,2) pic [behind path] {seagull} |
| 353 |
-- (3,2) pic {seagull} |
| 354 |
-- (3,1) pic [rotate=30] {seagull} |
| 355 |
-- (2,1) pic [red, behind path] {seagull}; |
| 356 |
\end{codeexample} |
| 357 |
% |
| 358 |
In contrast to nodes, a pic need not only be completely behind the path or |
| 359 |
in front of the path as specified by the user. Instead, a pic type may also |
| 360 |
specify that a certain part of the drawing should always be behind the path |
| 361 |
and it may specify that a certain other part should always be before the |
| 362 |
path. For this, the values of the following keys are relevant: |
| 363 |
|
| 364 |
\begin{key}{/tikz/pics/foreground code=\meta{code}} |
| 365 |
This key stores \meta{code} that will always be drawn in front of the |
| 366 |
current path, even when |behind path| is used. If |behind path| is not |
| 367 |
used and |code| is (also) set, the code of |code| is drawn first, |
| 368 |
following by the foreground \meta{code}. |
| 369 |
\end{key} |
| 370 |
|
| 371 |
\begin{key}{/tikz/pics/background code=\meta{code}} |
| 372 |
Like |foreground code|, only that the \meta{code} is always put behind |
| 373 |
the path, except when the |behind path| option is applied to the pic, |
| 374 |
then the background code is drawn in front of the ``behind path'' code. |
| 375 |
\end{key} |
| 376 |
|
| 377 |
\medskip |
| 378 |
\textbf{The foreach statement for pics.} |
| 379 |
As for nodes, a pic specification may start with |foreach|. The effect and |
| 380 |
semantics are the same as for nodes. |
| 381 |
% |
| 382 |
\begin{codeexample}[ |
| 383 |
pre={\tikzset{ |
| 384 |
seagull/.pic={ |
| 385 |
% Code for a "seagull". Do you see it?... |
| 386 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 387 |
}, |
| 388 |
}}] |
| 389 |
\tikz \pic foreach \x in {1,2,3} at (\x,0) {seagull}; |
| 390 |
\end{codeexample} |
| 391 |
|
| 392 |
\medskip |
| 393 |
\textbf{Styles for pics.} |
| 394 |
The following styles influence how nodes are rendered: |
| 395 |
% |
| 396 |
\begin{stylekey}{/tikz/every pic (initially \normalfont empty)} |
| 397 |
This style is installed at the beginning of every pic. |
| 398 |
% |
| 399 |
\begin{codeexample}[ |
| 400 |
pre={\tikzset{ |
| 401 |
seagull/.pic={ |
| 402 |
% Code for a "seagull". Do you see it?... |
| 403 |
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); |
| 404 |
}, |
| 405 |
}}] |
| 406 |
\begin{tikzpicture}[every pic/.style={scale=2,transform shape}] |
| 407 |
\pic foreach \x in {1,2,3} at (\x,0) {seagull}; |
| 408 |
\end{tikzpicture} |
| 409 |
\end{codeexample} |
| 410 |
\end{stylekey} |
| 411 |
|
| 412 |
\medskip |
| 413 |
\textbf{Name scopes.} |
| 414 |
You can specify a \meta{name} for a pic using the key |name=|\meta{name} or |
| 415 |
by giving the name in parenthesis inside the pic's specification. The |
| 416 |
effect of this is, for once, quite different from what happens for nodes: |
| 417 |
All that happens is that |name prefix| is set to \meta{name} at the |
| 418 |
beginning of the pic. |
| 419 |
|
| 420 |
The |name prefix| key was already introduced in the description of the |
| 421 |
|node| command: It allows you to set some text that is prefixed to all |
| 422 |
nodes in a scope. For pics this makes particular sense: All nodes defined |
| 423 |
by a pic's code can be referenced from outside the pic with the prefix |
| 424 |
provided. |
| 425 |
|
| 426 |
To see how this works, let us add some nodes to the code of the seagull: |
| 427 |
% |
| 428 |
\begin{codeexample}[code only] |
| 429 |
\tikzset{ |
| 430 |
seagull/.pic={ |
| 431 |
% Code for a "seagull". Do you see it?... |
| 432 |
\coordinate (-left wing) at (-3mm,0); |
| 433 |
\coordinate (-head) at (0,0); |
| 434 |
\coordinate (-right wing) at (3mm,0); |
| 435 |
|
| 436 |
\draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing); |
| 437 |
} |
| 438 |
} |
| 439 |
\end{codeexample} |
| 440 |
% |
| 441 |
\tikzset{ |
| 442 |
seagull/.pic={ |
| 443 |
% Code for a "seagull". Do you see it?... |
| 444 |
\coordinate (-left wing) at (-3mm,0); |
| 445 |
\coordinate (-head) at (0,0); |
| 446 |
\coordinate (-right wing) at (3mm,0); |
| 447 |
|
| 448 |
\draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing); |
| 449 |
} |
| 450 |
} |
| 451 |
|
| 452 |
Now, we can use it as follows: |
| 453 |
% |
| 454 |
\begin{codeexample}[code only] |
| 455 |
\tikz { |
| 456 |
\pic (Emma) {seagull}; |
| 457 |
\pic (Alexandra) at (0,1) {seagull}; |
| 458 |
|
| 459 |
\draw (Emma-left wing) -- (Alexandra-right wing); |
| 460 |
} |
| 461 |
\end{codeexample} |
| 462 |
|
| 463 |
Sometimes, you may also wish your pic to access nodes outside the pic |
| 464 |
(typically, because they are given as parameters). In this case, the name |
| 465 |
prefix gets in the way since the nodes outside the picture do not have this |
| 466 |
prefix. The trick is to locally reset the name prefix to the value it had |
| 467 |
outside the picture, which is achieved using the following style: |
| 468 |
|
| 469 |
\begin{key}{/tikz/name prefix ..} |
| 470 |
This key is available only inside the code of a pic. There, it |
| 471 |
(locally) changes the name prefix to the value it had outside the pic. |
| 472 |
This allows you to access nodes outside the current pic. |
| 473 |
\end{key} |
| 474 |
|
| 475 |
\medskip |
| 476 |
\textbf{Animations for pics.} |
| 477 |
Just as for nodes, you can use the attribute--colon syntax to add an |
| 478 |
animation to a pic: |
| 479 |
% |
| 480 |
\begin{codeexample}[ |
| 481 |
preamble={\usetikzlibrary{animations}}, |
| 482 |
animation list={0.5,1,1.5,2}, |
| 483 |
pre={\tikzset{ |
| 484 |
seagull/.pic={ |
| 485 |
% Code for a "seagull". Do you see it?... |
| 486 |
\coordinate (-left wing) at (-3mm,0); |
| 487 |
\coordinate (-head) at (0,0); |
| 488 |
\coordinate (-right wing) at (3mm,0); |
| 489 |
% |
| 490 |
\draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing); |
| 491 |
} |
| 492 |
}}, |
| 493 |
] |
| 494 |
\tikz { |
| 495 |
\pic :rotate={0s="0", 20s="90"} {seagull}; |
| 496 |
\pic at (1.5,1.5) {seagull}; |
| 497 |
} |
| 498 |
\end{codeexample} |
| 499 |
% |
| 500 |
Naturally, you can also use animations in the code of a picture: |
| 501 |
% |
| 502 |
\begin{codeexample}[ |
| 503 |
preamble={\usetikzlibrary{animations}}, |
| 504 |
animation list={0.5,1,1.5,2}, |
| 505 |
width=3cm, |
| 506 |
] |
| 507 |
\begin{tikzpicture} [flapping seagull/.pic={ |
| 508 |
\draw (0,0) :path={ |
| 509 |
0s= {"{(180:3mm) to [bend left] (0,0) to [bend left] (0:3mm)}"=base}, |
| 510 |
1s= "{(160:3mm) to [bend left] (0,0) to [bend left] (20:3mm)}", |
| 511 |
2s= "{(180:3mm) to [bend left] (0,0) to [bend left] (0:3mm)}", |
| 512 |
repeats }; |
| 513 |
}] |
| 514 |
\pic :rotate={0s="0", 20s="90"} {flapping seagull}; |
| 515 |
\pic at (1.5,1.5) {flapping seagull}; |
| 516 |
\end{tikzpicture} |
| 517 |
\end{codeexample} |
| 518 |
% |
| 519 |
\end{pathoperation} |
| 520 |
|
| 521 |
There are two general purpose keys that pics may find useful: |
| 522 |
|
| 523 |
\begin{key}{/tikz/pic text=\meta{text}} |
| 524 |
This macro stores the \meta{text} in the macro |\tikzpictext|, which is |
| 525 |
|\let| to |\relax| by default. Setting the |pic text| to some value is the |
| 526 |
``preferred'' way of communicating a (single) piece of text that should |
| 527 |
become part of a pic (typically of a node). In particular, the |quotes| |
| 528 |
library maps quoted parameters to this key. |
| 529 |
\end{key} |
| 530 |
|
| 531 |
\begin{key}{/tikz/pic text options=\meta{options}} |
| 532 |
This macro stores the \meta{options} in the macro |\tikzpictextoptions|, |
| 533 |
which is |\let| to the empty string by default. The |quotes| library maps |
| 534 |
options for quoted parameters to this key. |
| 535 |
\end{key} |
| 536 |
|
| 537 |
|
| 538 |
\subsubsection{The Quotes Syntax} |
| 539 |
\label{section-pic-quotes} |
| 540 |
|
| 541 |
When you load the |quotes| library, you can use the ``quotes syntax'' inside |
| 542 |
the options of a pic. Recall that for nodes this syntax is used to add a label |
| 543 |
to a node. For pics, the quotes syntax is used to set the |pic text| key. |
| 544 |
Whether or not the pic type's code takes this key into consideration is, |
| 545 |
however, up to the key. |
| 546 |
|
| 547 |
In detail, when the |quotes| library is loaded, each time a key--value pair in |
| 548 |
a list of options passed to an |pic| starts with |"|, the key--value pair must |
| 549 |
actually be a string of the following form: |
| 550 |
% |
| 551 |
\begin{quote} |
| 552 |
|"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} |
| 553 |
\end{quote} |
| 554 |
% |
| 555 |
This string is transformed into the following: |
| 556 |
% |
| 557 |
\begin{quote} |
| 558 |
|every pic quotes/.try,pic text=|\meta{text}|, pic text options={|\meta{options}|}| |
| 559 |
\end{quote} |
| 560 |
|
| 561 |
As example of a pic type that takes these values into account is the |angle| |
| 562 |
pic type: |
| 563 |
% |
| 564 |
\begin{codeexample}[preamble={\usetikzlibrary{angles,quotes}}] |
| 565 |
\tikz \draw (3,0) coordinate (A) |
| 566 |
-- (0,1) coordinate (B) |
| 567 |
-- (1,2) coordinate (C) |
| 568 |
pic [draw, "$\alpha$"] {angle}; |
| 569 |
\end{codeexample} |
| 570 |
|
| 571 |
As described in Section~\ref{section-label-quotes}, the apostrophe becomes part |
| 572 |
of the \meta{options}, when present. As can be seen above, the following style |
| 573 |
is executed: |
| 574 |
% |
| 575 |
\begin{stylekey}{/tikz/every pic quotes (initially \normalfont empty)} |
| 576 |
\end{stylekey} |
| 577 |
|
| 578 |
|
| 579 |
\subsection{Defining New Pic Types} |
| 580 |
\label{section-new-pic-types} |
| 581 |
|
| 582 |
As explained in the description of the |pic| command, in order to define a new |
| 583 |
pic type you need to |
| 584 |
% |
| 585 |
\begin{enumerate} |
| 586 |
\item define a key with the path prefix |/tikz/pics| that |
| 587 |
\item sets the key |/tikz/pics/code| to the code of the pic. |
| 588 |
\end{enumerate} |
| 589 |
|
| 590 |
It turns out that this is easy enough to achieve using styles: |
| 591 |
|
| 592 |
\begin{codeexample}[code only] |
| 593 |
\tikzset{ |
| 594 |
pics/seagull/.style ={ |
| 595 |
% Ok, this is the key that should, when |
| 596 |
% executed, set the code key: |
| 597 |
code = { % |
| 598 |
\draw (...) ... ; |
| 599 |
} |
| 600 |
} |
| 601 |
} |
| 602 |
\end{codeexample} |
| 603 |
|
| 604 |
Even though the above pattern is easy enough, there is a special so-called key |
| 605 |
handler that allows us to write even simpler code, namely: |
| 606 |
% |
| 607 |
\begin{codeexample}[code only] |
| 608 |
\tikzset{ |
| 609 |
seagull/.pic = { |
| 610 |
\draw (...) ... ; |
| 611 |
} |
| 612 |
} |
| 613 |
\end{codeexample} |
| 614 |
|
| 615 |
\begin{handler}{{.pic}|=|\meta{some code}} |
| 616 |
This handler can only be used with a key with the prefix |/tikz/|, so you |
| 617 |
should normally use it only as an option to a \tikzname\ command or to the |
| 618 |
|\tikzset| command. It takes the \meta{key}'s path and, inside that path, |
| 619 |
it replaces |/tikz/| by |/tikz/pics/| (so, basically, it adds the |
| 620 |
``missing'' |pics| part of the path). Then, it sets up things so that the |
| 621 |
resulting name to key is a style that executes |code=some code|. |
| 622 |
\end{handler} |
| 623 |
|
| 624 |
In almost all cases, the |.pic| key handler will suffice to setup keys. |
| 625 |
However, there are cases where you really need to use the first version using |
| 626 |
|.style| and |code=|: |
| 627 |
% |
| 628 |
\begin{itemize} |
| 629 |
\item Whenever your pic type needs to set the foreground or the background |
| 630 |
code. |
| 631 |
\item In case of complicated arguments given to the keys. |
| 632 |
\end{itemize} |
| 633 |
|
| 634 |
As an example, let us define a simple pic that draws a filled circle behind the |
| 635 |
path. Furthermore, we make the circle's radius a parameter of the pic: |
| 636 |
% |
| 637 |
\begin{codeexample}[] |
| 638 |
\tikzset{ |
| 639 |
pics/my circle/.style = { |
| 640 |
background code = { \fill circle [radius=#1]; } |
| 641 |
} |
| 642 |
} |
| 643 |
\tikz [fill=blue!30] |
| 644 |
\draw (0,0) pic {my circle=2mm} -- (1,1) pic {my circle=5mm}; |
| 645 |
\end{codeexample} |