diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex | 3156 |
1 files changed, 1636 insertions, 1520 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex index 612ca23d1c4..bce298b285a 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex @@ -7,124 +7,123 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Nodes and Edges} +\section{Nodes and Edges} \label{section-nodes} \subsection{Overview} -In the present section, the usage of \emph{nodes} in -\tikzname\ is explained. A node is typically a rectangle or circle or -another simple shape with some text on it. - -Nodes are added to paths using the special path -operation |node|. Nodes \emph{are not part of the path - itself}. Rather, they are added to the picture just before or after -the path has been drawn. - -In Section~\ref{section-nodes-basic} the basic syntax of the node -operation is explained, followed in Section~\ref{section-nodes-multi} -by the syntax for multi-part nodes, which are nodes that contain -several different text parts. After this, the different options for -the text in nodes are explained. In -Section~\ref{section-nodes-anchors} the concept of \emph{anchors} is -introduced along with their usage. In -Section~\ref{section-nodes-transformations} the different ways -transformations affect nodes are -studied. Sections~\ref{section-nodes-placing-1} -and~\ref{section-nodes-placing-2} are about placing nodes on or next -to straight lines and curves. -Section~\ref{section-nodes-connecting} explains how a node can -be used as a ``pseudo-coordinate.'' Section~\ref{section-nodes-edges} -introduces the |edge| operation, which -works similar to the |to| operation and also similar to the |node| -operation. +In the present section, the usage of \emph{nodes} in \tikzname\ is explained. A +node is typically a rectangle or circle or another simple shape with some text +on it. + +Nodes are added to paths using the special path operation |node|. Nodes +\emph{are not part of the path itself}. Rather, they are added to the picture +just before or after the path has been drawn. + +In Section~\ref{section-nodes-basic} the basic syntax of the node operation is +explained, followed in Section~\ref{section-nodes-multi} by the syntax for +multi-part nodes, which are nodes that contain several different text parts. +After this, the different options for the text in nodes are explained. In +Section~\ref{section-nodes-anchors} the concept of \emph{anchors} is introduced +along with their usage. In Section~\ref{section-nodes-transformations} the +different ways transformations affect nodes are studied. +Sections~\ref{section-nodes-placing-1} and~\ref{section-nodes-placing-2} are +about placing nodes on or next to straight lines and curves. +Section~\ref{section-nodes-connecting} explains how a node can be used as a +``pseudo-coordinate''. Section~\ref{section-nodes-edges} introduces the |edge| +operation, which works similar to the |to| operation and also similar to the +|node| operation. \subsection{Nodes and Their Shapes} - \label{section-nodes-basic} -In the simplest case, a node is just some text that is -placed at some coordinate. However, a node can also have a border -drawn around it or have a more complex background and -foreground. Indeed, some nodes do not have a text at all, but consist -solely of the background. You can name nodes so that you can reference -their coordinates later in the same picture or, if certain precautions -are taken as explained in Section~\ref{section-cross-picture-tikz}, +In the simplest case, a node is just some text that is placed at some +coordinate. However, a node can also have a border drawn around it or have a +more complex background and foreground. Indeed, some nodes do not have a text +at all, but consist solely of the background. You can name nodes so that you +can reference their coordinates later in the same picture or, if certain +precautions are taken as explained in Section~\ref{section-cross-picture-tikz}, also in different pictures. There are no special \TeX\ commands for adding a node to a picture; rather, -there is path operation called |node| for this. Nodes are created -whenever \tikzname\ encounters |node| or |coordinate| at a point on a -path where it would expect a normal path operation (like |-- (1,1)| or -|rectangle (1,1)|). It is also possible to give node specifications -\emph{inside} certain path operations as explained later. - -The node operation is typically followed by some options, which apply -only to the node. Then, you can optionally \emph{name} the node by -providing a name in parentheses. Lastly, for the |node| operation you -must provide some label text for the node in curly braces, while for -the |coordinate| operation you may not. The node is placed at the -current position of the path either \emph{after the path has been - drawn} or (more seldomly and only if you add the |behind path| -option) \emph{just before the path is drawn.} Thus, all nodes are -drawn ``on top'' or ``behind'' the path and are retained until the -path is complete. If there are several nodes on a path, perhaps some -behind and some on top of the path, first come the nodes behind the -path in the order they were encountered, then comes that path, and -then come the remaining node, again in the order they are -encountered. - +there is path operation called |node| for this. Nodes are created whenever +\tikzname\ encounters |node| or |coordinate| at a point on a path where it +would expect a normal path operation (like |-- (1,1)| or |rectangle (1,1)|). It +is also possible to give node specifications \emph{inside} certain path +operations as explained later. + +The node operation is typically followed by some options, which apply only to +the node. Then, you can optionally \emph{name} the node by providing a name in +parentheses. Lastly, for the |node| operation you must provide some label text +for the node in curly braces, while for the |coordinate| operation you may not. +The node is placed at the current position of the path either \emph{after the +path has been drawn} or (more seldomly and only if you add the |behind path| +option) \emph{just before the path is drawn.} Thus, all nodes are drawn ``on +top'' or ``behind'' the path and are retained until the path is complete. If +there are several nodes on a path, perhaps some behind and some on top of the +path, first come the nodes behind the path in the order they were encountered, +then comes that path, and then come the remaining node, again in the order they +are encountered. +% \begin{codeexample}[] \tikz \fill [fill=yellow!80!black] - (0,0) node {first node} + (0,0) node {first node} -- (1,1) node[behind path] {second node} -- (2,0) node {third node}; \end{codeexample} + \subsubsection{Syntax of the Node Command} The syntax for specifying nodes is the following: -\begin{pathoperation}{node}{\opt{\meta{foreach statements}}% - \opt{|[|\meta{options}|]|}\opt{|(|\meta{name}|)|}% - \opt{|at(|\meta{coordinate}|)|}\opt{\marg{node contents}}} - Since this path operation is one of the most involved around, let us - go over it step by step. - - \medskip - \textbf{Order of the parts of the specification.} - Everything between ``|node|'' and the opening brace of a node is - optional. If there are \meta{foreach statements}, they must come - first, directly following ``|node|.'' Other than that, the ordering - of all the other elements of a node specification (the - \meta{options}, the \meta{name}, and \meta{coordinate}) is - arbitrary, indeed, there can be multiple occurrences of any of these - elements (although only for options this makes much sense). - - \medskip - \textbf{The text of a node.} - At the end of a node, you must (normally) provide some \meta{node contents} - in curly braces; indeed, the ``end'' of the node specification is - detected by the opening curly brace. For normal nodes it is possible to use - ``fragile'' stuff inside the \meta{node contents} like the |\verb| - command (for the technically savvy: code inside the \meta{node - contents} is allowed to change catcodes; however, this rule does - not apply to ``nodes on a path'' to be discussed later). - - Instead of giving \meta{node contents} at the end of the node in - curly braces, you can also use the following key: - \begin{key}{/tikz/node contents=\meta{node contents}} +% +\begin{pathoperation}{node}{ + \opt{\meta{foreach statements}} + \opt{|[|\meta{options}|]|} + \opt{|(|\meta{name}|)|} + \opt{|at(|\meta{coordinate}|)|} + \opt{|:|\meta{animation attribute}|=|\marg{options}} + \opt{\marg{node contents}}% +} + Since this path operation is one of the most involved around, let us go + over it step by step. + + \medskip + \textbf{Order of the parts of the specification.} + Everything between ``|node|'' and the opening brace of a node is optional. + If there are \meta{foreach statements}, they must come first, directly + following ``|node|''. Other than that, the ordering of all the other + elements of a node specification (the \meta{options}, the \meta{name}, + \meta{coordinate}, and \meta{animation attribute}) is arbitrary, indeed, + there can be multiple occurrences of any of these elements (although for + the name and the coordinate this makes no sense). + + \medskip + \textbf{The text of a node.} + At the end of a node, you must (normally) provide some \meta{node contents} + in curly braces; indeed, the ``end'' of the node specification is detected + by the opening curly brace. For normal nodes it is possible to use + ``fragile'' stuff inside the \meta{node contents} like the |\verb| command + (for the technically savvy: code inside the \meta{node contents} is allowed + to change catcodes; however, this rule does not apply to ``nodes on a + path'' to be discussed later). + + Instead of giving \meta{node contents} at the end of the node in curly + braces, you can also use the following key: + % + \begin{key}{/tikz/node contents=\meta{node contents}} \label{option-node-contents}% - This key sets the contents of the node to the given text as if - you had given it at the end in curly braces. When the option is - used inside the options of a node, the parsing of the node stops - immediately after the end of the option block. In particular, the - option block cannot be followed by further option blocks or curly - braces (or, rather, these do not count as part of the node - specification.) Also note that the \meta{node contents} may not - contain fragile stuff since the catcodes get fixed upon reading - the options. Here is an example: + This key sets the contents of the node to the given text as if you had + given it at the end in curly braces. When the option is used inside the + options of a node, the parsing of the node stops immediately after the + end of the option block. In particular, the option block cannot be + followed by further option blocks or curly braces (or, rather, these do + not count as part of the node specification.) Also note that the + \meta{node contents} may not contain fragile stuff since the catcodes + get fixed upon reading the options. Here is an example: + % \begin{codeexample}[] \tikz { \path (0,0) node [red] {A} @@ -133,38 +132,38 @@ The syntax for specifying nodes is the following: (3,0) node [node contents=D] ; } \end{codeexample} + % \end{key} - \medskip - \textbf{Specifying the location of the node.} - Nodes are placed at the last position mentioned on the path. The - effect of adding ``|at|'' to a node - specification is that the coordinate given after |at| is used - instead. The |at| syntax is not available when a node is given - inside a path operation (it would not make any sense there). - - \begin{key}{/tikz/at=\meta{coordinate}} - This is another way of specifying the |at| coordinate. Note that, - typically, you will have to enclose the \meta{coordinate} in curly - braces so that a comma inside the \meta{coordinate} does not - confuse \TeX. - \end{key} - - Another aspect of the ``location'' of a node is whether it appears - \emph{in front of} or \emph{behind} the current path. You can change - which of these two possibilities happens on a node-by-node basis - using the following keys: - \begin{key}{/tikz/behind path} - When this key is set, either as a local option for the node or - some surrounding scope, the node will be drawn behind the current - path. For this, \tikzname\ collects all nodes defined on the - current path with this option set and then inserts all of them, in - the order they appear, just before it draws the path. Thus, - several nodes with this option set may obscure one anther, but - never the path itself. ``Just before it draws the path'' actually - means that the nodes are inserted into the page output just before - any pre-actions are applied to the path (see below for what - pre-actions are). + \medskip + \textbf{Specifying the location of the node.} + Nodes are placed at the last position mentioned on the path. The effect of + adding ``|at|'' to a node specification is that the coordinate given after + |at| is used instead. The |at| syntax is not available when a node is given + inside a path operation (it would not make any sense there). + + \begin{key}{/tikz/at=\meta{coordinate}} + This is another way of specifying the |at| coordinate. Note that, + typically, you will have to enclose the \meta{coordinate} in curly + braces so that a comma inside the \meta{coordinate} does not confuse + \TeX. + \end{key} + + Another aspect of the ``location'' of a node is whether it appears \emph{in + front of} or \emph{behind} the current path. You can change which of these + two possibilities happens on a node-by-node basis using the following keys: + % + \begin{key}{/tikz/behind path} + When this key is set, either as a local option for the node or some + surrounding scope, the node will be drawn behind the current path. For + this, \tikzname\ collects all nodes defined on the current path with + this option set and then inserts all of them, in the order they appear, + just before it draws the path. Thus, several nodes with this option set + may obscure one another, but never the path itself. ``Just before it + draws the path'' actually means that the nodes are inserted into the + page output just before any pre-actions are applied to the path (see + below for what pre-actions are). + % \begin{codeexample}[] \tikz \fill [fill=blue!50, draw=blue, very thick] (0,0) node [behind path, fill=red!50] {first node} @@ -172,59 +171,59 @@ The syntax for specifying nodes is the following: -- (1.5,1) node [behind path, fill=brown!50] {third node} -- (0,1) node [ fill=blue!30] {fourth node}; \end{codeexample} - - Note that |behind path| only applies to the current path; not to - the current scope or picture. To put a node ``behind everything'' - you need to use layers and options like |on background layer|, see - the background library in Section~\ref{section-tikz-backgrounds}. - \end{key} - - \begin{key}{/tikz/in front of path} - This is the opposite of |behind path|: It causes nodes to be drawn - on top of the path. Since this is the default behaviour, you - usually do not need this option; it is only needed when an - enclosing scope has used |behind path| and you now wish to - ``switch back'' to the normal behaviour. - \end{key} - - \medskip - \textbf{The name of a node.} - The |(|\meta{name}|)| is a name for later reference and it is - optional. You may also add the option |name=|\meta{name} to the - \meta{option} list; it has the same effect. - - \begin{key}{/tikz/name=\meta{node name}} - Assigns a name to the node for later reference. Since this is a - ``high-level'' name (drivers never know of it), you can use spaces, - number, letters, or whatever you like when naming a node. Thus, you - can name a node just |1| or perhaps |start of chart| or even - |y_1|. Your node name should \emph{not} contain any punctuation like - a dot, a comma, or a colon since these are used to detect what kind - of coordinate you mean when you reference a node. - \end{key} - - \begin{key}{/tikz/alias=\meta{another node name}} - This option allows you to provide another name for the - node. Giving this option multiple times will allow you to access - the node via several aliases. Using the |node also| syntax, - you can also assign an alias name to a node at a later point, see - Section~\ref{section-node-also}. - \end{key} - - \medskip - \textbf{The options of a node.} - The \meta{options} is an optional list of options that \emph{apply - only to the node} and have no effect outside. The other way round, - most ``outside'' options also apply to the node, but not all. For - example, the ``outside'' rotation does not apply to nodes (unless some - special options are used, sigh). Also, the outside path action, like - |draw| or |fill|, never applies to the node and must be given in the - node (unless some special other options are used, deep sigh). - - \medskip - \textbf{The shape of a node.} - As mentioned before, we can add a border and even a background to a - node: + + Note that |behind path| only applies to the current path; not to the + current scope or picture. To put a node ``behind everything'' you need + to use layers and options like |on background layer|, see the + background library in Section~\ref{section-tikz-backgrounds}. + \end{key} + + \begin{key}{/tikz/in front of path} + This is the opposite of |behind path|: It causes nodes to be drawn on + top of the path. Since this is the default behaviour, you usually do + not need this option; it is only needed when an enclosing scope has + used |behind path| and you now wish to ``switch back'' to the normal + behaviour. + \end{key} + + \medskip + \textbf{The name of a node.} + The |(|\meta{name}|)| is a name for later reference and it is optional. You + may also add the option |name=|\meta{name} to the \meta{option} list; it + has the same effect. + + \begin{key}{/tikz/name=\meta{node name}} + Assigns a name to the node for later reference. Since this is a + ``high-level'' name (drivers never know of it), you can use spaces, + number, letters, or whatever you like when naming a node. Thus, you can + name a node just |1| or perhaps |start of chart| or even |y_1|. Your + node name should \emph{not} contain any punctuation like a dot, a + comma, or a colon since these are used to detect what kind of + coordinate you mean when you reference a node. + \end{key} + + \begin{key}{/tikz/alias=\meta{another node name}} + This option allows you to provide another name for the node. Giving + this option multiple times will allow you to access the node via + several aliases. Using the |node also| syntax, you can also assign an + alias name to a node at a later point, see + Section~\ref{section-node-also}. + \end{key} + + \medskip + \textbf{The options of a node.} + The \meta{options} is an optional list of options that \emph{apply only to + the node} and have no effect outside. The other way round, most ``outside'' + options also apply to the node, but not all. For example, the ``outside'' + rotation does not apply to nodes (unless some special options are used, + sigh). Also, the outside path action, like |draw| or |fill|, never applies + to the node and must be given in the node (unless some special other + options are used, deep sigh). + + \medskip + \textbf{The shape of a node.} + As mentioned before, we can add a border and even a background to a node: + % \begin{codeexample}[] \tikz \fill[fill=yellow!80!black] (0,0) node {first node} @@ -232,12 +231,12 @@ The syntax for specifying nodes is the following: -- (0,2) node[fill=red!20,draw,double,rounded corners] {third node}; \end{codeexample} - The ``border'' is actually just a special case of a much more general - mechanism. Each node has a certain \emph{shape} which, by default, is - a rectangle. However, we can also ask \tikzname\ to use a circle shape - instead or an ellipse shape (you have to include one of the - |shapes.geometric| library for the latter shape): - + The ``border'' is actually just a special case of a much more general + mechanism. Each node has a certain \emph{shape} which, by default, is a + rectangle. However, we can also ask \tikzname\ to use a circle shape + instead or an ellipse shape (you have to include one of the + |shapes.geometric| library for the latter shape): + % \begin{codeexample}[] \tikz \fill[fill=yellow!80!black] (0,0) node {first node} @@ -245,73 +244,98 @@ The syntax for specifying nodes is the following: -- (0,2) node[circle,fill=red!20] {third node}; \end{codeexample} - There are many more shapes available such as, say, a shape for a - resistor or a large arrow, see the |shapes| library in - Section~\ref{section-libs-shapes} for details. - - To select the shape of a node, the following option is used: - \begin{key}{/tikz/shape=\meta{shape name} (initially rectangle)} - Select the shape either of the current node or, when this option is - not given inside a node but somewhere outside, the shape of all - nodes in the current scope.% - \indexoption{\meta{shape name}} - - Since this option is used often, you can leave out the - |shape=|. When \tikzname\ encounters an option like |circle| - that it does not know, it will, after everything else has failed, - check whether this option is the name of some shape. If so, that - shape is selected as if you had said |shape=|\meta{shape name}. - - By default, the following shapes are available: |rectangle|, - |circle|, |coordinate|. Details of these shapes, like their anchors - and size options, are discussed in Section~\ref{section-the-shapes}. - \end{key} - - \medskip - \textbf{The foreach statement for nodes.} - At the beginning of a node specification (and only there) you can provide multiple - \meta{foreach statements}, each of which has the form |foreach| \meta{var} - |in| |{|\meta{list}|}| (note that there is no slash before - |foreach|). When they are given, instead of a single node, multiple - nodes will be created: The \meta{var} will iterate over all values - of \meta{list} and for each of them, a new node is created. These - nodes are all created using all the text following the \meta{foreach - statements}, but in each copy the \meta{var} will have the current - value of the current element in the \meta{list}. - - As an example, the following two codes have the same effect: + There are many more shapes available such as, say, a shape for a resistor + or a large arrow, see the |shapes| library in + Section~\ref{section-libs-shapes} for details. + + To select the shape of a node, the following option is used: + % + \begin{key}{/tikz/shape=\meta{shape name} (initially rectangle)} + Select the shape either of the current node or, when this option is not + given inside a node but somewhere outside, the shape of all nodes in + the current scope.% + \indexoption{\meta{shape name}} + + Since this option is used often, you can leave out the |shape=|. When + \tikzname\ encounters an option like |circle| that it does not know, it + will, after everything else has failed, check whether this option is + the name of some shape. If so, that shape is selected as if you had + said |shape=|\meta{shape name}. + + By default, the following shapes are available: |rectangle|, |circle|, + |coordinate|. Details of these shapes, like their anchors and size + options, are discussed in Section~\ref{section-the-shapes}. + \end{key} + + \medskip + \textbf{Animating a node.} + When you say |:|\meta{animation attribute}|={|\meta{options}|}|, an + \emph{animation} of the specified attribute is added to the node. + Animations are discussed in detail in + Section~\ref{section-tikz-animations}. Here is a typical example of how + this syntax can be used: + % +\begin{codeexample}[animation list={0.5,1,1.5,2}] +\tikz + \node :fill opacity = { 0s="1", 2s="0", begin on=click } + :rotate = { 0s="0", 2s="90", begin on=click } + [fill = blue!20, draw = blue, ultra thick, circle] + {Click me!}; +\end{codeexample} + + \medskip + \textbf{The foreach statement for nodes.} + At the beginning of a node specification (and only there) you can provide + multiple \meta{foreach statements}, each of which has the form |foreach| + \meta{var} |in| |{|\meta{list}|}| (note that there is no slash before + |foreach|). When they are given, instead of a single node, multiple nodes + will be created: The \meta{var} will iterate over all values of \meta{list} + and for each of them, a new node is created. These nodes are all created + using all the text following the \meta{foreach statements}, but in each + copy the \meta{var} will have the current value of the current element in + the \meta{list}. + + As an example, the following two codes have the same effect: + % \begin{codeexample}[] \tikz \draw (0,0) node foreach \x in {1,2,3} at (\x,0) {\x}; \end{codeexample} \begin{codeexample}[] \tikz \draw (0,0) node at (1,0) {1} node at (2,0) {2} node at (3,0) {3}; \end{codeexample} - When you provide several |foreach| statements, they work like - ``nested loops'': +% + When you provide several |foreach| statements, they work like ``nested + loops'': + % \begin{codeexample}[] \tikz \node foreach \x in {1,...,4} foreach \y in {1,2,3} [draw] at (\x,\y) {\x,\y}; \end{codeexample} - As the example shows, a \meta{list} can contain ellipses (three - dots) to indicated that a larger number of numbers is meant. Indeed, - you can use the full power of the |\foreach| command here, including - multiple parameters and options, see Section~\ref{section-foreach}. + % + As the example shows, a \meta{list} can contain ellipses (three dots) to + indicated that a larger number of numbers is meant. Indeed, you can use the + full power of the |\foreach| command here, including multiple parameters + and options, see Section~\ref{section-foreach}. - \medskip - \textbf{Styles for nodes.} - The following styles influence how nodes are rendered: - \begin{stylekey}{/tikz/every node (initially \normalfont empty)} - This style is installed at the beginning of every node. + \medskip + \textbf{Styles for nodes.} + The following styles influence how nodes are rendered: + % + \begin{stylekey}{/tikz/every node (initially \normalfont empty)} + This style is installed at the beginning of every node. + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw}] \draw (0,0) node {A} -- (1,1) node {B}; \end{tikzpicture} \end{codeexample} - \end{stylekey} - \begin{stylekey}{/tikz/every \meta{shape} node (initially \normalfont empty)} - These styles are installed at the beginning of a node of a given - \meta{shape}. For example, |every rectangle node| is used for - rectangle nodes, and so on. + \end{stylekey} + % + \begin{stylekey}{/tikz/every \meta{shape} node (initially \normalfont empty)} + These styles are installed at the beginning of a node of a given + \meta{shape}. For example, |every rectangle node| is used for rectangle + nodes, and so on. + % \begin{codeexample}[] \begin{tikzpicture} [every rectangle node/.style={draw}, @@ -319,24 +343,47 @@ The syntax for specifying nodes is the following: \draw (0,0) node[rectangle] {A} -- (1,1) node[circle] {B}; \end{tikzpicture} \end{codeexample} - \end{stylekey} - - \medskip - \textbf{Name scopes.} - It turns out that the name of a node can further be influenced using - two keys: - \begin{key}{/tikz/name prefix=\meta{text} (initially \normalfont empty)} - The value of this key is prefixed to every node inside the - current scope. This includes both the naming of the node (via - the |name| key or via the implicit |(|\meta{name}|)| syntax) as - well as any referencing of the node. Outside the scope, - the nodes can (and need to) be referenced using ``full name'' - consisting of the prefix and the node name. - - The net effect of this is that you can set the name prefix at - the beginning of a scope to some value and then use short and - simple names for the nodes inside the scope. Later, outside the - scope, you can reference the nodes via their full name: + \end{stylekey} + + \begin{key}{/tikz/execute at begin node=\meta{code}} + This option causes \meta{code} to be executed at the beginning of a + node. Using this option multiple times will cause the code to + accumulate. + \end{key} + + \begin{key}{/tikz/execute at end node=\meta{code}} + This option installs \meta{code} that will be executed at the end of + the node. Using this option multiple times will cause the code to + accumulate. + % +\begin{codeexample}[] +\begin{tikzpicture} + [execute at begin node={A}, + execute at end node={D}] + \node[execute at begin node={B}] {C}; +\end{tikzpicture} +\end{codeexample} + % + \end{key} + + \medskip + \textbf{Name scopes.} + It turns out that the name of a node can further be influenced using two + keys: + % + \begin{key}{/tikz/name prefix=\meta{text} (initially \normalfont empty)} + The value of this key is prefixed to every node inside the current + scope. This includes both the naming of the node (via the |name| key or + via the implicit |(|\meta{name}|)| syntax) as well as any referencing + of the node. Outside the scope, the nodes can (and need to) be + referenced using ``full name'' consisting of the prefix and the node + name. + + The net effect of this is that you can set the name prefix at the + beginning of a scope to some value and then use short and simple names + for the nodes inside the scope. Later, outside the scope, you can + reference the nodes via their full name: + % \begin{codeexample}[] \tikz { \begin{scope}[name prefix = top-] @@ -349,68 +396,67 @@ The syntax for specifying nodes is the following: \node (B) at (1,0) {B}; \draw (A) -- (B); \end{scope} - - \draw [red] (top-A) -- (bottom-B); + + \draw [red] (top-A) -- (bottom-B); } \end{codeexample} - As can be seen, name prefixing makes it easy to write - ``recycable'' code. - \end{key} - \begin{key}{/tikz/name suffix=\meta{text} (initially \normalfont empty)} - Works as |name prefix|, only the \meta{text} is appended to - every node name in the current scope. - \end{key} + % + As can be seen, name prefixing makes it easy to write reusable code. + \end{key} + % + \begin{key}{/tikz/name suffix=\meta{text} (initially \normalfont empty)} + Works as |name prefix|, only the \meta{text} is appended to every node + name in the current scope. + \end{key} \end{pathoperation} There is a special syntax for specifying ``light-weight'' nodes: \begin{pathoperation}{coordinate}{\opt{|[|\meta{options}|]|}|(|\meta{name}|)|\opt{|at(|\meta{coordinate}|)|}} - This has the same effect as + This has the same effect as - |\node[shape=coordinate]|\verb|[|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|, + |\node[shape=coordinate]|\verb|[|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|, - where the |at| part may be omitted. + where the |at| part may be omitted. \end{pathoperation} -Since nodes are often the only path operation on paths, there are two -special commands for creating paths containing only a node: +Since nodes are often the only path operation on paths, there are two special +commands for creating paths containing only a node: \begin{command}{\node} - Inside |{tikzpicture}| this is an abbreviation for |\path node|. + Inside |{tikzpicture}| this is an abbreviation for |\path node|. \end{command} \begin{command}{\coordinate} - Inside |{tikzpicture}| this is an abbreviation for |\path coordinate|. + Inside |{tikzpicture}| this is an abbreviation for |\path coordinate|. \end{command} \subsubsection{Predefined Shapes} - \label{section-nodes-predefined} - \label{section-the-shapes} -\pgfname\ and \tikzname\ define three shapes, by default: +\pgfname\ \todosp{why two labels for the same point? The first doesn't seem to +be used anywhere} and \tikzname\ define three shapes, by default: +% \begin{itemize} -\item - |rectangle|, -\item - |circle|, and -\item - |coordinate|. + \item |rectangle|, + \item |circle|, and + \item |coordinate|. \end{itemize} -By loading library packages, you can define more shapes like ellipses -or diamonds; see Section~\ref{section-libs-shapes} for the complete -list of shapes. - -\label{section-tikz-coordinate-shape} -The |coordinate| shape is handled in a special way by \tikzname. When -a node |x| whose shape is |coordinate| is used as a coordinate |(x)|, -this has the same effect as if you had said |(x.center)|. None of the -special ``line shortening rules'' apply in this case. This can be -useful since, normally, the line shortening causes paths to be -segmented and they cannot be used for filling. Here is an example that -demonstrates the difference: +% +By loading library packages, you can define more shapes like ellipses or +diamonds; see Section~\ref{section-libs-shapes} for the complete list of +shapes. + +\label{section-tikz-coordinate-shape}% +The |coordinate| shape is handled in a special way by \tikzname. When a node +|x| whose shape is |coordinate| is used as a coordinate |(x)|, this has the +same effect as if you had said |(x.center)|. None of the special ``line +shortening rules'' apply in this case. This can be useful since, normally, the +line shortening causes paths to be segmented and they cannot be used for +filling. Here is an example that demonstrates the difference: +% \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw}] \path[yshift=1.5cm,shape=rectangle] @@ -426,29 +472,25 @@ demonstrates the difference: \end{codeexample} - \subsubsection{Common Options: Separations, Margins, Padding and - Border Rotation} - + Border Rotation} \label{section-shape-seps} \label{section-shape-common-options} -The exact behaviour of shapes differs, shapes defined for more -special purposes (like a, say, transistor shape) will have even more -custom behaviors. However, there are some options that apply to most -shapes: +The \todosp{why two labels for the same point?} exact behaviour of shapes +differs, shapes defined for more special purposes (like a, say, transistor +shape) will have even more custom behaviors. However, there are some options +that apply to most shapes: \begin{key}{/pgf/inner sep=\meta{dimension} (initially .3333em)} - \keyalias{tikz} - An additional (invisible) separation space of \meta{dimension} will - be added inside the shape, between the text and the shape's - background path. The effect is as if you had added appropriate - horizontal and vertical skips at the beginning and end of the text - to make it a bit ``larger.'' - - For those familiar with \textsc{css}, this is the same as - \emph{padding}. + \keyalias{tikz} + An additional (invisible) separation space of \meta{dimension} will be + added inside the shape, between the text and the shape's background path. + The effect is as if you had added appropriate horizontal and vertical skips + at the beginning and end of the text to make it a bit ``larger''. + For those familiar with \textsc{css}, this is the same as \emph{padding}. + % \begin{codeexample}[] \begin{tikzpicture} \draw (0,0) node[inner sep=0pt,draw] {tight} @@ -456,31 +498,31 @@ shapes: (0cm,4em) node[fill=yellow!80!black] {default}; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/pgf/inner xsep=\meta{dimension} (initially .3333em)} - \keyalias{tikz} - Specifies the inner separation in the $x$-direction, only. + \keyalias{tikz} + Specifies the inner separation in the $x$-direction, only. \end{key} \begin{key}{/pgf/inner ysep=\meta{dimension} (initially .3333em)} - \keyalias{tikz} - Specifies the inner separation in the $y$-direction, only. + \keyalias{tikz} + Specifies the inner separation in the $y$-direction, only. \end{key} \begin{key}{/pgf/outer sep=\meta{dimension or ``auto''}} - \keyalias{tikz} - This option adds an additional (invisible) separation space of - \meta{dimension} outside the background path. The main effect of - this option is that all anchors will move a little ``to the - outside.'' + \keyalias{tikz} + This option adds an additional (invisible) separation space of + \meta{dimension} outside the background path. The main effect of this + option is that all anchors will move a little ``to the outside''. - For those familiar with \textsc{css}, this is same as \emph{margin}. + For those familiar with \textsc{css}, this is same as \emph{margin}. - The default for this option is half the line width. When the default - is used and when the background path is draw, the anchors will lie - exactly on the ``outside border'' of the path (not on the path - itself). + The default for this option is half the line width. When the default is + used and when the background path is draw, the anchors will lie exactly on + the ``outside border'' of the path (not on the path itself). + % \begin{codeexample}[] \begin{tikzpicture} \draw[line width=5pt] @@ -493,30 +535,29 @@ shapes: \draw[->] (1,-1) -- (s); \end{tikzpicture} \end{codeexample} - - As the above example demonstrates, the standard settings for the - outer sep are not always ``correct.'' First, when a shape is filled, - but not drawn, the outer sep should actually be |0|. Second, when a - node is scaled, for instance by a factor of 5, the outer separation - also gets scaled by a factor of 5, while the line width stays at its - original width; again causing problems. - - In such cases, you can say |outer sep=auto| to make \tikzname\ - \emph{try} to compensate for the effects described above. This is - done by, firstly, setting the outer sep to |0| when no drawing is - done and, secondly, setting the outer separations to half the line - width (as before) times two adjustment factors, one for the - horizontal separations and one for the vertical - separations (see Section~\ref{section-adjustment-transformations} - for details on these factors). Note, however, that these factors can - compensate only for transformations that are either scalings plus - rotations or scalings with different magnitudes in the horizontal - and the vertical direction. If you apply slanting, the factors will - only approximate the correct values. - - In general, it is a good idea to say |outer sep=auto| at some early - stage. It is not the default mainly for compatibility with earlier - versions. + + As the above example demonstrates, the standard settings for the outer sep + are not always ``correct''. First, when a shape is filled, but not drawn, + the outer sep should actually be |0|. Second, when a node is scaled, for + instance by a factor of 5, the outer separation also gets scaled by a + factor of 5, while the line width stays at its original width; again + causing problems. + + In such cases, you can say |outer sep=auto| to make \tikzname\ \emph{try} + to compensate for the effects described above. This is done by, firstly, + setting the outer sep to |0| when no drawing is done and, secondly, setting + the outer separations to half the line width (as before) times two + adjustment factors, one for the horizontal separations and one for the + vertical separations (see Section~\ref{section-adjustment-transformations} + for details on these factors). Note, however, that these factors can + compensate only for transformations that are either scalings plus rotations + or scalings with different magnitudes in the horizontal and the vertical + direction. If you apply slanting, the factors will only approximate the + correct values. + + In general, it is a good idea to say |outer sep=auto| at some early stage. + It is not the default mainly for compatibility with earlier versions. + % \begin{codeexample}[] \begin{tikzpicture}[outer sep=auto] \draw[line width=5pt] @@ -529,140 +570,137 @@ shapes: \draw[->] (1,-1) -- (s); \end{tikzpicture} \end{codeexample} + % \end{key} - \begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)} - \keyalias{tikz} - Specifies the outer separation in the $x$-direction, only. This - value will be overwritten when |outer sep| is set, either to the - value given there or a computed value in case of |auto|. + \keyalias{tikz} + Specifies the outer separation in the $x$-direction, only. This value will + be overwritten when |outer sep| is set, either to the value given there or + a computed value in case of |auto|. \end{key} \begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)} - \keyalias{tikz} - Specifies the outer separation in the $y$-direction, only. + \keyalias{tikz} + Specifies the outer separation in the $y$-direction, only. \end{key} - \begin{key}{/pgf/minimum height=\meta{dimension} (initially 0pt)} - \keyalias{tikz} - This option ensures that the height of the shape (including the - inner, but ignoring the outer separation) will be at least - \meta{dimension}. Thus, if the text plus the inner separation is not - at least as large as \meta{dimension}, the shape will be enlarged - appropriately. However, if the text is already larger than - \meta{dimension}, the shape will not be shrunk. + \keyalias{tikz} + This option ensures that the height of the shape (including the inner, but + ignoring the outer separation) will be at least \meta{dimension}. Thus, if + the text plus the inner separation is not at least as large as + \meta{dimension}, the shape will be enlarged appropriately. However, if the + text is already larger than \meta{dimension}, the shape will not be shrunk. + % \begin{codeexample}[] \begin{tikzpicture} \draw (0,0) node[minimum height=1cm,draw] {1cm} (2,0) node[minimum height=0cm,draw] {0cm}; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/pgf/minimum width=\meta{dimension} (initially 0pt)} - \keyalias{tikz} - Same as |minimum height|, only for the width. + \keyalias{tikz} + Same as |minimum height|, only for the width. + % \begin{codeexample}[] \begin{tikzpicture} \draw (0,0) node[minimum height=2cm,minimum width=3cm,draw] {$3 \times 2$}; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/pgf/minimum size=\meta{dimension}} - \keyalias{tikz} - Sets both the minimum height and width at the same time. + \keyalias{tikz} + Sets both the minimum height and width at the same time. + % \begin{codeexample}[] \begin{tikzpicture} \draw (0,0) node[minimum size=2cm,draw] {square}; \draw (0,-2) node[minimum size=2cm,draw,circle] {circle}; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/pgf/shape aspect=\meta{aspect ratio}} - \keyalias{tikz} - Sets a desired aspect ratio for the shape. For the |diamond| shape, - this option sets the ratio between width and height of the shape. + \keyalias{tikz} + Sets a desired aspect ratio for the shape. For the |diamond| shape, this + option sets the ratio between width and height of the shape. + % \begin{codeexample}[] \begin{tikzpicture} \draw (0,0) node[shape aspect=1,diamond,draw] {aspect 1}; \draw (0,-2) node[shape aspect=2,diamond,draw] {aspect 2}; \end{tikzpicture} \end{codeexample} + % \end{key} -\label{section-rotating-shape-borders} + \label{section-rotating-shape-borders} -Some shapes (but not all), support a special kind of rotation. This -rotation affects only the border of a shape and is independent of the -node contents, but \emph{in addition} to any other transformations. - +Some shapes (but not all), support a special kind of rotation. This rotation +affects only the border of a shape and is independent of the node contents, but +\emph{in addition} to any other transformations. +% \begin{codeexample}[] -\tikzstyle{every node}=[dart, shape border uses incircle, - inner sep=1pt, draw] +\tikzset{every node/.style={dart, shape border uses incircle, + inner sep=1pt, draw}} \tikz \node foreach \a/\b/\c in {A/0/0, B/45/0, C/0/45, D/45/45} [shape border rotate=\b, rotate=\c] at (\b/36,-\c/36) {\a}; \end{codeexample} -There are two types of rotation: restricted and unrestricted. Which -type of rotation is applied is determined by on how the shape border -is constructed. If the shape border is constructed using an incircle, -that is, a circle that tightly fits the node contents (including -the |inner sep|), then the rotation can be unrestricted. If, however, -the border is constructed using the natural dimensions of the node -contents, the rotation is restricted to integer multiples of 90 -degrees. - -Why should there be two kinds of rotation and border construction? -Borders constructed using the natural dimensions of the node contents -provide a much tighter fit to the node contents, but to maintain -this tight fit, the border rotation must be restricted to integer -multiples of 90 degrees. By using an incircle, unrestricted rotation -is possible, but the border will not make a very tight fit to the -node contents. - -\begin{codeexample}[] -\tikzstyle{every node}=[isosceles triangle, draw] +There are two types of rotation: restricted and unrestricted. Which type of +rotation is applied is determined by on how the shape border is constructed. If +the shape border is constructed using an incircle, that is, a circle that +tightly fits the node contents (including the |inner sep|), then the rotation +can be unrestricted. If, however, the border is constructed using the natural +dimensions of the node contents, the rotation is restricted to integer +multiples of 90 degrees. + +Why should there be two kinds of rotation and border construction? Borders +constructed using the natural dimensions of the node contents provide a much +tighter fit to the node contents, but to maintain this tight fit, the border +rotation must be restricted to integer multiples of 90 degrees. By using an +incircle, unrestricted rotation is possible, but the border will not make a +very tight fit to the node contents. +% +\begin{codeexample}[] +\tikzset{every node/.style={isosceles triangle, draw}} \begin{tikzpicture} \node {abc}; \node [shape border uses incircle] at (2,0) {abc}; \end{tikzpicture} \end{codeexample} -There are \pgfname{} keys that determine how a shape border is -constructed, and to specify its rotation. -It should be noted that not all shapes support these keys, so -reference should be made to the documentation for individual -shapes. - -\begin{key}{/pgf/shape border uses incircle=\opt{\meta{boolean}} - (default true)} - \keyalias{tikz} - Determines if the border of a shape is constructed using the - incircle. If no value is given \meta{boolean} will take the default - value |true|. -\end{key} +There are \pgfname{} keys that determine how a shape border is constructed, and +to specify its rotation. It should be noted that not all shapes support these +keys, so reference should be made to the documentation for individual shapes. +\begin{key}{/pgf/shape border uses incircle=\opt{\meta{boolean}} (default true)} + \keyalias{tikz} + Determines if the border of a shape is constructed using the incircle. If + no value is given \meta{boolean} will take the default value |true|. +\end{key} \begin{key}{/pgf/shape border rotate=\meta{angle} (initially 0)} - \keyalias{tikz} - Rotates the border of a shape independently of the node contents, - but in addition to any other transformations. If the shape - border is not constructed using the incircle, the rotation will be - rounded to the nearest integer multiple of 90 degrees when the - shape is drawn. + \keyalias{tikz} + Rotates the border of a shape independently of the node contents, but in + addition to any other transformations. If the shape border is not + constructed using the incircle, the rotation will be rounded to the nearest + integer multiple of 90 degrees when the shape is drawn. \end{key} -Note that if the border of the shape is rotated, -the compass point anchors, and `text box' anchors (including -|mid east|, |base west|, and so on), \emph{do not rotate}, but the -other anchors do: - +Note that if the border of the shape is rotated, the compass point anchors, and +`text box' anchors (including |mid east|, |base west|, and so on), \emph{do not +rotate}, but the other anchors do: +% \begin{codeexample}[] -\tikzstyle{every node}=[shape=trapezium, draw, shape border uses incircle] +\tikzset{every node/.style={shape=trapezium, draw, shape border uses incircle}} \begin{tikzpicture} \node at (0,0) (A) {A}; \node [shape border rotate=30] at (1.5,0) (B) {B}; @@ -674,42 +712,36 @@ other anchors do: \end{tikzpicture} \end{codeexample} -Finally, a somewhat unfortunate side-effect of rotating shape borders -is that the supporting shapes do not distinguish between -|outer xsep| and |outer ysep|, and typically, the larger of the -two values will be used. - - +Finally, a somewhat unfortunate side-effect of rotating shape borders is that +the supporting shapes do not distinguish between |outer xsep| and |outer ysep|, +and typically, the larger of the two values will be used. \subsection{Multi-Part Nodes} - \label{section-nodes-multi} -Most nodes just have a single simple text label. However, nodes of a -more complicated shape might be made up from several \emph{node - parts}. For example, in automata theory a so-called Moore state has -a state name, drawn in the upper part of the state circle, and an -output text, drawn in the lower part of the state circle. These two -parts are quite independent. Similarly, a \textsc{uml} class shape -would have a name part, a method part, and an attributes -part. Different molecule shapes might use parts for the different atoms -to be drawn at the different positions, and so on. - -Both \pgfname\ and \tikzname\ support such multipart nodes. On the -lower level, \pgfname\ provides a system for specifying that a shape -consists of several parts. On the \tikzname\ level, you specify the -different node parts by using the following command: +Most nodes just have a single simple text label. However, nodes of a more +complicated shape might be made up from several \emph{node parts}. For example, +in automata theory a so-called Moore state has a state name, drawn in the upper +part of the state circle, and an output text, drawn in the lower part of the +state circle. These two parts are quite independent. Similarly, a \textsc{uml} +class shape would have a name part, a method part, and an attributes part. +Different molecule shapes might use parts for the different atoms to be drawn +at the different positions, and so on. -\begin{command}{\nodepart\opt{|[|\meta{options}|]|}\marg{part name}} - This command can only be used inside the \meta{text} argument of a - |node| path operation. It works a little bit like a |\part| command - in \LaTeX. It will stop the typesetting of whatever node part was - typeset until now and then start putting all following text into the - node part named \meta{part name}---until another |\partname| is - encountered or until the node \meta{text} ends. The \meta{options} - will be local to this part. +Both \pgfname\ and \tikzname\ support such multipart nodes. On the lower level, +\pgfname\ provides a system for specifying that a shape consists of several +parts. On the \tikzname\ level, you specify the different node parts by using +the following command: +\begin{command}{\nodepart\opt{|[|\meta{options}|]|}\marg{part name}} + This command can only be used inside the \meta{text} argument of a |node| + path operation. It works a little bit like a |\part| command in \LaTeX. It + will stop the typesetting of whatever node part was typeset until now and + then start putting all following text into the node part named \meta{part + name} -- until another |\partname| is encountered or until the node + \meta{text} ends. The \meta{options} will be local to this part. + % \begin{codeexample}[] \begin{tikzpicture} \node [circle split,draw,double,fill=red!20] @@ -723,36 +755,36 @@ different node parts by using the following command: \end{tikzpicture} \end{codeexample} - You will have to lookup which parts are defined by a shape. + You will have to lookup which parts are defined by a shape. - The following styles influences node parts: - \begin{stylekey}{/tikz/every \meta{part name} node part (initially - \normalfont empty)} - This style is installed at the beginning of every node part named - \meta{part name}. + The following styles influences node parts: + % + \begin{stylekey}{/tikz/every \meta{part name} node part (initially \normalfont empty)} + This style is installed at the beginning of every node part named + \meta{part name}. + % \begin{codeexample}[] \tikz [every lower node part/.style={red}] \node [circle split,draw] {$q_1$ \nodepart{lower} $00$}; \end{codeexample} - \end{stylekey} + \end{stylekey} \end{command} - \subsection{The Node Text} - \label{section-nodes-options} \subsubsection{Text Parameters: Color and Opacity} -The simplest option for the text in nodes is its color. Normally, this -color is just the last color installed using |color=|, possibly -inherited from another scope. However, it is possible to specifically -set the color used for text using the following option: +The simplest option for the text in nodes is its color. Normally, this color is +just the last color installed using |color=|, possibly inherited from another +scope. However, it is possible to specifically set the color used for text +using the following option: \begin{key}{/tikz/text=\meta{color}} - Sets the color to be used for text labels. A |color=| option - will immediately override this option. + Sets the color to be used for text labels. A |color=| option will + immediately override this option. + % \begin{codeexample}[] \begin{tikzpicture} \draw[red] (0,0) -- +(1,1) node[above] {red}; @@ -760,46 +792,52 @@ set the color used for text using the following option: \draw (2,0) -- +(1,1) node[above,red] {red}; \end{tikzpicture} \end{codeexample} + % \end{key} -Just like the color itself, you may also wish to set the opacity of -the text only. For this, use the |text opacity| option, which -is detailed in Section~\ref{section-tikz-transparency}. +Just like the color itself, you may also wish to set the opacity of the text +only. For this, use the |text opacity| option, which is detailed in +Section~\ref{section-tikz-transparency}. + \subsubsection{Text Parameters: Font} -Next, you may wish to adjust the font used for the text. Naturally, -you can just use a font command like |\small| or |\rm| at the -beginning of a node. However, the following two options make it easier -to set the font used in nodes on a general basis. Let us start with: +Next, you may wish to adjust the font used for the text. Naturally, you can +just use a font command like |\small| or |\rm| at the beginning of a node. +However, the following two options make it easier to set the font used in nodes +on a general basis. Let us start with: \begin{key}{/tikz/node font=\meta{font commands}} - This option sets the font used for all text used in a node. + This option sets the font used for all text used in a node. + % \begin{codeexample}[] \begin{tikzpicture} \draw[node font=\itshape] (1,0) -- +(1,1) node[above] {italic}; \end{tikzpicture} \end{codeexample} - Since the \meta{font commands} are executed at a very early stage in - the construction of the node, the font selected using this command - will also dictate the values of dimensions defined in terms of |em| - or |ex|. For instance, when the |minimum height| of a node is |3em|, - the actual height will be (at least) three times the line distance - selected by the \meta{font commands}: + % + Since the \meta{font commands} are executed at a very early stage in the + construction of the node, the font selected using this command will also + dictate the values of dimensions defined in terms of |em| or |ex|. For + instance, when the |minimum height| of a node is |3em|, the actual height + will be (at least) three times the line distance selected by the \meta{font + commands}: \begin{codeexample}[] \tikz \node [node font=\tiny, minimum height=3em, draw] {tiny}; \tikz \node [node font=\small, minimum height=3em, draw] {small}; \end{codeexample} + % \end{key} The other font command is: - +% \begin{key}{/tikz/font=\meta{font commands}} - Sets the font used for the text inside nodes. However, this font - will \emph{not} (yet) be installed when any of the dimensions of the - node are being computed, so dimensions like |1em| will be with - respect to the font used outside the node (usually the font that was - in force when the picture started). + Sets the font used for the text inside nodes. However, this font will + \emph{not} (yet) be installed when any of the dimensions of the node are + being computed, so dimensions like |1em| will be with respect to the font + used outside the node (usually the font that was in force when the picture + started). + % \begin{codeexample}[] \begin{tikzpicture} \node [font=\itshape] {italic}; @@ -811,34 +849,35 @@ The other font command is: \tikz \node [font=\small, minimum height=3em, draw] {small}; \end{codeexample} - A useful example of how the |font| option can be used is the - following: - + A useful example of how the |font| option can be used is the following: + % \begin{codeexample}[] \tikz [every text node part/.style={font=\itshape}, every lower node part/.style={font=\footnotesize}] \node [circle split,draw] {state \nodepart{lower} output}; \end{codeexample} - As can be seen, the font can be changed for each node part. This - does \emph{not} work with the |node font| command since, as the name - suggests, this command can only be used to select the ``overall'' - font for the node and this is done very early. + As can be seen, the font can be changed for each node part. This does + \emph{not} work with the |node font| command since, as the name suggests, + this command can only be used to select the ``overall'' font for the node + and this is done very early. \end{key} \subsubsection{Text Parameters: Alignment and Width for Multi-Line Text} -Normally, when a node is typeset, all the text you give in the braces -is put in one long line (in an |\hbox|, to be precise) and the node -will become as wide as necessary. +Normally, when a node is typeset, all the text you give in the braces is put in +one long line (in an |\hbox|, to be precise) and the node will become as wide +as necessary. -From time to time you may wish to create nodes that contain multiple -lines of text. There are three different ways of achieving this: +From time to time you may wish to create nodes that contain multiple lines of +text. There are three different ways of achieving this: +% \begin{enumerate} -\item Inside the node, you can put some standard environment that - produces multi-line, aligned text. For instance, you can use a - |{tabular}| inside a node: + \item Inside the node, you can put some standard environment that produces + multi-line, aligned text. For instance, you can use a |{tabular}| + inside a node: + % \begin{codeexample}[width=5cm] \tikz \node [draw] { \begin{tabular}{cc} @@ -847,119 +886,134 @@ lines of text. There are three different ways of achieving this: \end{tabular} }; \end{codeexample} - This approach offers the most flexibility in the sense that it - allows you to use all of the alignment commands offered by your - format of choice. -\item You use |\\| inside your node to mark the end of lines and then - request \tikzname\ to arrange these lines in some manner. This will - only be done, however, if the |align| option has been given. + % + This approach offers the most flexibility in the sense that it allows + you to use all of the alignment commands offered by your format of + choice. + \item You use |\\| inside your node to mark the end of lines and then + request \tikzname\ to arrange these lines in some manner. This will + only be done, however, if the |align| option has been given. + % \begin{codeexample}[] \tikz[align=left] \node[draw] {This is a\\demonstration.}; \end{codeexample} + % \begin{codeexample}[] \tikz[align=center] \node[draw] {This is a\\demonstration.}; \end{codeexample} - The |\\| command takes an optional extra space as an argument in square - brackets. + % + The |\\| command takes an optional extra space as an argument in square + brackets. + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,align=right] {This is a\\[-2pt] demonstration text for\\[1ex] alignments.}; \end{codeexample} -\item You can request that \tikzname\ does an automatic line-breaking - for you inside the node by specifying a fixed |text width| for the - node. In this case, you can still use |\\| to enforce a - line-break. Note that when you specify a text width, the node will - have this width, independently of whether the text actually - ``reaches the end'' of the node. + % + \item You can request that \tikzname\ does an automatic line-breaking for + you inside the node by specifying a fixed |text width| for the node. In + this case, you can still use |\\| to enforce a line-break. Note that + when you specify a text width, the node will have this width, + independently of whether the text actually ``reaches the end'' of the + node. \end{enumerate} Let us now first have a look at the |text width| command. + % \begin{key}{/tikz/text width=\meta{dimension}} - This option will put the text of a node in a box of the given width - (something akin to a |{minipage}| of this width, only portable - across formats). If the node text is not as wide as - \meta{dimension}, it will nevertheless be put in a box of this - width. If it is larger, line breaking will be done. - - By default, when this option is given, a ragged right border will be - used (|align=left|). This is sensible since, typically, these boxes - are narrow and justifying the text looks ugly. You can, however, - change the alignment using |align| or directly using commands line - |\centering|. + This option will put the text of a node in a box of the given width + (something akin to a |{minipage}| of this width, only portable across + formats). If the node text is not as wide as \meta{dimension}, it will + nevertheless be put in a box of this width. If it is larger, line breaking + will be done. + + By default, when this option is given, a ragged right border will be used + (|align=left|). This is sensible since, typically, these boxes are narrow + and justifying the text looks ugly. You can, however, change the alignment + using |align| or directly using commands line |\centering|. + % \begin{codeexample}[] \tikz \draw (0,0) node[fill=yellow!80!black,text width=3cm] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - Setting \meta{dimension} to an empty string causes the automatic - line breaking to be disabled. + % + Setting \meta{dimension} to an empty string causes the automatic line + breaking to be disabled. \end{key} \begin{key}{/tikz/align=\meta{alignment option}} - This key is used to set up an alignment for multi-line text inside a - node. If |text width| is set to some width (let us call this - \emph{alignment with line breaking}), the |align| key will - setup the |\leftskip| and the |\rightskip| in such a way that the - text is broken and aligned according to \meta{alignment option}. If |text width| - is not set (that is, set to the empty string; let us call this - \emph{alignment without line breaking}), then a different - mechanism is used internally, namely the key |node halign header|, is - set to an appropriate value. While this key, which is documented - below, is not to be used by beginners, the net effect is simple: - When |text width| is not set, you can use |\\| to break lines and - align them according to \meta{alignment option} and the resulting node's width - will be minimal to encompass the resulting lines. - - In detail, you can set \meta{alignment option} to one of the following values: - \begin{description} - \item[|align=|\declare{|left|}] - For alignment without line breaking, the different lines are simply - aligned such that their left borders are below one another. + This key is used to set up an alignment for multi-line text inside a node. + If |text width| is set to some width (let us call this \emph{alignment with + line breaking}), the |align| key will setup the |\leftskip| and the + |\rightskip| in such a way that the text is broken and aligned according to + \meta{alignment option}. If |text width| is not set (that is, set to the + empty string; let us call this \emph{alignment without line breaking}), + then a different mechanism is used internally, namely the key + |node halign header|, is set to an appropriate value. While this key, which + is documented below, is not to be used by beginners, the net effect is + simple: When |text width| is not set, you can use |\\| to break lines and + align them according to \meta{alignment option} and the resulting node's + width will be minimal to encompass the resulting lines. + + In detail, you can set \meta{alignment option} to one of the following values: + % + \begin{description} + \item[|align=|\declare{|left|}] For alignment without line breaking, + the different lines are simply aligned such that their left borders + are below one another. + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,align=left] {This is a\\ demonstration text for\\ alignments.}; \end{codeexample} - For alignment with line breaking, the same will happen only - the lines will now, additionally, be broken automatically: + % + For alignment with line breaking, the same will happen only the + lines will now, additionally, be broken automatically: + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,text width=3cm,align=left] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - - \item[|align=|\declare{\texttt{flush left}}] - For alignment without line breaking this option has exactly the - same effect as |left|. However, for alignment with line breaking, - there is a difference: While |left| uses the - original plain \TeX\ definition of a ragged right border, in which - \TeX\ will try to balance the right border as well as possible, - |flush left| causes the right border to be ragged in the - \LaTeX-style, in which no balancing occurs. This looks ugly, but - it may be useful for very narrow boxes and when you wish to avoid - hyphenations. + % + \item[|align=|\declare{\texttt{flush left}}] For alignment without line + breaking this option has exactly the same effect as |left|. + However, for alignment with line breaking, there is a difference: + While |left| uses the original plain \TeX\ definition of a ragged + right border, in which \TeX\ will try to balance the right border + as well as possible, |flush left| causes the right border to be + ragged in the \LaTeX-style, in which no balancing occurs. This + looks ugly, but it may be useful for very narrow boxes and when you + wish to avoid hyphenations. + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,text width=3cm,align=flush left] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - - \item[|align=|\declare{|right|}] - Works like |left|, only for right alignment. + % + \item[|align=|\declare{|right|}] Works like |left|, only for right + alignment. + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,align=right] {This is a\\ demonstration text for\\ alignments.}; \end{codeexample} + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,text width=3cm,align=right] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - - \item[|align=|\declare{\texttt{flush right}}] - Works like |flush left|, only for right alignment. + % + \item[|align=|\declare{\texttt{flush right}}] Works like |flush left|, + only for right alignment. + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,text width=3cm,align=flush right] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - - \item[|align=|\declare{|center|}] - Works like |left| or |right|, only for centered alignment. + % + \item[|align=|\declare{|center|}] Works like |left| or |right|, only + for centered alignment. + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,align=center] {This is a\\ demonstration text for\\ alignments.}; @@ -969,44 +1023,41 @@ Let us now first have a look at the |text width| command. {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - There is one annoying problem with the |center| - alignment (but not with |flush center| and the other options): If - you specify a large line width and the node text - fits on a single line and is, in fact, much shorter than the - specified |text width|, an underfull horizontal box will - result. Unfortunately, this cannot be avoided, due to the way - \TeX\ works (more precisely, I have thought long and hard about this - and have not been able to figure out a sensible way to avoid this). - For this reason, \tikzname\ switches off horizontal badness - warnings inside boxes with |align=center|. Since this will also - suppress some ``wanted'' warnings, there is also an option for - switching the warnings on once more: - - \begin{key}{/tikz/badness warnings for centered text=\meta{true or - false} (initially false)} - If set to true, normal badness warnings will be issued for - centered boxes. Note that you may get annoying warnings for - perfectly normal boxes, namely whenever the box is very large - and the contents is not long enough to fill the box - sufficiently. - \end{key} - - \item[|align=|\declare{\texttt{flush center}}] - Works like |flush left| or |flush right|, only for center - alignment. Because of all the trouble that results from the - |center| option in conjunction with narrow lines, I suggest picking - this option rather than |center| \emph{unless} you have longer - text, in which case |center| will give the typographically better - results. + There is one annoying problem with the |center| alignment (but not + with |flush center| and the other options): If you specify a large + line width and the node text fits on a single line and is, in fact, + much shorter than the specified |text width|, an underfull + horizontal box will result. Unfortunately, this cannot be avoided, + due to the way \TeX\ works (more precisely, I have thought long and + hard about this and have not been able to figure out a sensible way + to avoid this). For this reason, \tikzname\ switches off horizontal + badness warnings inside boxes with |align=center|. Since this will + also suppress some ``wanted'' warnings, there is also an option for + switching the warnings on once more: + % + \begin{key}{/tikz/badness warnings for centered text=\meta{true or false} (initially false)} + If set to true, normal badness warnings will be issued for + centered boxes. Note that you may get annoying warnings for + perfectly normal boxes, namely whenever the box is very large + and the contents is not long enough to fill the box + sufficiently. + \end{key} + \item[|align=|\declare{\texttt{flush center}}] Works like |flush left| + or |flush right|, only for center alignment. Because of all the + trouble that results from the |center| option in conjunction with + narrow lines, I suggest picking this option rather than |center| + \emph{unless} you have longer text, in which case |center| will + give the typographically better results. + % \begin{codeexample}[] \tikz \node[fill=yellow!80!black,text width=3cm,align=flush center] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - - \item[|align=|\declare{|justify|}] - For alignment without line breaking, this has the same effect as - |left|. For alignment with line breaking, this causes the text to - be ``justified.'' Use this only with rather broad nodes. + % + \item[|align=|\declare{|justify|}] For alignment without line breaking, + this has the same effect as |left|. For alignment with line + breaking, this causes the text to be ``justified''. Use this only + with rather broad nodes. {% \hbadness=10000 \begin{codeexample}[] @@ -1014,130 +1065,124 @@ Let us now first have a look at the |text width| command. {This is a demonstration text for showing how line breaking works.}; \end{codeexample} } - In the above example, \TeX\ complains (rightfully) about three very - badly typeset lines. (For this manual I asked \TeX\ to stop - complaining by using |\hbadness=10000|, but this is a foul deed, - indeed.) - - \item[|align=|\declare{|none|}] - Disables all alignments and |\\| will not be redefined. - \end{description} + In the above example, \TeX\ complains (rightfully) about three very + badly typeset lines. (For this manual I asked \TeX\ to stop + complaining by using |\hbadness=10000|, but this is a foul deed, + indeed.) + \item[|align=|\declare{|none|}] Disables all alignments and |\\| will + not be redefined. + \end{description} \end{key} - -\begin{key}{/tikz/node halign header=\meta{macro storing a header} (initially - \normalfont empty)} - This is the key that is used by |align| internally for alignment - without line breaking. Read the following only if you are familiar - with the |\halign| command. - - This key only has an effect if |text width| - is empty, otherwise it is ignored. Furthermore, if \meta{macro storing a header} is - empty, then this key also has no effect. So, suppose |text width| is - empty, but \meta{header} is not. In this case the following happens: - - When the node text is parsed, the command |\\| is redefined - internally. This redefinition is done in such a way that the text - from the start of the node to the first occurrence of |\\| is put in - an |\hbox|. Then the text following |\\| up to the next |\\| is put - in another |\hbox|. This goes on until the text between the last - |\\| and the closing |}| is also put in an |\hbox|. - - The \meta{macro storing a header} should be a macro that contains - some text suitable for use as a header for the |\halign| - command. For instance, you might define +\begin{key}{/tikz/node halign header=\meta{macro storing a header} (initially \normalfont empty)} + This is the key that is used by |align| internally for alignment without + line breaking. Read the following only if you are familiar with the + |\halign| command. + + This key only has an effect if |text width| is empty, otherwise it is + ignored. Furthermore, if \meta{macro storing a header} is empty, then this + key also has no effect. So, suppose |text width| is empty, but + \meta{header} is not. In this case the following happens: + + When the node text is parsed, the command |\\| is redefined internally. + This redefinition is done in such a way that the text from the start of the + node to the first occurrence of |\\| is put in an |\hbox|. Then the text + following |\\| up to the next |\\| is put in another |\hbox|. This goes on + until the text between the last |\\| and the closing |}| is also put in an + |\hbox|. + + The \meta{macro storing a header} should be a macro that contains some text + suitable for use as a header for the |\halign| command. For instance, you + might define + % \begin{codeexample}[code only] \def\myheader{\hfil\hfil##\hfil\cr} \tikz [node halign header=\myheader] ... \end{codeexample} - You cannot just say |node halign header=\hfil\hfil#\hfil\cr| because - this confuses \TeX\ inside matrices, so this detour via a macro is - needed. - - Next, conceptually, all these boxes are recursively put inside an - |\halign| command. Assuming that \meta{first} is the first of the - above boxes, the command |\halign{|\meta{header} |\box|\meta{first} - |\cr}| is used to create a new box, which we will call the - \meta{previous box}. Then, the following box is created, where - \meta{second} is the second input box: - |\halign{|\meta{header} |\box|\meta{previous box} |\cr| - |\box|\meta{second}|\cr}|. Let us call the resulting box the - \meta{previous box} once more. Then the next box that is created is - |\halign{|\meta{header} |\box|\meta{previous box} |\cr| + % + You cannot just say |node halign header=\hfil\hfil#\hfil\cr| because this + confuses \TeX\ inside matrices, so this detour via a macro is needed. + + Next, conceptually, all these boxes are recursively put inside an |\halign| + command. Assuming that \meta{first} is the first of the above boxes, the + command |\halign{|\meta{header} |\box|\meta{first} |\cr}| is used to create + a new box, which we will call the \meta{previous box}. Then, the following + box is created, where \meta{second} is the second input box: + |\halign{|\meta{header} |\box|\meta{previous box} |\cr| + |\box|\meta{second}|\cr}|. Let us call the resulting box the \meta{previous + box} once more. Then the next box that is created is + |\halign{|\meta{header} |\box|\meta{previous box} |\cr| |\box|\meta{third}|\cr}|. - All of this means that if \meta{header} is an |\halign| header - like |\hfil#\hfil\cr|, then all boxes will be centered relative to - one another. Similarly, a \meta{header} of |\hfil#\cr| causes the - text to be flushed right. + All of this means that if \meta{header} is an |\halign| header like + |\hfil#\hfil\cr|, then all boxes will be centered relative to one another. + Similarly, a \meta{header} of |\hfil#\cr| causes the text to be flushed + right. - Note that this mechanism is not flexible enough to all multiple - columns inside \meta{header}. You will have to use a |tabular| or a - |matrix| in such cases. + Note that this mechanism is not flexible enough to all multiple columns + inside \meta{header}. You will have to use a |tabular| or a |matrix| in + such cases. - One further note: Since the text of each line is placed in a box, - settings will be local to each ``line.'' This is very similar to the - way a cell in a |tabular| or a |matrix| behaves. + One further note: Since the text of each line is placed in a box, settings + will be local to each ``line''. This is very similar to the way a cell in a + |tabular| or a |matrix| behaves. \end{key} \subsubsection{Text Parameters: Height and Depth of Text} -In addition to changing the width of nodes, you can also change the -height of nodes. This can be done in two ways: First, you can use the -option |minimum height|, which ensures that the height of the whole -node is at least the given height (this option is described in more -detail later). Second, you can use the option |text height|, which -sets the height of the text itself, more precisely, of the \TeX\ text -box of the text. Note that the |text height| typically is not the -height of the shape's box: In addition to the |text height|, an -internal |inner sep| is added as extra space and the text depth is -also taken into account. +In addition to changing the width of nodes, you can also change the height of +nodes. This can be done in two ways: First, you can use the option +|minimum height|, which ensures that the height of the whole node is at least +the given height (this option is described in more detail later). Second, you +can use the option |text height|, which sets the height of the text itself, +more precisely, of the \TeX\ text box of the text. Note that the |text height| +typically is not the height of the shape's box: In addition to the +|text height|, an internal |inner sep| is added as extra space and the text +depth is also taken into account. -I recommend using |minimum size| instead of |text height| except for -special situations. +I recommend using |minimum size| instead of |text height| except for special +situations. \begin{key}{/tikz/text height=\meta{dimension}} - Sets the height of the text boxes in shapes. Thus, when you write - something like |node {text}|, the |text| is first typeset, resulting - in some box of a certain height. This height is then replaced by the - height |text height|. The resulting box is then used to determine - the size of the shape, which will typically be larger. When you - write |text height=| without specifying anything, the ``natural'' - size of the text box remains unchanged. + Sets the height of the text boxes in shapes. Thus, when you write something + like |node {text}|, the |text| is first typeset, resulting in some box of a + certain height. This height is then replaced by the height |text height|. + The resulting box is then used to determine the size of the shape, which + will typically be larger. When you write |text height=| without specifying + anything, the ``natural'' size of the text box remains unchanged. + % \begin{codeexample}[] \tikz \node[draw] {y}; \tikz \node[draw,text height=10pt] {y}; \end{codeexample} + % \end{key} \begin{key}{/tikz/text depth=\meta{dimension}} - This option works like |text height|, only for the depth of the text - box. This option is mostly useful when you need to ensure a uniform - depth of text boxes that need to be aligned. + This option works like |text height|, only for the depth of the text box. + This option is mostly useful when you need to ensure a uniform depth of + text boxes that need to be aligned. \end{key} - \subsection{Positioning Nodes} - \label{section-nodes-anchors} When you place a node at some coordinate, the node is centered on this -coordinate by default. This is often undesirable and it would be -better to have the node to the right or above the actual coordinate. +coordinate by default. This is often undesirable and it would be better to have +the node to the right or above the actual coordinate. \subsubsection{Positioning Nodes Using Anchors} -\pgfname\ uses a so-called anchoring mechanism to give you a very fine -control over the placement. The idea is simple: Imagine a node of -rectangular shape of a certain size. \pgfname\ defines numerous anchor -positions in the shape. For example to upper right corner is called, -well, not ``upper right anchor,'' but the |north east| anchor of the -shape. The center of the shape has an anchor called |center| on top of -it, and so on. Here are some examples (a complete list is given in -Section~\ref{section-the-shapes}). +\pgfname\ uses a so-called anchoring mechanism to give you a very fine control +over the placement. The idea is simple: Imagine a node of rectangular shape of +a certain size. \pgfname\ defines numerous anchor positions in the shape. For +example to upper right corner is called, well, not ``upper right anchor'', but +the |north east| anchor of the shape. The center of the shape has an anchor +called |center| on top of it, and so on. Here are some examples (a complete +list is given in Section~\ref{section-the-shapes}). \medskip\noindent \begin{tikzpicture} @@ -1150,37 +1195,35 @@ Section~\ref{section-the-shapes}). (x.base) circle (2pt) node[below] {|base|}; \end{tikzpicture} -Now, when you place a node at a certain coordinate, you can ask \tikzname\ -to place the node shifted around in such a way that a certain -anchor is at the coordinate. In the following example, we ask \tikzname\ -to shift the first node such that its |north east| anchor is at -coordinate |(0,0)| and that the |west| anchor of the second node is at -coordinate |(1,1)|. - +Now, when you place a node at a certain coordinate, you can ask \tikzname\ to +place the node shifted around in such a way that a certain anchor is at the +coordinate. In the following example, we ask \tikzname\ to shift the first node +such that its |north east| anchor is at coordinate |(0,0)| and that the |west| +anchor of the second node is at coordinate |(1,1)|. +% \begin{codeexample}[] \tikz \draw (0,0) node[anchor=north east] {first node} rectangle (1,1) node[anchor=west] {second node}; \end{codeexample} -Since the default anchor is |center|, the default behaviour is to -shift the node in such a way that it is centered on the current -position. +Since the default anchor is |center|, the default behaviour is to shift the +node in such a way that it is centered on the current position. \begin{key}{/tikz/anchor=\meta{anchor name}} - Causes the node to be shifted such that it's anchor \meta{anchor - name} lies on the current coordinate. + Causes the node to be shifted such that it's anchor \meta{anchor name} lies + on the current coordinate. - The only anchor that is present in all shapes is |center|. However, - most shapes will at least define anchors in all ``compass - directions.'' Furthermore, the standard shapes also define a |base| - anchor, as well as |base west| and |base east|, for placing things on - the baseline of the text. + The only anchor that is present in all shapes is |center|. However, most + shapes will at least define anchors in all ``compass directions''. + Furthermore, the standard shapes also define a |base| anchor, as well as + |base west| and |base east|, for placing things on the baseline of the + text. - The standard shapes also define a |mid| anchor (and |mid west| and - |mid east|). This anchor is half the height of the character ``x'' - above the base line. This anchor is useful for vertically centering - multiple nodes that have different heights and depth. Here is an - example: + The standard shapes also define a |mid| anchor (and |mid west| and + |mid east|). This anchor is half the height of the character ``x'' above + the base line. This anchor is useful for vertically centering multiple + nodes that have different heights and depth. Here is an example: + % \begin{codeexample}[] \begin{tikzpicture}[scale=3,transform shape] % First, center alignment -> wobbles @@ -1191,71 +1234,76 @@ position. \draw[anchor=mid] (0,0) node{x} -- (0.5,0) node{y} -- (1,0) node{t}; \end{tikzpicture} \end{codeexample} + % \end{key} - \subsubsection{Basic Placement Options} -Unfortunately, while perfectly logical, it is often rather -counter-intuitive that in order to place a node \emph{above} a given -point, you need to specify the |south| anchor. For this reason, there -are some useful options that allow you to select the standard anchors -more intuitively: +Unfortunately, while perfectly logical, it is often rather counter-intuitive +that in order to place a node \emph{above} a given point, you need to specify +the |south| anchor. For this reason, there are some useful options that allow +you to select the standard anchors more intuitively: \begin{key}{/tikz/above=\meta{offset} (default 0pt)} - Does the same as |anchor=south|. If the \meta{offset} is specified, - the node is additionally shifted upwards by the given - \meta{offset}. + Does the same as |anchor=south|. If the \meta{offset} is specified, the + node is additionally shifted upwards by the given \meta{offset}. + % \begin{codeexample}[] \tikz \fill (0,0) circle (2pt) node[above] {above}; \end{codeexample} + % \begin{codeexample}[] \tikz \fill (0,0) circle (2pt) node[above=2pt] {above}; \end{codeexample} + % \end{key} \begin{key}{/tikz/below=\meta{offset} (default 0pt)} - Similar to |above|. + Similar to |above|. \end{key} \begin{key}{/tikz/left=\meta{offset} (default 0pt)} - Similar to |above|. + Similar to |above|. \end{key} \begin{key}{/tikz/right=\meta{offset} (default 0pt)} - Similar to |above|. + Similar to |above|. \end{key} \begin{key}{/tikz/above left} - Does the same as |anchor=south east|. Note that giving both |above| - and |left| options does not have the same effect as |above left|, - rather only the last |left| ``wins.'' Actually, this option also - takes an \meta{offset} parameter, but using this parameter without - using the |positioning| library is deprecated. (The |positioning| - library changes the meaning of this parameter to something more - sensible.) + Does the same as |anchor=south east|. Note that giving both |above| and + |left| options does not have the same effect as |above left|, rather only + the last |left| ``wins''. Actually, this option also takes an \meta{offset} + parameter, but using this parameter without using the |positioning| library + is deprecated. (The |positioning| library changes the meaning of this + parameter to something more sensible.) + % \begin{codeexample}[] \tikz \fill (0,0) circle (2pt) node[above left] {above left}; \end{codeexample} + % \end{key} \begin{key}{/tikz/above right} - Similar to |above left|. + Similar to |above left|. + % \begin{codeexample}[] \tikz \fill (0,0) circle (2pt) node[above right] {above right}; \end{codeexample} + % \end{key} \begin{key}{/tikz/below left} - Similar to |above left|. + Similar to |above left|. \end{key} + \begin{key}{/tikz/below right} - Similar to |above left|. + Similar to |above left|. \end{key} \begin{key}{/tikz/centered} - A shorthand for |anchor=center|. + A shorthand for |anchor=center|. \end{key} % A second set of options behaves similarly, namely the |above of|, @@ -1278,13 +1326,13 @@ more intuitively: % \end{tikzpicture} % \end{codeexample} % \end{key} - +% % \begin{key}{/tikz/above left of=\meta{node}} % Works like |above of|, only the node is now put above and left. The % |node distance| is the Euclidean distance between the two nodes, not % the $L_1$-distance. % \end{key} - +% % \begin{key}{/tikz/above right of=\meta{node}} % Works similarly. % \end{key} @@ -1310,48 +1358,50 @@ more intuitively: % \end{key} - \subsubsection{Advanced Placement Options} While the standard placement options suffice for simple cases, the |positioning| library offers more convenient placement options. \begin{tikzlibrary}{positioning} - The library defines additional options for placing nodes - conveniently. It also redefines the standard options like |above| so - that they give you better control of node placement. + The library defines additional options for placing nodes conveniently. It + also redefines the standard options like |above| so that they give you + better control of node placement. \end{tikzlibrary} When this library is loaded, the options like |above| or |above left| behave differently. \begin{key}{/tikz/above=\opt{\meta{specification}} (default 0pt)} - With the |positioning| library loaded, the |above| option does not - take a simple \meta{dimension} as its parameter. Rather, it can - (also) take a more elaborate \meta{specification} as parameter. This - \meta{specification} has the following general form: It starts with - an optional \meta{shifting part} and is followed by an optional - \meta{of-part}. Let us start with the \meta{shifting part}, which - can have three forms: - \begin{enumerate} - \item It can simply be a \declare{\meta{dimension}} (or a mathematical - expression that evaluates to a dimension) like |2cm| or - |3cm/2+4cm|. In this case, the following happens: the node's - anchor is set to |south| and the node is vertically shifted - upwards by \meta{dimension}. + With the |positioning| library loaded, the |above| option does not take a + simple \meta{dimension} as its parameter. Rather, it can (also) take a more + elaborate \meta{specification} as parameter. This \meta{specification} has + the following general form: It starts with an optional \meta{shifting part} + and is followed by an optional \meta{of-part}. Let us start with the + \meta{shifting part}, which can have three forms: + % + \begin{enumerate} + \item It can simply be a \declare{\meta{dimension}} (or a mathematical + expression that evaluates to a dimension) like |2cm| or + |3cm/2+4cm|. In this case, the following happens: the node's anchor + is set to |south| and the node is vertically shifted upwards by + \meta{dimension}. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (2,2); \node at (1,1) [above=2pt+3pt,draw] {above}; \end{tikzpicture} \end{codeexample} - This use of the |above| option is the same as if the |positioning| - library were not loaded. - \item It can be a \declare{\meta{number}} (that is, any mathematical - expression that does not include a unit like |pt| or - |cm|). Examples are |2| or |3+sin(60)|. In this case, the anchor - is also set to |south| and the node is vertically shifted by - the vertical component of the coordinate |(0,|\meta{number}|)|. + % + This use of the |above| option is the same as if the |positioning| + library were not loaded. + \item It can be a \declare{\meta{number}} (that is, any mathematical + expression that does not include a unit like |pt| or |cm|). + Examples are |2| or |3+sin(60)|. In this case, the anchor is also + set to |south| and the node is vertically shifted by the vertical + component of the coordinate |(0,|\meta{number}|)|. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (2,2); @@ -1359,19 +1409,21 @@ differently. % south border of the node is now 2mm above (1,1) \end{tikzpicture} \end{codeexample} - \item It can be of the form \declare{\meta{number or - dimension 1}| and |\meta{number or dimension 2}}. This specification - does not make particular sense for the |above| option, it is much - more useful for options like |above left|. The reason it is - allowed for the |above| option is that it is sometimes - automatically used, as explained later. - - The effect of this option is the following. First, the point - |(|\meta{number or dimension 2}|,|\meta{number or dimension 1}|)| - is computed (note the inversed order), using the normal rules for - evaluating such a coordinate, yielding some position. Then, the - node is shifted by the vertical component of this point. The - anchor is set to |south|. + % + \item It can be of the form + \declare{\meta{number or dimension 1}| and |\meta{number or dimension 2}}. + This specification does not make particular sense for the |above| + option, it is much more useful for options like |above left|. The + reason it is allowed for the |above| option is that it is sometimes + automatically used, as explained later. + + The effect of this option is the following. First, the point + |(|\meta{number or dimension 2}|,|\meta{number or dimension 1}|)| + is computed (note the inverted order), using the normal rules for + evaluating such a coordinate, yielding some position. Then, the + node is shifted by the vertical component of this point. The anchor + is set to |south|. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (2,2); @@ -1379,19 +1431,22 @@ differently. % south border of the node is also 2mm above (1,1) \end{tikzpicture} \end{codeexample} - \end{enumerate} - The \meta{shifting part} can optionally be followed by a - \meta{of-part}, which has one of the following forms: - \begin{enumerate} - \item The \meta{of-part} can be \declareandlabel{of}| |\meta{coordinate}, - where \meta{coordinate} is \emph{not} in parentheses and it is - \emph{not} just a node name. An example would be - |of somenode.north| or |of 2,3|. In this case, the - following happens: First, the node's |at| parameter is set to the - \meta{coordinate}. Second, the node is shifted according to the - \meta{shift-part}. Third, the anchor is set to |south|. - - Here is a basic example: + \end{enumerate} + % + The \meta{shifting part} can optionally be followed by a \meta{of-part}, + which has one of the following forms: + % + \begin{enumerate} + \item The \meta{of-part} can be + \declareandlabel{of}| |\meta{coordinate}, where \meta{coordinate} is + \emph{not} in parentheses and it is \emph{not} just a node name. An + example would be |of somenode.north| or |of 2,3|. In this case, the + following happens: First, the node's |at| parameter is set to the + \meta{coordinate}. Second, the node is shifted according to the + \meta{shift-part}. Third, the anchor is set to |south|. + + Here is a basic example: + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style=draw] \draw[help lines] (0,0) grid (2,2); @@ -1401,26 +1456,30 @@ differently. \node [above=1cm of somenode.north] {\tiny 1cm of somenode.north}; \end{tikzpicture} \end{codeexample} - As can be seen the |above=5mm of somenode.north east| option does, - indeed, place the node 5mm above the north east anchor of - |somenode|. The same effect could have been achieved writing - |above=5mm| followed by |at=(somenode.north east)|. - - If the \meta{shifting-part} is missing, the shift is not zero, but - rather the value of the |node distance| key is used, see below. - \item The \meta{of-part} can be |of |\meta{node name}. An - example would be |of somenode|. In this case, the following - usually happens: - \begin{itemize} - \item The anchor is set to |south|. - \item The node is shifted according to the \meta{shifting part} - or, if it is missing, according to the value of |node distance|. - \item The node's |at| parameter is set to \meta{node - name}|.north|. - \end{itemize} - The net effect of all this is that the new node will be placed in - such a way that the distance between is south border and - \meta{node name}'s north border is exactly the given distance. + % + As can be seen the |above=5mm of somenode.north east| option does, + indeed, place the node 5mm above the north east anchor of + |somenode|. The same effect could have been achieved writing + |above=5mm| followed by |at=(somenode.north east)|. + + If the \meta{shifting-part} is missing, the shift is not zero, but + rather the value of the |node distance| key is used, see below. + \item The \meta{of-part} can be |of |\meta{node name}. An example would + be |of somenode|. In this case, the following usually happens: + % + \begin{itemize} + \item The anchor is set to |south|. + \item The node is shifted according to the \meta{shifting part} + or, if it is missing, according to the value of + |node distance|. + \item The node's |at| parameter is set to \meta{node + name}|.north|. + \end{itemize} + % + The net effect of all this is that the new node will be placed in + such a way that the distance between is south border and \meta{node + name}'s north border is exactly the given distance. + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style=draw] \draw[help lines] (0,0) grid (2,2); @@ -1432,19 +1491,23 @@ differently. node [midway,right,draw=none] {1cm}; \end{tikzpicture} \end{codeexample} - It is possible to change the behaviour of this - \meta{specification} rather drastically, using the following key: - \begin{key}{/tikz/on grid=\meta{boolean} (initially false)} - When this key is set to |true|, an \meta{of-part} of the - current form behaves differently: The anchors set for the - current node as well as the anchor used for the other \meta{node name} are set to |center|. - - This has the following effect: When you say - |above=1cm of somenode| with |on grid| set to true, the new node - will be placed in such a way that its center is 1cm above the - center of |somenode|. Repeatedly placing nodes in this way will - result in nodes that are centered on ``grid coordinate,'' hence - the name of the option. + % + It is possible to change the behaviour of this \meta{specification} + rather drastically, using the following key: + % + \begin{key}{/tikz/on grid=\meta{boolean} (initially false)} + When this key is set to |true|, an \meta{of-part} of the + current form behaves differently: The anchors set for the + current node as well as the anchor used for the other + \meta{node name} are set to |center|. + + This has the following effect: When you say + |above=1cm of somenode| with |on grid| set to true, the new + node will be placed in such a way that its center is 1cm above + the center of |somenode|. Repeatedly placing nodes in this way + will result in nodes that are centered on ``grid coordinate'', + hence the name of the option. + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style=draw] \draw[help lines] (0,0) grid (2,3); @@ -1460,13 +1523,13 @@ differently. \node (c2) [on grid,above=1cm of b2] {a}; \end{tikzpicture} \end{codeexample} - \end{key} - \end{enumerate} + \end{key} + \end{enumerate} - \begin{key}{/tikz/node distance=\meta{shifting part} (initially 1cm and 1cm)} - The value of this key is used as \meta{shifting part} is used if - and only if a \meta{of-part} is present, but no \meta{shifting - part}. + \begin{key}{/tikz/node distance=\meta{shifting part} (initially 1cm and 1cm)} + The value of this key is used as \meta{shifting part} is used if and + only if a \meta{of-part} is present, but no \meta{shifting part}. + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style=draw,node distance=5mm] \draw[help lines] (0,0) grid (2,3); @@ -1484,51 +1547,54 @@ differently. \end{scope} \end{tikzpicture} \end{codeexample} - \end{key} + \end{key} \end{key} \begin{key}{/tikz/below=\opt{\meta{specification}}} - This key is redefined in the same manner as |above|. + This key is redefined in the same manner as |above|. \end{key} \begin{key}{/tikz/left=\opt{\meta{specification}}} - This key is redefined in the same manner as |above|, only all - vertical shifts are replaced by horizontal shifts. + This key is redefined in the same manner as |above|, only all vertical + shifts are replaced by horizontal shifts. \end{key} \begin{key}{/tikz/right=\opt{\meta{specification}}} - This key is redefined in the same manner as |left|. + This key is redefined in the same manner as |left|. \end{key} \begin{key}{/tikz/above left=\opt{\meta{specification}}} - This key is also redefined in a manner similar to the above, but - behaviour of the \meta{shifting part} is more complicated: - \begin{enumerate} - \item When the \meta{shifting part} is of the form \meta{number or - dimension}| and |\meta{number or dimension}, it has - (essentially) the effect of shifting the node vertically upwards - by the first \meta{number or dimension} and to the left by the - second. To be more precise, the coordinate |(|\meta{second number - or dimension}|,|\meta{first number or dimension}|)| is computed - and then the node is shifted vertically by the $y$-part of - the resulting coordinate and horizontally be the negated $x$-part - of the result. (This is exactly what you expect, except possibly - when you have used the |x| and |y| options to modify the - |xy|-coordinate system so that the unit vectors no longer point - in the expected directions.) - \item When the \meta{shifting part} is of the form \meta{number or - dimension}, the node is shifted by this \meta{number or - dimension} in the direction of $135^\circ$. This means that - there is a difference between a \meta{shifting part} of |1cm| and - of |1cm and 1cm|: In the second case, the node is shifted by 1cm - upward and 1cm to the left; in the first case it is shifted by - $\frac{1}{2}\sqrt{2}$cm upward and by the same amount to the - left. A more mathematical way of phrasing this is the following: A - plain \meta{dimension} is measured in the $l_2$-norm, while a - \meta{dimension}| and |\meta{dimension} is measured in the - $l_1$-norm. - \end{enumerate} - The following example should help to illustrate the difference: + This key is also redefined in a manner similar to the above, but behaviour + of the \meta{shifting part} is more complicated: + % + \begin{enumerate} + \item When the \meta{shifting part} is of the form + \meta{number or dimension}| and |\meta{number or dimension}, it has + (essentially) the effect of shifting the node vertically upwards by + the first \meta{number or dimension} and to the left by the second. + To be more precise, the coordinate |(|\meta{second number or + dimension}|,|\meta{first number or dimension}|)| is computed and + then the node is shifted vertically by the $y$-part of the + resulting coordinate and horizontally be the negated $x$-part of + the result. (This is exactly what you expect, except possibly when + you have used the |x| and |y| options to modify the |xy|-coordinate + system so that the unit vectors no longer point in the expected + directions.) + \item When the \meta{shifting part} is of the form \meta{number or + dimension}, the node is shifted by this \meta{number or dimension} + in the direction of $135^\circ$. This means that there is a + difference between a \meta{shifting part} of |1cm| and of + |1cm and 1cm|: In the second case, the node is shifted by 1cm + upward and 1cm to the left; in the first case it is shifted by + $\frac{1}{2}\sqrt{2}$cm upward and by the same amount to the left. + A more mathematical way of phrasing this is the following: A plain + \meta{dimension} is measured in the $l_2$-norm, while a + \meta{dimension}| and |\meta{dimension} is measured in the + $l_1$-norm. + \end{enumerate} + % + The following example should help to illustrate the difference: + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw,circle}] \draw[help lines] (0,0) grid (2,5); @@ -1548,6 +1614,7 @@ differently. \end{scope} \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw,rectangle}] \draw[help lines] (0,0) grid (2,5); @@ -1567,6 +1634,7 @@ differently. \end{scope} \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw,rectangle},on grid] \draw[help lines] (0,0) grid (4,4); @@ -1586,27 +1654,31 @@ differently. \end{scope} \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/below left=\opt{\meta{specification}}} - Works similar to |above left|. + Works similar to |above left|. \end{key} + \begin{key}{/tikz/above right=\opt{\meta{specification}}} - Works similar to |above left|. + Works similar to |above left|. \end{key} + \begin{key}{/tikz/below right=\opt{\meta{specification}}} - Works similar to |above left|. + Works similar to |above left|. \end{key} -The |positioning| package also introduces the following new placement -keys: +The |positioning| package also introduces the following new placement keys: +% \begin{key}{/tikz/base left=\opt{\meta{specification}}} - This key works like the |left| key, only instead of the |east| anchor, - the |base east| anchor is used and, when the second form of an - \meta{of-part} is used, the corresponding |base west| anchor. + This key works like the |left| key, only instead of the |east| anchor, the + |base east| anchor is used and, when the second form of an \meta{of-part} + is used, the corresponding |base west| anchor. - This key is useful for chaining together nodes so that their base - lines are aligned. + This key is useful for chaining together nodes so that their base lines are + aligned. + % \begin{codeexample}[] \begin{tikzpicture}[node distance=1ex] \draw[help lines] (0,0) grid (3,1); @@ -1620,50 +1692,48 @@ keys: \node (y) [base right=of a] {y}; \end{tikzpicture} \end{codeexample} + % \end{key} + \begin{key}{/tikz/base right=\opt{\meta{specification}}} - Works like |base left|. + Works like |base left|. \end{key} \begin{key}{/tikz/mid left=\opt{\meta{specification}}} - Works like |base left|, but with |mid east| and |mid west| anchors - instead of |base east| and |base west|. + Works like |base left|, but with |mid east| and |mid west| anchors instead + of |base east| and |base west|. \end{key} + \begin{key}{/tikz/mid right=\opt{\meta{specification}}} - Works like |mid left|. + Works like |mid left|. \end{key} - - \subsubsection{Advanced Arrangements of Nodes} -The simple |above| and |right| options may not always suffice for -arranging a large number of nodes. For such situations \tikzname\ -offers libraries that make positioning easier: The |graphdrawing| -library and the |matrix| library. These libraries for positioning -nodes are described in two separate Sections~\ref{section-matrices} -and~\ref{section-intro-gd}. +The simple |above| and |right| options may not always suffice for arranging a +large number of nodes. For such situations \tikzname\ offers libraries that +make positioning easier: The |graphdrawing| library and the |matrix| library. +These libraries for positioning nodes are described in two separate +Sections~\ref{section-matrices} and~\ref{section-intro-gd}. \subsection{Fitting Nodes to a Set of Coordinates} - \label{section-nodes-fitting} -It is sometimes desirable that the size and position of a node is not -given using anchors and size parameters, rather one would sometimes -have a box be placed and be sized such that it ``is just large enough -to contain this, that, and that point.'' This situation typically -arises when a picture has been drawn and, afterwards, parts of the -picture are supposed to be encircled or highlighted. - -In this situation the |fit| option from the |fit| library is useful, -see Section~\ref{section-library-fit} for the details. The idea is -that you may give the |fit| option to a node. The |fit| option expects -a list of coordinates (one after the other without commas) as its -parameter. The effect will be that the node's text area has exactly -the necessary size so that it contains all the given coordinates. Here -is an example: - +It is sometimes desirable that the size and position of a node is not given +using anchors and size parameters, rather one would sometimes have a box be +placed and be sized such that it ``is just large enough to contain this, that, +and that point''. This situation typically arises when a picture has been drawn +and, afterwards, parts of the picture are supposed to be encircled or +highlighted. + +In this situation the |fit| option from the |fit| library is useful, see +Section~\ref{section-library-fit} for the details. The idea is that you may +give the |fit| option to a node. The |fit| option expects a list of coordinates +(one after the other without commas) as its parameter. The effect will be that +the node's text area has exactly the necessary size so that it contains all the +given coordinates. Here is an example: +% \begin{codeexample}[] \begin{tikzpicture}[level distance=8mm] \node (root) {root} @@ -1678,9 +1748,9 @@ is an example: \end{tikzpicture} \end{codeexample} -If you want to fill the fitted node you will usually have to place it -on a background layer. - +If you want to fill the fitted node you will usually have to place it on a +background layer. +% \begin{codeexample}[] \begin{tikzpicture}[level distance=8mm] \node (root) {root} @@ -1697,32 +1767,31 @@ on a background layer. \end{tikzpicture} \end{codeexample} -\subsection{Transformations} +\subsection{Transformations} \label{section-nodes-transformations} +It is possible to transform nodes, but, by default, transformations do not +apply to nodes. The reason is that you usually do \emph{not} want your text to +be scaled or rotated even if the main graphic is transformed. Scaling text is +evil, rotating slightly less so. -It is possible to transform nodes, but, by default, transformations do -not apply to nodes. The reason is that you usually do \emph{not} want -your text to be scaled or rotated even if the main graphic is -transformed. Scaling text is evil, rotating slightly less so. - -However, sometimes you \emph{do} wish to transform a node, for -example, it certainly sometimes makes sense to rotate a node by -90 degrees. There are two ways to achieve this: - +However, sometimes you \emph{do} wish to transform a node, for example, it +certainly sometimes makes sense to rotate a node by 90 degrees. There are two +ways to achieve this: +% \begin{enumerate} -\item - You can use the following option: - \begin{key}{/tikz/transform shape} - Causes the current ``external'' transformation matrix to be - applied to the shape. For example, if you said - |\tikz[scale=3]| and then say |node[transform shape] {X}|, you - will get a ``huge'' X in your graphic. - \end{key} -\item - You can give transformation options \emph{inside} the option list of - the node. \emph{These} transformations always apply to the node. + \item You can use the following option: + % + \begin{key}{/tikz/transform shape} + Causes the current ``external'' transformation matrix to be applied + to the shape. For example, if you said |\tikz[scale=3]| and then + say |node[transform shape] {X}|, you will get a ``huge'' X in your + graphic. + \end{key} + \item You can give transformation options \emph{inside} the option list of + the node. \emph{These} transformations always apply to the node. + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw}] \draw[help lines](0,0) grid (3,2); @@ -1734,22 +1803,23 @@ example, it certainly sometimes makes sense to rotate a node by (2,0) node[transform shape,rotate=90,scale=1.5] {B}; \end{tikzpicture} \end{codeexample} + % \end{enumerate} - -Even though \tikzname\ currently does not allow you to configure -so-called \emph{nonlinear transformations,} see -Section~\ref{section-nonlinear-transformations}, there is an option -that influences how nodes are transformed when nonlinear -transformations are in force: - +Even though \tikzname\ currently does not allow you to configure so-called +\emph{nonlinear transformations,} see +Section~\ref{section-nonlinear-transformations}, there is an option that +influences how nodes are transformed when nonlinear transformations are in +force: +% \begin{key}{/tikz/transform shape nonlinear=\opt{\meta{true or false}} (initially false)} - When set to true, \tikzname\ will try to apply any current nonlinear - transformation also to nodes. Typically, for the text in nodes this - is not possible in general, in such cases a linear approximation of - the nonlinear transformation is used. For more details, see - Section~\ref{section-nonlinear-transformations}. -\makeatletter + When set to true, \tikzname\ will try to apply any current nonlinear + transformation also to nodes. Typically, for the text in nodes this is not + possible in general, in such cases a linear approximation of the nonlinear + transformation is used. For more details, see + Section~\ref{section-nonlinear-transformations}. + % +\makeatletter \begin{codeexample}[] \begin{tikzpicture} % Install a nonlinear transformation: @@ -1762,54 +1832,53 @@ transformations are in force: % Draw something: \draw [help lines] (0,-30pt) grid [step=10pt] (80pt,30pt); - + \foreach \x in {0,20,...,80} \node [fill=red!20] at (\x pt, -20pt) {\x}; - + \foreach \x in {0,20,...,80} \node [fill=blue!20, transform shape nonlinear] at (\x pt, 20pt) {\x}; \end{tikzpicture} \end{codeexample} + % \end{key} - \subsection{Placing Nodes on a Line or Curve Explicitly} - \label{section-nodes-placing-1} -Until now, we always placed node on a coordinate that is mentioned in -the path. Often, however, we wish to place nodes on ``the middle'' of -a line and we do not wish to compute these coordinates ``by hand.'' -To facilitate such placements, \tikzname\ allows you to specify that a -certain node should be somewhere ``on'' a line. There are two ways of -specifying this: Either explicitly by using the |pos| option or -implicitly by placing the node ``inside'' a path operation. These two -ways are described in the following. +Until now, we always placed node on a coordinate that is mentioned in the path. +Often, however, we wish to place nodes on ``the middle'' of a line and we do +not wish to compute these coordinates ``by hand''. To facilitate such +placements, \tikzname\ allows you to specify that a certain node should be +somewhere ``on'' a line. There are two ways of specifying this: Either +explicitly by using the |pos| option or implicitly by placing the node +``inside'' a path operation. These two ways are described in the following. -\label{section-pos-option} + \label{section-pos-option} \begin{key}{/tikz/pos=\meta{fraction}} - When this option is given, the node is not anchored on the last - coordinate. Rather, it is anchored on some point on the line from - the previous coordinate to the current point. The \meta{fraction} - dictates how ``far'' on the line the point should be. A - \meta{fraction} of 0 is the previous coordinate, 1 is the current - one, everything else is in between. In particular, 0.5 is the - middle. + When this option is given, the node is not anchored on the last coordinate. + Rather, it is anchored on some point on the line from the previous + coordinate to the current point. The \meta{fraction} dictates how ``far'' + on the line the point should be. A \meta{fraction} of 0 is the previous + coordinate, 1 is the current one, everything else is in between. In + particular, 0.5 is the middle. - Now, what is ``the previous line''? This depends on the previous - path construction operation. + Now, what is ``the previous line''? This depends on the previous path + construction operation. - In the simplest case, the previous path operation was a ``line-to'' - operation, that is, a |--|\meta{coordinate} operation: + In the simplest case, the previous path operation was a ``line-to'' + operation, that is, a |--|\meta{coordinate} operation: + % \begin{codeexample}[] \tikz \draw (0,0) -- (3,1) node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; \end{codeexample} - For the |arc| operation, the position is simply the corresponding - position on the arc: + For the |arc| operation, the position is simply the corresponding position + on the arc: + % \begin{codeexample}[] \tikz { \draw [help lines] (0,0) grid (3,2); @@ -1818,26 +1887,26 @@ ways are described in the following. } \end{codeexample} - The next case is the curve-to operation (the |..| operation). In this - case, the ``middle'' of the curve, that is, the position |0.5| is - not necessarily the point at the exact half distance on the - line. Rather, it is some point at ``time'' 0.5 of a point traveling - from the start of the curve, where it is at time 0, to the end of - the curve, which it reaches at time 0.5. The ``speed'' of the point - depends on the length of the support vectors (the vectors that - connect the start and end points to the control points). The exact - math is a bit complicated (depending on your point of view, of - course); you may wish to consult a good book on computer graphics - and B\'ezier curves if you are intrigued. + The next case is the curve-to operation (the |..| operation). In this case, + the ``middle'' of the curve, that is, the position |0.5| is not necessarily + the point at the exact half distance on the line. Rather, it is some point + at ``time'' 0.5 of a point traveling from the start of the curve, where it + is at time 0, to the end of the curve, which it reaches at time 0.5. The + ``speed'' of the point depends on the length of the support vectors (the + vectors that connect the start and end points to the control points). The + exact math is a bit complicated (depending on your point of view, of + course); you may wish to consult a good book on computer graphics and + Bézier curves if you are intrigued. + % \begin{codeexample}[] \tikz \draw (0,0) .. controls +(right:3.5cm) and +(right:3.5cm) .. (0,3) node foreach \p in {0,0.125,...,1} [pos=\p]{\p}; \end{codeexample} - Another interesting case are the horizontal/vertical line-to operations - \verb!|-! and \verb!-|!. For them, the position (or time) |0.5| is - exactly the corner point. - + Another interesting case are the horizontal/vertical line-to operations + \verb!|-! and \verb!-|!. For them, the position (or time) |0.5| is exactly + the corner point. + % \begin{codeexample}[] \tikz \draw (0,0) |- (3,1) node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; @@ -1848,25 +1917,24 @@ ways are described in the following. node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; \end{codeexample} - For all other path construction operations, \emph{the position - placement does not work}, currently. + For all other path construction operations, \emph{the position placement + does not work}, currently. \end{key} \begin{key}{/tikz/auto=\opt{\meta{direction}} (default \normalfont is scope's setting)} - This option causes an anchor positions to be calculated - automatically according to the following rule. Consider a line - between to points. If the \meta{direction} is |left|, then the - anchor is chosen such that the node is to the left of this line. If - the \meta{direction} is |right|, then the node is to the right of - this line. Leaving out \meta{direction} causes automatic placement - to be enabled with the last value of |left| or |right| used. A - \meta{direction} of |false| disables automatic placement. This - happens also whenever an anchor is given explicitly by the - |anchor| option or by one of the |above|, |below|, etc.\ options. - - This option only has an effect for nodes that are placed on lines or - curves. - + This option causes an anchor positions to be calculated automatically + according to the following rule. Consider a line between to points. If the + \meta{direction} is |left|, then the anchor is chosen such that the node is + to the left of this line. If the \meta{direction} is |right|, then the node + is to the right of this line. Leaving out \meta{direction} causes automatic + placement to be enabled with the last value of |left| or |right| used. A + \meta{direction} of |false| disables automatic placement. This happens also + whenever an anchor is given explicitly by the |anchor| option or by one of + the |above|, |below|, etc.\ options. + + This option only has an effect for nodes that are placed on lines or + curves. + % \begin{codeexample}[] \begin{tikzpicture} [scale=.8,auto=left,every node/.style={circle,fill=blue!20}] @@ -1884,12 +1952,14 @@ ways are described in the following. node[midway,fill=red!20] {\from--\to}; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/swap} - This option exchanges the roles of |left| and |right| in automatic - placement. That is, if |left| is the current |auto| placement, - |right| is set instead and the other way round. + This option exchanges the roles of |left| and |right| in automatic + placement. That is, if |left| is the current |auto| placement, |right| is + set instead and the other way round. + % \begin{codeexample}[] \begin{tikzpicture}[auto] \draw[help lines,use as bounding box] (0,-.5) grid (4,5); @@ -1901,6 +1971,7 @@ ways are described in the following. [pos=\pos,fill=blue!20] {\pos}; \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture}[shorten >=1pt,node distance=2cm,auto] \draw[help lines] (0,0) grid (3,2); @@ -1918,50 +1989,57 @@ ways are described in the following. edge [loop below] node {1} (); \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/'} - This is a very short alias for |swap|. + This is a very short alias for |swap|. \end{key} \begin{key}{/tikz/sloped} - This option causes the node to be rotated such that a horizontal - line becomes a tangent to the curve. The rotation is normally - done in such a way that text is never ``upside down.'' To get - upside-down text, use can use |[rotate=180]| or - |[allow upside down]|, see below. + This option causes the node to be rotated such that a horizontal line + becomes a tangent to the curve. The rotation is normally done in such a way + that text is never ``upside down''. To get upside-down text, use can use + |[rotate=180]| or |[allow upside down]|, see below. + % \begin{codeexample}[] \tikz \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3) node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p}; \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture}[->] \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$}; \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$}; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/allow upside down=\meta{boolean} (default true, initially false)} - If set to |true|, \tikzname\ will not ``righten'' upside down text. + If set to |true|, \tikzname\ will not ``righten'' upside down text. + % \begin{codeexample}[] \tikz [allow upside down] \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3) node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p}; \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture}[->,allow upside down] \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$}; \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$}; \end{tikzpicture} \end{codeexample} + % \end{key} - There exist styles for specifying positions a bit less ``technically'': + \begin{stylekey}{/tikz/midway} - This has the same effect as |pos=0.5|. + This has the same effect as |pos=0.5|. + % \begin{codeexample}[] \tikz \draw (0,0) .. controls +(up:2cm) and +(left:3cm) .. (1,5) node[at end] {\texttt{at end}} @@ -1972,68 +2050,64 @@ There exist styles for specifying positions a bit less ``technically'': node[very near start] {\texttt{very near start}} node[at start] {\texttt{at start}}; \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/near start} - Set to |pos=0.25|. + Set to |pos=0.25|. \end{stylekey} \begin{stylekey}{/tikz/near end} - Set to |pos=0.75|. + Set to |pos=0.75|. \end{stylekey} \begin{stylekey}{/tikz/very near start} - Set to |pos=0.125|. + Set to |pos=0.125|. \end{stylekey} \begin{stylekey}{/tikz/very near end} - Set to |pos=0.875|. + Set to |pos=0.875|. \end{stylekey} \begin{stylekey}{/tikz/at start} - Set to |pos=0|. + Set to |pos=0|. \end{stylekey} \begin{stylekey}{/tikz/at end} - Set to |pos=1|. + Set to |pos=1|. \end{stylekey} \subsection{Placing Nodes on a Line or Curve Implicitly} - \label{section-nodes-placing-2} -When you wish to place a node on the line |(0,0) -- (1,1)|, -it is natural to specify the node not following the |(1,1)|, but -``somewhere in the middle.'' This is, indeed, possible and you can -write |(0,0) -- node{a} (1,1)| to place a node midway between |(0,0)| and -|(1,1)|. - -What happens is the following: The syntax of the line-to path -operation is actually |--| -\opt{|node|\meta{node specification}}\meta{coordinate}. (It is even -possible to give multiple nodes in this way.) When the optional -|node| is encountered, that is, -when the |--| is directly followed by |node|, then the -specification(s) are read and ``stored away.'' Then, after the -\meta{coordinate} has finally been reached, they are inserted again, -but with the |pos| option set. +When you wish to place a node on the line |(0,0) -- (1,1)|, it is natural to +specify the node not following the |(1,1)|, but ``somewhere in the middle''. +This is, indeed, possible and you can write |(0,0) -- node{a} (1,1)| to place a +node midway between |(0,0)| and |(1,1)|. + +What happens is the following: The syntax of the line-to path operation is +actually |--| \opt{|node|\meta{node specification}}\meta{coordinate}. (It is +even possible to give multiple nodes in this way.) When the optional |node| is +encountered, that is, when the |--| is directly followed by |node|, then the +specification(s) are read and ``stored away''. Then, after the +\meta{coordinate} has finally been reached, they are inserted again, but with +the |pos| option set. There are two things to note about this: When a node specification is -``stored,'' its catcodes become fixed. This means that you cannot use -overly complicated verbatim text in them. If you really need, say, a -verbatim text, you will have to put it in a normal node following the -coordinate and add the |pos| option. - -Second, which |pos| is chosen for the node? The position is inherited -from the surrounding scope. However, this holds only for nodes -specified in this implicit way. Thus, if you add the option -|[near end]| to a scope, this does not mean that \emph{all} nodes given -in this scope will be put on near the end of lines. Only the nodes -for which an implicit |pos| is added will be placed near the -end. Typically, this is what you want. Here are some examples that +``stored'', its catcodes become fixed. This means that you cannot use overly +complicated verbatim text in them. If you really need, say, a verbatim text, +you will have to put it in a normal node following the coordinate and add the +|pos| option. + +Second, which |pos| is chosen for the node? The position is inherited from the +surrounding scope. However, this holds only for nodes specified in this +implicit way. Thus, if you add the option |[near end]| to a scope, this does +not mean that \emph{all} nodes given in this scope will be put on near the end +of lines. Only the nodes for which an implicit |pos| is added will be placed +near the end. Typically, this is what you want. Here are some examples that should make this clearer: - +% \begin{codeexample}[] \begin{tikzpicture}[near end] \draw (0cm,4em) -- (3cm,4em) node{A}; @@ -2044,20 +2118,20 @@ should make this clearer: \end{codeexample} Like the line-to operation, the curve-to operation |..| also allows you to -specify nodes ``inside'' the operation. After both the first |..| and -also after the second |..| you can place node specifications. Like for -the |--| operation, these will be collected and then reinserted after -the operation with the |pos| option set. +specify nodes ``inside'' the operation. After both the first |..| and also +after the second |..| you can place node specifications. Like for the |--| +operation, these will be collected and then reinserted after the operation with +the |pos| option set. \subsection{The Label and Pin Options} \subsubsection{Overview} -In addition to the |node| path operation, the two options |label| and -|pin| can be used to ``add a node next to another node''. As an -example, suppose we want to draw a graph in which the nodes are -small circles: +In addition to the |node| path operation, the two options |label| and |pin| can +be used to ``add a node next to another node''. As an example, suppose we want +to draw a graph in which the nodes are small circles: +% \begin{codeexample}[] \tikz [circle] { \node [draw] (s) {}; @@ -2067,14 +2141,14 @@ small circles: } \end{codeexample} -Now, in the above example, suppose we wish to indicate that the first -node is the start node and the last node is the target node. We could -write |\node (s) {$s$};|, but this would enlarge the first -node. Rather, we want the ``$s$'' to be placed next to the node. For -this, we need to create \emph{another} node, but next to the existing -node. The |label| and |pin| option allow us to do exactly this without -having to use the cumbersome |node| syntax: - +Now, in the above example, suppose we wish to indicate that the first node is +the start node and the last node is the target node. We could write +|\node (s) {$s$};|, but this would enlarge the first node. Rather, we want the +``$s$'' to be placed next to the node. For this, we need to create +\emph{another} node, but next to the existing node. The |label| and |pin| +option allow us to do exactly this without having to use the cumbersome |node| +syntax: +% \begin{codeexample}[] \tikz [circle] { \node [draw] (s) [label=$s$] {}; @@ -2084,77 +2158,82 @@ having to use the cumbersome |node| syntax: } \end{codeexample} + \subsubsection{The Label Option} \begin{key}{/tikz/label=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}} - \label{label-option}% - When this option is given to a |node| operation, it causes - \emph{another} node to be added to the path after the current node - has been finished. This extra node will have the text - \meta{text}. It is placed, in principle, in the direction - \meta{angle} relative to the main node, but the exact rules are a - bit complex. Suppose the |node| currently under construction is called - |main node| and let us call the label node |label node|. Then the - following happens: - \begin{enumerate} - \item The \meta{angle} is used to determine a position on the border - of the |main node|. If the \meta{angle} is missing, the value of - the following key is used instead: - \begin{key}{/tikz/label position=\meta{angle} (initially above)} - Sets the default position for labels. - \end{key} - The \meta{angle} determines the position on the border of the - shape in two different ways. Normally, the border position is - given by |main node.|\meta{angle}. This means that the - \meta{angle} can either be a number like |0| or |-340|, but it can - also be an anchor like |north|. Additionally, the special angles - |above|, |below|, |left|, |right|, |above left|, and so on are - automatically replaced by the corresponding angles |90|, |270|, - |180|, |0|, |135|, and so on. - - A special case arises when the following key is set: - \begin{key}{/tikz/absolute=\meta{true or false} (default true)} - When this key is set, the \meta{angle} is interpreted - differently: We still use a point on the border of the - |main node|, but the angle is measured ``absolutely,'' that is, - an angle of |0| refers to the point on the border that lies on a - straight line from the |main node|'s center to the right - (relative to the paper, not relative to the local coordinate - system of either the node or the scope). - - The difference can be seen in the following example: + \label{label-option}% + When this option is given to a |node| operation, it causes \emph{another} + node to be added to the path after the current node has been finished. This + extra node will have the text \meta{text}. It is placed, in principle, in + the direction \meta{angle} relative to the main node, but the exact rules + are a bit complex. Suppose the |node| currently under construction is + called |main node| and let us call the label node |label node|. Then the + following happens: + % + \begin{enumerate} + \item The \meta{angle} is used to determine a position on the border of + the |main node|. If the \meta{angle} is missing, the value of the + following key is used instead: + % + \begin{key}{/tikz/label position=\meta{angle} (initially above)} + Sets the default position for labels. + \end{key} + % + The \meta{angle} determines the position on the border of the shape + in two different ways. Normally, the border position is given by + |main node.|\meta{angle}. This means that the \meta{angle} can + either be a number like |0| or |-340|, but it can also be an anchor + like |north|. Additionally, the special angles |above|, |below|, + |left|, |right|, |above left|, and so on are automatically replaced + by the corresponding angles |90|, |270|, |180|, |0|, |135|, and so + on. + + A special case arises when the following key is set: + % + \begin{key}{/tikz/absolute=\meta{true or false} (default true)} + When this key is set, the \meta{angle} is interpreted + differently: We still use a point on the border of the + |main node|, but the angle is measured ``absolutely'', that is, + an angle of |0| refers to the point on the border that lies on + a straight line from the |main node|'s center to the right + (relative to the paper, not relative to the local coordinate + system of either the node or the scope). + + The difference can be seen in the following example: + % \begin{codeexample}[] \tikz [rotate=-80,every label/.style={draw,red}] \node [transform shape,rectangle,draw,label=right:label] {main node}; \end{codeexample} + % \begin{codeexample}[] \tikz [rotate=-80,every label/.style={draw,red},absolute] \node [transform shape,rectangle,draw,label=right:label] {main node}; \end{codeexample} - \end{key} - \item Then, an anchor point for the |label node| is computed. It is determined - in such a way that the |label node| will ``face away'' from the - border of the |main node|. The anchor that is chosen depends on - the position of the border point that is chosen and its position - relative to the center of the |main node| and on whether the - |transform shape| option is set. In detail, when the computed - border point is at $0^\circ$, the anchor |west| will be - used. Similarly, when the border point is at $90^\circ$, the - anchor |south| will be used, and so on for $180^\circ$ and - $270^\circ$. - - For angles between these ``major'' angles, like - $30^\circ$ or $110^\circ$, combined anchors, like |south west| for - $30^\circ$ or |south east| for $110^\circ$, are used. However, for - angles close to the major angles, (differing by up to $2^\circ$ - from the major angle), the anchor for the major angle is - used. Thus, a label at a border point for $2^\circ$ will have the - anchor |west|, while a label for $3^\circ$ will have the anchor - |south west|, resulting in a ``jump'' of the anchor. You can set - the anchor ``by hand'' using the |anchor| key or indirect keys - like |left|. -\begin{codeexample}[] -\tikz + \end{key} + \item Then, an anchor point for the |label node| is computed. It is + determined in such a way that the |label node| will ``face away'' + from the border of the |main node|. The anchor that is chosen + depends on the position of the border point that is chosen and its + position relative to the center of the |main node| and on whether + the |transform shape| option is set. In detail, when the computed + border point is at $0^\circ$, the anchor |west| will be used. + Similarly, when the border point is at $90^\circ$, the anchor + |south| will be used, and so on for $180^\circ$ and $270^\circ$. + + For angles between these ``major'' angles, like $30^\circ$ or + $110^\circ$, combined anchors, like |south west| for $30^\circ$ or + |south east| for $110^\circ$, are used. However, for angles close + to the major angles, (differing by up to $2^\circ$ from the major + angle), the anchor for the major angle is used. Thus, a label at a + border point for $2^\circ$ will have the anchor |west|, while a + label for $3^\circ$ will have the anchor |south west|, resulting in + a ``jump'' of the anchor. You can set the anchor ``by hand'' using + the |anchor| key or indirect keys like |left|. + % +\begin{codeexample}[] +\tikz \node [circle, draw, label=default, label=60:$60^\circ$, @@ -2164,22 +2243,23 @@ having to use the cumbersome |node| syntax: label={[below]180:$180^\circ$}, label={[centered]135:$115^\circ$}] {my circle}; \end{codeexample} - \item - One \meta{angle} is special: If you set the \meta{angle} to - |center|, then the label will be placed on the center of the main - node. This is mainly useful for adding a label text to an existing - node, especially if it has been rotated. + \item One \meta{angle} is special: If you set the \meta{angle} to + |center|, then the label will be placed on the center of the main + node. This is mainly useful for adding a label text to an existing + node, especially if it has been rotated. + % \begin{codeexample}[] \tikz \node [transform shape,rotate=90, rectangle,draw,label={[red]center:R}] {main node}; \end{codeexample} - \end{enumerate} + \end{enumerate} - You can pass \meta{options} to the node |label node|. For this, you - provide the options in square brackets before the \meta{angle}. If you - do so, you need to add braces around the whole argument of the - |label| option and this is also the case if you have brackets or - commas or semicolons or anything special in the \meta{text}. + You can pass \meta{options} to the node |label node|. For this, you provide + the options in square brackets before the \meta{angle}. If you do so, you + need to add braces around the whole argument of the |label| option and this + is also the case if you have brackets or commas or semicolons or anything + special in the \meta{text}. + % \begin{codeexample}[] \tikz \node [circle,draw,label={[red]above:X}] {my circle}; \end{codeexample} @@ -2191,62 +2271,73 @@ having to use the cumbersome |node| syntax: \end{tikzpicture} \end{codeexample} - If you provide multiple |label| options, then multiple extra label - nodes are added in the order they are given. + If you provide multiple |label| options, then multiple extra label nodes + are added in the order they are given. - The following styles influence how labels are drawn: - \begin{key}{/tikz/label distance=\meta{distance} (initially 0pt)} - The \meta{distance} is additionally inserted between the main node - and the label node. + The following styles influence how labels are drawn: + % + \begin{key}{/tikz/label distance=\meta{distance} (initially 0pt)} + The \meta{distance} is additionally inserted between the main node and + the label node. + % \begin{codeexample}[] \tikz[label distance=5mm] \node [circle,draw,label=right:X, label=above right:Y, label=above:Z] {my circle}; \end{codeexample} - \end{key} - \begin{stylekey}{/tikz/every label (initially \normalfont empty)} - This style is used in every node created by the |label| - option. The default is |draw=none,fill=none|. - \end{stylekey} + \end{key} + % + \begin{stylekey}{/tikz/every label (initially \normalfont empty)} + This style is used in every node created by the |label| option. The + default is |draw=none,fill=none|. + \end{stylekey} \end{key} -See Section~\ref{section-label-quotes} for an easier -syntax for specifying nodes. +See Section~\ref{section-label-quotes} for an easier syntax for specifying +nodes. + \subsubsection{The Pin Option} \begin{key}{/tikz/pin=\opt{|[|\meta{options}|]|}\meta{angle}|:|\meta{text}} - This option is quite similar to the |label| option, but there is - one difference: In addition to adding an extra node to the picture, - it also adds an edge from this node to the main node. This causes - the node to look like a pin that has been added to the main node: + This option is quite similar to the |label| option, but there is one + difference: In addition to adding an extra node to the picture, it also + adds an edge from this node to the main node. This causes the node to look + like a pin that has been added to the main node: + % \begin{codeexample}[] \tikz \node [circle,fill=blue!50,minimum size=1cm,pin=60:$q_0$] {}; \end{codeexample} - The meaning of the \meta{options} and the \meta{angle} and the - \meta{text} is exactly the same as for the |node| option. Only, the - options and styles the influence the way pins look are different: - \begin{key}{/tikz/pin distance=\meta{distance} (initially 3ex)} - This \meta{distance} is used instead of the |label distance| for - the distance between the main node and the label node. + The meaning of the \meta{options} and the \meta{angle} and the \meta{text} + is exactly the same as for the |node| option. Only, the options and styles + the influence the way pins look are different: + % + \begin{key}{/tikz/pin distance=\meta{distance} (initially 3ex)} + This \meta{distance} is used instead of the |label distance| for the + distance between the main node and the label node. + % \begin{codeexample}[] \tikz[pin distance=1cm] \node [circle,draw,pin=right:X, pin=above right:Y, pin=above:Z] {my circle}; \end{codeexample} - \end{key} - \begin{stylekey}{/tikz/every pin (initially {draw=none,fill=none})} - This style is used in every node created by the |pin| - option. - \end{stylekey} - \begin{key}{/tikz/pin position=\meta{angle} (initially above)} - The default pin position. Works like |label position|. - \end{key} - \begin{stylekey}{/tikz/every pin edge (initially help lines)} - This style is used in every edge created by the |pin| options. + % + \end{key} + + \begin{stylekey}{/tikz/every pin (initially {draw=none,fill=none})} + This style is used in every node created by the |pin| option. + \end{stylekey} + + \begin{key}{/tikz/pin position=\meta{angle} (initially above)} + The default pin position. Works like |label position|. + \end{key} + + \begin{stylekey}{/tikz/every pin edge (initially help lines)} + This style is used in every edge created by the |pin| options. + % \begin{codeexample}[] \tikz [pin distance=15mm, every pin edge/.style={<-,shorten <=1pt,decorate, @@ -2255,70 +2346,77 @@ syntax for specifying nodes. pin=above right:Y, pin=above:Z] {my circle}; \end{codeexample} - \end{stylekey} + \end{stylekey} - \begin{key}{/tikz/pin edge=\meta{options} (initially \normalfont empty)} - This option can be used to set the options that are to be used - in the edge created by the |pin| option. + \begin{key}{/tikz/pin edge=\meta{options} (initially \normalfont empty)} + This option can be used to set the options that are to be used in the + edge created by the |pin| option. + % \begin{codeexample}[] \tikz[pin distance=10mm] \node [circle,draw,pin={[pin edge={blue,thick}]right:X}, pin=above:Z] {my circle}; \end{codeexample} + % \begin{codeexample}[] \tikz [every pin edge/.style={}, initial/.style={pin={[pin distance=5mm, pin edge={<-,shorten <=1pt}]left:start}}] \node [circle,draw,initial] {my circle}; \end{codeexample} - \end{key} + \end{key} \end{key} \subsubsection{The Quotes Syntax} \label{section-label-quotes} -The |label| and |pin| option provide a syntax for -creating nodes next to existing nodes, but this syntax is often a -bit too verbose. By including the following library, you get access to -an even more concise syntax: +The |label| and |pin| option provide a syntax for creating nodes next to +existing nodes, but this syntax is often a bit too verbose. By including the +following library, you get access to an even more concise syntax: \begin{tikzlibrary}{quotes} - Enables the quotes syntax for labels, pins, edge nodes, and pic - texts. + Enables the quotes syntax for labels, pins, edge nodes, and pic texts. \end{tikzlibrary} -Let us start with the basics of what this library does: Once loaded, -inside the options of a |node| command, instead of the usual -\meta{key}|=|\meta{value} pairs, you may also provide strings of the -following form (the actual syntax slightly more general, see the -detailed descriptions later on): +Let us start with the basics of what this library does: Once loaded, inside the +options of a |node| command, instead of the usual \meta{key}|=|\meta{value} +pairs, you may also provide strings of the following form (the actual syntax +slightly more general, see the detailed descriptions later on): +% \begin{quote} - |"|\meta{text}|"|\opt{\meta{options}} + |"|\meta{text}|"|\opt{\meta{options}} \end{quote} -The \meta{options} must be surrounded in curly braces when they -contain a comma, otherwise the curly braces are optional. The may be -preceded by an optional space. +% +The \meta{options} must be surrounded in curly braces when they contain a +comma, otherwise the curly braces are optional. The may be preceded by an +optional space. -When a \meta{string} of the above form is encountered inside the -options of a |node|, then it is internally transformed to +When a \meta{string} of the above form is encountered inside the options of a +|node|, then it is internally transformed to +% +% (the double vertical bar after = is needed to avoid the two opening brackets +% being typeset in italics) \begin{quote} - |label={[|\meta{options}|]|\meta{text}|}| + |label=||{[|\meta{options}|]|\meta{text}|}| \end{quote} Let us have a look at an example: +% \begin{codeexample}[] \tikz \node ["my label" red, draw] {my node}; \end{codeexample} +% The above has the same effect as the following: +% \begin{codeexample}[] \tikz \node [label={[red]my label}, draw] {my node}; \end{codeexample} -Here are further examples, one where no \meta{options} are added -to the |label|, one where a position is specified, and examples with -more complicated options in curly braces: - +Here are further examples, one where no \meta{options} are added to the +|label|, one where a position is specified, and examples with more complicated +options in curly braces: +% \begin{codeexample}[] \begin{tikzpicture} \matrix [row sep=5mm] { @@ -2327,148 +2425,158 @@ more complicated options in curly braces: \node [draw, "label" centered] {C}; \\ \node [draw, "label" color=red] {D}; \\ \node [draw, "label" {red,draw,thick}] {E}; \\ - }; + }; \end{tikzpicture} \end{codeexample} -Let us now have a more detailed look at what which commands this -library provides: +Let us now have a more detailed look at what which commands this library +provides: \begin{key}{/tikz/quotes mean label} - When this option is used (which is the default when this library is - loaded), then, as described above, inside the options of a node a - special syntax check is done. - - \medskip - \noindent\textbf{The syntax.} - For each string in the list of options - it is tested whether it starts with a quotation mark (note that this - will never happen for normal keys since the normal keys of - \tikzname\ do not start with quotation marks). When this happens, - the \meta{string} should not be a key--value pair, but, rather, must - have the form: - \begin{quote} - |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} - \end{quote} - - (We will discuss the optional apostrophe in a moment. It is not - really important for the current option, but only for - edge labels, which are discussed later). - - \medskip - \noindent\textbf{Transformation to a label option.} - When a \meta{string} has the above form, it is treated (almost) as - if you had written - \begin{quote} - |label={[|\meta{options}|]|\meta{text}|}| - \end{quote} - instead. The ``almost'' refers to the following additional feature: - In reality, before the \meta{options} are executed inside the - |label| command, the direction keys |above|, |left|, |below right| - and so on are redefined so that |above| is a shorthand for - |label position=90| and similarly for the other keys. The net effect - is that in order to specify the position of the \meta{text} relative - to the main node you can just put something like |left| or - |above right| inside the \meta{options}: -\begin{codeexample}[] -\tikz + When this option is used (which is the default when this library is + loaded), then, as described above, inside the options of a node a special + syntax check is done. + + \medskip + \noindent\textbf{The syntax.} + For each string in the list of options it is tested whether it starts with + a quotation mark (note that this will never happen for normal keys since + the normal keys of \tikzname\ do not start with quotation marks). When this + happens, the \meta{string} should not be a key--value pair, but, rather, + must have the form: + % + \begin{quote} + |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} + \end{quote} + + (We will discuss the optional apostrophe in a moment. It is not really + important for the current option, but only for edge labels, which are + discussed later). + + \medskip + \noindent\textbf{Transformation to a label option.} + When a \meta{string} has the above form, it is treated (almost) as if you + had written + % + \begin{quote} + |label={[|\meta{options}|]|\meta{text}|}| + \end{quote} + % + instead. The ``almost'' refers to the following additional feature: In + reality, before the \meta{options} are executed inside the |label| command, + the direction keys |above|, |left|, |below right| and so on are redefined + so that |above| is a shorthand for |label position=90| and similarly for + the other keys. The net effect is that in order to specify the position of + the \meta{text} relative to the main node you can just put something like + |left| or |above right| inside the \meta{options}: + % +\begin{codeexample}[] +\tikz \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle}; \end{codeexample} - Alternatively, you can also use \meta{direction}|:|\meta{actual - text} as your \meta{text}. This works since the |label| command - allows you to specify a direction at the beginning when it is - separated by a colon: + Alternatively, you can also use \meta{direction}|:|\meta{actual text} as + your \meta{text}. This works since the |label| command allows you to + specify a direction at the beginning when it is separated by a colon: + % \begin{codeexample}[] -\tikz +\tikz \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle}; \end{codeexample} - Arguably, placing |above| or |left| behind the \meta{text} seems - more natural than having it inside the \meta{text}. + % + Arguably, placing |above| or |left| behind the \meta{text} seems more + natural than having it inside the \meta{text}. - In addition to the above, before the \meta{options} are executed, - the following style is also executed: - \begin{stylekey}{/tikz/every label quotes} + In addition to the above, before the \meta{options} are executed, the + following style is also executed: + % + \begin{stylekey}{/tikz/every label quotes} \begin{codeexample}[] \tikz [every label quotes/.style=red] \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle}; \end{codeexample} - \end{stylekey} - - \medskip - \noindent\textbf{Handling commas and colons inside the text.} - The \meta{text} may not contain a comma, unless it is inside curly - braces. The reason is that the key handler separates the total - options of a |node| along the commas it finds. So, in order to have - text containing a comma, just add curly braces around either the - comma or just around the whole \meta{text}: + \end{stylekey} + + \medskip + \noindent\textbf{Handling commas and colons inside the text.} + The \meta{text} may not contain a comma, unless it is inside curly braces. + The reason is that the key handler separates the total options of a |node| + along the commas it finds. So, in order to have text containing a comma, + just add curly braces around either the comma or just around the whole + \meta{text}: + % \begin{codeexample}[] \tikz \node ["{yes, we can}", draw] {foo}; \end{codeexample} - The same is true for a colon, only in this case you may need to - surround specifically the colon by curly braces to stop the |label| - option from interpreting everything before the colon as a direction: + % + The same is true for a colon, only in this case you may need to surround + specifically the colon by curly braces to stop the |label| option from + interpreting everything before the colon as a direction: + % \begin{codeexample}[] \tikz \node ["yes{:} we can", draw] {foo}; \end{codeexample} - \medskip - \noindent\textbf{The optional apostrophe.} - Following the closing quotation marks in a \meta{string} there may - (but need - not) be a single quotation mark (an apostrophe), possibly surrounded - by whitespaces. If it is present, it is simply added to the - \meta{options} as another option (and, indeed, a single apostrophe - is a legal option in \tikzname, it is a shorthand for |swap|): - - \begin{tabular}{ll} - String & has the same effect as \\\hline - |"foo"'| & |"foo" {'}| \\ - |"foo"' red| & |"foo" {',red}| \\ - |"foo"'{red}| & |"foo" {',red}| \\ - |"foo"{',red}| & |"foo" {',red}| \\ - |"foo"{red,'}| & |"foo" {red,'}| \\ - |"foo"{'red}| & |"foo" {'red}| (illegal; there is no key |'red|)\\ - |"foo" red'| & |"foo" {red'}| (illegal; there is no key |red'|)\\ - \end{tabular} + \medskip + \noindent\textbf{The optional apostrophe.} + Following the closing quotation marks in a \meta{string} there may (but + need not) be a single quotation mark (an apostrophe), possibly surrounded + by whitespaces. If it is present, it is simply added to the \meta{options} + as another option (and, indeed, a single apostrophe is a legal option in + \tikzname, it is a shorthand for |swap|): + + \begin{tabular}{ll} + String & has the same effect as \\\hline + |"foo"'| & |"foo" {'}| \\ + |"foo"' red| & |"foo" {',red}| \\ + |"foo"'{red}| & |"foo" {',red}| \\ + |"foo"{',red}| & |"foo" {',red}| \\ + |"foo"{red,'}| & |"foo" {red,'}| \\ + |"foo"{'red}| & |"foo" {'red}| (illegal; there is no key |'red|)\\ + |"foo" red'| & |"foo" {red'}| (illegal; there is no key |red'|)\\ + \end{tabular} \end{key} \begin{key}{/tikz/quotes mean pin} - This option has exactly the same effect as |quotes mean label|, only - instead of transforming quoted text to the |label| option, they get - transformed to the |pin| option: + This option has exactly the same effect as |quotes mean label|, only + instead of transforming quoted text to the |label| option, they get + transformed to the |pin| option: + % \begin{codeexample}[] \tikz [quotes mean pin] \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle}; -\end{codeexample} - Instead of |every label quotes|, the following style is executed - with each such pin: - \begin{stylekey}{/tikz/every pin quotes} - \end{stylekey} +\end{codeexample} + % + Instead of |every label quotes|, the following style is executed + with each such pin: + % + \begin{stylekey}{/tikz/every pin quotes} + \end{stylekey} \end{key} If instead of |label|s or |pin|s you would like quoted strings to be -interpreted in a different manner, you can also define your own -handlers: +interpreted in a different manner, you can also define your own handlers: \begin{key}{/tikz/node quotes mean=\meta{replacement}} - This key allows you to define your own handler for quotes - options. Inside the options of a |node|, whenever a key--value pair - with the syntax - \begin{quote} - |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} - \end{quote} - is encountered, the following happens: The above string gets - replaced by \meta{replacement} where inside the \meta{replacement} - the parameter |#1| is \meta{text} and |#2| is \meta{options}. If the - apostrophe is present (see also the discussion of - |quotes mean label|), the \meta{options} start with |',|. - - The \meta{replacement} is then parsed normally as options (using - |\pgfkeys|). - - Here is an example, where the quotes are used to define labels that - are automatically named according to the |text|: + This key allows you to define your own handler for quotes options. Inside + the options of a |node|, whenever a key--value pair with the syntax + % + \begin{quote} + |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} + \end{quote} + % + is encountered, the following happens: The above string gets replaced by + \meta{replacement} where inside the \meta{replacement} the parameter |#1| + is \meta{text} and |#2| is \meta{options}. If the apostrophe is present + (see also the discussion of |quotes mean label|), the \meta{options} start + with |',|. + + The \meta{replacement} is then parsed normally as options (using + |\pgfkeys|). + + Here is an example, where the quotes are used to define labels that are + automatically named according to the |text|: + % \begin{codeexample}[] \tikzset{node quotes mean={label={[#2,name={#1}]#1}}} @@ -2477,47 +2585,47 @@ handlers: \draw (1) -- (2); } \end{codeexample} + % \end{key} -Some further options provided by the |quotes| library concern labels -next to edges rather than nodes and they are described in -Section~\ref{section-edge-quotes}. +Some further options provided by the |quotes| library concern labels next to +edges rather than nodes and they are described in +Section~\ref{section-edge-quotes}. -\subsection{Connecting Nodes: Using Nodes as Coordinates} +\subsection{Connecting Nodes: Using Nodes as Coordinates} \label{section-nodes-connecting} -Once you have defined a node and given it a name, you can use this -name to reference it. This can be done in two ways, see also +Once you have defined a node and given it a name, you can use this name to +reference it. This can be done in two ways, see also Section~\ref{section-node-coordinates}. Suppose you have said |\path(0,0) node(x) {Hello World!};| in order to define a node named |x|. +% \begin{enumerate} -\item - Once the node |x| has been defined, you can use - |(x.|\meta{anchor}|)| wherever you would normally use a normal - coordinate. This will yield the position at which the given - \meta{anchor} is in the picture. Note that transformations do not - apply to this coordinate, that is, |(x.north)| will be the northern - anchor of |x| even if you have said |scale=3| or |xshift=4cm|. This - is usually what you would expect. -\item - You can also just use |(x)| as a coordinate. In most cases, this - gives the same coordinate as |(x.center)|. Indeed, if the |shape| of - |x| is |coordinate|, then |(x)| and |(x.center)| have exactly the - same effect. - - However, for most other shapes, some path construction operations like - |--| try to be ``clever'' when they are asked to draw a line - from such a coordinate or to such a coordinate. When you say - |(x)--(1,1)|, the |--| path operation will not draw a line from the center - of |x|, but \emph{from the border} of |x| in the direction going - towards |(1,1)|. Likewise, |(1,1)--(x)| will also have the line - end on the border in the direction coming from |(1,1)|. - - In addition to |--|, the curve-to path operation |..| and the path - operations \verb!-|! and \verb!|-! will also handle nodes without - anchors correctly. Here is an example, see also - Section~\ref{section-node-coordinates}: + \item Once the node |x| has been defined, you can use |(x.|\meta{anchor}|)| + wherever you would normally use a normal coordinate. This will yield + the position at which the given \meta{anchor} is in the picture. Note + that transformations do not apply to this coordinate, that is, + |(x.north)| will be the northern anchor of |x| even if you have said + |scale=3| or |xshift=4cm|. This is usually what you would expect. + \item You can also just use |(x)| as a coordinate. In most cases, this + gives the same coordinate as |(x.center)|. Indeed, if the |shape| of + |x| is |coordinate|, then |(x)| and |(x.center)| have exactly the same + effect. + + However, for most other shapes, some path construction operations like + |--| try to be ``clever'' when they are asked to draw a line from such + a coordinate or to such a coordinate. When you say |(x)--(1,1)|, the + |--| path operation will not draw a line from the center of |x|, but + \emph{from the border} of |x| in the direction going towards |(1,1)|. + Likewise, |(1,1)--(x)| will also have the line end on the border in the + direction coming from |(1,1)|. + + In addition to |--|, the curve-to path operation |..| and the path + operations \verb!-|! and \verb!|-! will also handle nodes without + anchors correctly. Here is an example, see also + Section~\ref{section-node-coordinates}: + % \begin{codeexample}[] \begin{tikzpicture} \path (0,0) node (x) {Hello World!} @@ -2528,58 +2636,54 @@ Section~\ref{section-node-coordinates}. Suppose you have said \draw[->,orange] (x) .. controls +(up:1cm) and +(left:1cm) .. node[above,sloped] {label} (y); \end{tikzpicture} \end{codeexample} + % \end{enumerate} - - \subsection{Connecting Nodes: Using the Edge Operation} - \label{section-nodes-edges} \subsubsection{Basic Syntax of the Edge Operation} -The |edge| operation works like a |to| operation that is added after -the main path has been drawn, much like a node is added after the main -path has been drawn. This allows each |edge| to have a -different appearance. As the |node| operation, an |edge| temporarily -suspends the construction of the current path and a new path $p$ is -constructed. This new path $p$ will be drawn after the main path has -been drawn. Note that $p$ can be totally different from the main -path with respect to its options. Also note that if there are -several |to| and/or |node| operations in the main path, each -creates its own path(s) and they are drawn in the order that they -are encountered on the main path. - -\begin{pathoperation}{edge}{\opt{|[|\meta{options}|]|} - \opt{\meta{nodes}} |(|\meta{coordinate}|)|} - The effect of the |edge| operation is that after the main path the - following path is added to the picture: - \begin{quote} - |\path[every edge,|\meta{options}|] (\tikztostart) |\meta{path}|;| - \end{quote} - Here, \meta{path} is the |to path|. Note that, unlike the path added - by the |to| operation, the |(\tikztostart)| is added before the - \meta{path} (which is unnecessary for the |to| operation, since this - coordinate is already part of the main path). - - The |\tikztostart| is the last coordinate on the path just before - the |edge| operation, just as for the |node| or |to| operations. - However, there is one exception to this rule: If the |edge| - operation is directly preceded by a |node| operation, then this - just-declared node is the start coordinate (and not, as would - normally be the case, the coordinate where this just-declared node - is placed -- a small, but subtle difference). In this regard, |edge| - differs from both |node| and |to|. - - If there are several |edge| operations in a row, the start coordinate - is the same for all of them as their target coordinates are not, - after all, part of the main path. The start coordinate is, thus, the - coordinate preceding the first |edge| operation. This is - similar to nodes insofar as the |edge| operation does not modify the - current path at all. In particular, it does not change the last - coordinate visited, see the following example: - +The |edge| operation works like a |to| operation that is added after the main +path has been drawn, much like a node is added after the main path has been +drawn. This allows each |edge| to have a different appearance. As the |node| +operation, an |edge| temporarily suspends the construction of the current path +and a new path $p$ is constructed. This new path $p$ will be drawn after the +main path has been drawn. Note that $p$ can be totally different from the main +path with respect to its options. Also note that if there are several |edge| +and/or |node| operations in the main path, each creates its own path(s) and +they are drawn in the order that they are encountered on the main path. + +\begin{pathoperation}{edge}{\opt{|[|\meta{options}|]|} \opt{\meta{nodes}} |(|\meta{coordinate}|)|} + The effect of the |edge| operation is that after the main path the + following path is added to the picture: + % + \begin{quote} + |\path[every edge,|\meta{options}|] (\tikztostart) |\meta{path}|;| + \end{quote} + % + Here, \meta{path} is the |to path|. Note that, unlike the path added by the + |to| operation, the |(\tikztostart)| is added before the \meta{path} (which + is unnecessary for the |to| operation, since this coordinate is already + part of the main path). + + The |\tikztostart| is the last coordinate on the path just before the + |edge| operation, just as for the |node| or |to| operations. However, there + is one exception to this rule: If the |edge| operation is directly preceded + by a |node| operation, then this just-declared node is the start coordinate + (and not, as would normally be the case, the coordinate where this + just-declared node is placed -- a small, but subtle difference). In this + regard, |edge| differs from both |node| and |to|. + + If there are several |edge| operations in a row, the start coordinate is + the same for all of them as their target coordinates are not, after all, + part of the main path. The start coordinate is, thus, the coordinate + preceding the first |edge| operation. This is similar to nodes insofar as + the |edge| operation does not modify the current path at all. In + particular, it does not change the last coordinate visited, see the + following example: + % \begin{codeexample}[] \begin{tikzpicture} \node (a) at (0:1) {$a$}; @@ -2592,9 +2696,9 @@ are encountered on the main path. \end{tikzpicture} \end{codeexample} - A different way of specifying the above graph using the |edge| - operation is the following: - + A different way of specifying the above graph using the |edge| operation is + the following: + % \begin{codeexample}[] \begin{tikzpicture} \node foreach \name/\angle in {a/0,b/90,c/180,d/270} @@ -2609,9 +2713,9 @@ are encountered on the main path. \end{tikzpicture} \end{codeexample} - As can be seen, the path of the |edge| operation inherits the - options from the main path, but you can locally overrule them. - + As can be seen, the path of the |edge| operation inherits the options from + the main path, but you can locally overrule them. + % \begin{codeexample}[] \begin{tikzpicture} \node foreach \name/\angle in {a/0,b/90,c/180,d/270} @@ -2627,91 +2731,100 @@ are encountered on the main path. \end{tikzpicture} \end{codeexample} - Instead of |every to|, the style |every edge| is installed at the - beginning of the main path. - \begin{stylekey}{/tikz/every edge (initially draw)} - Executed for each |edge|. + Instead of |every to|, the style |every edge| is installed at the beginning + of the main path. + % + \begin{stylekey}{/tikz/every edge (initially draw)} + Executed for each |edge|. + % \begin{codeexample}[] -\begin{tikzpicture}[every to/.style={draw,dashed}] +\begin{tikzpicture}[every edge/.style={draw,dashed}] \path (0,0) edge (3,2); \end{tikzpicture} \end{codeexample} - \end{stylekey} + \end{stylekey} \end{pathoperation} \subsubsection{Nodes on Edges: Quotes Syntax} \label{section-edge-quotes} -The standard way of specifying nodes that are placed ``on'' an edge -(or on a to-path; all of the following is also true for to--paths) is -to put node specifications after the |edge| keyword, but before the -target coordinate. Another way is to use the |edge node| option and -its friends. Yet another way is to use the quotes syntax. +The standard way of specifying nodes that are placed ``on'' an edge (or on a +to-path; all of the following is also true for to--paths) is to put node +specifications after the |edge| keyword, but before the target coordinate. +Another way is to use the |edge node| option and its friends. Yet another way +is to use the quotes syntax. -The syntax is essentially the same as for labels added to nodes as -described in Section~\ref{section-label-quotes} and you also need to -load the |quotes| library. +The syntax is essentially the same as for labels added to nodes as described in +Section~\ref{section-label-quotes} and you also need to load the |quotes| +library. -In detail, when the |quotes| library is loaded, each time a key--value -pair in a list of options passed to an |edge| or a |to| path command -starts with |"|, the key--value pair must actually be a string of the -following form: +In detail, when the |quotes| library is loaded, each time a key--value pair in +a list of options passed to an |edge| or a |to| path command starts with |"|, +the key--value pair must actually be a string of the following form: +% \begin{quote} - |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} + |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} \end{quote} +% This string is transformed into the following: +% \begin{quote} - |edge node=node [every edge quotes,|\meta{options}|]{|\meta{text}|}| + |edge node=node [every edge quotes,|\meta{options}|]{|\meta{text}|}| \end{quote} -As described in Section~\ref{section-label-quotes}, the apostrophe -becomes part of the \meta{options}, when present. +% +As described in Section~\ref{section-label-quotes}, the apostrophe becomes part +of the \meta{options}, when present. The following style is important for the placement of the labels: + \begin{stylekey}{/tikz/every edge quotes (initially auto)} - This style is |auto| by default, which causes labels specified using - the quotes-syntax to be placed next to the edges. Unless the setting - of |auto| has been changed, they will be placed to the left. + This style is |auto| by default, which causes labels specified using the + quotes-syntax to be placed next to the edges. Unless the setting of |auto| + has been changed, they will be placed to the left. + % \begin{codeexample}[] \tikz \draw (0,0) edge ["left", ->] (2,0); \end{codeexample} - In order to place all labels to the right by default, change this - style to |auto=right|: + In order to place all labels to the right by default, change this style to + |auto=right|: + % \begin{codeexample}[] \tikz [every edge quotes/.style={auto=right}] \draw (0,0) edge ["right", ->] (2,0); \end{codeexample} - To place all nodes ``on'' the edge, just make this style empty (and, - possibly, make your labels opaque): + To place all nodes ``on'' the edge, just make this style empty (and, + possibly, make your labels opaque): + % \begin{codeexample}[] \tikz [every edge quotes/.style={fill=white,font=\footnotesize}] \draw (0,0) edge ["mid", ->] (2,1); \end{codeexample} + % \end{stylekey} -You may often wish to place some edge nodes to the right of edges and -some to the left. For this, the special treatment of the apostrophe is -particularly convenient: Recall that in \tikzname\ there is an option -just called |'|, which is a shorthand for |swap|. Now, following the -closing quotation mark come the options of an edge node. Thus, if the -closing quotation mark is followed by an apostrophe, the |swap| option -will be added to the edge label, causing it is be placed on the other -side. Because of the special treatment, you can even add another -option like |near end| after the apostrophe without having to add -curly braces and commas: - +You may often wish to place some edge nodes to the right of edges and some to +the left. For this, the special treatment of the apostrophe is particularly +convenient: Recall that in \tikzname\ there is an option just called |'|, which +is a shorthand for |swap|. Now, following the closing quotation mark come the +options of an edge node. Thus, if the closing quotation mark is followed by an +apostrophe, the |swap| option will be added to the edge label, causing it is be +placed on the other side. Because of the special treatment, you can even add +another option like |near end| after the apostrophe without having to add curly +braces and commas: +% \begin{codeexample}[] -\tikz +\tikz \draw (0,0) edge ["left", "right"', "start" near start, "end"' near end] (4,0); \end{codeexample} -In order to modify the distance between the edge labels and the edge, -you should consider introducing some styles: - +In order to modify the distance between the edge labels and the edge, you +should consider introducing some styles: +% \begin{codeexample}[] \tikz [tight/.style={inner sep=1pt}, loose/.style={inner sep=.7em}] \draw (0,0) edge ["left" tight, @@ -2721,96 +2834,100 @@ you should consider introducing some styles: \subsection{Referencing Nodes Outside the Current Picture} - \label{section-cross-picture-tikz} \subsubsection{Referencing a Node in a Different Picture} -It is possible (but not quite trivial) to reference nodes in pictures -other than the current one. This means that you can create a picture -and a node therein and, later, you can draw a line from some other -position to this node. +It is possible (but not quite trivial) to reference nodes in pictures other +than the current one. This means that you can create a picture and a node +therein and, later, you can draw a line from some other position to this node. To reference nodes in different pictures, proceed as follows: +% \begin{enumerate} -\item You need to add the |remember picture| option to all pictures - that contain nodes that you wish to reference and also to all - pictures from which you wish to reference a node in another - picture. -\item You need to add the |overlay| option to paths or to whole - pictures that contain references to nodes in different - pictures. (This option switches the computation of the - bounding box off.) -\item You need to use a driver that supports picture remembering and - you need to run \TeX\ twice. + \item You need to add the |remember picture| option to all pictures that + contain nodes that you wish to reference and also to all pictures from + which you wish to reference a node in another picture. + \item You need to add the |overlay| option to paths or to whole pictures + that contain references to nodes in different pictures. (This option + switches the computation of the bounding box off.) + \item You need to use a driver that supports picture remembering and you + need to run \TeX\ twice. \end{enumerate} +% (For more details on what is going on behind the scenes, see Section~\ref{section-cross-pictures-pgf}.) Let us have a look at the effect of these options. +% \begin{key}{/tikz/remember picture=\meta{boolean} (initially false)} - This option tells \tikzname\ that it should attempt to remember the - position of the current picture on the page. This attempt may fail - depending on which backend driver is used. Also, even if remembering - works, the position may only be available on a second run of \TeX. + This option tells \tikzname\ that it should attempt to remember the + position of the current picture on the page. This attempt may fail + depending on which backend driver is used. Also, even if remembering works, + the position may only be available on a second run of \TeX. - Provided that remembering works, you may consider saying + Provided that remembering works, you may consider saying + % \begin{codeexample}[code only] -\tikzstyle{every picture}+=[remember picture] +\tikzset{every picture/.append style={remember picture}} \end{codeexample} - to make \tikzname\ remember all pictures. This will add one line in - the |.aux| file for each picture in your document -- which typically - is not very much. Then, you do not have to worry about remembered - pictures at all. + % + to make \tikzname\ remember all pictures. This will add one line in the + |.aux| file for each picture in your document -- which typically is not + very much. Then, you do not have to worry about remembered pictures at all. \end{key} \begin{key}{/tikz/overlay=\meta{boolean} (default true)} - This option is mainly intended for use when nodes in other pictures - are referenced, but you can also use it in other situations. The - effect of this option is that everything within the current scope is - not taken into consideration when the bounding box of the current - picture is computed. - - You need to specify this option on all paths (or at least on all - parts of paths) that contain a reference to a node in another - picture. The reason is that, otherwise, \tikzname\ will attempt to - make the current picture large enough to encompass \emph{the node in - the other picture}. However, on a second run of \TeX\ this will - create an even bigger picture, leading to larger and larger - pictures. Unless you know what you are doing, I suggest specifying - the |overlay| option with all pictures that contain references to - other pictures. + This option is mainly intended for use when nodes in other pictures are + referenced, but you can also use it in other situations. The effect of this + option is that everything within the current scope is not taken into + consideration when the bounding box of the current picture is computed. + + You need to specify this option on all paths (or at least on all parts of + paths) that contain a reference to a node in another picture. The reason is + that, otherwise, \tikzname\ will attempt to make the current picture large + enough to encompass \emph{the node in the other picture}. However, on a + second run of \TeX\ this will create an even bigger picture, leading to + larger and larger pictures. Unless you know what you are doing, I suggest + specifying the |overlay| option with all pictures that contain references + to other pictures. \end{key} -Let us now have a look at a few examples. These examples work only if -this document is processed with a driver that supports picture -remembering. +Let us now have a look at a few examples. These examples work only if this +document is processed with a driver that supports picture remembering. \medskip -\noindent\begin{minipage}{\textwidth} -Inside the current text we place two pictures, containing nodes named -|n1| and |n2|, using +\noindent% +\begin{minipage}{\textwidth} +Inside the current text we place two pictures, containing nodes named |n1| and +|n2|, using +% \begin{codeexample}[code only] \tikz[remember picture] \node[circle,fill=red!50] (n1) {}; \end{codeexample} -which yields \tikz[remember picture] \node[circle,fill=red!50] (n1) -{};, and +% +which yields \tikz[remember picture] \node[circle,fill=red!50] (n1) {};, and +% \begin{codeexample}[code only] \tikz[remember picture] \node[fill=blue!50] (n2) {}; \end{codeexample} -yielding the node \tikz[remember picture] \node[fill=blue!50] (n2) -{};. To connect these nodes, we create another picture using the -|overlay| option and also the |remember picture| option. +% +yielding the node \tikz[remember picture] \node[fill=blue!50] (n2) {};. To +connect these nodes, we create another picture using the |overlay| option and +also the |remember picture| option. +% \begin{codeexample}[] \begin{tikzpicture}[remember picture,overlay] \draw[->,very thick] (n1) -- (n2); \end{tikzpicture} \end{codeexample} -Note that the last picture is seemingly empty. What happens is that it -has zero size and contains an arrow that lies well outside its bounds. -As a last example, we connect a node in another picture to the first -two nodes. Here, we provide the |overlay| option only with the line -that we do not wish to count as part of the picture. +% +Note that the last picture is seemingly empty. What happens is that it has zero +size and contains an arrow that lies well outside its bounds. As a last +example, we connect a node in another picture to the first two nodes. Here, we +provide the |overlay| option only with the line that we do not wish to count as +part of the picture. +% \begin{codeexample}[] \begin{tikzpicture}[remember picture] \node (c) [circle,draw] {Big circle}; @@ -2824,18 +2941,17 @@ that we do not wish to count as part of the picture. \subsubsection{Referencing the Current Page Node -- Absolute Positioning} -There is a special node called |current page| that can be used to -access the current page. It is a node of shape rectangle whose -|south west| anchor is the lower left corner of the page and whose -|north east| anchor is the upper right corner of the page. While this -node is handled in a special way internally, you can reference it as -if it were defined in some remembered picture other than the current -one. Thus, by giving the |remember picture| and the |overlay| -options to a picture, you can position nodes \emph{absolutely} on a -page. +There is a special node called |current page| that can be used to access the +current page. It is a node of shape rectangle whose |south west| anchor is the +lower left corner of the page and whose |north east| anchor is the upper right +corner of the page. While this node is handled in a special way internally, you +can reference it as if it were defined in some remembered picture other than +the current one. Thus, by giving the |remember picture| and the |overlay| +options to a picture, you can position nodes \emph{absolutely} on a page. -The first example places some text in the lower left corner of the -current page: +The first example places some text in the lower left corner of the current +page: +% \begin{codeexample}[] \begin{tikzpicture}[remember picture,overlay] \node [xshift=1cm,yshift=1cm] at (current page.south west) @@ -2848,6 +2964,7 @@ current page: \end{codeexample} The next example adds a circle in the middle of the page. +% \begin{codeexample}[] \begin{tikzpicture}[remember picture,overlay] \draw [line width=1mm,opacity=.25] @@ -2855,9 +2972,9 @@ The next example adds a circle in the middle of the page. \end{tikzpicture} \end{codeexample} -The final example overlays some text over the page (depending on where -this example is found on the page, the text may also be behind the -page). +The final example overlays some text over the page (depending on where this +example is found on the page, the text may also be behind the page). +% \begin{codeexample}[] \begin{tikzpicture}[remember picture,overlay] \node [rotate=60,scale=10,text opacity=0.2] @@ -2866,66 +2983,65 @@ page). \end{codeexample} - \subsection{Late Code and Late Options} \label{section-node-also} -All options given to a node only locally affect this one node. While -this is a blessing in most cases, you may sometimes want to cause -options to have effects ``later'' on. The other way round, you may -sometimes note ``only later'' that some options should be added to the -options of a node. For this, the following version of the |node| path -command can be used: +All options given to a node only locally affect this one node. While this is a +blessing in most cases, you may sometimes want to cause options to have effects +``later'' on. The other way round, you may sometimes note ``only later'' that +some options should be added to the options of a node. For this, the following +version of the |node| path command can be used: \begin{pathoperation}{node also}{\opt{|[|\meta{late options}|]|}|(|\meta{name}|)|} - Note that the \meta{name} is compulsory and that \emph{no} text may - be given. Also, the ordering of options and node label must be as above. - - The effect of the above is the following effect: The node - \meta{name} must already be existing. Now, the \meta{late options} are - executed in a local scope. Most of these options will have no effect - since you \emph{cannot change the appearance of the node,} that is, - you cannot change a red node into a green node using these ``late'' - options. However, giving the |append after command| and - |prefix after command| options inside - the \meta{late options} (directly or indirectly) does have the desired - effect: The given path gets executed with the |\tikzlastnode| - set to the determined node. - - The net effect of all this is that you can provide, say, the |label| - option inside the \meta{options} to a add a label to a node that has - already been constructed. - + Note that the \meta{name} is compulsory and that \emph{no} text may be + given. Also, the ordering of options and node label must be as above. + + The effect of the above is the following effect: The node \meta{name} must + already be existing. Now, the \meta{late options} are executed in a local + scope. Most of these options will have no effect since you \emph{cannot + change the appearance of the node,} that is, you cannot change a red node + into a green node using these ``late'' options. However, giving the + |append after command| and |prefix after command| options inside the + \meta{late options} (directly or indirectly) does have the desired effect: + The given path gets executed with the |\tikzlastnode| set to the determined + node. + + The net effect of all this is that you can provide, say, the |label| option + inside the \meta{options} to a add a label to a node that has already been + constructed. + % \begin{codeexample}[] \begin{tikzpicture} \node [draw,circle] (a) {Hello}; \node also [label=above:world] (a); \end{tikzpicture} \end{codeexample} + % \end{pathoperation} -As explained in Section~\ref{section-paths}, you -can use the options |append after command| and -|prefix after command| to add a path after a node. The following macro may be -useful there: +As explained in Section~\ref{section-paths}, you can use the options +|append after command| and |prefix after command| to add a path after a node. +The following macro may be useful there: +% \begin{command}{\tikzlastnode} - Expands to the last node on the path. + Expands to the last node on the path. \end{command} Instead of the |node also| syntax, you can also the following option: \begin{key}{/tikz/late options=\meta{options}} - This option can be given on a path (but not as an argument to a - |node| path command) and has the same effect as the |node also| path - command. Inside the \meta{options}, you should use the |name| option - to specify the node for which you wish to add late options: - + This option can be given on a path (but not as an argument to a |node| path + command) and has the same effect as the |node also| path command. Inside + the \meta{options}, you should use the |name| option to specify the node + for which you wish to add late options: + % \begin{codeexample}[] \begin{tikzpicture} \node [draw,circle] (a) {Hello}; \path [late options={name=a, label=above:world}]; \end{tikzpicture} \end{codeexample} + % \end{key} |