diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex')
| -rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex | 3061 |
1 files changed, 3061 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex b/graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex new file mode 100644 index 0000000000..f30010976a --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex @@ -0,0 +1,3061 @@ +% Copyright 2019 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Nodes and 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. + + +\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}, +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. +% +\begin{codeexample}[] +\tikz \fill [fill=yellow!80!black] + (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{|:|\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: + % +\begin{codeexample}[] +\tikz { + \path (0,0) node [red] {A} + (1,0) node [blue] {B} + (2,0) node [green, node contents=C] + (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 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} + -- (1.5,0) node [behind path, fill=green!50] {second node} + -- (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 + |backgrounds| 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 behavior, 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 + behavior. + \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} + -- (1,1) node[draw, behind path] {second node} + -- (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): + % +\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}] +\tikz \fill[fill=yellow!80!black] + (0,0) node {first node} + -- (1,1) node[ellipse,draw, behind path] {second node} + -- (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{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}[preamble={\usetikzlibrary{animations}},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 backslash 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'': + % +\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 + indicate 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. + % +\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. + % +\begin{codeexample}[] +\begin{tikzpicture} + [every rectangle node/.style={draw}, + every circle node/.style={draw,double}] + \draw (0,0) node[rectangle] {A} -- (1,1) node[circle] {B}; +\end{tikzpicture} +\end{codeexample} + \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-] + \node (A) at (0,1) {A}; + \node (B) at (1,1) {B}; + \draw (A) -- (B); + \end{scope} + \begin{scope}[name prefix = bottom-] + \node (A) at (0,0) {A}; + \node (B) at (1,0) {B}; + \draw (A) -- (B); + \end{scope} + + \draw [red] (top-A) -- (bottom-B); +} +\end{codeexample} + % + 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 + + |\node[shape=coordinate]|\verb|[|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|, + + 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: + +\begin{command}{\node} + Inside |{tikzpicture}| this is an abbreviation for |\path node|. +\end{command} + +\begin{command}{\coordinate} + Inside |{tikzpicture}| this is an abbreviation for |\path coordinate|. +\end{command} + + +\subsubsection{Predefined Shapes} +\label{section-nodes-predefined} +\label{section-the-shapes} + +\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|. +\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: +% +\begin{codeexample}[] +\begin{tikzpicture}[every node/.style={draw}] + \path[yshift=1.5cm,shape=rectangle] + (0,0) node(a1){} (1,0) node(a2){} + (1,1) node(a3){} (0,1) node(a4){}; + \filldraw[fill=yellow!80!black] (a1) -- (a2) -- (a3) -- (a4); + + \path[shape=coordinate] + (0,0) coordinate(b1) (1,0) coordinate(b2) + (1,1) coordinate(b3) (0,1) coordinate(b4); + \filldraw[fill=yellow!80!black] (b1) -- (b2) -- (b3) -- (b4); +\end{tikzpicture} +\end{codeexample} + + +\subsubsection{Common Options: Separations, Margins, Padding and + Border Rotation} +\label{section-shape-seps} +\label{section-shape-common-options} + +The \todosp{why two labels for the same point?} exact behavior 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}. + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) node[inner sep=0pt,draw] {tight} + (0cm,2em) node[inner sep=5pt,draw] {loose} + (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. +\end{key} + +\begin{key}{/pgf/inner ysep=\meta{dimension} (initially .3333em)} + \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''. + + 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). + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw[line width=5pt] + (0,0) node[fill=yellow!80!black] (f) {filled} + (2,0) node[draw] (d) {drawn} + (1,-2) node[draw,scale=2] (s) {scaled}; + + \draw[->] (1,-1) -- (f); + \draw[->] (1,-1) -- (d); + \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. + % +\begin{codeexample}[] +\begin{tikzpicture}[outer sep=auto] + \draw[line width=5pt] + (0,0) node[fill=yellow!80!black] (f) {filled} + (2,0) node[draw] (d) {drawn} + (1,-2) node[draw,scale=2] (s) {scaled}; + + \draw[->] (1,-1) -- (f); + \draw[->] (1,-1) -- (d); + \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|. +\end{key} + +\begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)} + \keyalias{tikz} + Specifies the outer separation in the $y$-direction, only. +\end{key} + +\begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)} + \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 1pt)} + \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. + % +\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. + % +\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}] +\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} + +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}[preamble={\usetikzlibrary{shapes.geometric}}] +\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}[preamble={\usetikzlibrary{shapes.geometric}}] +\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} + +\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. +\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: +% +\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}] +\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}; + \foreach \s/\t in + {left side/base east, bottom side/north, bottom left corner/base}{ + \fill[red] (A.\s) circle(1.5pt) (B.\s) circle(1.5pt); + \fill[blue] (A.\t) circle(1.5pt) (B.\t) circle(1.5pt); + } +\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. + + +\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: + +\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 |\nodepart| is encountered or until the node + \meta{text} ends. The \meta{options} will be local to this part. + % +\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}] +\begin{tikzpicture} + \node [circle split,draw,double,fill=red!20] + { + % No \nodepart has been used, yet. So, the following is put in the + % ``text'' node part by default. + $q_1$ + \nodepart{lower} % Ok, end ``text'' part, start ``output'' part + $00$ + }; % output part ended. +\end{tikzpicture} +\end{codeexample} + + 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}. + % +\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}] +\tikz [every lower node part/.style={red}] + \node [circle split,draw] {$q_1$ \nodepart{lower} $00$}; +\end{codeexample} + \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: + +\begin{key}{/tikz/text=\meta{color}} + 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}; + \draw[text=red] (1,0) -- +(1,1) node[above] {red}; + \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}. + + +\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: + +\begin{key}{/tikz/node font=\meta{font commands}} + 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}: +\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). + % +\begin{codeexample}[] +\begin{tikzpicture} + \node [font=\itshape] {italic}; +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\tikz \node [font=\tiny, minimum height=3em, draw] {tiny}; +\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: + % +\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}] +\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. +\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. + +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: + % +\begin{codeexample}[width=5cm] +\tikz \node [draw] { + \begin{tabular}{cc} + upper left & upper right\\ + lower left & lower right + \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. + % +\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. + % +\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. +\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|. + % +\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. +\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. + % +\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: + % +\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. + % +\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. + % +\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. + % +\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. + % +\begin{codeexample}[] +\tikz \node[fill=yellow!80!black,align=center] + {This is a\\ demonstration text for\\ alignments.}; +\end{codeexample} +\begin{codeexample}[] +\tikz \node[fill=yellow!80!black,text width=3cm,align=center] + {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. + % +\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. +{% +\hbadness=10000 +\begin{codeexample}[] +\tikz \node[fill=yellow!80!black,text width=3cm,align=justify] + {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} +\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{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| + |\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. + + 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. +\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. + +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. + % +\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. +\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. + + +\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}). + +\medskip\noindent +\begin{tikzpicture} + \path node[minimum height=2cm,minimum width=5cm,fill=blue!25](x) {Big node}; + \fill (x.north) circle (2pt) node[above] {|north|} + (x.north east) circle (2pt) node[above] {|north east|} + (x.north west) circle (2pt) node[above] {|north west|} + (x.west) circle (2pt) node[left] {|west|} + (x.east) circle (2pt) node[right] {|east|} + (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)|. +% +\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 behavior 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 its 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 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 + \draw[anchor=center] (0,1) node{x} -- (0.5,1) node{y} -- (1,1) node{t}; + % Second, base alignment -> no wobble, but too high + \draw[anchor=base] (0,.5) node{x} -- (0.5,.5) node{y} -- (1,.5) node{t}; + % Third, mid alignment + \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: + +\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}. + % +\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|. +\end{key} + +\begin{key}{/tikz/left=\meta{offset} (default 0pt)} + Similar to |above|. +\end{key} + +\begin{key}{/tikz/right=\meta{offset} (default 0pt)} + 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.) + % +\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|. + % +\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|. +\end{key} + +\begin{key}{/tikz/below right} + Similar to |above left|. +\end{key} + +\begin{key}{/tikz/centered} + A shorthand for |anchor=center|. +\end{key} + +% A second set of options behaves similarly, namely the |above of|, +% |below of|, and so on options. They cause the same anchors to be set +% as the options without |of|, however, their parameter is different: +% You must provide the name of another node. The current node will then +% be placed, say, above this specified node at a distance given by the +% option |node distance|. +% \begin{key}{/tikz/above of=\meta{node}} +% This option causes the node to be placed at the distance +% |node distance| above of \meta{node}. The anchor is |center|. +% \begin{codeexample}[] +% \begin{tikzpicture}[node distance=1cm] +% \draw[help lines] (0,0) grid (3,2); +% \node (a) {a}; +% \node (b) [above of=a] {b}; +% \node (c) [above of=b] {c}; +% \node (d) [right of=c] {d}; +% \node (e) [below right of=d] {e}; +% \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} +% \begin{key}{/tikz/left of=\meta{node}} +% Works similarly. +% \end{key} +% \begin{key}{/tikz/right of=\meta{node}} +% Works similarly. +% \end{key} +% \begin{key}{/tikz/below of=\meta{node}} +% Works similarly. +% \end{key} +% \begin{key}{/tikz/below left of=\meta{node}} +% Works similarly. +% \end{key} +% \begin{key}{/tikz/below right of=\meta{node}} +% Works similarly. +% \end{key} +% \begin{key}{/tikz/node distance=\meta{dimension}} +% Sets the distance between nodes that are placed using the +% |... of| options. Note that this distance is the distance between +% the centers of the nodes, not the distance between their borders. +% \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. +\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}. + % +\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}|)|. + % +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \node at (1,1) [above=.2,draw] {above}; + % 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 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}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \node at (1,1) [above=.2 and 3mm,draw] {above}; + % 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: + % +\begin{codeexample}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture}[every node/.style=draw] + \draw[help lines] (0,0) grid (2,2); + \node (somenode) at (1,1) {some node}; + + \node [above=5mm of somenode.north east] {\tiny 5mm of somenode.north east}; + \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 its south border and \meta{node + name}'s north border is exactly the given distance. + % +\begin{codeexample}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture}[every node/.style=draw] + \draw[help lines] (0,0) grid (2,2); + \node (some node) at (1,1) {some node}; + + \node (other node) [above=1cm of some node] {\tiny above=1cm of some node}; + + \draw [<->] (some node.north) -- (other node.south) + node [midway,right,draw=none] {1cm}; +\end{tikzpicture} +\end{codeexample} + % + It is possible to change the behavior 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}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture}[every node/.style=draw] + \draw[help lines] (0,0) grid (2,3); + + % Not gridded + \node (a1) at (0,0) {not gridded}; + \node (b1) [above=1cm of a1] {fooy}; + \node (c1) [above=1cm of b1] {a}; + + % gridded + \node (a2) at (2,0) {gridded}; + \node (b2) [on grid,above=1cm of a2] {fooy}; + \node (c2) [on grid,above=1cm of b2] {a}; +\end{tikzpicture} +\end{codeexample} + \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{codeexample}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture}[every node/.style=draw,node distance=5mm] + \draw[help lines] (0,0) grid (2,3); + + % Not gridded + \node (a1) at (0,0) {not gridded}; + \node (b1) [above=of a1] {fooy}; + \node (c1) [above=of b1] {a}; + + % gridded + \begin{scope}[on grid] + \node (a2) at (2,0) {gridded}; + \node (b2) [above=of a2] {fooy}; + \node (c2) [above=of b2] {a}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + \end{key} +\end{key} + +\begin{key}{/tikz/below=\opt{\meta{specification}}} + 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. +\end{key} + +\begin{key}{/tikz/right=\opt{\meta{specification}}} + 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 behavior + 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}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture}[every node/.style={draw,circle}] + \draw[help lines] (0,0) grid (2,5); + \begin{scope}[node distance=5mm and 5mm] + \node (b) at (1,4) {b}; + \node [left=of b] {1}; \node [right=of b] {2}; + \node [above=of b] {3}; \node [below=of b] {4}; + \node [above left=of b] {5}; \node [above right=of b] {6}; + \node [below left=of b] {7}; \node [below right=of b] {8}; + \end{scope} + \begin{scope}[node distance=5mm] + \node (a) at (1,1) {a}; + \node [left=of a] {1}; \node [right=of a] {2}; + \node [above=of a] {3}; \node [below=of a] {4}; + \node [above left=of a] {5}; \node [above right=of a] {6}; + \node [below left=of a] {7}; \node [below right=of a] {8}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + % +\begin{codeexample}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture}[every node/.style={draw,rectangle}] + \draw[help lines] (0,0) grid (2,5); + \begin{scope}[node distance=5mm and 5mm] + \node (b) at (1,4) {b}; + \node [left=of b] {1}; \node [right=of b] {2}; + \node [above=of b] {3}; \node [below=of b] {4}; + \node [above left=of b] {5}; \node [above right=of b] {6}; + \node [below left=of b] {7}; \node [below right=of b] {8}; + \end{scope} + \begin{scope}[node distance=5mm] + \node (a) at (1,1) {a}; + \node [left=of a] {1}; \node [right=of a] {2}; + \node [above=of a] {3}; \node [below=of a] {4}; + \node [above left=of a] {5}; \node [above right=of a] {6}; + \node [below left=of a] {7}; \node [below right=of a] {8}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + % +\begin{codeexample}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture}[every node/.style={draw,rectangle},on grid] + \draw[help lines] (0,0) grid (4,4); + \begin{scope}[node distance=1] + \node (a) at (2,3) {a}; + \node [left=of a] {1}; \node [right=of a] {2}; + \node [above=of a] {3}; \node [below=of a] {4}; + \node [above left=of a] {5}; \node [above right=of a] {6}; + \node [below left=of a] {7}; \node [below right=of a] {8}; + \end{scope} + \begin{scope}[node distance=1 and 1] + \node (b) at (2,0) {b}; + \node [left=of b] {1}; \node [right=of b] {2}; + \node [above=of b] {3}; \node [below=of b] {4}; + \node [above left=of b] {5}; \node [above right=of b] {6}; + \node [below left=of b] {7}; \node [below right=of b] {8}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + % +\end{key} + +\begin{key}{/tikz/below left=\opt{\meta{specification}}} + Works similar to |above left|. +\end{key} + +\begin{key}{/tikz/above right=\opt{\meta{specification}}} + Works similar to |above left|. +\end{key} + +\begin{key}{/tikz/below right=\opt{\meta{specification}}} + Works similar to |above left|. +\end{key} + +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 is useful for chaining together nodes so that their base lines are + aligned. + % +\begin{codeexample}[preamble={\usetikzlibrary{positioning}}] +\begin{tikzpicture}[node distance=1ex] + \draw[help lines] (0,0) grid (3,1); + \huge + \node (X) at (0,1) {X}; + \node (a) [right=of X] {a}; + \node (y) [right=of a] {y}; + + \node (X) at (0,0) {X}; + \node (a) [base right=of X] {a}; + \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|. +\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|. +\end{key} + +\begin{key}{/tikz/mid right=\opt{\meta{specification}}} + 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 |matrix| library and the |graphdrawing| 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: +% +\begin{codeexample}[preamble={\usetikzlibrary{fit,shapes.geometric}}] +\begin{tikzpicture}[level distance=8mm] + \node (root) {root} + child { node (a) {a} } + child { node (b) {b} + child { node (d) {d} } + child { node (e) {e} } } + child { node (c) {c} }; + + \node[draw=red,inner sep=0pt,thick,ellipse,fit=(root) (b) (d) (e)] {}; + \node[draw=blue,inner sep=0pt,thick,ellipse,fit=(b) (c) (e)] {}; +\end{tikzpicture} +\end{codeexample} + +If you want to fill the fitted node you will usually have to place it on a +background layer. +% +\begin{codeexample}[preamble={\usetikzlibrary{backgrounds,fit,shapes.geometric}}] +\begin{tikzpicture}[level distance=8mm] + \node (root) {root} + child { node (a) {a} } + child { node (b) {b} + child { node (d) {d} } + child { node (e) {e} } } + child { node (c) {c} }; + + \begin{scope}[on background layer] + \node[fill=red!20,inner sep=0pt,ellipse,fit=(root) (b) (d) (e)] {}; + \node[fill=blue!20,inner sep=0pt,ellipse,fit=(b) (c) (e)] {}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + + +\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. + +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. + % +\begin{codeexample}[ + preamble={\usepgfmodule{nonlineartransformations}\usetikzlibrary{curvilinear}}, + pre={\makeatletter}, +] +\begin{tikzpicture}[every node/.style={draw}] + \draw[help lines](0,0) grid (3,2); + \draw (1,0) node{A} + (2,0) node[rotate=90,scale=1.5] {B}; + \draw[rotate=30] (1,0) node{A} + (2,0) node[rotate=90,scale=1.5] {B}; + \draw[rotate=60] (1,0) node[transform shape] {A} + (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: +% +\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 +\begin{codeexample}[ + preamble={\usepgfmodule{nonlineartransformations}\usetikzlibrary{curvilinear}}, + pre={\makeatletter}, +] +\begin{tikzpicture} + % Install a nonlinear transformation: + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{10mm}{20mm}} + {\pgfpoint{10mm}{10mm}} + {\pgfpoint{20mm}{10mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}% + + % 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 nodes 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} + +\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. + + 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: + % +\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: + % +\begin{codeexample}[] +\tikz { + \draw [help lines] (0,0) grid (3,2); + \draw (2,0) arc [x radius=1, y radius=2, start angle=0, end angle=180] + node foreach \t in {0,0.125,...,1} [pos=\t,auto] {\t}; +} +\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é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. + % +\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} + +\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 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 position to be calculated automatically + according to the following rule. Consider a line between two 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}] + \node (a) at (-1,-2) {a}; + \node (b) at ( 1,-2) {b}; + \node (c) at ( 2,-1) {c}; + \node (d) at ( 2, 1) {d}; + \node (e) at ( 1, 2) {e}; + \node (f) at (-1, 2) {f}; + \node (g) at (-2, 1) {g}; + \node (h) at (-2,-1) {h}; + + \foreach \from/\to in {a/b,b/c,c/d,d/e,e/f,f/g,g/h,h/a} + \draw [->] (\from) -- (\to) + 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. + % +\begin{codeexample}[preamble={\usetikzlibrary{automata}}] +\begin{tikzpicture}[auto] + \draw[help lines,use as bounding box] (0,-.5) grid (4,5); + + \draw (0.5,0) .. controls (9,6) and (-5,6) .. (3.5,0) + node foreach \pos in {0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1} + [pos=\pos,swap,fill=red!20] {\pos} + node foreach \pos in {0.025,0.2,0.4,0.6,0.8,0.975} + [pos=\pos,fill=blue!20] {\pos}; +\end{tikzpicture} +\end{codeexample} + % +\begin{codeexample}[preamble={\usetikzlibrary{automata}}] +\begin{tikzpicture}[shorten >=1pt,node distance=2cm,auto] + \draw[help lines] (0,0) grid (3,2); + + \node[state] (q_0) {$q_0$}; + \node[state] (q_1) [above right of=q_0] {$q_1$}; + \node[state] (q_2) [below right of=q_0] {$q_2$}; + \node[state] (q_3) [below right of=q_1] {$q_3$}; + + \path[->] (q_0) edge node {0} (q_1) + edge node [swap] {1} (q_2) + (q_1) edge node {1} (q_3) + edge [loop above] node {0} () + (q_2) edge node [swap] {0} (q_3) + edge [loop below] node {1} (); +\end{tikzpicture} +\end{codeexample} + % +\end{key} + +\begin{key}{/tikz/'} + 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. + % +\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. + % +\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|. + % +\begin{codeexample}[] +\tikz \draw (0,0) .. controls +(up:2cm) and +(left:3cm) .. (1,5) + node[at end] {\texttt{at end}} + node[very near end] {\texttt{very near end}} + node[near end] {\texttt{near end}} + node[midway] {\texttt{midway}} + node[near start] {\texttt{near start}} + 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|. +\end{stylekey} + +\begin{stylekey}{/tikz/near end} + Set to |pos=0.75|. +\end{stylekey} + +\begin{stylekey}{/tikz/very near start} + Set to |pos=0.125|. +\end{stylekey} + +\begin{stylekey}{/tikz/very near end} + Set to |pos=0.875|. +\end{stylekey} + +\begin{stylekey}{/tikz/at start} + Set to |pos=0|. +\end{stylekey} + +\begin{stylekey}{/tikz/at end} + 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. + +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 +should make this clearer: +% +\begin{codeexample}[] +\begin{tikzpicture}[near end] + \draw (0cm,4em) -- (3cm,4em) node{A}; + \draw (0cm,3em) -- node{B} (3cm,3em); + \draw (0cm,2em) -- node[midway] {C} (3cm,2em); + \draw (0cm,1em) -- (3cm,1em) node[midway] {D} ; +\end{tikzpicture} +\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. + + +\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: +% +\begin{codeexample}[preamble={\usetikzlibrary{positioning}}] +\tikz [circle] { + \node [draw] (s) {}; + \node [draw] (a) [right=of s] {} edge (s); + \node [draw] (b) [right=of a] {} edge (a); + \node [draw] (t) [right=of b] {} edge (b); +} +\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: +% +\begin{codeexample}[preamble={\usetikzlibrary{positioning}}] +\tikz [circle] { + \node [draw] (s) [label=$s$] {}; + \node [draw] (a) [right=of s] {} edge (s); + \node [draw] (b) [right=of a] {} edge (a); + \node [draw] (t) [right=of b, label=$t$] {} edge (b); +} +\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: + % +\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 + \node [circle, draw, + label=default, + label=60:$60^\circ$, + label=below:$-90^\circ$, + label=3:$3^\circ$, + label=2:$2^\circ$, + label={[below]180:$180^\circ$}, + label={[centered]135:$135^\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. + % +\begin{codeexample}[] +\tikz \node [transform shape,rotate=90, + rectangle,draw,label={[red]center:R}] {main node}; +\end{codeexample} + \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}. + % +\begin{codeexample}[] +\tikz \node [circle,draw,label={[red]above:X}] {my circle}; +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \node [circle,draw,label={[name=label node]above left:$a,b$}] {}; + \draw (label node) -- +(1,1); +\end{tikzpicture} +\end{codeexample} + + 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. + % +\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} + +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: + % +\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. + % +\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. + % +\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}] +\tikz [pin distance=15mm, + every pin edge/.style={<-,shorten <=1pt,decorate, + decoration={snake,pre length=4pt}}] + \node [circle,draw,pin=right:X, + pin=above right:Y, + pin=above:Z] {my circle}; +\end{codeexample} + \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{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} + + +\subsubsection{The Quotes Syntax} +\label{section-label-quotes} + +The |label| and |pin| options 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. +\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 is +slightly more general, see the detailed descriptions later on): +% +\begin{quote} + |"|\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 \meta{options} 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 +% +% (the double vertical bar after = is needed to avoid the two opening brackets +% being typeset in italics) +\begin{quote} + |label=||{[|\meta{options}|]|\meta{text}|}| +\end{quote} + +Let us have a look at an example: +% +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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: +% +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\begin{tikzpicture} + \matrix [row sep=5mm] { + \node [draw, "label"] {A}; \\ + \node [draw, "label" left] {B}; \\ + \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 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}[preamble={\usetikzlibrary{quotes}}] +\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: + % +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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}. + + 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}[preamble={\usetikzlibrary{quotes}}] +\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}: + % +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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: + % +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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} +\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: + % +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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{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: + +\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|: + % +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\tikzset{node quotes mean={label={[#2,name={#1}]#1}}} + +\tikz { + \node ["1", "2" label position=left, circle, draw] {circle}; + \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}. + + +\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 +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)|. + + If the specified coordinate is almost identical to the node center, for + example |(x)--(0,0)|, no line will be drawn and a warning message will + be printed. + + 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!} + (3,1) node[circle,draw](y) {$\int_1^2 x \mathrm d x$}; + + \draw[->,blue] (x) -- (y); + \draw[->,red] (x) -| node[near start,below] {label} (y); + \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 |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$}; + \node (b) at (90:1) {$b$} edge [->] (a); + \node (c) at (180:1) {$c$} edge [->] (a) + edge [<-] (b); + \node (d) at (270:1) {$d$} edge [->] (a) + edge [dotted] (b) + edge [<-] (c); +\end{tikzpicture} +\end{codeexample} + + 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} + (\name) at (\angle:1) {$\name$}; + + \path[->] (b) edge (a) + edge (c) + edge [-,dotted] (d) + (c) edge (a) + edge (d) + (d) edge (a); +\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. + % +\begin{codeexample}[] +\begin{tikzpicture} + \node foreach \name/\angle in {a/0,b/90,c/180,d/270} + (\name) at (\angle:1.5) {$\name$}; + + \path[->] (b) edge node[above right] {$5$} (a) + edge (c) + edge [-,dotted] node[below,sloped] {missing} (d) + (c) edge (a) + edge (d) + (d) edge [red] node[above,sloped] {very} + node[below,sloped] {bad} (a); +\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|. + % +\begin{codeexample}[] +\begin{tikzpicture}[every edge/.style={draw,dashed}] + \path (0,0) edge (3,2); +\end{tikzpicture} +\end{codeexample} + \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 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: +% +\begin{quote} + |"|\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}|}| +\end{quote} +% +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. + % +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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|: + % +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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): + % +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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: +% +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\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: +% +\begin{codeexample}[preamble={\usetikzlibrary{quotes}}] +\tikz [tight/.style={inner sep=1pt}, loose/.style={inner sep=.7em}] + \draw (0,0) edge ["left" tight, + "right"' loose, + "start" near start] (4,0); +\end{codeexample} + + +\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. + +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. +\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. + + Provided that remembering works, you may consider saying + % +\begin{codeexample}[code only] +\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. +\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. +\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. +\medskip + +\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 +% +\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. +% +\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. +% +\begin{codeexample}[] +\begin{tikzpicture}[remember picture] + \node (c) [circle,draw] {Big circle}; + + \draw [overlay,->,very thick,red,opacity=.5] + (c) to[bend left] (n1) (n1) -| (n2); +\end{tikzpicture} +\end{codeexample} +\end{minipage} + + +\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. + +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) + [text width=7cm,fill=red!20,rounded corners,above right] + { + This is an absolutely positioned text in the + lower left corner. No shipout-hackery is used. + }; +\end{tikzpicture} +\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] + (current page.center) circle (3cm); +\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). +% +\begin{codeexample}[] +\begin{tikzpicture}[remember picture,overlay] + \node [rotate=60,scale=10,text opacity=0.2] + at (current page.center) {Example}; +\end{tikzpicture} +\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: + +\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. + % +\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: +% +\begin{command}{\tikzlastnode} + Expands to the last node on the path. +\end{command} + +Instead of the |node also| syntax, you can also use 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: + % +\begin{codeexample}[] +\begin{tikzpicture} + \node [draw,circle] (a) {Hello}; + \path [late options={name=a, label=above:world}]; +\end{tikzpicture} +\end{codeexample} + % +\end{key} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |