| 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{Nodes and Shapes} |
| 12 |
|
| 13 |
\label{section-shapes} |
| 14 |
|
| 15 |
This section describes the |shapes| module. |
| 16 |
|
| 17 |
\begin{pgfmodule}{shapes} |
| 18 |
This module defines commands both for creating nodes and for creating |
| 19 |
shapes. The package is loaded automatically by |pgf|, but you can load it |
| 20 |
manually if you have only included |pgfcore|. |
| 21 |
\end{pgfmodule} |
| 22 |
|
| 23 |
|
| 24 |
\subsection{Overview} |
| 25 |
|
| 26 |
\pgfname\ comes with a sophisticated set of commands for creating \emph{nodes} |
| 27 |
and \emph{shapes}. A \emph{node} is a graphical object that consists |
| 28 |
(typically) of (one or more) text labels and some additional stroked or filled |
| 29 |
paths. Each node has a certain \emph{shape}, which may be something simple like |
| 30 |
a |rectangle| or a |circle|, but it may also be something complicated like a |
| 31 |
|uml class diagram| (this shape is currently not implemented, though). |
| 32 |
Different nodes that have the same shape may look quite different, however, |
| 33 |
since shapes (need not) specify whether the shape path is stroked or filled. |
| 34 |
|
| 35 |
|
| 36 |
\subsubsection{Creating and Referencing Nodes} |
| 37 |
|
| 38 |
You create a node by calling the macro |\pgfnode| or the more general |
| 39 |
|\pgfmultipartnode|. This macro takes several parameters and draws the |
| 40 |
requested shape at a certain position. In addition, it will ``remember'' the |
| 41 |
node's position within the current |{pgfpicture}|. You can then, later on, |
| 42 |
refer to the node's position. Coordinate transformations are ``fully |
| 43 |
supported'', which means that if you used coordinate transformations to shift |
| 44 |
or rotate the shape of a node, the node's position will still be correctly |
| 45 |
determined by \pgfname. This is \emph{not} the case if you use canvas |
| 46 |
transformations instead. |
| 47 |
|
| 48 |
|
| 49 |
\subsubsection{Anchors} |
| 50 |
|
| 51 |
An important property of a node or a shape in general are its \emph{anchors}. |
| 52 |
Anchors are ``important'' positions in a shape. For example, the |center| |
| 53 |
anchor lies at the center of a shape, the |north| anchor is usually ``at the |
| 54 |
top, in the middle'' of a shape, the |text| anchor is the lower left corner of |
| 55 |
the shape's text label (if present), and so on. |
| 56 |
|
| 57 |
Anchors are important both when you create a node and when you reference it. |
| 58 |
When you create a node, you specify the node's ``position'' by asking \pgfname\ |
| 59 |
to place the shape in such a way that a certain anchor lies at a certain point. |
| 60 |
For example, you might ask that the node is placed such that the |north| anchor |
| 61 |
is at the origin. This will effectively cause the node to be placed below the |
| 62 |
origin. |
| 63 |
|
| 64 |
When you reference a node, you always reference an anchor of the node. For |
| 65 |
example, when you request the ``|north| anchor of the node just placed'' you |
| 66 |
will get the origin. However, you can also request the ``|south| anchor of this |
| 67 |
node'', which will give you a point somewhere below the origin. When a |
| 68 |
coordinate transformation was in force at the time of creation of a node, all |
| 69 |
anchors are also transformed accordingly. |
| 70 |
|
| 71 |
|
| 72 |
\subsubsection{Layers of a Shape} |
| 73 |
|
| 74 |
The simplest shape, the |coordinate|, has just one anchor, namely the |center|, |
| 75 |
and a label (which is usually empty). More complicated shapes like the |
| 76 |
|rectangle| shape also have a \emph{background path}. This is a \pgfname-path |
| 77 |
that is defined by the shape. The shape does not prescribe what should happen |
| 78 |
with the path: When a node is created, this path may be stroked (resulting in a |
| 79 |
frame around the label), filled (resulting in a background color for the text), |
| 80 |
or just discarded. |
| 81 |
|
| 82 |
Although most shapes consist just of a background path plus some label text, |
| 83 |
when a shape is drawn, up to seven different layers are drawn: |
| 84 |
% |
| 85 |
\begin{enumerate} |
| 86 |
\item The ``behind the background layer''. Unlike the background path, |
| 87 |
which can be used in different ways by different nodes, the graphic |
| 88 |
commands given for this layer will always stroke or always fill the |
| 89 |
path they construct. They might also insert some text that is ``behind |
| 90 |
everything''. |
| 91 |
\item The background path layer. How this path is used depends on the |
| 92 |
arguments of the |\pgfnode| command. |
| 93 |
\item The ``before the background path layer''. This layer works like the |
| 94 |
first one, only the commands of this layer are executed after the |
| 95 |
background path has been used (in whatever way the creator of the node |
| 96 |
chose). |
| 97 |
\item The label layer. This layer inserts the node's text box(es). |
| 98 |
\item The ``behind the foreground layer''. This layer, like the first |
| 99 |
layer, once more contains graphic commands that are ``simply |
| 100 |
executed''. |
| 101 |
\item The foreground path layer. This path is treated in the same way as |
| 102 |
the background path, only it is drawn after the label text has been |
| 103 |
drawn. |
| 104 |
\item The ``before the foreground layer''. |
| 105 |
\end{enumerate} |
| 106 |
|
| 107 |
Which of these layers are actually used depends on the shape. |
| 108 |
|
| 109 |
|
| 110 |
\subsubsection{Node Parts} |
| 111 |
|
| 112 |
A shape typically does not consist only of different background and foreground |
| 113 |
paths, but it may also have text labels. Indeed, for many shapes the text |
| 114 |
labels are the more important part of the shape. |
| 115 |
|
| 116 |
Most shapes will have only one text label. In this case, this text label is |
| 117 |
simply passed as a parameter to the |\pgfnode| command. When the node is drawn, |
| 118 |
the text label is shifted around such that its lower left corner is at the |
| 119 |
|text| anchor of the node. |
| 120 |
|
| 121 |
More complicated shapes may have more than one text label. Nodes of such shapes |
| 122 |
are called \emph{multipart nodes}. The different \emph{node parts} are simply |
| 123 |
the different text labels. For example, a |uml class| shape might have a |
| 124 |
|class name| part, a |method| part and an |attributes| part. Indeed, single |
| 125 |
part nodes are a special case of multipart nodes: They only have one part named |
| 126 |
|text|. |
| 127 |
|
| 128 |
When a shape is declared, you must specify the node parts. There is a simple |
| 129 |
command called |\nodeparts| that takes a list of the part names as input. When |
| 130 |
you create a node of a multipart shape, for each part of the node you must have |
| 131 |
set up a \TeX-box containing the text of the part. For a part named |XYZ| you |
| 132 |
must set up the box |\pgfnodepartXYZbox|. The box will be placed at the anchor |
| 133 |
|XYZ|. See the description of |\pgfmultipartnode| for more details. |
| 134 |
|
| 135 |
|
| 136 |
\subsection{Creating Nodes} |
| 137 |
|
| 138 |
\subsubsection{Creating Simple Nodes} |
| 139 |
|
| 140 |
\begin{command}{\pgfnode\marg{shape}\marg{anchor}\marg{label text}\marg{name}\marg{path usage command}} |
| 141 |
This command creates a new node. The \meta{shape} of the node must have |
| 142 |
been declared previously using |\pgfdeclareshape|. |
| 143 |
|
| 144 |
The shape is shifted such that the \meta{anchor} is at the origin. In order |
| 145 |
to place the shape somewhere else, use the coordinate transformation prior |
| 146 |
to calling this command. |
| 147 |
|
| 148 |
The \meta{name} is a name for later reference. If no name is given, nothing |
| 149 |
will be ``saved'' for the node, it will just be drawn. |
| 150 |
|
| 151 |
The \meta{path usage command} is executed for the background and the |
| 152 |
foreground path (if the shape defines them). |
| 153 |
% |
| 154 |
\begin{codeexample}[] |
| 155 |
\begin{tikzpicture} |
| 156 |
\draw[help lines] (0,0) grid (4,3); |
| 157 |
{ |
| 158 |
\pgftransformshift{\pgfpoint{1.5cm}{1cm}} |
| 159 |
\pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}} |
| 160 |
} |
| 161 |
{ |
| 162 |
\color{red!20} |
| 163 |
\pgftransformrotate{10} |
| 164 |
\pgftransformshift{\pgfpoint{3cm}{1cm}} |
| 165 |
\pgfnode{rectangle}{center} |
| 166 |
{\color{black}Hello World}{hellonode}{\pgfusepath{fill}} |
| 167 |
} |
| 168 |
\end{tikzpicture} |
| 169 |
\end{codeexample} |
| 170 |
|
| 171 |
As can be seen, all coordinate transformations are also applied to the text |
| 172 |
of the shape. Sometimes, it is desirable that the transformations are |
| 173 |
applied to the point where the shape will be anchored, but you do not wish |
| 174 |
the shape itself to be transformed. In this case, you should call |
| 175 |
|\pgftransformresetnontranslations| prior to calling the |\pgfnode| |
| 176 |
command. |
| 177 |
% |
| 178 |
\begin{codeexample}[] |
| 179 |
\begin{tikzpicture} |
| 180 |
\draw[help lines] (0,0) grid (4,3); |
| 181 |
{ |
| 182 |
\color{red!20} |
| 183 |
\pgftransformrotate{10} |
| 184 |
\pgftransformshift{\pgfpoint{3cm}{1cm}} |
| 185 |
\pgftransformresetnontranslations |
| 186 |
\pgfnode{rectangle}{center} |
| 187 |
{\color{black}Hello World}{hellonode}{\pgfusepath{fill}} |
| 188 |
} |
| 189 |
\end{tikzpicture} |
| 190 |
\end{codeexample} |
| 191 |
|
| 192 |
The \meta{label text} is typeset inside the \TeX-box |\pgfnodeparttextbox|. |
| 193 |
This box is shown at the |text| anchor of the node, if the node has a |
| 194 |
|text| part. See the description of |\pgfmultipartnode| for details. |
| 195 |
\end{command} |
| 196 |
|
| 197 |
|
| 198 |
\subsubsection{Creating Multi-Part Nodes} |
| 199 |
|
| 200 |
\begin{command}{\pgfmultipartnode\marg{shape}\marg{anchor}\marg{name}\marg{path usage command}} |
| 201 |
This command is the more general (and less user-friendly) version of the |
| 202 |
|\pgfnode| command. While the |\pgfnode| command can only be used for |
| 203 |
shapes that have a single part (which is the case for most shapes), this |
| 204 |
command can also be used with multi-part nodes. |
| 205 |
|
| 206 |
When this command is called, for each node part of the node you must have |
| 207 |
set up one \TeX-box. Suppose the shape has two parts: The |text| part and |
| 208 |
the |lower| part. Then, prior to calling |\pgfmultipartnode|, you must have |
| 209 |
set up the boxes |\pgfnodeparttextbox| and |\pgfnodepartlowerbox|. These |
| 210 |
boxes may contain any \TeX-text. The shape code will then compute the |
| 211 |
positions of the shape's anchors based on the sizes of the these shapes. |
| 212 |
Finally, when the node is drawn, the boxes are placed at the anchor |
| 213 |
positions |text| and |lower|. |
| 214 |
% |
| 215 |
\begin{codeexample}[preamble={\usetikzlibrary{shapes}}] |
| 216 |
\setbox\pgfnodeparttextbox=\hbox{$q_1$} |
| 217 |
\setbox\pgfnodepartlowerbox=\hbox{01} |
| 218 |
\begin{pgfpicture} |
| 219 |
\pgfmultipartnode{circle split}{center}{my state}{\pgfusepath{stroke}} |
| 220 |
\end{pgfpicture} |
| 221 |
\end{codeexample} |
| 222 |
|
| 223 |
\emph{Note:} Be careful when using the |\setbox| command inside a |
| 224 |
|{pgfpicture}| command. You will have to use |\pgfinterruptpath| at the |
| 225 |
beginning of the box and |\endpgfinterruptpath| at the end of the box to |
| 226 |
make sure that the box is typeset correctly. In the above example this |
| 227 |
problem was sidestepped by moving the box construction outside the |
| 228 |
environment. |
| 229 |
|
| 230 |
\emph{Note:} It is not necessary to use |\newbox| for every node part |
| 231 |
name. Although you need a different box for each part of a single shape, |
| 232 |
two different shapes may very well use the same box even when the names of |
| 233 |
the parts are different. Suppose you have a |circle split| shape that has a |
| 234 |
|lower| part and you have a |uml class| shape that has a |methods| part. |
| 235 |
Then, in order to avoid exhausting \TeX's limited number of box registers, |
| 236 |
you can say |
| 237 |
% |
| 238 |
\begin{codeexample}[code only] |
| 239 |
\newbox\pgfnodepartlowerbox |
| 240 |
\let\pgfnodepartmethodsbox=\pgfnodepartlowerbox |
| 241 |
\end{codeexample} |
| 242 |
% |
| 243 |
Also, when you have a node part name with spaces like |class name|, it may |
| 244 |
be useful to create an alias: |
| 245 |
% |
| 246 |
\begin{codeexample}[code only] |
| 247 |
\newbox\mybox |
| 248 |
\expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox |
| 249 |
\end{codeexample} |
| 250 |
% |
| 251 |
\end{command} |
| 252 |
|
| 253 |
\begin{command}{\pgfcoordinate\marg{name}\marg{coordinate}} |
| 254 |
This command creates a node of shape |coordinate| at the given |
| 255 |
\meta{coordinate}. Exactly the same effect can be achieved using first a |
| 256 |
shift of the coordinate system to \meta{coordinate}, followed by creating a |
| 257 |
node of shape |coordinate| named \meta{name}. However, this command is |
| 258 |
easier and more natural to use and, more importantly, it is much faster. |
| 259 |
\end{command} |
| 260 |
|
| 261 |
\begin{command}{\pgfnodealias\marg{new name}\marg{existing node}} |
| 262 |
This command does not actually create a new node. Rather, it allows you to |
| 263 |
subsequently access the node \meta{existing node} using the name \meta{new |
| 264 |
name}. |
| 265 |
\end{command} |
| 266 |
|
| 267 |
\begin{command}{\pgfnoderename\marg{new name}\marg{existing node}} |
| 268 |
This command renames an existing node. |
| 269 |
\end{command} |
| 270 |
|
| 271 |
There are a number of values that have an influence on the size of a node. |
| 272 |
These values are stored in the following keys. |
| 273 |
|
| 274 |
\begin{key}{/pgf/minimum width=\meta{dimension} (initially 1pt)} |
| 275 |
\keyalias{tikz} |
| 276 |
This key stores the \emph{recommended} minimum width of a shape. Thus, when |
| 277 |
a shape is drawn and when the shape's width would be smaller than |
| 278 |
\meta{dimension}, the shape's width is enlarged by adding some empty space. |
| 279 |
|
| 280 |
Note that this value is just a recommendation. A shape may choose to ignore |
| 281 |
this key. |
| 282 |
% |
| 283 |
\begin{codeexample}[] |
| 284 |
\begin{tikzpicture} |
| 285 |
\draw[help lines] (-2,0) grid (2,1); |
| 286 |
|
| 287 |
\pgfset{minimum width=3cm} |
| 288 |
\pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} |
| 289 |
\end{tikzpicture} |
| 290 |
\end{codeexample} |
| 291 |
% |
| 292 |
\end{key} |
| 293 |
|
| 294 |
\begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)} |
| 295 |
\keyalias{tikz} |
| 296 |
Works like |/pgf/minimum width|. |
| 297 |
\end{key} |
| 298 |
|
| 299 |
\begin{key}{/pgf/minimum size=\meta{dimension}} |
| 300 |
\keyalias{tikz} |
| 301 |
This style both |/pgf/minimum width| and |/pgf/minimum height| to \meta{dimension}. |
| 302 |
\end{key} |
| 303 |
|
| 304 |
\begin{key}{/pgf/inner xsep=\meta{dimension} (initially 0.3333em)} |
| 305 |
\keyalias{tikz} |
| 306 |
This key stores the \emph{recommended} horizontal inner separation between |
| 307 |
the label text and the background path. As before, this value is just a |
| 308 |
recommendation and a shape may choose to ignore this key. |
| 309 |
% |
| 310 |
\begin{codeexample}[] |
| 311 |
\begin{tikzpicture} |
| 312 |
\draw[help lines] (-2,0) grid (2,1); |
| 313 |
|
| 314 |
\pgfset{inner xsep=1cm} |
| 315 |
\pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} |
| 316 |
\end{tikzpicture} |
| 317 |
\end{codeexample} |
| 318 |
% |
| 319 |
\end{key} |
| 320 |
|
| 321 |
\begin{key}{/pgf/inner ysep=\meta{dimension} (initially 0.3333em)} |
| 322 |
\keyalias{tikz} |
| 323 |
Works like |/pgf/inner xsep|. |
| 324 |
\end{key} |
| 325 |
|
| 326 |
\begin{key}{/pgf/inner sep=\meta{dimension}} |
| 327 |
\keyalias{tikz} |
| 328 |
This style sets both |/pgf/inner xsep| and |/pgf/inner ysep| to |
| 329 |
\meta{dimension}. |
| 330 |
\end{key} |
| 331 |
|
| 332 |
\begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)} |
| 333 |
\keyalias{tikz} |
| 334 |
This key stores the recommended horizontal separation between the |
| 335 |
background path and the ``outer anchors''. For example, if \meta{dimension} |
| 336 |
is |1cm| then the |east| anchor will be 1cm to the right of the right |
| 337 |
border of the background path. As before, this value is just a |
| 338 |
recommendation. |
| 339 |
% |
| 340 |
\begin{codeexample}[] |
| 341 |
\begin{tikzpicture} |
| 342 |
\draw[help lines] (-2,0) grid (2,1); |
| 343 |
|
| 344 |
\pgfset{outer xsep=.5cm} |
| 345 |
\pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}} |
| 346 |
|
| 347 |
\pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} |
| 348 |
\pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} |
| 349 |
\pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} |
| 350 |
\pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} |
| 351 |
\pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} |
| 352 |
\pgfusepath{fill} |
| 353 |
\end{tikzpicture} |
| 354 |
\end{codeexample} |
| 355 |
% |
| 356 |
\end{key} |
| 357 |
|
| 358 |
\begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)} |
| 359 |
\keyalias{tikz} |
| 360 |
Works like |/pgf/outer xsep|. |
| 361 |
\end{key} |
| 362 |
|
| 363 |
\begin{key}{/pgf/outer sep=\meta{dimension}} |
| 364 |
\keyalias{tikz} |
| 365 |
This style sets both |/pgf/outer xsep| and |/pgf/outer ysep| to |
| 366 |
\meta{dimension}. |
| 367 |
\end{key} |
| 368 |
|
| 369 |
|
| 370 |
\subsubsection{Deferred Node Positioning} |
| 371 |
\label{section-shapes-deferred-node-positioning} |
| 372 |
|
| 373 |
Normally, when a node is created using a command like |\pgfnode|, the node is |
| 374 |
immediately inserted into the current picture. In particular, you have no |
| 375 |
chance to change the position of a created node after it has been created. |
| 376 |
Using |\pgfpositionnodelater| in concert with |\pgfpositionnodenow|, you can |
| 377 |
create a node whose position is determined only at some later time. |
| 378 |
|
| 379 |
\begin{command}{\pgfpositionnodelater\marg{macro name}} |
| 380 |
This command is not a replacement for |\pgfnode|. Rather, when this command |
| 381 |
is used in a scope, all subsequent node creations in this scope will be |
| 382 |
affected in the following way: When a node is created, it is not inserted |
| 383 |
into the current picture. Instead, it is stored in the box |
| 384 |
|\pgfpositionnodelaterbox|. Furthermore, the node is not relevant for the |
| 385 |
picture's bounding box, but a bounding box for the node is computed and |
| 386 |
stored in the macros |\pgfpositionnodelaterminx| to |
| 387 |
|\pgfpositionnodelatermaxy|. Then, the \meta{macro name} is called with the |
| 388 |
following macros set up: |
| 389 |
|
| 390 |
\begin{command}{\pgfpositionnodelaterbox} |
| 391 |
A box register number (|0| currently) that stores the node's paths and |
| 392 |
texts. You should move the contents of this box to a box of your choice |
| 393 |
inside \meta{macro name}. |
| 394 |
\end{command} |
| 395 |
|
| 396 |
\begin{command}{\pgfpositionnodelatername} |
| 397 |
The name of the just-created-node. This name will be the originally |
| 398 |
``desired'' name of the box plus the fixed prefix |
| 399 |
|not yet positionedPGFINTERNAL|. The idea is to ensure that the |
| 400 |
original name is not inadvertently used before the node is actually |
| 401 |
positioned. When |\pgfpositionnodenow| is called, it will change the |
| 402 |
name to the |
| 403 |
original name. |
| 404 |
\end{command} |
| 405 |
|
| 406 |
\begin{command}{\pgfpositionnodelaterminx} |
| 407 |
The minimal $x$-position of a bounding box of the node. This bounding |
| 408 |
box refers to the node when it is positioned with the anchor at the |
| 409 |
origin. It is guaranteed, that this macro will contain a dimension in |
| 410 |
the format \meta{number}|pt|. |
| 411 |
\end{command} |
| 412 |
% |
| 413 |
\begin{command}{\pgfpositionnodelaterminy} |
| 414 |
\end{command} |
| 415 |
% |
| 416 |
\begin{command}{\pgfpositionnodelatermaxx} |
| 417 |
\end{command} |
| 418 |
% |
| 419 |
\begin{command}{\pgfpositionnodelatermaxy} |
| 420 |
\end{command} |
| 421 |
|
| 422 |
Once a late node has been created, you can add arbitrary code in the same |
| 423 |
picture. Then, at some later point, you call |\pgfpositionnodenow| to |
| 424 |
finally position the node at a given position. At this point, the above |
| 425 |
macros must have the exact same values they had when \meta{macro name} was |
| 426 |
called. Note that the above macros are local to a scope that ends right |
| 427 |
after the call to \meta{macro name}, so it is your job to copy the values |
| 428 |
to safety inside \meta{macro name}. |
| 429 |
|
| 430 |
The following two macros will also be set inside the call to \meta{macro |
| 431 |
name}, but they are only ``informative'' in the sense that you need |
| 432 |
\emph{not} restore these macros when |\pgfpositionnodenow| is called. |
| 433 |
|
| 434 |
\begin{command}{\pgfpositionnodelaterpath} |
| 435 |
This macro stores the path of the background of the node. See |
| 436 |
Section~\ref{section-soft-paths} for an overview of how these paths are |
| 437 |
encode. |
| 438 |
\end{command} |
| 439 |
|
| 440 |
By setting \meta{macro name} to |\relax| (which is the default), you can |
| 441 |
switch off the whole mechanism. When a picture is interrupted, this is done |
| 442 |
automatically. |
| 443 |
\end{command} |
| 444 |
|
| 445 |
\begin{command}{\pgfpositionnodenow\marg{coordinate}} |
| 446 |
This command is used to position a node that has previously been created |
| 447 |
using the command |\pgfpositionnodelater|. When |\pgfpositionnodenow| is |
| 448 |
called, the macros and boxes mentioned in the description of |
| 449 |
|\pgfpositionnodenow| must be set to the value they had when the |
| 450 |
\meta{macro name} was called. Provided this is the case, this command will |
| 451 |
insert the box into the current picture, shifted by \meta{coordinate}. |
| 452 |
Then, the late code (see below) is called. Subsequently, you can refer to |
| 453 |
the node with its original name as if it had just been created. |
| 454 |
% |
| 455 |
\begin{codeexample}[] |
| 456 |
\newbox\mybox |
| 457 |
|
| 458 |
\def\mysaver{ |
| 459 |
\global\setbox\mybox=\box\pgfpositionnodelaterbox |
| 460 |
\global\let\myname=\pgfpositionnodelatername |
| 461 |
\global\let\myminx=\pgfpositionnodelaterminx |
| 462 |
\global\let\myminy=\pgfpositionnodelaterminy |
| 463 |
\global\let\mymaxx=\pgfpositionnodelatermaxx |
| 464 |
\global\let\mymaxy=\pgfpositionnodelatermaxy |
| 465 |
} |
| 466 |
|
| 467 |
\begin{tikzpicture} |
| 468 |
{ |
| 469 |
\pgfpositionnodelater{\mysaver} |
| 470 |
\node [fill=blue!20,below,rotate=30] (hi) {Hello world}; |
| 471 |
} |
| 472 |
\draw [help lines] (0,0) grid (3,2); |
| 473 |
|
| 474 |
\let\pgfpositionnodelatername=\myname |
| 475 |
\let\pgfpositionnodelaterminx=\myminx |
| 476 |
\let\pgfpositionnodelaterminy=\myminy |
| 477 |
\let\pgfpositionnodelatermaxx=\mymaxx |
| 478 |
\let\pgfpositionnodelatermaxy=\mymaxy |
| 479 |
\setbox\pgfpositionnodelaterbox=\box\mybox |
| 480 |
\pgfpositionnodenow{\pgfqpoint{2cm}{2cm}} |
| 481 |
|
| 482 |
\draw (hi) -- (0,0); |
| 483 |
\end{tikzpicture} |
| 484 |
\end{codeexample} |
| 485 |
% |
| 486 |
\end{command} |
| 487 |
|
| 488 |
\begin{command}{\pgfnodepostsetupcode\marg{node name}\marg{code}} |
| 489 |
When you call this macro inside a scope for which the |
| 490 |
|\pgfpositionnodelater| has been called, the \meta{code} will be stored |
| 491 |
internally. Later, when the node named \meta{node name} is actually |
| 492 |
positioned using |\pgfpositionnodenow|, the \meta{code} will be executed. |
| 493 |
When this macro is called multiple times with the same \meta{node name}, |
| 494 |
the \meta{code} accumulates. However, When |\pgfpositionnodenow| is called, |
| 495 |
the code stored for the node is cleared. |
| 496 |
|
| 497 |
The main purpose of this mechanism is to allow \tikzname\ to store |
| 498 |
so-called ``late options'' with a node that will be positioned only later. |
| 499 |
\end{command} |
| 500 |
|
| 501 |
|
| 502 |
\subsection{Using Anchors} |
| 503 |
|
| 504 |
Each shape defines a set of anchors. We saw already that the anchors are used |
| 505 |
when the shape is drawn: the shape is placed in such a way that the given |
| 506 |
anchor is at the origin (which in turn is typically translated somewhere else). |
| 507 |
|
| 508 |
One has to look up the set of anchors of each shape, there is no ``default'' |
| 509 |
set of anchors, except for the |center| anchor, which should always be present. |
| 510 |
Also, most shapes will declare anchors like |north| or |east|, but this is not |
| 511 |
guaranteed. |
| 512 |
|
| 513 |
|
| 514 |
\subsubsection{Referencing Anchors of Nodes in the Same Picture} |
| 515 |
|
| 516 |
Once a node has been defined, you can refer to its anchors using the following |
| 517 |
commands: |
| 518 |
|
| 519 |
\begin{command}{\pgfpointanchor\marg{node}\marg{anchor}} |
| 520 |
This command is another ``point command'' like the commands described in |
| 521 |
Section~\ref{section-points}. It returns the coordinate of the given |
| 522 |
\meta{anchor} in the given \meta{node}. The command can be used in commands |
| 523 |
like |\pgfpathmoveto|. |
| 524 |
% |
| 525 |
\begin{codeexample}[] |
| 526 |
\begin{pgfpicture} |
| 527 |
\pgftransformrotate{30} |
| 528 |
\pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} |
| 529 |
|
| 530 |
\pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} |
| 531 |
\pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} |
| 532 |
\pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} |
| 533 |
\pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} |
| 534 |
\pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} |
| 535 |
\pgfusepath{fill} |
| 536 |
\end{pgfpicture} |
| 537 |
\end{codeexample} |
| 538 |
|
| 539 |
In the above example, you may have noticed something curious: The rotation |
| 540 |
transformation is still in force when the anchors are invoked, but it does |
| 541 |
not seem to have an effect. You might expect that the rotation should apply |
| 542 |
to the already rotated points once more. |
| 543 |
|
| 544 |
However, |\pgfpointanchor| returns a point that takes the current |
| 545 |
transformation matrix into account: \emph{The inverse transformation to the |
| 546 |
current coordinate transformation is applied to an anchor point before |
| 547 |
returning it.} |
| 548 |
|
| 549 |
This behavior may seem a bit strange, but you will find it very natural in |
| 550 |
most cases. If you really want to apply a transformation to an anchor point |
| 551 |
(for example, to ``shift it away'' a little bit), you have to invoke |
| 552 |
|\pgfpointanchor| without any transformations in force. Here is an example: |
| 553 |
% |
| 554 |
\makeatletter |
| 555 |
\begin{codeexample}[pre={\makeatletter}] |
| 556 |
\begin{pgfpicture} |
| 557 |
\pgftransformrotate{30} |
| 558 |
\pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} |
| 559 |
|
| 560 |
{ |
| 561 |
\pgftransformreset |
| 562 |
\pgfpointanchor{x}{east} |
| 563 |
\xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}} |
| 564 |
} |
| 565 |
|
| 566 |
\pgfpathcircle{\mycoordinate}{2pt} |
| 567 |
\pgfusepath{fill} |
| 568 |
\end{pgfpicture} |
| 569 |
\end{codeexample} |
| 570 |
|
| 571 |
A special situation arises when the \meta{node} lies in a picture different |
| 572 |
from the current picture. In this case, if you have not told \pgfname\ that |
| 573 |
the picture should be ``remembered'', the \meta{node} will be treated as if |
| 574 |
it lay in the current picture. For example, if the \meta{node} was at |
| 575 |
position $(3,2)$ in the original picture, it is treated as if it lay at |
| 576 |
position $(3,2)$ in the current picture. However, if you have told |
| 577 |
\pgfname\ to remember the picture position of the node's picture and also |
| 578 |
of the current picture, then |\pgfpointanchor| will return a coordinate |
| 579 |
that corresponds to the position of the node's anchor on the page, |
| 580 |
transformed into the current coordinate system. For examples and more |
| 581 |
details see Section~\ref{section-cross-pictures-pgf}. |
| 582 |
\end{command} |
| 583 |
|
| 584 |
\begin{command}{\pgfpointshapeborder\marg{node}\marg{point}} |
| 585 |
This command returns the point on the border of the shape that lies on a |
| 586 |
straight line from the center of the node to \meta{point}. For complex |
| 587 |
shapes it is not guaranteed that this point will actually lie on the |
| 588 |
border, it may be on the border of a ``simplified'' version of the shape. |
| 589 |
% |
| 590 |
\begin{codeexample}[] |
| 591 |
\begin{pgfpicture} |
| 592 |
\begin{pgfscope} |
| 593 |
\pgftransformrotate{30} |
| 594 |
\pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} |
| 595 |
\end{pgfscope} |
| 596 |
\pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt} |
| 597 |
\pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} |
| 598 |
\pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt} |
| 599 |
\pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt} |
| 600 |
\pgfusepath{fill} |
| 601 |
\end{pgfpicture} |
| 602 |
\end{codeexample} |
| 603 |
% |
| 604 |
\emph{Remark:} If the given \meta{point} is almost identical to the center |
| 605 |
of \meta{node}, the node center is returned and a warning message will be |
| 606 |
printed. |
| 607 |
\end{command} |
| 608 |
|
| 609 |
|
| 610 |
\subsubsection{Referencing Anchors of Nodes in Different Pictures} |
| 611 |
\label{section-cross-pictures-pgf} |
| 612 |
|
| 613 |
As a picture is typeset, \pgfname\ keeps track of the positions of all nodes |
| 614 |
inside the picture. What \pgfname\ does not remember is the position of the |
| 615 |
picture \emph{itself} on the page. Thus, if you define a node in one picture |
| 616 |
and then try to reference this node while another picture is typeset, \pgfname\ |
| 617 |
will only know the position of the nodes that you try to typeset inside the |
| 618 |
original picture, but it will not know where this picture lies. What is missing |
| 619 |
is the relative positioning of the two pictures. |
| 620 |
|
| 621 |
To overcome this problem, you need to tell \pgfname\ that it should remember |
| 622 |
the position of pictures on a page. If these positions are remembered, then |
| 623 |
\pgfname\ can compute the offset between the pictures and make nodes in |
| 624 |
different pictures accessible. |
| 625 |
|
| 626 |
Determining the positions of pictures on the page is, alas, not-so-easy. |
| 627 |
Because of this, \pgfname\ does not do so automatically. Rather, you have to |
| 628 |
proceed as follows: |
| 629 |
% |
| 630 |
\begin{enumerate} |
| 631 |
\item You have to use a backend driver that supports position tracking. |
| 632 |
pdf\TeX\ is one such driver, |dvips| currently is not. |
| 633 |
\item You have to say |\pgfrememberpicturepositiononpagetrue| somewhere |
| 634 |
before or inside every picture |
| 635 |
% |
| 636 |
\begin{itemize} |
| 637 |
\item in which you wish to reference a node and |
| 638 |
\item from which you wish to reference a node in another picture. |
| 639 |
\end{itemize} |
| 640 |
% |
| 641 |
The second item is important since \pgfname\ does not only need to know |
| 642 |
the position of the picture in which the node you wish to reference |
| 643 |
lies, but it also needs to know where the current picture lies. |
| 644 |
\item You typically have to run \TeX\ twice (depending on the backend |
| 645 |
driver) since the position information typically gets written into an |
| 646 |
external file on the first run and is available only on the second run. |
| 647 |
\item You have to switch off automatic bounding bound computations. The |
| 648 |
reason is that the node in the other picture should not influence the |
| 649 |
size of the bounding box of the current picture. You should say |
| 650 |
|\pgfusepath{use as bounding box}| before using a coordinate in another |
| 651 |
picture. |
| 652 |
\end{enumerate} |
| 653 |
|
| 654 |
|
| 655 |
\subsection{Special Nodes} |
| 656 |
|
| 657 |
There are several special nodes that are always defined and which you should |
| 658 |
not attempt to redefine. |
| 659 |
|
| 660 |
\begin{predefinednode}{current bounding box} |
| 661 |
This node is of shape |rectangle|. Unlike normal nodes, its size changes |
| 662 |
constantly and always reflects the size of the bounding box of the current |
| 663 |
picture. This means that, for instance, that |
| 664 |
% |
| 665 |
\begin{codeexample}[code only] |
| 666 |
\pgfpointanchor{current bounding box}{south east} |
| 667 |
\end{codeexample} |
| 668 |
% |
| 669 |
returns the lower left corner of the bounding box of the current picture. |
| 670 |
\end{predefinednode} |
| 671 |
|
| 672 |
\begin{predefinednode}{current path bounding box} |
| 673 |
This node is also of shape |rectangle|. Its size is the size of the |
| 674 |
bounding box of the current path. |
| 675 |
\end{predefinednode} |
| 676 |
|
| 677 |
\begin{predefinednode}{current subpath start} |
| 678 |
This node is of shape |coordinate| and is at the beginning of the current |
| 679 |
subpath. This is the position of the last move-to operation. |
| 680 |
\end{predefinednode} |
| 681 |
|
| 682 |
\begin{predefinednode}{current page} |
| 683 |
This node is inside a virtual remembered picture. The size of this node is |
| 684 |
the size of the current page. This means that if you create a remembered |
| 685 |
picture and inside this picture you reference an anchor of this node, you |
| 686 |
reference an absolute position on the page. To demonstrate the effect, the |
| 687 |
following code puts some text in the lower left corner of the current page. |
| 688 |
Note that this works only if the backend driver supports it, otherwise the |
| 689 |
text is inserted right here. |
| 690 |
% |
| 691 |
{% |
| 692 |
\pgfrememberpicturepositiononpagetrue% |
| 693 |
\begin{pgfpicture} |
| 694 |
\pgfusepath{use as bounding box} |
| 695 |
\pgftransformshift{\pgfpointanchor{current page}{south west}} |
| 696 |
\pgftransformshift{\pgfpoint{1cm}{1cm}} |
| 697 |
\pgftext[left,base]{ |
| 698 |
\textcolor{red}{ |
| 699 |
Text absolutely positioned in |
| 700 |
the lower left corner.} |
| 701 |
} |
| 702 |
\end{pgfpicture} |
| 703 |
}% |
| 704 |
\begin{codeexample}[code only] |
| 705 |
\pgfrememberpicturepositiononpagetrue |
| 706 |
\begin{pgfpicture} |
| 707 |
\pgfusepath{use as bounding box} |
| 708 |
\pgftransformshift{\pgfpointanchor{current page}{south west}} |
| 709 |
\pgftransformshift{\pgfpoint{1cm}{1cm}} |
| 710 |
\pgftext[left,base]{ |
| 711 |
\textcolor{red}{ |
| 712 |
Text absolutely positioned in |
| 713 |
the lower left corner.} |
| 714 |
} |
| 715 |
\end{pgfpicture} |
| 716 |
\end{codeexample} |
| 717 |
% |
| 718 |
\end{predefinednode} |
| 719 |
|
| 720 |
There is also an option that allows you to create new special nodes quite |
| 721 |
similar to the above: |
| 722 |
% |
| 723 |
\begin{key}{/pgf/local bounding box=\meta{node name}} |
| 724 |
\keyalias{tikz} |
| 725 |
This defines a new node \meta{node name} whose size is the bounding box |
| 726 |
around all objects in the current scope starting at the position where this |
| 727 |
option was given. After the end of the scope, the \meta{node name} is still |
| 728 |
available. You can use this option to keep track of the size of a certain |
| 729 |
area. Note that excessive use of this option (keeping track of dozens of |
| 730 |
bounding boxes at the same time) will slow things down. |
| 731 |
% |
| 732 |
\begin{codeexample}[preamble={\usetikzlibrary{scopes}}] |
| 733 |
\begin{tikzpicture} |
| 734 |
\draw [help lines] (0,0) grid (3,2); |
| 735 |
{ [local bounding box=outer box] |
| 736 |
\draw (1,1) circle (.5) [local bounding box=inner box] (2,2) circle (.5); |
| 737 |
} |
| 738 |
\draw (outer box.south west) rectangle (outer box.north east); |
| 739 |
\draw[red] (inner box.south west) rectangle (inner box.north east); |
| 740 |
\end{tikzpicture} |
| 741 |
\end{codeexample} |
| 742 |
% |
| 743 |
\end{key} |
| 744 |
|
| 745 |
|
| 746 |
\subsection{Declaring New Shapes} |
| 747 |
|
| 748 |
There are only three predefined shapes, see |
| 749 |
Section~\ref{section-predefined-shapes}, so there must be some way of defining |
| 750 |
new shapes. Defining a shape is, unfortunately, a not-quite-trivial process. |
| 751 |
The reason is that shapes need to be both very flexible (their size will vary |
| 752 |
greatly according to circumstances) and they need to be constructed reasonably |
| 753 |
``fast''. \pgfname\ must be able to handle pictures with several hundreds of |
| 754 |
nodes and documents with thousands of nodes in total. It would not do if |
| 755 |
\pgfname\ had to compute and store, say, dozens of anchor positions for every |
| 756 |
node. |
| 757 |
|
| 758 |
|
| 759 |
\subsubsection{What Must Be Defined For a Shape?} |
| 760 |
|
| 761 |
In order to define a new shape, you must provide: |
| 762 |
% |
| 763 |
\begin{itemize} |
| 764 |
\item a \emph{shape name}, |
| 765 |
\item code for computing the \emph{saved anchors} and \emph{saved |
| 766 |
dimensions}, |
| 767 |
\item code for computing \emph{anchor} positions in terms of the saved |
| 768 |
anchors, |
| 769 |
\item optionally code for the \emph{background path} and \emph{foreground |
| 770 |
path}, |
| 771 |
\item optionally code for \emph{things to be drawn before or behind} the |
| 772 |
background and foreground paths. |
| 773 |
\item optionally a list of node parts. |
| 774 |
\end{itemize} |
| 775 |
|
| 776 |
|
| 777 |
\subsubsection{Normal Anchors Versus Saved Anchors} |
| 778 |
|
| 779 |
Anchors are special places in a shape. For example, the |north east| anchor, |
| 780 |
which is a normal anchor, lies at the upper right corner of the |rectangle| |
| 781 |
shape, as does |\northeast|, which is a saved anchor. The difference is the |
| 782 |
following: \emph{saved anchors are computed and stored for each node, anchors |
| 783 |
are only computed as needed.} The user only has access to the normal anchors, |
| 784 |
but a normal anchor can just ``copy'' or ``pass through'' the location of a |
| 785 |
saved anchor. |
| 786 |
|
| 787 |
The idea behind all this is that a shape can declare a very large number of |
| 788 |
normal anchors, but when a node of this shape is created, these anchors are not |
| 789 |
actually computed. However, this causes a problem: When we wish to reference an |
| 790 |
anchor of a node at some later time, we must still be able to compute the |
| 791 |
position of the anchor. For this, we may need a lot of information: What was |
| 792 |
the transformation matrix that was in force when the node was created? What was |
| 793 |
the size of the text box? What were the values of the different separation |
| 794 |
dimensions? And so on. |
| 795 |
|
| 796 |
To solve this problem, \pgfname\ will always compute the locations of all |
| 797 |
\emph{saved anchors} and store these positions. Then, when an normal anchor |
| 798 |
position is requested later on, the anchor position can be given just from |
| 799 |
knowing where the locations of the saved anchors are. |
| 800 |
|
| 801 |
As an example, consider the |rectangle| shape. For this shape two anchors are |
| 802 |
saved: The |\northeast| corner and the |\southwest| corner. A normal anchor |
| 803 |
like |north west| can now easily be expressed in terms of these coordinates: |
| 804 |
Take the $x$-position of the |\southwest| point and the $y$-position of the |
| 805 |
|\northeast| point. The |rectangle| shape currently defines 13 normal anchors, |
| 806 |
but needs only two saved anchors. Adding new anchors like a |south south east| |
| 807 |
anchor would not increase the memory and computation requirements of pictures. |
| 808 |
|
| 809 |
All anchors (both saved and normal) are specified in a local \emph{shape |
| 810 |
coordinate space}. This is also true for the background and foreground paths. |
| 811 |
The |\pgfnode| macro will automatically apply appropriate transformations to |
| 812 |
the coordinates so that the shape is shifted to the right anchor or otherwise |
| 813 |
transformed. |
| 814 |
|
| 815 |
|
| 816 |
\subsubsection{Command for Declaring New Shapes} |
| 817 |
|
| 818 |
The following command declares a new shape: |
| 819 |
% |
| 820 |
\begin{command}{\pgfdeclareshape\marg{shape name}\marg{shape specification}} |
| 821 |
This command declares a new shape named \meta{shape name}. The shape name |
| 822 |
can later be used in commands like |\pgfnode|. |
| 823 |
|
| 824 |
The \meta{shape specification} is some \TeX\ code containing calls to |
| 825 |
special commands that are only defined inside the \meta{shape |
| 826 |
specification} (similarly to commands like |\draw| that are only available |
| 827 |
inside the |{tikzpicture}| environment). |
| 828 |
|
| 829 |
\example Here is the code of the |coordinate| shape: |
| 830 |
% |
| 831 |
\begin{codeexample}[code only] |
| 832 |
\pgfdeclareshape{coordinate} |
| 833 |
{ |
| 834 |
\savedanchor\centerpoint{% |
| 835 |
\pgf@x=.5\wd\pgfnodeparttextbox% |
| 836 |
\pgf@y=.5\ht\pgfnodeparttextbox% |
| 837 |
\advance\pgf@y by -.5\dp\pgfnodeparttextbox% |
| 838 |
} |
| 839 |
\anchor{center}{\centerpoint} |
| 840 |
\anchorborder{\centerpoint} |
| 841 |
} |
| 842 |
\end{codeexample} |
| 843 |
|
| 844 |
The special commands are explained next. In the examples given for the |
| 845 |
special commands a new shape will be constructed, which we might call |
| 846 |
|simple rectangle|. It should behave like the normal rectangle shape, only |
| 847 |
without bothering about the fine details like inner and outer separations. |
| 848 |
The skeleton for the shape is the following. |
| 849 |
% |
| 850 |
\begin{codeexample}[code only] |
| 851 |
\pgfdeclareshape{simple rectangle}{ |
| 852 |
... |
| 853 |
} |
| 854 |
\end{codeexample} |
| 855 |
|
| 856 |
\begin{command}{\nodeparts\marg{list of node parts}} |
| 857 |
This command declares which parts make up nodes of this shape. A |
| 858 |
\emph{node part} is a (possibly empty) text label that is drawn when a |
| 859 |
node of the shape is created. |
| 860 |
|
| 861 |
By default, a shape has just one node part called |text|. However, |
| 862 |
there can be several node parts. For example, the |circle split| shape |
| 863 |
has two parts: the |text| part, which shows that the upper text, and a |
| 864 |
|lower| part, which shows the lower text. For the |circle split| shape |
| 865 |
the |\nodeparts| command was called with the argument |{text,lower}|. |
| 866 |
|
| 867 |
When a multipart node is created, the text labels are drawn in the |
| 868 |
sequences listed in the \meta{list of node parts}. For each node part, |
| 869 |
you must have declared one anchor and the \TeX-box of the part is |
| 870 |
placed at this anchor. For a node part called |XYZ| the \TeX-box |
| 871 |
|\pgfnodepartXYZbox| is placed at anchor |XYZ|. |
| 872 |
\end{command} |
| 873 |
|
| 874 |
\begin{command}{\savedanchor\marg{command}\marg{code}} |
| 875 |
This command declares a saved anchor. The argument \meta{command} |
| 876 |
should be a \TeX\ macro name like |\centerpoint|. |
| 877 |
|
| 878 |
The \meta{code} will be executed each time |\pgfnode| (or |
| 879 |
|\pgfmultipartnode|) is called to create a node of the shape |
| 880 |
\meta{shape name}. When the \meta{code} is executed, the \TeX-boxes of |
| 881 |
the node parts will contain the text labels of the node. Possibly, |
| 882 |
these box are void. For example, if there is just a |text| part, the |
| 883 |
node |\pgfnodeparttextbox| will be set up when the \meta{code} is |
| 884 |
executed. |
| 885 |
|
| 886 |
The \meta{code} can use the width, height, and depth of the box(es) to |
| 887 |
compute the location of the saved anchor. In addition, the \meta{code} |
| 888 |
can take into account the values of dimensions like |\pgfshapeminwidth| |
| 889 |
or |\pgfshapeinnerxsep|. Furthermore, the \meta{code} can take into |
| 890 |
consideration the values of any further shape-specific variables that |
| 891 |
are set at the moment when |\pgfnode| is called. |
| 892 |
|
| 893 |
The net effect of the \meta{code} should be to set the two \TeX\ |
| 894 |
dimensions |\pgf@x| and |\pgf@y|. One way to achieve this is to say |
| 895 |
|\pgfpoint{|\meta{x value}|}{|\meta{y value}|}| at the end of the |
| 896 |
\meta{code}, but you can also just set these variables. The values that |
| 897 |
|\pgf@x| and |\pgf@y| have after the code has been executed, let us |
| 898 |
call them $x$ and $y$, will be recorded and stored together with the |
| 899 |
node that is created by the command |\pgfnode|. |
| 900 |
|
| 901 |
The macro \meta{command} is defined to be |\pgfpoint{|$x$|}{|$y$|}|. |
| 902 |
However, the \meta{command} is only locally defined while anchor |
| 903 |
positions are being computed. Thus, it is possible to use very simple |
| 904 |
names for \meta{command}, like |\center| or |\a|, without causing a |
| 905 |
name-clash. (To be precise, very simple \meta{command} names will clash |
| 906 |
with existing names, but only locally inside the computation of anchor |
| 907 |
positions; and we do not need the normal |\center| command during these |
| 908 |
computations.) |
| 909 |
|
| 910 |
For our |simple rectangle| shape, we will need only one saved anchor: |
| 911 |
The upper right corner. The lower left corner could either be the |
| 912 |
origin or the ``mirrored'' upper right corner, depending on whether we |
| 913 |
want the text label to have its lower left corner at the origin or |
| 914 |
whether the text label should be centered on the origin. Either will be |
| 915 |
fine, for the final shape this will make no difference since the shape |
| 916 |
will be shifted anyway. So, let us assume that the text label is |
| 917 |
centered on the origin (this will be specified later on using the |
| 918 |
|text| anchor). We get the following code for the upper right corner: |
| 919 |
% |
| 920 |
\begin{codeexample}[code only] |
| 921 |
\savedanchor{\upperrightcorner}{ |
| 922 |
\pgf@y=.5\ht\pgfnodeparttextbox % height of the box, ignoring the depth |
| 923 |
\pgf@x=.5\wd\pgfnodeparttextbox % width of the box |
| 924 |
} |
| 925 |
\end{codeexample} |
| 926 |
|
| 927 |
If we wanted to take, say, the |\pgfshapeminwidth| into account, we |
| 928 |
could use the following code: |
| 929 |
% |
| 930 |
\begin{codeexample}[code only] |
| 931 |
\savedanchor{\upperrightcorner}{ |
| 932 |
\pgf@y=.\ht\pgfnodeparttextbox % height of the box |
| 933 |
\pgf@x=.\wd\pgfnodeparttextbox % width of the box |
| 934 |
\setlength{\pgf@xa}{\pgfshapeminwidth} |
| 935 |
\ifdim\pgf@x<.5\pgf@xa |
| 936 |
\pgf@x=.5\pgf@xa |
| 937 |
\fi |
| 938 |
} |
| 939 |
\end{codeexample} |
| 940 |
% |
| 941 |
Note that we could not have written |.5\pgfshapeminwidth| since the |
| 942 |
minimum width is stored in a ``plain text macro'', not as a real |
| 943 |
dimension. So if |\pgfshapeminwidth| depth were 2cm, writing |
| 944 |
|.5\pgfshapeminwidth| would yield the same as |.52cm|. |
| 945 |
|
| 946 |
In the ``real'' |rectangle| shape the code is somewhat more complex, |
| 947 |
but you get the basic idea. |
| 948 |
\end{command} |
| 949 |
% |
| 950 |
\begin{command}{\saveddimen\marg{command}\marg{code}} |
| 951 |
This command is similar to |\savedanchor|, only instead of setting |
| 952 |
\meta{command} to |\pgfpoint{|$x$|}{|$y$|}|, the \meta{command} is set |
| 953 |
just to (the value of) $x$. |
| 954 |
|
| 955 |
In the |simple rectangle| shape we might use a saved dimension to store |
| 956 |
the depth of the shape box. |
| 957 |
% |
| 958 |
\begin{codeexample}[code only] |
| 959 |
\saveddimen{\depth}{ |
| 960 |
\pgf@x=\dp\pgfnodeparttextbox |
| 961 |
} |
| 962 |
\end{codeexample} |
| 963 |
\end{command} |
| 964 |
% |
| 965 |
\begin{command}{\savedmacro\marg{command}\marg{code}} |
| 966 |
This command is similar to |\saveddimen|, only at some point in |
| 967 |
\meta{code}, \meta{command} should be defined appropriately, (this |
| 968 |
could be a value, or some text). |
| 969 |
|
| 970 |
In the |regular polygon| shape, a saved macro is used to store the |
| 971 |
number of sides of the polygon. |
| 972 |
% |
| 973 |
\begin{codeexample}[code only] |
| 974 |
\savedmacro{\sides}{\let\sides\pgfpolygonsides} |
| 975 |
\end{codeexample} |
| 976 |
\end{command} |
| 977 |
% |
| 978 |
\begin{command}{\anchor\marg{name}\marg{code}} |
| 979 |
This command declares an anchor named \meta{name}. Unlike for saved |
| 980 |
anchors, the \meta{code} will not be executed each time a node is |
| 981 |
declared. Rather, the \meta{code} is only executed when the anchor is |
| 982 |
specifically requested; either for anchoring the node during its |
| 983 |
creation or as a position in the shape referenced later on. |
| 984 |
|
| 985 |
The \meta{name} is a quite arbitrary string that is not ``passed down'' |
| 986 |
to the system level. Thus, names like |south| or |1| or |::| would all |
| 987 |
be fine. |
| 988 |
|
| 989 |
A saved anchor is not automatically also a normal anchor. If you wish |
| 990 |
to give the users access to a saved anchor you must declare a normal |
| 991 |
anchor that just returns the position of the saved anchor. |
| 992 |
|
| 993 |
When the \meta{code} is executed, all saved anchor macros will be |
| 994 |
defined. Thus, you can reference them in your \meta{code}. The effect |
| 995 |
of the \meta{code} should be to set the values of |\pgf@x| and |\pgf@y| |
| 996 |
to the coordinates of the anchor. |
| 997 |
|
| 998 |
Let us consider some example for the |simple rectangle| shape. First, |
| 999 |
we would like to make the upper right corner publicly available, for |
| 1000 |
example as |north east|: |
| 1001 |
% |
| 1002 |
\begin{codeexample}[code only] |
| 1003 |
\anchor{north east}{\upperrightcorner} |
| 1004 |
\end{codeexample} |
| 1005 |
|
| 1006 |
The |\upperrightcorner| macro will set |\pgf@x| and |\pgf@y| to the |
| 1007 |
coordinates of the upper right corner. Thus, |\pgf@x| and |\pgf@y| will |
| 1008 |
have exactly the right values at the end of the anchor's code. |
| 1009 |
|
| 1010 |
Next, let us define a |north west| anchor. For this anchor, we can |
| 1011 |
negate the |\pgf@x| variable: |
| 1012 |
% |
| 1013 |
\begin{codeexample}[code only] |
| 1014 |
\anchor{north west}{ |
| 1015 |
\upperrightcorner |
| 1016 |
\pgf@x=-\pgf@x |
| 1017 |
} |
| 1018 |
\end{codeexample} |
| 1019 |
|
| 1020 |
Finally, it is a good idea to always define a |center| anchor, which |
| 1021 |
will be the default location for a shape. |
| 1022 |
% |
| 1023 |
\begin{codeexample}[code only] |
| 1024 |
\anchor{center}{\pgfpointorigin} |
| 1025 |
\end{codeexample} |
| 1026 |
|
| 1027 |
You might wonder whether we should not take into consideration that the |
| 1028 |
node is not placed at the origin, but has been shifted somewhere. |
| 1029 |
However, the anchor positions are always specified in the shape's |
| 1030 |
``private'' coordinate system. The ``outer'' transformation that has |
| 1031 |
been applied to the shape upon its creation is applied automatically to |
| 1032 |
the coordinates returned by the anchor's \meta{code}. |
| 1033 |
|
| 1034 |
Our |simple rectangle| only has one text label (node part) called |
| 1035 |
|text|. This is the default situation, so we do not need to do |
| 1036 |
anything. For the |text| node part we must set up a |text| anchor. Upon |
| 1037 |
creation of a node, this anchor will be made to coincide with the left |
| 1038 |
endpoint of the baseline of the text label (within the private |
| 1039 |
coordinate system of the shape). By default, the |text| anchor is at |
| 1040 |
the origin, but you may change this. For example, we would say |
| 1041 |
% |
| 1042 |
\begin{codeexample}[code only] |
| 1043 |
\anchor{text}{% |
| 1044 |
\upperrightcorner% |
| 1045 |
\pgf@x=-\pgf@x% |
| 1046 |
\pgf@y=-\pgf@y% |
| 1047 |
} |
| 1048 |
\end{codeexample} |
| 1049 |
to center the text label on the origin in the shape coordinate space. |
| 1050 |
Note that we could \emph{not} have written the following: |
| 1051 |
% |
| 1052 |
\begin{codeexample}[code only] |
| 1053 |
\anchor{text}{\pgfpoint{-.5\wd\pgfnodeparttextbox}{-.5\ht\pgfnodeparttextbox}} |
| 1054 |
\end{codeexample} |
| 1055 |
% |
| 1056 |
Do you see why this is wrong? The problem is that the box |
| 1057 |
|\pgfnodeparttextbox| will most likely not have the correct size when |
| 1058 |
the anchor is computed. After all, the anchor position might be |
| 1059 |
recomputed at a time when several other nodes have been created. |
| 1060 |
|
| 1061 |
If a shape has several node parts, we would have to define an anchor |
| 1062 |
for each part. |
| 1063 |
\end{command} |
| 1064 |
|
| 1065 |
\begin{command}{\deferredanchor\marg{name}\marg{code}} |
| 1066 |
This command declares an anchor named \meta{name}. It works like |
| 1067 |
|\anchor|. However, unlike for anchors declared by |\anchor|, |
| 1068 |
\meta{name} will \emph{not} be expanded during the shape declaration |
| 1069 |
(i.e.\ not during |\pgfdeclareshape|). Rather, the \meta{name} is |
| 1070 |
expanded when the \emph{node} is actually used (with |\pgfnode| or more |
| 1071 |
likely with |\node|). This may be useful if the anchor name is context |
| 1072 |
dependent (depending, for example, on the value of a key). |
| 1073 |
% |
| 1074 |
\begin{codeexample}[code only] |
| 1075 |
\makeatletter |
| 1076 |
\def\foo{foo} |
| 1077 |
\pgfdeclareshape{simple shape}{% |
| 1078 |
\savedanchor{\center}{% |
| 1079 |
\pgfpointorigin} |
| 1080 |
\anchor{center}{\center} |
| 1081 |
\savedanchor{\anchorfoo}{% |
| 1082 |
\pgf@x=1cm |
| 1083 |
\pgf@y=0cm} |
| 1084 |
\deferredanchor{anchor \foo}{\anchorfoo}} |
| 1085 |
|
| 1086 |
\begin{tikzpicture} |
| 1087 |
\node[simple shape] (Test1) at (0,0) {}; |
| 1088 |
\fill (Test1.anchor foo) circle (2pt) node[below] {anchor foo anchor}; |
| 1089 |
% |
| 1090 |
\def\foo{bar} |
| 1091 |
\node[simple shape] (Test2) at (2,2) {}; |
| 1092 |
\fill (Test2.anchor bar) circle (2pt) node[below] {anchor bar anchor}; |
| 1093 |
\end{tikzpicture} |
| 1094 |
\end{codeexample} |
| 1095 |
\end{command} |
| 1096 |
% |
| 1097 |
\begin{command}{\anchorborder\marg{code}} |
| 1098 |
A \emph{border anchor} is an anchor point on the border of the shape. |
| 1099 |
What exactly is considered as the ``border'' of the shape depends on |
| 1100 |
the shape. |
| 1101 |
|
| 1102 |
When the user requests a point on the border of the shape using the |
| 1103 |
|\pgfpointshapeborder| command, the \meta{code} will be executed to |
| 1104 |
discern this point. When the execution of the \meta{code} starts, the |
| 1105 |
dimensions |\pgf@x| and |\pgf@y| will have been set to a location $p$ |
| 1106 |
in the shape's coordinate system, and relative to the anchor |center|. |
| 1107 |
Note that |\pgfpointshapeborder| will produce an error if the shape does |
| 1108 |
not contain the |center| anchor. |
| 1109 |
|
| 1110 |
It is now the job of the \meta{code} to set up |\pgf@x| and |\pgf@y| |
| 1111 |
such that they specify the point on the shape's border that lies on a |
| 1112 |
straight line from the shape's center to the point $p$. Usually, this is |
| 1113 |
a somewhat complicated computation, involving many case distinctions and |
| 1114 |
some basic math. Note that the output coordinates must be returned in the |
| 1115 |
shape's coordinate system, \emph{no longer} relative to the |center| |
| 1116 |
anchor. While these different points of reference are only noticeable if |
| 1117 |
the |center| anchor is not at the origin of the shape's coordinate system, |
| 1118 |
it implies that ``doing nothing'' as a border anchor, i.e., returning the |
| 1119 |
point that was fed to |\pgfpointshapeborder| requires adding the |center| |
| 1120 |
anchor to the input coordinates. |
| 1121 |
|
| 1122 |
For our |simple rectangle| we must compute a point on the border of a |
| 1123 |
rectangle whose one corner is the origin (ignoring the depth for |
| 1124 |
simplicity) and whose other corner is |\upperrightcorner|. The |
| 1125 |
following code might be used: |
| 1126 |
% |
| 1127 |
\begin{codeexample}[code only] |
| 1128 |
\anchorborder{% |
| 1129 |
% Call a function that computes a border point. Since this |
| 1130 |
% function will modify dimensions like \pgf@x, we must move them to |
| 1131 |
% other dimensions. |
| 1132 |
\@tempdima=\pgf@x |
| 1133 |
\@tempdimb=\pgf@y |
| 1134 |
\pgfpointborderrectangle{\pgfpoint{\@tempdima}{\@tempdimb}}{\upperrightcorner} |
| 1135 |
} |
| 1136 |
\end{codeexample} |
| 1137 |
\end{command} |
| 1138 |
% |
| 1139 |
\begin{command}{\backgroundpath\marg{code}} |
| 1140 |
This command specifies the path that ``makes up'' the background of the |
| 1141 |
shape. Note that the shape cannot prescribe what is going to happen |
| 1142 |
with the path: It might be drawn, shaded, filled, or even thrown away. |
| 1143 |
If you want to specify that something should ``always'' happen when |
| 1144 |
this shape is drawn (for example, if the shape is a stop-sign, we |
| 1145 |
\emph{always} want it to be filled with a red color), you can use |
| 1146 |
commands like |\beforebackgroundpath|, explained below. |
| 1147 |
|
| 1148 |
When the \meta{code} is executed, all saved anchors will be in effect. |
| 1149 |
The \meta{code} should contain path construction commands. |
| 1150 |
|
| 1151 |
For our |simple rectangle|, the following code might be used: |
| 1152 |
% |
| 1153 |
\begin{codeexample}[code only] |
| 1154 |
\backgroundpath{ |
| 1155 |
\pgfpathrectanglecorners |
| 1156 |
{\upperrightcorner} |
| 1157 |
{\pgfpointscale{-1}{\upperrightcorner}} |
| 1158 |
} |
| 1159 |
\end{codeexample} |
| 1160 |
% |
| 1161 |
As the name suggests, the background path is used ``behind'' the text |
| 1162 |
labels. Thus, this path is used first, then the text labels are drawn, |
| 1163 |
possibly obscuring part of the path. |
| 1164 |
\end{command} |
| 1165 |
% |
| 1166 |
\begin{command}{\foregroundpath\marg{code}} |
| 1167 |
This command works like |\backgroundpath|, only it is invoked after the |
| 1168 |
text labels have been drawn. This means that this path can possibly |
| 1169 |
obscure (part of) the text labels. |
| 1170 |
\end{command} |
| 1171 |
% |
| 1172 |
\begin{command}{\behindbackgroundpath\marg{code}} |
| 1173 |
Unlike the previous two commands, \meta{code} should not only construct |
| 1174 |
a path, it should also use this path in whatever way is appropriate. |
| 1175 |
For example, the \meta{code} might fill some area with a uniform color. |
| 1176 |
|
| 1177 |
Whatever the \meta{code} does, it does it first. This means that any |
| 1178 |
drawing done by \meta{code} will be even behind the background path. |
| 1179 |
|
| 1180 |
Note that the \meta{code} is protected with a |{pgfscope}|. |
| 1181 |
\end{command} |
| 1182 |
% |
| 1183 |
\begin{command}{\beforebackgroundpath\marg{code}} |
| 1184 |
This command works like |\behindbackgroundpath|, only the \meta{code} |
| 1185 |
is executed after the background path has been used, but before the |
| 1186 |
texts label are drawn. |
| 1187 |
\end{command} |
| 1188 |
% |
| 1189 |
\begin{command}{\behindforegroundpath\marg{code}} |
| 1190 |
The \meta{code} is executed after the text labels have been drawn, but |
| 1191 |
before the foreground path is used. |
| 1192 |
\end{command} |
| 1193 |
% |
| 1194 |
\begin{command}{\beforeforegroundpath\marg{code}} |
| 1195 |
This \meta{code} is executed at the very end. |
| 1196 |
\end{command} |
| 1197 |
% |
| 1198 |
\begin{command}{\inheritsavedanchors|[from=|\marg{another shape name}|]|} |
| 1199 |
This command allows you to inherit the code for saved anchors from |
| 1200 |
\meta{another shape name}. The idea is that if you wish to create a new |
| 1201 |
shape that is just a small modification of a another shape, you can |
| 1202 |
recycle the code used for \meta{another shape name}. |
| 1203 |
|
| 1204 |
The effect of this command is the same as if you had called |
| 1205 |
|\savedanchor| and |\saveddimen| for each saved anchor or saved |
| 1206 |
dimension declared in \meta{another shape name}. Thus, it is not |
| 1207 |
possible to ``selectively'' inherit only some saved anchors, you always |
| 1208 |
have to inherit all saved anchors from another shape. However, you can |
| 1209 |
inherit the saved anchors of more than one shape by calling this |
| 1210 |
command several times. |
| 1211 |
\end{command} |
| 1212 |
% |
| 1213 |
\begin{command}{\inheritbehindbackgroundpath|[from=|\marg{another shape name}|]|} |
| 1214 |
This command can be used to inherit the code used for the drawings |
| 1215 |
behind the background path from \meta{another shape name}. |
| 1216 |
\end{command} |
| 1217 |
% |
| 1218 |
\begin{command}{\inheritbackgroundpath|[from=|\marg{another shape name}|]|} |
| 1219 |
Inherits the background path code from \meta{another shape name}. |
| 1220 |
\end{command} |
| 1221 |
% |
| 1222 |
\begin{command}{\inheritbeforebackgroundpath|[from=|\marg{another shape name}|]|} |
| 1223 |
Inherits the before background path code from \meta{another shape |
| 1224 |
name}. |
| 1225 |
\end{command} |
| 1226 |
% |
| 1227 |
\begin{command}{\inheritbehindforegroundpath|[from=|\marg{another shape name}|]|} |
| 1228 |
Inherits the behind foreground path code from \meta{another shape |
| 1229 |
name}. |
| 1230 |
\end{command} |
| 1231 |
% |
| 1232 |
\begin{command}{\inheritforegroundpath|[from=|\marg{another shape name}|]|} |
| 1233 |
Inherits the foreground path code from \meta{another shape name}. |
| 1234 |
\end{command} |
| 1235 |
% |
| 1236 |
\begin{command}{\inheritbeforeforegroundpath|[from=|\marg{another shape name}|]|} |
| 1237 |
Inherits the before foreground path code from \meta{another shape |
| 1238 |
name}. |
| 1239 |
\end{command} |
| 1240 |
% |
| 1241 |
\begin{command}{\inheritanchor|[from=|\marg{another shape name}|]|\marg{name}} |
| 1242 |
Inherits the code of one specific anchor named \meta{name} from |
| 1243 |
\meta{another shape name}. Thus, unlike saved anchors, which must be |
| 1244 |
inherited collectively, normal anchors can and must be inherited |
| 1245 |
individually. |
| 1246 |
\end{command} |
| 1247 |
% |
| 1248 |
\begin{command}{\inheritanchorborder|[from=|\marg{another shape name}|]|} |
| 1249 |
Inherits the border anchor code from \meta{another shape name}. |
| 1250 |
\end{command} |
| 1251 |
|
| 1252 |
The following example shows how a shape can be defined that relies heavily |
| 1253 |
on inheritance: |
| 1254 |
% |
| 1255 |
\makeatletter |
| 1256 |
\begin{codeexample}[ |
| 1257 |
preamble={\usetikzlibrary{shapes.geometric}}, |
| 1258 |
pre={\makeatletter}, |
| 1259 |
] |
| 1260 |
\pgfdeclareshape{document}{ |
| 1261 |
\inheritsavedanchors[from=rectangle] % this is nearly a rectangle |
| 1262 |
\inheritanchorborder[from=rectangle] |
| 1263 |
\inheritanchor[from=rectangle]{center} |
| 1264 |
\inheritanchor[from=rectangle]{north} |
| 1265 |
\inheritanchor[from=rectangle]{south} |
| 1266 |
\inheritanchor[from=rectangle]{west} |
| 1267 |
\inheritanchor[from=rectangle]{east} |
| 1268 |
% ... and possibly more |
| 1269 |
\backgroundpath{% this is new |
| 1270 |
% store lower right in xa/ya and upper right in xb/yb |
| 1271 |
\southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y |
| 1272 |
\northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y |
| 1273 |
% compute corner of ``flipped page'' |
| 1274 |
\pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter |
| 1275 |
\pgf@yc=\pgf@yb \advance\pgf@yc by-5pt |
| 1276 |
% construct main path |
| 1277 |
\pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}} |
| 1278 |
\pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}} |
| 1279 |
\pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}} |
| 1280 |
\pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} |
| 1281 |
\pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}} |
| 1282 |
\pgfpathclose |
| 1283 |
% add little corner |
| 1284 |
\pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}} |
| 1285 |
\pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} |
| 1286 |
\pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} |
| 1287 |
\pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} |
| 1288 |
} |
| 1289 |
}\hskip-1.2cm |
| 1290 |
\begin{tikzpicture} |
| 1291 |
\node[shade,draw,shape=document,inner sep=2ex] (x) {Remark}; |
| 1292 |
\node[fill=yellow!80!black,draw,ellipse,double] |
| 1293 |
at ([shift=(-80:3cm)]x) (y) {Use Case}; |
| 1294 |
|
| 1295 |
\draw[dashed] (x) -- (y); |
| 1296 |
\end{tikzpicture} |
| 1297 |
\end{codeexample} |
| 1298 |
% |
| 1299 |
\end{command} |
| 1300 |
|
| 1301 |
|
| 1302 |
%%% Local Variables: |
| 1303 |
%%% mode: latex |
| 1304 |
%%% TeX-master: "pgfmanual" |
| 1305 |
%%% End: |