summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex1546
1 files changed, 763 insertions, 783 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex
index c40d308b3f4..4e0ba4f5361 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex
@@ -15,159 +15,142 @@
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|.
+ 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.
+\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
+|\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
+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.
+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.
+\subsubsection{Layers of a Shape}
-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:
+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.''
+ \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.
+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.
+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|.
+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.
+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.
+\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 \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 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{path usage command} is executed for the background and the
- foreground path (if the shape defines them).
+ 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);
@@ -185,14 +168,13 @@ the description of |\pgfmultipartnode| for more details.
\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 the
- transformed. In this case, you should call
- |\pgftransformresetnontranslations| prior to calling the |\pgfnode|
- command.
-
+ 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 the 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);
@@ -207,33 +189,29 @@ the description of |\pgfmultipartnode| for more details.
\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.
+ 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{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}[]
\setbox\pgfnodeparttextbox=\hbox{$q_1$}
\setbox\pgfnodepartlowerbox=\hbox{01}
@@ -242,66 +220,66 @@ the description of |\pgfmultipartnode| for more details.
\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
+ \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:
+ %
+ 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.
+ 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}.
+ 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.
+ 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.
+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.
-
+\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);
@@ -310,26 +288,25 @@ node. These values are stored in the following keys.
\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|.
+\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}.
+\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.
-
+\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);
@@ -338,28 +315,28 @@ node. These values are stored in the following keys.
\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|.
+\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}.
+\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.
-
+\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);
@@ -375,106 +352,107 @@ node. These values are stored in the following keys.
\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|.
+\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}.
+\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.
+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.
+ 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}[]
+ 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{
@@ -503,50 +481,47 @@ determined only at some later time.
\draw (hi) -- (0,0);
\end{tikzpicture}
- \end{codeexample}
+\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.
+ 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).
+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.
+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:
+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|.
-
+ 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}
@@ -561,23 +536,21 @@ following commands:
\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:
-
+ 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}[]
\begin{pgfpicture}
@@ -595,28 +568,25 @@ following commands:
\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}.
+ 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.
-
+ 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}
@@ -630,102 +600,102 @@ following commands:
\pgfusepath{fill}
\end{pgfpicture}
\end{codeexample}
+ %
\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:
+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.
+ \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.
+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
+ 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.
+ %
+ 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.
+ 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.
+ 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.%
+ 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.}
- }
+ \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]
@@ -741,20 +711,21 @@ should not attempt to redefine.
}
\end{pgfpicture}
\end{codeexample}
+ %
\end{predefinednode}
-
-There is also an option that allows you to create new special nodes
-quite similar to the above:
+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.
+\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}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -765,101 +736,95 @@ quite similar to the above:
\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.
+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
+ \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.
+ \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
+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
+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.
+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.
+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.
+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|.
+%
+\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).
+ 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:
+ \example Here is the code of the |coordinate| shape:
+ %
\begin{codeexample}[code only]
\pgfdeclareshape{coordinate}
{
@@ -873,86 +838,82 @@ The following command declares a new shape:
}
\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.
+ 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{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
@@ -960,9 +921,9 @@ The following command declares a new shape:
}
\end{codeexample}
- If we wanted to take, say, the |\pgfshapeminwidth| into account,
- we could use the following code:
-
+ 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
@@ -973,76 +934,79 @@ The following command declares a new shape:
\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.
-
+ %
+ 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.
-
+ \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|:
-
+ \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:
+ 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
@@ -1050,28 +1014,28 @@ The following command declares a new shape:
}
\end{codeexample}
- Finally, it is a good idea to always define a |center| anchor,
- which will be the default location for a shape.
-
+ 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. This anchor is used upon creation of a node to determine
- the lower left corner 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
+ 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%
@@ -1079,31 +1043,31 @@ The following command declares a new shape:
\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:
-
+ 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.
+ %
+ 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).
-
+ 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}
@@ -1125,27 +1089,28 @@ The following command declares a new shape:
\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. 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.
-
- 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:
+ \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. 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.
+
+ 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
@@ -1156,22 +1121,22 @@ The following command declares a new shape:
\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:
+ \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
@@ -1179,84 +1144,101 @@ The following command declares a new shape:
{\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:
+ %
+ 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}[]
\pgfdeclareshape{document}{
@@ -1297,12 +1279,10 @@ The following command declares a new shape:
\draw[dashed] (x) -- (y);
\end{tikzpicture}
\end{codeexample}
-
+ %
\end{command}
-
-
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"