summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex1004
1 files changed, 813 insertions, 191 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex
index 5cd58695209..e5fe70f35c7 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex
@@ -19,8 +19,8 @@ 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 after the path has
-been drawn.
+ 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}
@@ -33,8 +33,8 @@ 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. In
-Section~\ref{section-nodes-connecting} it is explained how a node can
+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|
@@ -58,7 +58,7 @@ 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
-|sin (1,1)|). It is also possible to give node specifications
+|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
@@ -66,27 +66,129 @@ only to the node. Then, you can optionally \emph{name} the node by
providing a name in round braces. 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 \emph{after the path has been
- drawn}. Thus, all nodes are drawn ``on top'' of the path and
-retained until the path is complete. If there are several nodes on a
-path, they are drawn on top of the path in the order they are
-encountered.
+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=examplefill]
- (0,0) node {first node}
- -- (1,1) node {second node}
- -- (0,2) node {third node};
+\tikz \fill [fill=yellow!80!black]
+ (0,0) node {first node}
+ -- (1,1) node[behind path] {second node}
+ -- (0,2) node {third node};
\end{codeexample}
+\subsubsection{Syntax of the Node Command}
+
The syntax for specifying nodes is the following:
-\begin{pathoperation}{node}{\opt{|[|\meta{options}|]|}\opt{|(|\meta{name}|)|}%
- \opt{|at(|\meta{coordinate}|)|}\opt{\marg{text}}}
- The effect of |at| is to place the node at the coordinate given
- after |at| and not, as would normally be the case, at the last
- position. The |at| syntax is not available when a node is given
- inside a path operation (it would not make any sense, there).
+\begin{pathoperation}{node}{\opt{\meta{foreach statements}}%
+ \opt{|[|\meta{options}|]|}\opt{|(|\meta{name}|)|}%
+ \opt{|at(|\meta{coordinate}|)|}\opt{\marg{node contents}}}
+ Since this path operation is one of the most involved around, let us
+ go over it step by step.
+
+ \medskip
+ \textbf{Order of the parts of the specification.}
+ Everything between ``|node|'' and the opening brace of a node is
+ optional. If there are \meta{foreach statements}, they must come
+ first, directly following ``|node|.'' Other than that, the ordering
+ of all the other elements of a node specification (the
+ \meta{options}, the \meta{name}, and \meta{coordinate}) is
+ arbitrary, indeed, there can be multiple occurrences of any of these
+ elements (although only for options this makes much sense).
+
+ \medskip
+ \textbf{The text of a node.}
+ At the end of a node, you must (normally) provide some \meta{node contents}
+ in curly braces; indeed, the ``end'' of the node specification is
+ detected by the opening curly brace. For normal nodes it is possible to use
+ ``fragile'' stuff inside the \meta{node contents} like the |\verb|
+ command (for the technically savvy: code inside the \meta{node
+ contents} is allowed to change catcodes; however, this rule does
+ not apply to ``nodes on a path'' to be discussed later).
+
+ Instead of giving \meta{node contents} at the end of the node in
+ curly braces, you can also use the following key:
+ \begin{key}{/tikz/node contents=\meta{node contents}}
+ \label{option-node-contents}%
+ This key sets that 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 anther, but
+ never the path itself. ``Just before it draws the path'' actually
+ means that the nodes are inserted into the page output just before
+ any pre-actions are applied to the path (see below for what
+ pre-actions are).
+\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 background library in Section~\ref{section-tikz-backgrounds}.
+ \end{key}
+ \begin{key}{/tikz/in front of path}
+ This is the opposite of |behind path|: It causes nodes to be drawn
+ on top of the path. Since this is the default behaviour, you
+ usually do not need this option; it is only needed when an
+ enclosing scope has used |behind path| and you now wish to
+ ``switch back'' to the normal behaviour.
+ \end{key}
+
+ \medskip
+ \textbf{The name of a node.}
The |(|\meta{name}|)| is a name for later reference and it is
optional. You may also add the option |name=|\meta{name} to the
\meta{option} list; it has the same effect.
@@ -104,17 +206,13 @@ The syntax for specifying nodes is the following:
\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 |late options| options,
- you can also assign an alias name to a node at a later point.
+ 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}
-
- \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}
-
+
+ \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
@@ -123,12 +221,14 @@ The syntax for specifying nodes is the following:
|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=examplefill]
+\tikz \fill[fill=yellow!80!black]
(0,0) node {first node}
- -- (1,1) node[draw] {second node}
+ -- (1,1) node[draw, behind path] {second node}
-- (0,2) node[fill=red!20,draw,double,rounded corners] {third node};
\end{codeexample}
@@ -139,16 +239,15 @@ The syntax for specifying nodes is the following:
|shapes.geometric| library for the latter shape):
\begin{codeexample}[]
-\tikz \fill[fill=examplefill]
- (0,0) node{first node}
- -- (1,1) node[ellipse,draw] {second node}
- -- (0,2) node[circle,fill=red!20] {third node};
+\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}
- In the future, there might be much more complicated shapes available
- such as, say, a shape for a resistor or a shape for a \textsc{uml}
- class. Unfortunately, creating new shapes is a bit tricky and makes
- it necessary to use the basic layer directly. Life is hard.
+ 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)}
@@ -163,13 +262,44 @@ The syntax for specifying nodes is the following:
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|, % this par has to be adapted: no more shapes library available, only several sublibraries
- |circle|, |coordinate|, and, when the package |pgflibraryshapes| is
- loaded, also |ellipse|. Details of these shapes, like their anchors
+ 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}
- The following styles influences how nodes are rendered:
+ \medskip
+ \textbf{The foreach statement for nodes.}
+ At the beginning of a node specification (and only there) you can provide multiple
+ \meta{foreach statements}, each of which has the form |foreach| \meta{var}
+ |in| |{|\meta{list}|}| (note that there is no slash before
+ |foreach|). When they are given, instead of a single node, multiple
+ nodes will be created: The \meta{var} will iterate over all values
+ of \meta{list} and for each of them, a new node is created. These
+ nodes are all created using all the text following the \meta{foreach
+ statements}, but in each copy the \meta{var} will have the current
+ value of the current element in the \meta{list}.
+
+ As an example, the following two codes have the same effect:
+\begin{codeexample}[]
+\tikz \draw (0,0) node foreach \x in {1,2,3} at (\x,0) {\x};
+\end{codeexample}
+\begin{codeexample}[]
+\tikz \draw (0,0) node at (1,0) {1} node at (2,0) {2} node at (3,0) {3};
+\end{codeexample}
+ When you provide several |foreach| statements, they work like
+ ``nested loops'':
+\begin{codeexample}[]
+\tikz \node foreach \x in {1,...,4} foreach \y in {1,2,3}
+ [draw] at (\x,\y) {\x,\y};
+\end{codeexample}
+ As the example shows, a \meta{list} can contain ellipses (three
+ dots) to indicated that a larger number of numbers is meant. Indeed,
+ you can use the full power of the |\foreach| command here, including
+ multiple parameters and options, see Section~\ref{section-foreach}.
+
+ \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}[]
@@ -190,16 +320,56 @@ The syntax for specifying nodes is the following:
\end{tikzpicture}
\end{codeexample}
\end{stylekey}
+
+ \medskip
+ \textbf{Name scopes.}
+ It turns out that the name of a node can further be influenced using
+ two keys:
+ \begin{key}{/tikz/name prefix=\meta{text} (initially \normalfont empty)}
+ The value of this key is prefixed to every node inside the
+ current scope. This includes both the naming of the node (via
+ the |name| key or via the implicit |(|\meta{name}|)| syntax) as
+ well as any referencing of the node. Outside the scope,
+ the nodes can (and need to) be referenced using ``full name''
+ consisting of the prefix and the node name.
+
+ The net effect of this is that you can set the name prefix at
+ the beginning of a scope to some value and then use short and
+ simple names for the nodes inside the scope. Later, outside the
+ scope, you can reference the nodes via their full name:
+\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
+ ``recycable'' code.
+ \end{key}
+ \begin{key}{/tikz/name suffix=\meta{text} (initially \normalfont empty)}
+ Works as |name prefix|, only the \meta{text} is appended to
+ every node name in the current scope.
+ \end{key}
\end{pathoperation}
-There is a special syntax for specifying ``light-weighed'' nodes:
+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][|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|,
+ |\node[shape=coordinate]|\verb|[|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|,
- where the |at| part might be missing.
+ where the |at| part may be omitted.
\end{pathoperation}
Since nodes are often the only path operation on paths, there are two
@@ -246,12 +416,12 @@ demonstrates the difference:
\path[yshift=1.5cm,shape=rectangle]
(0,0) node(a1){} (1,0) node(a2){}
(1,1) node(a3){} (0,1) node(a4){};
- \filldraw[fill=examplefill] (a1) -- (a2) -- (a3) -- (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=examplefill] (b1) -- (b2) -- (b3) -- (b4);
+ \filldraw[fill=yellow!80!black] (b1) -- (b2) -- (b3) -- (b4);
\end{tikzpicture}
\end{codeexample}
@@ -283,7 +453,7 @@ shapes:
\begin{tikzpicture}
\draw (0,0) node[inner sep=0pt,draw] {tight}
(0cm,2em) node[inner sep=5pt,draw] {loose}
- (0cm,4em) node[fill=examplefill] {default};
+ (0cm,4em) node[fill=yellow!80!black] {default};
\end{tikzpicture}
\end{codeexample}
\end{key}
@@ -312,11 +482,11 @@ shapes:
exactly on the ``outside border'' of the path (not on the path
itself). When the shape is filled, but not drawn, this may not be
desirable. In this case, the |outer sep| should be set to zero
- point.
+ points.
\begin{codeexample}[]
\begin{tikzpicture}
\draw[line width=5pt]
- (0,0) node[outer sep=0pt,fill=examplefill] (f) {filled}
+ (0,0) node[outer sep=0pt,fill=yellow!80!black] (f) {filled}
(2,0) node[inner sep=.5\pgflinewidth+2pt,draw] (d) {drawn};
\draw[->] (1,-1) -- (f);
@@ -393,10 +563,8 @@ node contents, but \emph{in addition} to any other transformations.
\begin{codeexample}[]
\tikzstyle{every node}=[dart, shape border uses incircle,
inner sep=1pt, draw]
-\begin{tikzpicture}
- \foreach \a/\b/\c in {A/0/0, B/45/0, C/0/45, D/45/45}
- \node [shape border rotate=\b, rotate=\c] at (\b/36,-\c/36) {\a};
-\end{tikzpicture}
+\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
@@ -424,7 +592,7 @@ node contents.
\end{tikzpicture}
\end{codeexample}
-There are \pgfname{} keys determine how a shape border is
+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
@@ -479,13 +647,13 @@ two values will be used.
\label{section-nodes-multi}
Most nodes just have a single simple text label. However, nodes of a
-more complicated shapes might be made up from several \emph{node
+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 shape might use parts for the different atoms
+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
@@ -555,29 +723,68 @@ set the color used for text using the following option:
\end{key}
Just like the color itself, you may also wish to set the opacity of
-the text only. For this, use the option |text opacity| option, which
+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. Use the
-following option for this:
+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 text labels.
+ 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}
- \draw[font=\itshape] (1,0) -- +(1,1) node[above] {italic};
+ \node [font=\itshape] {italic};
\end{tikzpicture}
\end{codeexample}
- A perhaps more useful example is the following:
+
+\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}[]
\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}
-\end{key}
+ 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}
@@ -615,7 +822,7 @@ lines of text. There are three different ways of achieving this:
The |\\| command takes an optional extra space as an argument in square
brackets.
\begin{codeexample}[]
-\tikz \node[fill=examplefill,align=right]
+\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
@@ -640,45 +847,45 @@ Let us now first have a look at the |text width| command.
change the alignment using |align| or directly using commands line
|\centering|.
\begin{codeexample}[]
-\tikz \draw (0,0) node[fill=examplefill,text width=3cm]
+\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{how}}
- This key is used to setup an alignment for multi-line text inside a
+\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{how}. If |text width|
+ 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{how} and the resulting node's width
+ 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{how} to one of the following values:
+ 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=examplefill,align=left]
+\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=examplefill,text width=3cm,align=left]
+\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{|flush left|}]
+ \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
@@ -689,55 +896,79 @@ Let us now first have a look at the |text width| command.
it may be useful for very narrow boxes and when you wish to avoid
hyphenations.
\begin{codeexample}[]
-\tikz \node[fill=examplefill,text width=3cm,align=flush left]
+\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=examplefill,align=right]
+\tikz \node[fill=yellow!80!black,align=right]
{This is a\\ demonstration text for\\ alignments.};
\end{codeexample}
\begin{codeexample}[]
-\tikz \node[fill=examplefill,text width=3cm,align=right]
+\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{|flush right|}]
+ \item[|align=|\declare{\texttt{flush right}}]
Works like |flush left|, only for right alignment.
\begin{codeexample}[]
-\tikz \node[fill=examplefill,text width=3cm,align=flush right]
+\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=examplefill,align=center]
+\tikz \node[fill=yellow!80!black,align=center]
{This is a\\ demonstration text for\\ alignments.};
\end{codeexample}
\begin{codeexample}[]
-\tikz \node[fill=examplefill,text width=3cm,align=center]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=center]
{This is a demonstration text for showing how line breaking works.};
\end{codeexample}
- \item[|align=|\declare{|flush center|}]
- Works like |flush left| or |flush right|, only for center alignment.
+ 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.
+ 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=examplefill,text width=3cm,align=flush center]
+\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 pretty broad nodes.
+ be ``justified.'' Use this only with rather broad nodes.
{%
\hbadness=10000
\begin{codeexample}[]
-\tikz \node[fill=examplefill,text width=3cm,align=justify]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=justify]
{This is a demonstration text for showing how line breaking works.};
\end{codeexample}
}
@@ -759,7 +990,7 @@ Let us now first have a look at the |text width| command.
with the |\halign| command.
This key only has an effect if |text width|
- is empty, otherwise it is ignored. Furthermore, if \meta{header} is
+ 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:
@@ -858,7 +1089,7 @@ 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: Imaging a node of
+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
@@ -1090,7 +1321,7 @@ differently.
automatically used, as explained later.
The effect of this option is the following. First, the point
- |(|\meta{number of dimension 2}|,|\meta{number or dimension 1}|)|
+ |(|\meta{number or dimension 2}|,|\meta{number or dimension 1}|)|
is computed (note the inversed order), using the normal rules for
evaluating such a coordinate, yielding some position. Then, the
node is shifted by the vertical component of this point. The
@@ -1106,8 +1337,8 @@ differently.
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 declare{|of |\meta{coordinate}},
- where\meta{coordinate} is \emph{not} in parentheses and it is
+ \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
@@ -1129,9 +1360,9 @@ differently.
|somenode|. The same effect could have been achieved writing
|above=5mm| followed by |at=(somenode.north east)|.
- If the \meta{shift-part} is missing, the shift is not zero, but
+ 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 have be |of |\meta{node name}. An
+ \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}
@@ -1160,8 +1391,7 @@ differently.
\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 other \meta{node
- name} are set the |center|.
+ 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
@@ -1256,13 +1486,6 @@ differently.
\begin{codeexample}[]
\begin{tikzpicture}[every node/.style={draw,circle}]
\draw[help lines] (0,0) grid (2,5);
- \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}
\begin{scope}[node distance=5mm and 5mm]
\node (b) at (1,4) {b};
\node [left=of b] {1}; \node [right=of b] {2};
@@ -1270,11 +1493,6 @@ differently.
\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}
-\begin{codeexample}[]
-\begin{tikzpicture}[every node/.style={draw,rectangle}]
- \draw[help lines] (0,0) grid (2,5);
\begin{scope}[node distance=5mm]
\node (a) at (1,1) {a};
\node [left=of a] {1}; \node [right=of a] {2};
@@ -1282,6 +1500,11 @@ differently.
\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}[]
+\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};
@@ -1289,6 +1512,13 @@ differently.
\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}[]
@@ -1315,10 +1545,10 @@ differently.
\begin{key}{/tikz/below left=\opt{\meta{specification}}}
Works similar to |above left|.
\end{key}
-\begin{key}{/tikz/above left=\opt{\meta{specification}}}
+\begin{key}{/tikz/above right=\opt{\meta{specification}}}
Works similar to |above left|.
\end{key}
-\begin{key}{/tikz/above right=\opt{\meta{specification}}}
+\begin{key}{/tikz/below right=\opt{\meta{specification}}}
Works similar to |above left|.
\end{key}
@@ -1359,7 +1589,7 @@ keys:
-\subsubsection{Arranging Nodes Using a Chains and Matrices}
+\subsubsection{Arranging Nodes Using Chains and Matrices}
The simple |above| and |right| options may not always suffice for
arranging a large number of nodes. For such situations \tikzname\
@@ -1379,11 +1609,11 @@ 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 an, afterwards, parts of the
+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 a the details. The idea is
+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
@@ -1435,7 +1665,7 @@ 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 in which you can achieve this:
+90 degrees. There are two ways to achieve this:
\begin{enumerate}
\item
@@ -1447,7 +1677,7 @@ example, it certainly sometimes makes sense to rotate a node by
will get a ``huge'' X in your graphic.
\end{key}
\item
- You can give transformation option \emph{inside} the option list of
+ You can give transformation options \emph{inside} the option list of
the node. \emph{These} transformations always apply to the node.
\begin{codeexample}[]
\begin{tikzpicture}[every node/.style={draw}]
@@ -1463,6 +1693,41 @@ example, it certainly sometimes makes sense to rotate a node by
\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}[]
+\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}
@@ -1485,7 +1750,7 @@ ways are described in the following.
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} or 0 is the previous coordinate, 1 is the current
+ \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.
@@ -1499,6 +1764,16 @@ ways are described in the following.
node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
\end{codeexample}
+ For 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
@@ -1509,10 +1784,10 @@ ways are described in the following.
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.
+ and B\'ezier curves if you are intrigued.
\begin{codeexample}[]
- \tikz \draw (0,0) .. controls +(right:3.5cm) and +(right:3.5cm) .. (0,3)
- \foreach \p in {0,0.125,...,1} {node[pos=\p]{\p}};
+\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
@@ -1530,11 +1805,10 @@ ways are described in the following.
\end{codeexample}
For all other path construction operations, \emph{the position
- placement does not work}, currently. This will hopefully change in
- the future (especially for the arc operation).
+ placement does not work}, currently.
\end{key}
-\begin{key}{/tikz/auto=\meta{left or right} (default \normalfont is scope's setting)}
+\begin{key}{/tikz/auto=\opt{\meta{direction}} (default \normalfont is scope's setting)}
This option causes an anchor positions to be calculated
automatically according to the following rule. Consider a line
between to points. If the \meta{direction} is |left|, then the
@@ -1577,10 +1851,10 @@ ways are described in the following.
\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)
- \foreach \pos in {0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1}
- {node [pos=\pos,swap,fill=red!20] {\pos}}
- \foreach \pos in {0.025,0.2,0.4,0.6,0.8,0.975}
- {node [pos=\pos,fill=blue!20] {\pos}};
+ 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}[]
@@ -1602,6 +1876,10 @@ ways are described in the following.
\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
@@ -1610,7 +1888,7 @@ ways are described in the following.
|[allow upside down]|, see below.
\begin{codeexample}[]
\tikz \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3)
- \foreach \p in {0,0.25,...,1} {node[sloped,above,pos=\p]{\p}};
+ node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p};
\end{codeexample}
\begin{codeexample}[]
\begin{tikzpicture}[->]
@@ -1626,7 +1904,7 @@ ways are described in the following.
\begin{codeexample}[]
\tikz [allow upside down]
\draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3)
- \foreach \p in {0,0.25,...,1} {node[sloped,above,pos=\p]{\p}};
+ node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p};
\end{codeexample}
\begin{codeexample}[]
\begin{tikzpicture}[->,allow upside down]
@@ -1642,13 +1920,13 @@ There exist styles for specifying positions a bit less ``technically'':
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] {|at end|}
- node[very near end] {|very near end|}
- node[near end] {|near end|}
- node[midway] {|midway|}
- node[near start] {|near start|}
- node[very near start] {|very near start|}
- node[at start] {|at start|};
+ 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}
@@ -1730,9 +2008,39 @@ the operation with the |pos| option set.
\subsection{The Label and Pin Options}
-In addition to the |node| path operation, nodes can also be added
-using the |label| and the |pin| option. This is mostly useful
-for simple nodes.
+\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}[]
+\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}[]
+\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}%
@@ -1780,20 +2088,34 @@ for simple nodes.
\node [transform shape,rectangle,draw,label=right:label] {main node};
\end{codeexample}
\end{key}
- \item Then, an anchor point for the |label node|. It is determined
- in such a way that the |labe node| will ``face away'' from the
+ \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 general, the choice should be
- what you would expect, but you may have to set the anchor yourself
- in difficult situations.
-\begin{codeexample}[]
-\tikz
- \node [circle,draw,
+ |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. If this is
+ not desired, you will have to set the anchor yourself.
+\begin{codeexample}[]
+\tikz
+ \node [circle, draw,
label=default,
label=60:$60^\circ$,
- label=below:$-90^\circ$] {my circle};
+ label=below:$-90^\circ$,
+ label=3:$3^\circ$,
+ label=2:$2^\circ$] {my circle};
\end{codeexample}
\item
One \meta{angle} is special: If you set the \meta{angle} to
@@ -1842,9 +2164,12 @@ for simple nodes.
\end{stylekey}
\end{key}
+
+\subsubsection{The Pin Option}
+
\begin{key}{/tikz/pin=\opt{|[|\meta{options}|]|}\meta{angle}|:|\meta{text}}
- This is option is quite similar to the |label| option, but there is
- one difference: In addition to adding a extra node to the picture,
+ 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}[]
@@ -1901,6 +2226,213 @@ for simple nodes.
\end{key}
+\subsubsection{The Quotes Syntax}
+\label{section-label-quotes}
+
+The |label| and |pin| option provide a syntax for
+creating nodes next to existing nodes, but this syntax is often a
+bit too verbose. By including the following library, you get access to
+an even more concise syntax:
+
+\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 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 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
+\begin{quote}
+ |label={[|\meta{options}|]|\meta{text}|}|
+\end{quote}
+
+Let us have a look at an example:
+\begin{codeexample}[]
+\tikz \node ["my label" red, draw] {my node};
+\end{codeexample}
+The above has the same effect as the following:
+\begin{codeexample}[]
+\tikz \node [label={[red]my label}, draw] {my node};
+\end{codeexample}
+
+Here are further examples, one where no \meta{options} are added
+to the |label|, one where a position is specified, and examples with
+more complicated options in curly braces:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [row sep=5mm] {
+ \node [draw, "label"] {A}; \\
+ \node [draw, "label" left] {B}; \\
+ \node [draw, "label" color=red] {C}; \\
+ \node [draw, "label" {red,draw,thick}] {D}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+Let us now have a more detailed look at what which commands this
+library provides:
+
+\begin{key}{/tikz/quotes mean label}
+ When this option is used (which is the default when this library is
+ loaded), then, as described above, inside the options of a node a
+ special syntax check is done.
+
+ \medskip
+ \noindent\textbf{The syntax.}
+ For each string in the list of options
+ it is tested whether it starts with a quotation mark (note that this
+ will never happen for normal keys since the normal keys of
+ \tikzname\ do not start with quotation marks). When this happens,
+ the \meta{string} should not be a key--value pair, but, rather, must
+ have the form:
+ \begin{quote}
+ |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}}
+ \end{quote}
+
+ (We will discuss the optional apostrophe in a moment. It is not
+ really important for the current option, but only for
+ edge labels, which are discussed later).
+
+ \medskip
+ \noindent\textbf{Transformation to a label option.}
+ When a \meta{string} has the above form, it is treated (almost) as
+ if you had written
+ \begin{quote}
+ |label={[|\meta{options}|]|\meta{text}|}|
+ \end{quote}
+ instead. The ``almost'' refers to the following additional feature:
+ In reality, before the \meta{options} are executed inside the
+ |label| command, the direction keys |above|, |left|, |below right|
+ and so on are redefined so that |above| is a shorthand for
+ |label position=90| and similarly for the other keys. The net effect
+ is that in order to specify the position of the \meta{text} relative
+ to the main node you can just put something like |left| or
+ |above right| inside the \meta{options}:
+\begin{codeexample}[]
+\tikz
+ \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}[]
+\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}[]
+\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}[]
+\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}[]
+\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}[]
+\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}[]
+\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}
@@ -1925,7 +2457,7 @@ Section~\ref{section-node-coordinates}. Suppose you have said
same effect.
However, for most other shapes, some path construction operations like
- |--| try to be ``clever'' when this they are asked to draw a line
+ |--| 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
@@ -1955,9 +2487,11 @@ Section~\ref{section-node-coordinates}. Suppose you have said
\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 you to have each |edge| to have a
+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
@@ -1965,7 +2499,7 @@ been drawn. Note that $p$ can be totally different from the main
path with respect to its options. Also note that if there are
several |to| and/or |node| operations in the main path, each
creates its own path(s) and they are drawn in the order that they
-are encountered on the path.
+are encountered on the main path.
\begin{pathoperation}{edge}{\opt{|[|\meta{options}|]|}
\opt{\meta{nodes}} |(|\meta{coordinate}|)|}
@@ -2013,8 +2547,8 @@ are encountered on the path.
\begin{codeexample}[]
\begin{tikzpicture}
- \foreach \name/\angle in {a/0,b/90,c/180,d/270}
- \node (\name) at (\angle:1) {$\name$};
+ \node foreach \name/\angle in {a/0,b/90,c/180,d/270}
+ (\name) at (\angle:1) {$\name$};
\path[->] (b) edge (a)
edge (c)
@@ -2030,8 +2564,8 @@ are encountered on the path.
\begin{codeexample}[]
\begin{tikzpicture}
- \foreach \name/\angle in {a/0,b/90,c/180,d/270}
- \node (\name) at (\angle:1.5) {$\name$};
+ \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)
@@ -2045,18 +2579,98 @@ are encountered on the path.
Instead of |every to|, the style |every edge| is installed at the
beginning of the main path.
- \begin{stylekey}{/tikz/every edge (inititially draw)} % inititially --> initially? (ff) (this is the definition of the key, so please have a look)
+ \begin{stylekey}{/tikz/every edge (initially draw)}
Executed for each |edge|.
\begin{codeexample}[]
\begin{tikzpicture}[every to/.style={draw,dashed}]
- \path (0,0) to (3,2);
+ \path (0,0) edge (3,2);
\end{tikzpicture}
\end{codeexample}
\end{stylekey}
\end{pathoperation}
-\subsection{Referencing Nodes Outside the Current Pictures}
+\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}[]
+\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}[]
+\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}[]
+\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}[]
+\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}[]
+\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}
@@ -2166,7 +2780,7 @@ access the current page. It is a node of shape rectangle 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 |remembered picture| and the |overlay|
+one. Thus, by giving the |remember picture| and the |overlay|
options to a picture, you can position nodes \emph{absolutely} on a
page.
@@ -2204,12 +2818,41 @@ page).
\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.
+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
@@ -2219,41 +2862,20 @@ useful there:
Expands to the last node on the path.
\end{command}
-A \emph{late option} for a node is an option that is given a long time
-after the node has already been constructed.
+Instead of the |node also| syntax, you can also the following option:
\begin{key}{/tikz/late options=\meta{options}}
This option can be given on a path (but not as an argument to a
- |node| path command). It has the following effect: An already
- \meta{existing node} is determined (in a way to be described in a moment)
- and, then, the \meta{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 late options. However, giving
- the |append after command| and |prefix after command| options inside
- the \meta{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. Likewise, you can use the |on chain|
- option to make an already \meta{existing node} part of a chain.
-
- The \meta{existing node} is determined as follows: If the
- |name=|\meta{existing node} option is used inside the
- \meta{options}, then this name is used. Otherwise, if the last
- coordinate on the current path was of the form |(|\meta{existing
- node}|)|, then this \meta{existing node} name is used. Otherwise,
- an error results.
-
+ |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 (a) [draw,circle] {Hello};
- \path (a) [late options={label=above:world}];
+ \node [draw,circle] (a) {Hello};
+ \path [late options={name=a, label=above:world}];
\end{tikzpicture}
\end{codeexample}
-
\end{key}