From 6f9e1680085e7bb4d258f6f8116369d122e196e1 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 16 Jan 2023 03:03:27 +0000 Subject: CTAN sync 202301160303 --- graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex | 1305 +++++++++++++++++++++ 1 file changed, 1305 insertions(+) create mode 100644 graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex (limited to 'graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex') diff --git a/graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex b/graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex new file mode 100644 index 0000000000..19499ec551 --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex @@ -0,0 +1,1305 @@ +% Copyright 2019 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Nodes and Shapes} + +\label{section-shapes} + +This section describes the |shapes| module. + +\begin{pgfmodule}{shapes} + This module defines commands both for creating nodes and for creating + shapes. The package is loaded automatically by |pgf|, but you can load it + manually if you have only included |pgfcore|. +\end{pgfmodule} + + +\subsection{Overview} + +\pgfname\ comes with a sophisticated set of commands for creating \emph{nodes} +and \emph{shapes}. A \emph{node} is a graphical object that consists +(typically) of (one or more) text labels and some additional stroked or filled +paths. Each node has a certain \emph{shape}, which may be something simple like +a |rectangle| or a |circle|, but it may also be something complicated like a +|uml class diagram| (this shape is currently not implemented, though). +Different nodes that have the same shape may look quite different, however, +since shapes (need not) specify whether the shape path is stroked or filled. + + +\subsubsection{Creating and Referencing Nodes} + +You create a node by calling the macro |\pgfnode| or the more general +|\pgfmultipartnode|. This macro takes several parameters and draws the +requested shape at a certain position. In addition, it will ``remember'' the +node's position within the current |{pgfpicture}|. You can then, later on, +refer to the node's position. Coordinate transformations are ``fully +supported'', which means that if you used coordinate transformations to shift +or rotate the shape of a node, the node's position will still be correctly +determined by \pgfname. This is \emph{not} the case if you use canvas +transformations instead. + + +\subsubsection{Anchors} + +An important property of a node or a shape in general are its \emph{anchors}. +Anchors are ``important'' positions in a shape. For example, the |center| +anchor lies at the center of a shape, the |north| anchor is usually ``at the +top, in the middle'' of a shape, the |text| anchor is the lower left corner of +the shape's text label (if present), and so on. + +Anchors are important both when you create a node and when you reference it. +When you create a node, you specify the node's ``position'' by asking \pgfname\ +to place the shape in such a way that a certain anchor lies at a certain point. +For example, you might ask that the node is placed such that the |north| anchor +is at the origin. This will effectively cause the node to be placed below the +origin. + +When you reference a node, you always reference an anchor of the node. For +example, when you request the ``|north| anchor of the node just placed'' you +will get the origin. However, you can also request the ``|south| anchor of this +node'', which will give you a point somewhere below the origin. When a +coordinate transformation was in force at the time of creation of a node, all +anchors are also transformed accordingly. + + +\subsubsection{Layers of a Shape} + +The simplest shape, the |coordinate|, has just one anchor, namely the |center|, +and a label (which is usually empty). More complicated shapes like the +|rectangle| shape also have a \emph{background path}. This is a \pgfname-path +that is defined by the shape. The shape does not prescribe what should happen +with the path: When a node is created, this path may be stroked (resulting in a +frame around the label), filled (resulting in a background color for the text), +or just discarded. + +Although most shapes consist just of a background path plus some label text, +when a shape is drawn, up to seven different layers are drawn: +% +\begin{enumerate} + \item The ``behind the background layer''. Unlike the background path, + which can be used in different ways by different nodes, the graphic + commands given for this layer will always stroke or always fill the + path they construct. They might also insert some text that is ``behind + everything''. + \item The background path layer. How this path is used depends on the + arguments of the |\pgfnode| command. + \item The ``before the background path layer''. This layer works like the + first one, only the commands of this layer are executed after the + background path has been used (in whatever way the creator of the node + chose). + \item The label layer. This layer inserts the node's text box(es). + \item The ``behind the foreground layer''. This layer, like the first + layer, once more contains graphic commands that are ``simply + executed''. + \item The foreground path layer. This path is treated in the same way as + the background path, only it is drawn after the label text has been + drawn. + \item The ``before the foreground layer''. +\end{enumerate} + +Which of these layers are actually used depends on the shape. + + +\subsubsection{Node Parts} + +A shape typically does not consist only of different background and foreground +paths, but it may also have text labels. Indeed, for many shapes the text +labels are the more important part of the shape. + +Most shapes will have only one text label. In this case, this text label is +simply passed as a parameter to the |\pgfnode| command. When the node is drawn, +the text label is shifted around such that its lower left corner is at the +|text| anchor of the node. + +More complicated shapes may have more than one text label. Nodes of such shapes +are called \emph{multipart nodes}. The different \emph{node parts} are simply +the different text labels. For example, a |uml class| shape might have a +|class name| part, a |method| part and an |attributes| part. Indeed, single +part nodes are a special case of multipart nodes: They only have one part named +|text|. + +When a shape is declared, you must specify the node parts. There is a simple +command called |\nodeparts| that takes a list of the part names as input. When +you create a node of a multipart shape, for each part of the node you must have +set up a \TeX-box containing the text of the part. For a part named |XYZ| you +must set up the box |\pgfnodepartXYZbox|. The box will be placed at the anchor +|XYZ|. See the description of |\pgfmultipartnode| for more details. + + +\subsection{Creating Nodes} + +\subsubsection{Creating Simple Nodes} + +\begin{command}{\pgfnode\marg{shape}\marg{anchor}\marg{label text}\marg{name}\marg{path usage command}} + This command creates a new node. The \meta{shape} of the node must have + been declared previously using |\pgfdeclareshape|. + + The shape is shifted such that the \meta{anchor} is at the origin. In order + to place the shape somewhere else, use the coordinate transformation prior + to calling this command. + + The \meta{name} is a name for later reference. If no name is given, nothing + will be ``saved'' for the node, it will just be drawn. + + The \meta{path usage command} is executed for the background and the + foreground path (if the shape defines them). + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (4,3); + { + \pgftransformshift{\pgfpoint{1.5cm}{1cm}} + \pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}} + } + { + \color{red!20} + \pgftransformrotate{10} + \pgftransformshift{\pgfpoint{3cm}{1cm}} + \pgfnode{rectangle}{center} + {\color{black}Hello World}{hellonode}{\pgfusepath{fill}} + } +\end{tikzpicture} +\end{codeexample} + + As can be seen, all coordinate transformations are also applied to the text + of the shape. Sometimes, it is desirable that the transformations are + applied to the point where the shape will be anchored, but you do not wish + the shape itself to be transformed. In this case, you should call + |\pgftransformresetnontranslations| prior to calling the |\pgfnode| + command. + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (4,3); + { + \color{red!20} + \pgftransformrotate{10} + \pgftransformshift{\pgfpoint{3cm}{1cm}} + \pgftransformresetnontranslations + \pgfnode{rectangle}{center} + {\color{black}Hello World}{hellonode}{\pgfusepath{fill}} + } +\end{tikzpicture} +\end{codeexample} + + The \meta{label text} is typeset inside the \TeX-box |\pgfnodeparttextbox|. + This box is shown at the |text| anchor of the node, if the node has a + |text| part. See the description of |\pgfmultipartnode| for details. +\end{command} + + +\subsubsection{Creating Multi-Part Nodes} + +\begin{command}{\pgfmultipartnode\marg{shape}\marg{anchor}\marg{name}\marg{path usage command}} + This command is the more general (and less user-friendly) version of the + |\pgfnode| command. While the |\pgfnode| command can only be used for + shapes that have a single part (which is the case for most shapes), this + command can also be used with multi-part nodes. + + When this command is called, for each node part of the node you must have + set up one \TeX-box. Suppose the shape has two parts: The |text| part and + the |lower| part. Then, prior to calling |\pgfmultipartnode|, you must have + set up the boxes |\pgfnodeparttextbox| and |\pgfnodepartlowerbox|. These + boxes may contain any \TeX-text. The shape code will then compute the + positions of the shape's anchors based on the sizes of the these shapes. + Finally, when the node is drawn, the boxes are placed at the anchor + positions |text| and |lower|. + % +\begin{codeexample}[preamble={\usetikzlibrary{shapes}}] +\setbox\pgfnodeparttextbox=\hbox{$q_1$} +\setbox\pgfnodepartlowerbox=\hbox{01} +\begin{pgfpicture} + \pgfmultipartnode{circle split}{center}{my state}{\pgfusepath{stroke}} +\end{pgfpicture} +\end{codeexample} + + \emph{Note:} Be careful when using the |\setbox| command inside a + |{pgfpicture}| command. You will have to use |\pgfinterruptpath| at the + beginning of the box and |\endpgfinterruptpath| at the end of the box to + make sure that the box is typeset correctly. In the above example this + problem was sidestepped by moving the box construction outside the + environment. + + \emph{Note:} It is not necessary to use |\newbox| for every node part + name. Although you need a different box for each part of a single shape, + two different shapes may very well use the same box even when the names of + the parts are different. Suppose you have a |circle split| shape that has a + |lower| part and you have a |uml class| shape that has a |methods| part. + Then, in order to avoid exhausting \TeX's limited number of box registers, + you can say + % +\begin{codeexample}[code only] +\newbox\pgfnodepartlowerbox +\let\pgfnodepartmethodsbox=\pgfnodepartlowerbox +\end{codeexample} + % + Also, when you have a node part name with spaces like |class name|, it may + be useful to create an alias: + % +\begin{codeexample}[code only] +\newbox\mybox +\expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox +\end{codeexample} + % +\end{command} + +\begin{command}{\pgfcoordinate\marg{name}\marg{coordinate}} + This command creates a node of shape |coordinate| at the given + \meta{coordinate}. Exactly the same effect can be achieved using first a + shift of the coordinate system to \meta{coordinate}, followed by creating a + node of shape |coordinate| named \meta{name}. However, this command is + easier and more natural to use and, more importantly, it is much faster. +\end{command} + +\begin{command}{\pgfnodealias\marg{new name}\marg{existing node}} + This command does not actually create a new node. Rather, it allows you to + subsequently access the node \meta{existing node} using the name \meta{new + name}. +\end{command} + +\begin{command}{\pgfnoderename\marg{new name}\marg{existing node}} + This command renames an existing node. +\end{command} + +There are a number of values that have an influence on the size of a node. +These values are stored in the following keys. + +\begin{key}{/pgf/minimum width=\meta{dimension} (initially 1pt)} +\keyalias{tikz} + This key stores the \emph{recommended} minimum width of a shape. Thus, when + a shape is drawn and when the shape's width would be smaller than + \meta{dimension}, the shape's width is enlarged by adding some empty space. + + Note that this value is just a recommendation. A shape may choose to ignore + this key. + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{minimum width=3cm} + \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} +\end{tikzpicture} +\end{codeexample} + % +\end{key} + +\begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)} +\keyalias{tikz} + Works like |/pgf/minimum width|. +\end{key} + +\begin{key}{/pgf/minimum size=\meta{dimension}} +\keyalias{tikz} + This style both |/pgf/minimum width| and |/pgf/minimum height| to \meta{dimension}. +\end{key} + +\begin{key}{/pgf/inner xsep=\meta{dimension} (initially 0.3333em)} +\keyalias{tikz} + This key stores the \emph{recommended} horizontal inner separation between + the label text and the background path. As before, this value is just a + recommendation and a shape may choose to ignore this key. + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{inner xsep=1cm} + \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} +\end{tikzpicture} +\end{codeexample} + % +\end{key} + +\begin{key}{/pgf/inner ysep=\meta{dimension} (initially 0.3333em)} +\keyalias{tikz} + Works like |/pgf/inner xsep|. +\end{key} + +\begin{key}{/pgf/inner sep=\meta{dimension}} +\keyalias{tikz} + This style sets both |/pgf/inner xsep| and |/pgf/inner ysep| to + \meta{dimension}. +\end{key} + +\begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)} +\keyalias{tikz} + This key stores the recommended horizontal separation between the + background path and the ``outer anchors''. For example, if \meta{dimension} + is |1cm| then the |east| anchor will be 1cm to the right of the right + border of the background path. As before, this value is just a + recommendation. + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{outer xsep=.5cm} + \pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}} + + \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} + % +\end{key} + +\begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)} +\keyalias{tikz} + Works like |/pgf/outer xsep|. +\end{key} + +\begin{key}{/pgf/outer sep=\meta{dimension}} +\keyalias{tikz} + This style sets both |/pgf/outer xsep| and |/pgf/outer ysep| to + \meta{dimension}. +\end{key} + + +\subsubsection{Deferred Node Positioning} +\label{section-shapes-deferred-node-positioning} + +Normally, when a node is created using a command like |\pgfnode|, the node is +immediately inserted into the current picture. In particular, you have no +chance to change the position of a created node after it has been created. +Using |\pgfpositionnodelater| in concert with |\pgfpositionnodenow|, you can +create a node whose position is determined only at some later time. + +\begin{command}{\pgfpositionnodelater\marg{macro name}} + This command is not a replacement for |\pgfnode|. Rather, when this command + is used in a scope, all subsequent node creations in this scope will be + affected in the following way: When a node is created, it is not inserted + into the current picture. Instead, it is stored in the box + |\pgfpositionnodelaterbox|. Furthermore, the node is not relevant for the + picture's bounding box, but a bounding box for the node is computed and + stored in the macros |\pgfpositionnodelaterminx| to + |\pgfpositionnodelatermaxy|. Then, the \meta{macro name} is called with the + following macros set up: + + \begin{command}{\pgfpositionnodelaterbox} + A box register number (|0| currently) that stores the node's paths and + texts. You should move the contents of this box to a box of your choice + inside \meta{macro name}. + \end{command} + + \begin{command}{\pgfpositionnodelatername} + The name of the just-created-node. This name will be the originally + ``desired'' name of the box plus the fixed prefix + |not yet positionedPGFINTERNAL|. The idea is to ensure that the + original name is not inadvertently used before the node is actually + positioned. When |\pgfpositionnodenow| is called, it will change the + name to the + original name. + \end{command} + + \begin{command}{\pgfpositionnodelaterminx} + The minimal $x$-position of a bounding box of the node. This bounding + box refers to the node when it is positioned with the anchor at the + origin. It is guaranteed, that this macro will contain a dimension in + the format \meta{number}|pt|. + \end{command} + % + \begin{command}{\pgfpositionnodelaterminy} + \end{command} + % + \begin{command}{\pgfpositionnodelatermaxx} + \end{command} + % + \begin{command}{\pgfpositionnodelatermaxy} + \end{command} + + Once a late node has been created, you can add arbitrary code in the same + picture. Then, at some later point, you call |\pgfpositionnodenow| to + finally position the node at a given position. At this point, the above + macros must have the exact same values they had when \meta{macro name} was + called. Note that the above macros are local to a scope that ends right + after the call to \meta{macro name}, so it is your job to copy the values + to safety inside \meta{macro name}. + + The following two macros will also be set inside the call to \meta{macro + name}, but they are only ``informative'' in the sense that you need + \emph{not} restore these macros when |\pgfpositionnodenow| is called. + + \begin{command}{\pgfpositionnodelaterpath} + This macro stores the path of the background of the node. See + Section~\ref{section-soft-paths} for an overview of how these paths are + encode. + \end{command} + + By setting \meta{macro name} to |\relax| (which is the default), you can + switch off the whole mechanism. When a picture is interrupted, this is done + automatically. +\end{command} + +\begin{command}{\pgfpositionnodenow\marg{coordinate}} + This command is used to position a node that has previously been created + using the command |\pgfpositionnodelater|. When |\pgfpositionnodenow| is + called, the macros and boxes mentioned in the description of + |\pgfpositionnodenow| must be set to the value they had when the + \meta{macro name} was called. Provided this is the case, this command will + insert the box into the current picture, shifted by \meta{coordinate}. + Then, the late code (see below) is called. Subsequently, you can refer to + the node with its original name as if it had just been created. + % +\begin{codeexample}[] +\newbox\mybox + +\def\mysaver{ + \global\setbox\mybox=\box\pgfpositionnodelaterbox + \global\let\myname=\pgfpositionnodelatername + \global\let\myminx=\pgfpositionnodelaterminx + \global\let\myminy=\pgfpositionnodelaterminy + \global\let\mymaxx=\pgfpositionnodelatermaxx + \global\let\mymaxy=\pgfpositionnodelatermaxy +} + +\begin{tikzpicture} + { + \pgfpositionnodelater{\mysaver} + \node [fill=blue!20,below,rotate=30] (hi) {Hello world}; + } + \draw [help lines] (0,0) grid (3,2); + + \let\pgfpositionnodelatername=\myname + \let\pgfpositionnodelaterminx=\myminx + \let\pgfpositionnodelaterminy=\myminy + \let\pgfpositionnodelatermaxx=\mymaxx + \let\pgfpositionnodelatermaxy=\mymaxy + \setbox\pgfpositionnodelaterbox=\box\mybox + \pgfpositionnodenow{\pgfqpoint{2cm}{2cm}} + + \draw (hi) -- (0,0); +\end{tikzpicture} +\end{codeexample} + % +\end{command} + +\begin{command}{\pgfnodepostsetupcode\marg{node name}\marg{code}} + When you call this macro inside a scope for which the + |\pgfpositionnodelater| has been called, the \meta{code} will be stored + internally. Later, when the node named \meta{node name} is actually + positioned using |\pgfpositionnodenow|, the \meta{code} will be executed. + When this macro is called multiple times with the same \meta{node name}, + the \meta{code} accumulates. However, When |\pgfpositionnodenow| is called, + the code stored for the node is cleared. + + The main purpose of this mechanism is to allow \tikzname\ to store + so-called ``late options'' with a node that will be positioned only later. +\end{command} + + +\subsection{Using Anchors} + +Each shape defines a set of anchors. We saw already that the anchors are used +when the shape is drawn: the shape is placed in such a way that the given +anchor is at the origin (which in turn is typically translated somewhere else). + +One has to look up the set of anchors of each shape, there is no ``default'' +set of anchors, except for the |center| anchor, which should always be present. +Also, most shapes will declare anchors like |north| or |east|, but this is not +guaranteed. + + +\subsubsection{Referencing Anchors of Nodes in the Same Picture} + +Once a node has been defined, you can refer to its anchors using the following +commands: + +\begin{command}{\pgfpointanchor\marg{node}\marg{anchor}} + This command is another ``point command'' like the commands described in + Section~\ref{section-points}. It returns the coordinate of the given + \meta{anchor} in the given \meta{node}. The command can be used in commands + like |\pgfpathmoveto|. + % +\begin{codeexample}[] +\begin{pgfpicture} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + + \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} + + In the above example, you may have noticed something curious: The rotation + transformation is still in force when the anchors are invoked, but it does + not seem to have an effect. You might expect that the rotation should apply + to the already rotated points once more. + + However, |\pgfpointanchor| returns a point that takes the current + transformation matrix into account: \emph{The inverse transformation to the + current coordinate transformation is applied to an anchor point before + returning it.} + + This behavior may seem a bit strange, but you will find it very natural in + most cases. If you really want to apply a transformation to an anchor point + (for example, to ``shift it away'' a little bit), you have to invoke + |\pgfpointanchor| without any transformations in force. Here is an example: + % +\makeatletter +\begin{codeexample}[pre={\makeatletter}] +\begin{pgfpicture} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + + { + \pgftransformreset + \pgfpointanchor{x}{east} + \xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}} + } + + \pgfpathcircle{\mycoordinate}{2pt} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} + + A special situation arises when the \meta{node} lies in a picture different + from the current picture. In this case, if you have not told \pgfname\ that + the picture should be ``remembered'', the \meta{node} will be treated as if + it lay in the current picture. For example, if the \meta{node} was at + position $(3,2)$ in the original picture, it is treated as if it lay at + position $(3,2)$ in the current picture. However, if you have told + \pgfname\ to remember the picture position of the node's picture and also + of the current picture, then |\pgfpointanchor| will return a coordinate + that corresponds to the position of the node's anchor on the page, + transformed into the current coordinate system. For examples and more + details see Section~\ref{section-cross-pictures-pgf}. +\end{command} + +\begin{command}{\pgfpointshapeborder\marg{node}\marg{point}} + This command returns the point on the border of the shape that lies on a + straight line from the center of the node to \meta{point}. For complex + shapes it is not guaranteed that this point will actually lie on the + border, it may be on the border of a ``simplified'' version of the shape. + % +\begin{codeexample}[] +\begin{pgfpicture} + \begin{pgfscope} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + \end{pgfscope} + \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt} + \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} + \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt} + \pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} + % + \emph{Remark:} If the given \meta{point} is almost identical to the center + of \meta{node}, the node center is returned and a warning message will be + printed. +\end{command} + + +\subsubsection{Referencing Anchors of Nodes in Different Pictures} +\label{section-cross-pictures-pgf} + +As a picture is typeset, \pgfname\ keeps track of the positions of all nodes +inside the picture. What \pgfname\ does not remember is the position of the +picture \emph{itself} on the page. Thus, if you define a node in one picture +and then try to reference this node while another picture is typeset, \pgfname\ +will only know the position of the nodes that you try to typeset inside the +original picture, but it will not know where this picture lies. What is missing +is the relative positioning of the two pictures. + +To overcome this problem, you need to tell \pgfname\ that it should remember +the position of pictures on a page. If these positions are remembered, then +\pgfname\ can compute the offset between the pictures and make nodes in +different pictures accessible. + +Determining the positions of pictures on the page is, alas, not-so-easy. +Because of this, \pgfname\ does not do so automatically. Rather, you have to +proceed as follows: +% +\begin{enumerate} + \item You have to use a backend driver that supports position tracking. + pdf\TeX\ is one such driver, |dvips| currently is not. + \item You have to say |\pgfrememberpicturepositiononpagetrue| somewhere + before or inside every picture + % + \begin{itemize} + \item in which you wish to reference a node and + \item from which you wish to reference a node in another picture. + \end{itemize} + % + The second item is important since \pgfname\ does not only need to know + the position of the picture in which the node you wish to reference + lies, but it also needs to know where the current picture lies. + \item You typically have to run \TeX\ twice (depending on the backend + driver) since the position information typically gets written into an + external file on the first run and is available only on the second run. + \item You have to switch off automatic bounding bound computations. The + reason is that the node in the other picture should not influence the + size of the bounding box of the current picture. You should say + |\pgfusepath{use as bounding box}| before using a coordinate in another + picture. +\end{enumerate} + + +\subsection{Special Nodes} + +There are several special nodes that are always defined and which you should +not attempt to redefine. + +\begin{predefinednode}{current bounding box} + This node is of shape |rectangle|. Unlike normal nodes, its size changes + constantly and always reflects the size of the bounding box of the current + picture. This means that, for instance, that + % +\begin{codeexample}[code only] +\pgfpointanchor{current bounding box}{south east} +\end{codeexample} + % + returns the lower left corner of the bounding box of the current picture. +\end{predefinednode} + +\begin{predefinednode}{current path bounding box} + This node is also of shape |rectangle|. Its size is the size of the + bounding box of the current path. +\end{predefinednode} + +\begin{predefinednode}{current subpath start} + This node is of shape |coordinate| and is at the beginning of the current + subpath. This is the position of the last move-to operation. +\end{predefinednode} + +\begin{predefinednode}{current page} + This node is inside a virtual remembered picture. The size of this node is + the size of the current page. This means that if you create a remembered + picture and inside this picture you reference an anchor of this node, you + reference an absolute position on the page. To demonstrate the effect, the + following code puts some text in the lower left corner of the current page. + Note that this works only if the backend driver supports it, otherwise the + text is inserted right here. + % +{% +\pgfrememberpicturepositiononpagetrue% +\begin{pgfpicture} + \pgfusepath{use as bounding box} + \pgftransformshift{\pgfpointanchor{current page}{south west}} + \pgftransformshift{\pgfpoint{1cm}{1cm}} + \pgftext[left,base]{ + \textcolor{red}{ + Text absolutely positioned in + the lower left corner.} + } +\end{pgfpicture} +}% +\begin{codeexample}[code only] +\pgfrememberpicturepositiononpagetrue +\begin{pgfpicture} + \pgfusepath{use as bounding box} + \pgftransformshift{\pgfpointanchor{current page}{south west}} + \pgftransformshift{\pgfpoint{1cm}{1cm}} + \pgftext[left,base]{ + \textcolor{red}{ + Text absolutely positioned in + the lower left corner.} + } +\end{pgfpicture} +\end{codeexample} + % +\end{predefinednode} + +There is also an option that allows you to create new special nodes quite +similar to the above: +% +\begin{key}{/pgf/local bounding box=\meta{node name}} +\keyalias{tikz} + This defines a new node \meta{node name} whose size is the bounding box + around all objects in the current scope starting at the position where this + option was given. After the end of the scope, the \meta{node name} is still + available. You can use this option to keep track of the size of a certain + area. Note that excessive use of this option (keeping track of dozens of + bounding boxes at the same time) will slow things down. + % +\begin{codeexample}[preamble={\usetikzlibrary{scopes}}] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { [local bounding box=outer box] + \draw (1,1) circle (.5) [local bounding box=inner box] (2,2) circle (.5); + } + \draw (outer box.south west) rectangle (outer box.north east); + \draw[red] (inner box.south west) rectangle (inner box.north east); +\end{tikzpicture} +\end{codeexample} + % +\end{key} + + +\subsection{Declaring New Shapes} + +There are only three predefined shapes, see +Section~\ref{section-predefined-shapes}, so there must be some way of defining +new shapes. Defining a shape is, unfortunately, a not-quite-trivial process. +The reason is that shapes need to be both very flexible (their size will vary +greatly according to circumstances) and they need to be constructed reasonably +``fast''. \pgfname\ must be able to handle pictures with several hundreds of +nodes and documents with thousands of nodes in total. It would not do if +\pgfname\ had to compute and store, say, dozens of anchor positions for every +node. + + +\subsubsection{What Must Be Defined For a Shape?} + +In order to define a new shape, you must provide: +% +\begin{itemize} + \item a \emph{shape name}, + \item code for computing the \emph{saved anchors} and \emph{saved + dimensions}, + \item code for computing \emph{anchor} positions in terms of the saved + anchors, + \item optionally code for the \emph{background path} and \emph{foreground + path}, + \item optionally code for \emph{things to be drawn before or behind} the + background and foreground paths. + \item optionally a list of node parts. +\end{itemize} + + +\subsubsection{Normal Anchors Versus Saved Anchors} + +Anchors are special places in a shape. For example, the |north east| anchor, +which is a normal anchor, lies at the upper right corner of the |rectangle| +shape, as does |\northeast|, which is a saved anchor. The difference is the +following: \emph{saved anchors are computed and stored for each node, anchors +are only computed as needed.} The user only has access to the normal anchors, +but a normal anchor can just ``copy'' or ``pass through'' the location of a +saved anchor. + +The idea behind all this is that a shape can declare a very large number of +normal anchors, but when a node of this shape is created, these anchors are not +actually computed. However, this causes a problem: When we wish to reference an +anchor of a node at some later time, we must still be able to compute the +position of the anchor. For this, we may need a lot of information: What was +the transformation matrix that was in force when the node was created? What was +the size of the text box? What were the values of the different separation +dimensions? And so on. + +To solve this problem, \pgfname\ will always compute the locations of all +\emph{saved anchors} and store these positions. Then, when an normal anchor +position is requested later on, the anchor position can be given just from +knowing where the locations of the saved anchors are. + +As an example, consider the |rectangle| shape. For this shape two anchors are +saved: The |\northeast| corner and the |\southwest| corner. A normal anchor +like |north west| can now easily be expressed in terms of these coordinates: +Take the $x$-position of the |\southwest| point and the $y$-position of the +|\northeast| point. The |rectangle| shape currently defines 13 normal anchors, +but needs only two saved anchors. Adding new anchors like a |south south east| +anchor would not increase the memory and computation requirements of pictures. + +All anchors (both saved and normal) are specified in a local \emph{shape +coordinate space}. This is also true for the background and foreground paths. +The |\pgfnode| macro will automatically apply appropriate transformations to +the coordinates so that the shape is shifted to the right anchor or otherwise +transformed. + + +\subsubsection{Command for Declaring New Shapes} + +The following command declares a new shape: +% +\begin{command}{\pgfdeclareshape\marg{shape name}\marg{shape specification}} + This command declares a new shape named \meta{shape name}. The shape name + can later be used in commands like |\pgfnode|. + + The \meta{shape specification} is some \TeX\ code containing calls to + special commands that are only defined inside the \meta{shape + specification} (similarly to commands like |\draw| that are only available + inside the |{tikzpicture}| environment). + + \example Here is the code of the |coordinate| shape: + % +\begin{codeexample}[code only] +\pgfdeclareshape{coordinate} +{ + \savedanchor\centerpoint{% + \pgf@x=.5\wd\pgfnodeparttextbox% + \pgf@y=.5\ht\pgfnodeparttextbox% + \advance\pgf@y by -.5\dp\pgfnodeparttextbox% + } + \anchor{center}{\centerpoint} + \anchorborder{\centerpoint} +} +\end{codeexample} + + The special commands are explained next. In the examples given for the + special commands a new shape will be constructed, which we might call + |simple rectangle|. It should behave like the normal rectangle shape, only + without bothering about the fine details like inner and outer separations. + The skeleton for the shape is the following. + % +\begin{codeexample}[code only] +\pgfdeclareshape{simple rectangle}{ + ... +} +\end{codeexample} + + \begin{command}{\nodeparts\marg{list of node parts}} + This command declares which parts make up nodes of this shape. A + \emph{node part} is a (possibly empty) text label that is drawn when a + node of the shape is created. + + By default, a shape has just one node part called |text|. However, + there can be several node parts. For example, the |circle split| shape + has two parts: the |text| part, which shows that the upper text, and a + |lower| part, which shows the lower text. For the |circle split| shape + the |\nodeparts| command was called with the argument |{text,lower}|. + + When a multipart node is created, the text labels are drawn in the + sequences listed in the \meta{list of node parts}. For each node part, + you must have declared one anchor and the \TeX-box of the part is + placed at this anchor. For a node part called |XYZ| the \TeX-box + |\pgfnodepartXYZbox| is placed at anchor |XYZ|. + \end{command} + + \begin{command}{\savedanchor\marg{command}\marg{code}} + This command declares a saved anchor. The argument \meta{command} + should be a \TeX\ macro name like |\centerpoint|. + + The \meta{code} will be executed each time |\pgfnode| (or + |\pgfmultipartnode|) is called to create a node of the shape + \meta{shape name}. When the \meta{code} is executed, the \TeX-boxes of + the node parts will contain the text labels of the node. Possibly, + these box are void. For example, if there is just a |text| part, the + node |\pgfnodeparttextbox| will be set up when the \meta{code} is + executed. + + The \meta{code} can use the width, height, and depth of the box(es) to + compute the location of the saved anchor. In addition, the \meta{code} + can take into account the values of dimensions like |\pgfshapeminwidth| + or |\pgfshapeinnerxsep|. Furthermore, the \meta{code} can take into + consideration the values of any further shape-specific variables that + are set at the moment when |\pgfnode| is called. + + The net effect of the \meta{code} should be to set the two \TeX\ + dimensions |\pgf@x| and |\pgf@y|. One way to achieve this is to say + |\pgfpoint{|\meta{x value}|}{|\meta{y value}|}| at the end of the + \meta{code}, but you can also just set these variables. The values that + |\pgf@x| and |\pgf@y| have after the code has been executed, let us + call them $x$ and $y$, will be recorded and stored together with the + node that is created by the command |\pgfnode|. + + The macro \meta{command} is defined to be |\pgfpoint{|$x$|}{|$y$|}|. + However, the \meta{command} is only locally defined while anchor + positions are being computed. Thus, it is possible to use very simple + names for \meta{command}, like |\center| or |\a|, without causing a + name-clash. (To be precise, very simple \meta{command} names will clash + with existing names, but only locally inside the computation of anchor + positions; and we do not need the normal |\center| command during these + computations.) + + For our |simple rectangle| shape, we will need only one saved anchor: + The upper right corner. The lower left corner could either be the + origin or the ``mirrored'' upper right corner, depending on whether we + want the text label to have its lower left corner at the origin or + whether the text label should be centered on the origin. Either will be + fine, for the final shape this will make no difference since the shape + will be shifted anyway. So, let us assume that the text label is + centered on the origin (this will be specified later on using the + |text| anchor). We get the following code for the upper right corner: + % +\begin{codeexample}[code only] +\savedanchor{\upperrightcorner}{ + \pgf@y=.5\ht\pgfnodeparttextbox % height of the box, ignoring the depth + \pgf@x=.5\wd\pgfnodeparttextbox % width of the box +} +\end{codeexample} + + If we wanted to take, say, the |\pgfshapeminwidth| into account, we + could use the following code: + % +\begin{codeexample}[code only] +\savedanchor{\upperrightcorner}{ + \pgf@y=.\ht\pgfnodeparttextbox % height of the box + \pgf@x=.\wd\pgfnodeparttextbox % width of the box + \setlength{\pgf@xa}{\pgfshapeminwidth} + \ifdim\pgf@x<.5\pgf@xa + \pgf@x=.5\pgf@xa + \fi +} +\end{codeexample} + % + Note that we could not have written |.5\pgfshapeminwidth| since the + minimum width is stored in a ``plain text macro'', not as a real + dimension. So if |\pgfshapeminwidth| depth were 2cm, writing + |.5\pgfshapeminwidth| would yield the same as |.52cm|. + + In the ``real'' |rectangle| shape the code is somewhat more complex, + but you get the basic idea. + \end{command} + % + \begin{command}{\saveddimen\marg{command}\marg{code}} + This command is similar to |\savedanchor|, only instead of setting + \meta{command} to |\pgfpoint{|$x$|}{|$y$|}|, the \meta{command} is set + just to (the value of) $x$. + + In the |simple rectangle| shape we might use a saved dimension to store + the depth of the shape box. + % +\begin{codeexample}[code only] +\saveddimen{\depth}{ + \pgf@x=\dp\pgfnodeparttextbox +} +\end{codeexample} + \end{command} + % + \begin{command}{\savedmacro\marg{command}\marg{code}} + This command is similar to |\saveddimen|, only at some point in + \meta{code}, \meta{command} should be defined appropriately, (this + could be a value, or some text). + + In the |regular polygon| shape, a saved macro is used to store the + number of sides of the polygon. + % +\begin{codeexample}[code only] +\savedmacro{\sides}{\let\sides\pgfpolygonsides} +\end{codeexample} + \end{command} + % + \begin{command}{\anchor\marg{name}\marg{code}} + This command declares an anchor named \meta{name}. Unlike for saved + anchors, the \meta{code} will not be executed each time a node is + declared. Rather, the \meta{code} is only executed when the anchor is + specifically requested; either for anchoring the node during its + creation or as a position in the shape referenced later on. + + The \meta{name} is a quite arbitrary string that is not ``passed down'' + to the system level. Thus, names like |south| or |1| or |::| would all + be fine. + + A saved anchor is not automatically also a normal anchor. If you wish + to give the users access to a saved anchor you must declare a normal + anchor that just returns the position of the saved anchor. + + When the \meta{code} is executed, all saved anchor macros will be + defined. Thus, you can reference them in your \meta{code}. The effect + of the \meta{code} should be to set the values of |\pgf@x| and |\pgf@y| + to the coordinates of the anchor. + + Let us consider some example for the |simple rectangle| shape. First, + we would like to make the upper right corner publicly available, for + example as |north east|: + % +\begin{codeexample}[code only] +\anchor{north east}{\upperrightcorner} +\end{codeexample} + + The |\upperrightcorner| macro will set |\pgf@x| and |\pgf@y| to the + coordinates of the upper right corner. Thus, |\pgf@x| and |\pgf@y| will + have exactly the right values at the end of the anchor's code. + + Next, let us define a |north west| anchor. For this anchor, we can + negate the |\pgf@x| variable: + % +\begin{codeexample}[code only] +\anchor{north west}{ + \upperrightcorner + \pgf@x=-\pgf@x +} +\end{codeexample} + + Finally, it is a good idea to always define a |center| anchor, which + will be the default location for a shape. + % +\begin{codeexample}[code only] +\anchor{center}{\pgfpointorigin} +\end{codeexample} + + You might wonder whether we should not take into consideration that the + node is not placed at the origin, but has been shifted somewhere. + However, the anchor positions are always specified in the shape's + ``private'' coordinate system. The ``outer'' transformation that has + been applied to the shape upon its creation is applied automatically to + the coordinates returned by the anchor's \meta{code}. + + Our |simple rectangle| only has one text label (node part) called + |text|. This is the default situation, so we do not need to do + anything. For the |text| node part we must set up a |text| anchor. Upon + creation of a node, this anchor will be made to coincide with the left + endpoint of the baseline of the text label (within the private + coordinate system of the shape). By default, the |text| anchor is at + the origin, but you may change this. For example, we would say + % +\begin{codeexample}[code only] +\anchor{text}{% + \upperrightcorner% + \pgf@x=-\pgf@x% + \pgf@y=-\pgf@y% +} +\end{codeexample} + to center the text label on the origin in the shape coordinate space. + Note that we could \emph{not} have written the following: + % +\begin{codeexample}[code only] +\anchor{text}{\pgfpoint{-.5\wd\pgfnodeparttextbox}{-.5\ht\pgfnodeparttextbox}} +\end{codeexample} + % + Do you see why this is wrong? The problem is that the box + |\pgfnodeparttextbox| will most likely not have the correct size when + the anchor is computed. After all, the anchor position might be + recomputed at a time when several other nodes have been created. + + If a shape has several node parts, we would have to define an anchor + for each part. + \end{command} + + \begin{command}{\deferredanchor\marg{name}\marg{code}} + This command declares an anchor named \meta{name}. It works like + |\anchor|. However, unlike for anchors declared by |\anchor|, + \meta{name} will \emph{not} be expanded during the shape declaration + (i.e.\ not during |\pgfdeclareshape|). Rather, the \meta{name} is + expanded when the \emph{node} is actually used (with |\pgfnode| or more + likely with |\node|). This may be useful if the anchor name is context + dependent (depending, for example, on the value of a key). + % +\begin{codeexample}[code only] +\makeatletter +\def\foo{foo} +\pgfdeclareshape{simple shape}{% + \savedanchor{\center}{% + \pgfpointorigin} + \anchor{center}{\center} + \savedanchor{\anchorfoo}{% + \pgf@x=1cm + \pgf@y=0cm} + \deferredanchor{anchor \foo}{\anchorfoo}} + +\begin{tikzpicture} + \node[simple shape] (Test1) at (0,0) {}; + \fill (Test1.anchor foo) circle (2pt) node[below] {anchor foo anchor}; + % + \def\foo{bar} + \node[simple shape] (Test2) at (2,2) {}; + \fill (Test2.anchor bar) circle (2pt) node[below] {anchor bar anchor}; +\end{tikzpicture} +\end{codeexample} + \end{command} + % + \begin{command}{\anchorborder\marg{code}} + A \emph{border anchor} is an anchor point on the border of the shape. + What exactly is considered as the ``border'' of the shape depends on + the shape. + + When the user requests a point on the border of the shape using the + |\pgfpointshapeborder| command, the \meta{code} will be executed to + discern this point. When the execution of the \meta{code} starts, the + dimensions |\pgf@x| and |\pgf@y| will have been set to a location $p$ + in the shape's coordinate system, and relative to the anchor |center|. + Note that |\pgfpointshapeborder| will produce an error if the shape does + not contain the |center| anchor. + + It is now the job of the \meta{code} to set up |\pgf@x| and |\pgf@y| + such that they specify the point on the shape's border that lies on a + straight line from the shape's center to the point $p$. Usually, this is + a somewhat complicated computation, involving many case distinctions and + some basic math. Note that the output coordinates must be returned in the + shape's coordinate system, \emph{no longer} relative to the |center| + anchor. While these different points of reference are only noticeable if + the |center| anchor is not at the origin of the shape's coordinate system, + it implies that ``doing nothing'' as a border anchor, i.e., returning the + point that was fed to |\pgfpointshapeborder| requires adding the |center| + anchor to the input coordinates. + + For our |simple rectangle| we must compute a point on the border of a + rectangle whose one corner is the origin (ignoring the depth for + simplicity) and whose other corner is |\upperrightcorner|. The + following code might be used: + % +\begin{codeexample}[code only] +\anchorborder{% + % Call a function that computes a border point. Since this + % function will modify dimensions like \pgf@x, we must move them to + % other dimensions. + \@tempdima=\pgf@x + \@tempdimb=\pgf@y + \pgfpointborderrectangle{\pgfpoint{\@tempdima}{\@tempdimb}}{\upperrightcorner} +} +\end{codeexample} + \end{command} + % + \begin{command}{\backgroundpath\marg{code}} + This command specifies the path that ``makes up'' the background of the + shape. Note that the shape cannot prescribe what is going to happen + with the path: It might be drawn, shaded, filled, or even thrown away. + If you want to specify that something should ``always'' happen when + this shape is drawn (for example, if the shape is a stop-sign, we + \emph{always} want it to be filled with a red color), you can use + commands like |\beforebackgroundpath|, explained below. + + When the \meta{code} is executed, all saved anchors will be in effect. + The \meta{code} should contain path construction commands. + + For our |simple rectangle|, the following code might be used: + % +\begin{codeexample}[code only] +\backgroundpath{ + \pgfpathrectanglecorners + {\upperrightcorner} + {\pgfpointscale{-1}{\upperrightcorner}} +} +\end{codeexample} + % + As the name suggests, the background path is used ``behind'' the text + labels. Thus, this path is used first, then the text labels are drawn, + possibly obscuring part of the path. + \end{command} + % + \begin{command}{\foregroundpath\marg{code}} + This command works like |\backgroundpath|, only it is invoked after the + text labels have been drawn. This means that this path can possibly + obscure (part of) the text labels. + \end{command} + % + \begin{command}{\behindbackgroundpath\marg{code}} + Unlike the previous two commands, \meta{code} should not only construct + a path, it should also use this path in whatever way is appropriate. + For example, the \meta{code} might fill some area with a uniform color. + + Whatever the \meta{code} does, it does it first. This means that any + drawing done by \meta{code} will be even behind the background path. + + Note that the \meta{code} is protected with a |{pgfscope}|. + \end{command} + % + \begin{command}{\beforebackgroundpath\marg{code}} + This command works like |\behindbackgroundpath|, only the \meta{code} + is executed after the background path has been used, but before the + texts label are drawn. + \end{command} + % + \begin{command}{\behindforegroundpath\marg{code}} + The \meta{code} is executed after the text labels have been drawn, but + before the foreground path is used. + \end{command} + % + \begin{command}{\beforeforegroundpath\marg{code}} + This \meta{code} is executed at the very end. + \end{command} + % + \begin{command}{\inheritsavedanchors|[from=|\marg{another shape name}|]|} + This command allows you to inherit the code for saved anchors from + \meta{another shape name}. The idea is that if you wish to create a new + shape that is just a small modification of a another shape, you can + recycle the code used for \meta{another shape name}. + + The effect of this command is the same as if you had called + |\savedanchor| and |\saveddimen| for each saved anchor or saved + dimension declared in \meta{another shape name}. Thus, it is not + possible to ``selectively'' inherit only some saved anchors, you always + have to inherit all saved anchors from another shape. However, you can + inherit the saved anchors of more than one shape by calling this + command several times. + \end{command} + % + \begin{command}{\inheritbehindbackgroundpath|[from=|\marg{another shape name}|]|} + This command can be used to inherit the code used for the drawings + behind the background path from \meta{another shape name}. + \end{command} + % + \begin{command}{\inheritbackgroundpath|[from=|\marg{another shape name}|]|} + Inherits the background path code from \meta{another shape name}. + \end{command} + % + \begin{command}{\inheritbeforebackgroundpath|[from=|\marg{another shape name}|]|} + Inherits the before background path code from \meta{another shape + name}. + \end{command} + % + \begin{command}{\inheritbehindforegroundpath|[from=|\marg{another shape name}|]|} + Inherits the behind foreground path code from \meta{another shape + name}. + \end{command} + % + \begin{command}{\inheritforegroundpath|[from=|\marg{another shape name}|]|} + Inherits the foreground path code from \meta{another shape name}. + \end{command} + % + \begin{command}{\inheritbeforeforegroundpath|[from=|\marg{another shape name}|]|} + Inherits the before foreground path code from \meta{another shape + name}. + \end{command} + % + \begin{command}{\inheritanchor|[from=|\marg{another shape name}|]|\marg{name}} + Inherits the code of one specific anchor named \meta{name} from + \meta{another shape name}. Thus, unlike saved anchors, which must be + inherited collectively, normal anchors can and must be inherited + individually. + \end{command} + % + \begin{command}{\inheritanchorborder|[from=|\marg{another shape name}|]|} + Inherits the border anchor code from \meta{another shape name}. + \end{command} + + The following example shows how a shape can be defined that relies heavily + on inheritance: + % +\makeatletter +\begin{codeexample}[ + preamble={\usetikzlibrary{shapes.geometric}}, + pre={\makeatletter}, +] +\pgfdeclareshape{document}{ + \inheritsavedanchors[from=rectangle] % this is nearly a rectangle + \inheritanchorborder[from=rectangle] + \inheritanchor[from=rectangle]{center} + \inheritanchor[from=rectangle]{north} + \inheritanchor[from=rectangle]{south} + \inheritanchor[from=rectangle]{west} + \inheritanchor[from=rectangle]{east} + % ... and possibly more + \backgroundpath{% this is new + % store lower right in xa/ya and upper right in xb/yb + \southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y + \northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y + % compute corner of ``flipped page'' + \pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter + \pgf@yc=\pgf@yb \advance\pgf@yc by-5pt + % construct main path + \pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}} + \pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}} + \pgfpathclose + % add little corner + \pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} + } +}\hskip-1.2cm +\begin{tikzpicture} + \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark}; + \node[fill=yellow!80!black,draw,ellipse,double] + at ([shift=(-80:3cm)]x) (y) {Use Case}; + + \draw[dashed] (x) -- (y); +\end{tikzpicture} +\end{codeexample} + % +\end{command} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: -- cgit v1.2.3