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.tex1299
1 files changed, 956 insertions, 343 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 91b85c34a8f..950dbe71a28 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
@@ -38,8 +38,7 @@ Section~\ref{section-nodes-connecting} it is explained 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. Section~\ref{section-nodes-predefined} lists the predefined
-shapes. Finally, Section~\ref{section-nodes-executing} explains the
+operation. Finally, Section~\ref{section-nodes-executing} explains the
special |after node path| options.
@@ -93,19 +92,29 @@ The syntax for specifying nodes is the following:
optional. You may also add the option |name=|\meta{name} to the
\meta{option} list; it has the same effect.
- \begin{itemize}
- \itemoption{name}|=|\meta{node name}
- assigns a name to the node for later reference. Since this is a
+ \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.
-
- \itemoption{at}|=|\meta{coordinate}
- is another way of specifying ath |at| coordinate.
- \end{itemize}
+ \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 |late options| options,
+ you can also assign an alias name to a node at a later point.
+ \end{key}
+
+ \begin{key}{/tikz/at=\meta{coordinate}}
+ This is another way of specifying ath |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}
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,
@@ -143,9 +152,8 @@ The syntax for specifying nodes is the following:
it necessary to use the basic layer directly. Life is hard.
To select the shape of a node, the following option is used:
- \begin{itemize}
- \itemoption{shape}|=|\meta{shape name}
- select the shape either of the current node or, when this option is
+ \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}}
@@ -160,31 +168,29 @@ The syntax for specifying nodes is the following:
|circle|, |coordinate|, and, when the package |pgflibraryshapes| is
loaded, also |ellipse|. Details of these shapes, like their anchors
and size options, are discussed in Section~\ref{section-the-shapes}.
- \end{itemize}
+ \end{key}
The following styles influences how nodes are rendered:
- \begin{itemize}
- \itemstyle{every node}
+ \begin{stylekey}{/tikz/every node (initially \normalfont empty)}
This style is installed at the beginning of every node.
\begin{codeexample}[]
-\begin{tikzpicture}
- \tikzstyle{every node}=[draw]
+\begin{tikzpicture}[every node/.style={draw}]
\draw (0,0) node {A} -- (1,1) node {B};
\end{tikzpicture}
\end{codeexample}
-
- \itemstyle{every \meta{shape} node}
+ \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}
- \tikzstyle{every rectangle node}=[draw]
- \tikzstyle{every circle node}= [draw,double]
+ [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{itemize}
+ \end{stylekey}
\end{pathoperation}
There is a special syntax for specifying ``light-weighed'' nodes:
@@ -209,6 +215,265 @@ special commands for creating paths containing only a node:
\end{command}
+\subsubsection{Predefined Shapes}
+
+\label{section-nodes-predefined}
+
+\label{section-the-shapes}
+
+\pgfname\ 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=examplefill] (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);
+\end{tikzpicture}
+\end{codeexample}
+
+
+
+\subsubsection{Common Options: Separations, Margins, Padding and
+ Border Rotation}
+
+\label{section-shape-seps}
+\label{section-shape-common-options}
+
+The exact behaviour of shapes differs, shapes defined for more
+special purposes (like a, say, transistor shape) will have even more
+custom behaviors. However, there are some options that apply to most
+shapes:
+
+\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=examplefill] {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} (initially .5\string\pgflinewidth)}
+ \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). 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.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[line width=5pt]
+ (0,0) node[outer sep=0pt,fill=examplefill] (f) {filled}
+ (2,0) node[inner sep=.5\pgflinewidth+2pt,draw] (d) {drawn};
+
+ \draw[->] (1,-1) -- (f);
+ \draw[->] (1,-1) -- (d);
+\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.
+\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 0pt)}
+ \keyalias{tikz}
+ This option ensures that the height of the shape (including the
+ inner, but ignoring the outer separation) will be at least
+ \meta{dimension}. Thus, if the text plus the inner separation is not
+ at least as large as \meta{dimension}, the shape will be enlarged
+ appropriately. However, if the text is already larger than
+ \meta{dimension}, the shape will not be shrunk.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw (0,0) node[minimum height=1cm,draw] {1cm}
+ (2,0) node[minimum height=0cm,draw] {0cm};
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+\begin{key}{/pgf/minimum width=\meta{dimension} (initially 0pt)}
+ \keyalias{tikz}
+ Same as |minimum height|, only for the width.
+\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}[]
+\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}[]
+\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}
+\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 contructed using an incircle,
+that is, a circle that tightly fits the node contents (including
+the |inner sep|), then the rotation can be unrestricted. If, however,
+the border is constructed using the natural dimensions of the node
+contents, the rotation is restricted to integer multiples of 90
+degrees.
+
+Why should there be two kinds of rotation and border construction?
+Borders constructed using the natural dimensions of the node contents
+provide a much tighter fit to the node contents, but to maintain
+this tight fit, the border rotation must be restricted to integer
+multiples of 90 degrees. By using an incircle, unrestricted rotation
+is possible, but the border will not make a very tight fit to the
+node contents.
+
+\begin{codeexample}[]
+\tikzstyle{every node}=[isosceles triangle, draw]
+\begin{tikzpicture}
+ \node {abc};
+ \node [shape border uses incircle] at (2,0) {abc};
+\end{tikzpicture}
+\end{codeexample}
+
+There are \pgfname{} keys determine how a shape border is
+contructed, 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}[]
+\tikzstyle{every node}=[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}
@@ -253,15 +518,15 @@ different node parts by using the following command:
You will have to lookup which parts are defined by a shape.
The following styles influences node parts:
- \begin{itemize}
- \itemstyle{every \meta{part name} node part}
+ \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}[]
-\tikzstyle{every lower node part}=[red]
-\tikz \node [circle split,draw] {$q_1$ \nodepart{lower} $00$};
+\tikz [every lower node part/.style={red}]
+ \node [circle split,draw] {$q_1$ \nodepart{lower} $00$};
\end{codeexample}
- \end{itemize}
+ \end{stylekey}
\end{command}
@@ -275,8 +540,7 @@ color is just the last color installed using |color=|, possibly
inherited from another scope. However, it is possible to specificly
set the color used for text using the following option:
-\begin{itemize}
- \itemoption{text}|=|\meta{color}
+\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}[]
@@ -286,29 +550,15 @@ set the color used for text using the following option:
\draw (2,0) -- +(1,1) node[above,red] {red};
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
Just like the color itself, you may also wish to set the opacity of
-the text only. For this, use the following option:
-\begin{itemize}
- \itemoption{text opacity}|=|\meta{value}
- Sets the opacity of text labels.
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[line width=2mm,blue!50,cap=round] (0,0) grid (3,2);
- \tikzstyle{every node}=[fill,draw]
-
- \node[opacity=0.5] at (1.5,2) {Upper node};
- \node[draw opacity=0.8,fill opacity=0.2,text opacity=1]
- at (1.5,0) {Lower node};
-\end{tikzpicture}
-\end{codeexample}
-\end{itemize}
+the text only. For this, use the option |text opacity| option, which
+is detailed in Section~\ref{section-tikz-transparency}.
Next, you may wish to adjust the font used for the text. Use the
following option for this:
-\begin{itemize}
- \itemoption{font}|=|\meta{font commands}
+\begin{key}{/tikz/font=\meta{font commands}}
Sets the font used for text labels.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -318,11 +568,11 @@ following option for this:
A perhaps more useful example is the following:
\begin{codeexample}[]
-\tikzstyle{every text node part}=[font=\itshape]
-\tikzstyle{every lower node part}=[font=\footnotesize]
-\tikz \node [circle split,draw] {state \nodepart{lower} output};
+\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{itemize}
+\end{key}
Normally, when a node is typeset, all the text you give in the braces
@@ -333,8 +583,7 @@ You can change this behaviour using the following options. They allow
you to limit the width of a node (naturally, at the expense of its
height).
-\begin{itemize}
- \itemoption{text width}|=|\meta{dimension}
+\begin{key}{/tikz/text width=\meta{dimension}}
This option will put the text of a node in a box of the given width
(more precisely, in a |{minipage}| of this width; for plain \TeX\ a
rudimentary ``minipage emulation'' is used).
@@ -350,8 +599,10 @@ height).
\tikz \draw (0,0) node[fill=examplefill,text width=3cm]
{This is a demonstration text for showing how line breaking works.};
\end{codeexample}
- \itemoption{text justified}
- causes the text to be justified instead of (right)ragged. Use this
+\end{key}
+
+\begin{key}{/tikz/text justified}
+ Causes the text to be justified instead of (right)ragged. Use this
only with pretty broad nodes.
{%
\hbadness=10000
@@ -364,8 +615,10 @@ height).
badly typeset lines. (For this manual I asked \TeX\ to stop
complaining by using |\hbadness=10000|, but this is a foul deed,
indeed.)
- \itemoption{text ragged}
- causes the text to be typeset with a ragged right. This uses the
+\end{key}
+
+\begin{key}{/tikz/text ragged}
+ Causes the text to be typeset with a ragged right. This 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. This
is the default.
@@ -373,27 +626,33 @@ height).
\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text ragged]
{This is a demonstration text for showing how line breaking works.};
\end{codeexample}
- \itemoption{text badly ragged}
- causes the right border to be ragged in the \LaTeX-style, in which
+\end{key}
+
+\begin{key}{/tikz/text badly ragged}
+ 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 \draw (0,0) node[fill=examplefill,text width=3cm,text badly ragged]
{This is a demonstration text for showing how line breaking works.};
\end{codeexample}
- \itemoption{text centered}
- centers the text, but tries to balance the lines.
+\end{key}
+
+\begin{key}{/tikz/text centered}
+ Centers the text, but tries to balance the lines.
\begin{codeexample}[]
\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text centered]
{This is a demonstration text for showing how line breaking works.};
\end{codeexample}
- \itemoption{text badly centered}
- centers the text, without balancing the lines.
+\end{key}
+
+\begin{key}{/tikz/text badly centered}
+ Centers the text, without balancing the lines.
\begin{codeexample}[]
\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text badly centered]
{This is a demonstration text for showing how line breaking works.};
\end{codeexample}
-\end{itemize}
+\end{key}
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
@@ -409,8 +668,7 @@ also taken into account.
I recommend using |minimum size| instead of |text height| except for
special situations.
-\begin{itemize}
- \itemoption{text height}|=|\meta{dimension}
+\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
@@ -422,16 +680,18 @@ special situations.
\tikz \node[draw] {y};
\tikz \node[draw,text height=10pt] {y};
\end{codeexample}
- \itemoption{text depth}|=|\meta{dimension}
+\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{itemize}
+\end{key}
-\subsection{Placing Nodes Using Anchors}
+\subsection{Positioning Nodes}
\label{section-nodes-anchors}
@@ -439,6 +699,9 @@ 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: Imaging a node of
rectangular shape of a certain size. \pgfname\ defines numerous anchor
@@ -475,9 +738,8 @@ Since the default anchor is |center|, the default behaviour is to
shift the node in such a way that it is centered on the current
position.
-\begin{itemize}
- \itemoption{anchor}|=|\meta{anchor name}
- causes the node to be shifted such that it's anchor \meta{anchor
+\begin{key}{/tikz/anchor=\meta{anchor name}}
+ Causes the node to be shifted such that it's anchor \meta{anchor
name} lies on the current coordinate.
The only anchor that is present in all shapes is |center|. However,
@@ -501,16 +763,20 @@ position.
\draw[anchor=mid] (0,0) node{x} -- (0.5,0) node{y} -- (1,0) node{t};
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\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{itemize}
- \itemoption{above}\opt{|=|\meta{offset}}
- does the same as |anchor=south|. If the \meta{offset} is specified,
+
+\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}[]
@@ -519,72 +785,488 @@ more intuitively:
\begin{codeexample}[]
\tikz \fill (0,0) circle (2pt) node[above=2pt] {above};
\end{codeexample}
- \itemoption{above left}\opt{|=|\meta{offset}}
- does the same as |anchor=south east|. If the \meta{offset} is
- specified, the node is additionally shifted upwards and right by
- \meta{offset}.
+\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 left=2pt] {above left};
+\tikz \fill (0,0) circle (2pt) node[above right] {above right};
\end{codeexample}
- \itemoption{above right}\opt{|=|\meta{offset}}
- does the same as |anchor=south west|.
+\end{key}
+
+\begin{key}{/tikz/below left}
+ Similar to |above left|.
+\end{key}
+\begin{key}{/tikz/below right}
+ Similar to |above left|.
+\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 paramter. 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}[]
-\tikz \fill (0,0) circle (2pt) node[above right] {above right};
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (2,2);
+ \node at (1,1) [above=2pt+3pt,draw] {above};
+\end{tikzpicture}
\end{codeexample}
- \itemoption{left}\opt{|=|\meta{offset}}
- does the same as |anchor=east|.
+ 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}[]
-\tikz \fill (0,0) circle (2pt) node[left] {left};
+\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}
- \itemoption{right}\opt{|=|\meta{offset}}
- does the same as |anchor=west|.
- \itemoption{below}\opt{|=|\meta{offset}}
- does the same as |anchor=north|.
- \itemoption{below left}\opt{|=|\meta{offset}}
- does the same as |anchor=north east|.
- \itemoption{below right}\opt{|=|\meta{offset}}
- does the same as |anchor=north west|.
-\end{itemize}
+ \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.
-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{itemize}
- \itemoption{above of}\opt{|=|\meta{node}}
- This option causes the node to be placed at the distance
- |node distance| above of \meta{node}. The anchor is |center|.
+ The effect of this option is the following. First, the point
+ |(|\meta{number of dimension 2}|,|\meta{number or dimension 1}|)|
+ is computed (note the inversed order), using the normal rules for
+ evaluating such a coordinate, yielding some position. Then, the
+ node is shifted by the vertical component of this point. The
+ anchor is set to |south|.
\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};
+\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}
- \itemoption{above left of}\opt{|=|\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.
- \itemoption{above right of}\opt{|=|\meta{node}} works similarly.
- \itemoption{left of}\opt{|=|\meta{node}} works similarly.
- \itemoption{right of}\opt{|=|\meta{node}} works similarly.
- \itemoption{below of}\opt{|=|\meta{node}} works similarly.
- \itemoption{below left of}\opt{|=|\meta{node}} works similarly.
- \itemoption{below right of}\opt{|=|\meta{node}} works similarly.
- \itemoption{node distance}\opt{|=|\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{itemize}
+ \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 declare{|of |\meta{coordinate}},
+ where\meta{coordinate} is \emph{not} in parentheses and it is
+ \emph{not} just a node name. An example would be
+ |of somenode.north| or |of 2,3|. In this case, the
+ following happens: First, the node's |at| parameter is set to the
+ \meta{coordinate}. Second, the node is shifted according to the
+ \meta{shift-part}. Third, the anchor is set to |south|.
+
+ Here is a basic example:
+\begin{codeexample}[]
+\begin{tikzpicture}[every node/.style=draw]
+ \draw[help lines] (0,0) grid (2,2);
+ \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{shift-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
+ example would be |of somenode|. In this case, the following
+ usually happens:
+ \begin{itemize}
+ \item The anchor is set to |south|.
+ \item The node is shifted according to the \meta{shifting part}
+ or, if it is missing, according to the value of |node distance|.
+ \item The node's |at| parameter is set to \meta{node
+ name}|.north|.
+ \end{itemize}
+ The net effect of all this is that the new node will be placed in
+ such a way that the distance between is south border and
+ \meta{node name}'s north border is exactly the given distance.
+\begin{codeexample}[]
+\begin{tikzpicture}[every node/.style=draw]
+ \draw[help lines] (0,0) grid (2,2);
+ \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 behaviour of this
+ \meta{specification} rather drastically, using the following key:
+ \begin{key}{/tikz/on grid=\meta{boolean} (initially false)}
+ When this key is set to |true|, an \meta{of-part} of the
+ current form behaves differently: The anchors set for the
+ current node as well as the anchor used for other \meta{node
+ name} are set the |center|.
+
+ This has the following effect: When you say
+ |above=1cm of somenode| with |on grid| set to true, the new node
+ will be placed in such a way that its center is 1cm above the
+ center of |somenode|. Repeatedly placing nodes in this way will
+ result in nodes that are centered on ``grid coordinate,'' hence
+ the name of the option.
+\begin{codeexample}[]
+\begin{tikzpicture}[every node/.style=draw]
+ \draw[help lines] (0,0) grid (2,3);
+
+ % 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}[]
+\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
+ behaviour of the \meta{shifting part} is more complicated:
+ \begin{enumerate}
+ \item When the \meta{shifting part} is of the form \meta{number or
+ dimension}| and |\meta{number or dimension}, it has
+ (essentially) the effect of shifting the node vertically upwards
+ by the first \meta{number or dimension} and to the left by the
+ second. To be more precise, the coordinate |(|\meta{second number
+ or dimension}|,|\meta{first number or dimension}|)| is computed
+ and then the node is shifted vertically by the $y$-part of
+ the resulting coordinate and horizontally be the negated $x$-part
+ of the result. (This is exactly what you expect, except possibly
+ when you have used the |x| and |y| options to modify the
+ |xy|-coordinate system so that the unit vectors no longer point
+ in the expected directions.)
+ \item When the \meta{shifting part} is of the form \meta{number or
+ dimension}, the node is shifted by this \meta{number or
+ dimension} in the direction of $135^\circ$. This means that
+ there is a difference between a \meta{shifting part} of |1cm| and
+ of |1cm and 1cm|: In the second case, the node is shifted by 1cm
+ upward and 1cm to the left; in the first case it is shifted by
+ $\frac{1}{2}\sqrt{2}$cm upward and by the same amount to the
+ left. A more mathematical way of phrasing this is the following: A
+ plain \meta{dimension} is measured in the $l_2$-norm, while a
+ \meta{dimension}| and |\meta{dimension} is measured in the
+ $l_1$-norm.
+ \end{enumerate}
+ The following example should help to illustrate the difference:
+\begin{codeexample}[]
+\begin{tikzpicture}[every node/.style={draw,circle}]
+ \draw[help lines] (0,0) grid (2,5);
+ \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};
+ \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}
+\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};
+ \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};
+ \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}
+\begin{codeexample}[]
+\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 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}
+
+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}[]
+\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{Arranging Nodes Using a Chains and Matrices}
+
+The simple |above| and |right| options may not always suffice for
+arranging a large number of nodes. For such situations \tikzname\
+offers two libraries that make positioning easier: The |chains|
+library and the |matrix| library. The first is mostly useful for
+creating ``chains of nodes'' and, more generally, ``flows.'' The
+second allows you to arrange multiple nodes in rows and columns. These
+methods for positioning nodes are described in two separate
+Sections~\ref{section-matrices} and~\ref{section-chains}.
+
+
+\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 an, afterwards, parts of the
+picture are supposed to be encircled or hilighted.
+
+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
+that you may give the |fit| option to a node. The |fit| option expects
+a list of coordinates (one after the other without commas) as its
+parameter. The effect will be that the node's text area has exactly
+the necessary size so that it contains all the given coordinates. Here
+is an example:
+
+\begin{codeexample}[]
+\begin{tikzpicture}[level distance=8mm]
+ \node (root) {root}
+ 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}[]
+\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{pgfonlayer}{background}
+ \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{pgfonlayer}
+\end{tikzpicture}
+\end{codeexample}
\subsection{Transformations}
@@ -603,20 +1285,18 @@ example, it certainly sometimes makes sense to rotate a node by
\begin{enumerate}
\item
You can use the following option:
- \begin{itemize}
- \itemoption{transform shape}
- causes the current ``external'' transformation matrix to be
+ \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{itemize}
+ \end{key}
\item
You can give transformation option \emph{inside} the option list of
the node. \emph{These} transformations always apply to the node.
\begin{codeexample}[]
-\begin{tikzpicture}
- \tikzstyle{every node}=[draw]
- \draw[style=help lines] (0,0) grid (3,2);
+\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}
@@ -645,8 +1325,7 @@ ways are described in the following.
\label{section-pos-option}
-\begin{itemize}
- \itemoption{pos}|=|\meta{fraction}
+\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}
@@ -698,8 +1377,9 @@ ways are described in the following.
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).
+\end{key}
- \itemoption{auto}\opt{|=|\meta{direction}}
+\begin{key}{/tikz/auto=\meta{left or right} (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
@@ -715,8 +1395,8 @@ ways are described in the following.
curves.
\begin{codeexample}[]
-\begin{tikzpicture}[scale=.8,auto=left]
- \tikzstyle{every node}=[circle,fill=blue!20]
+\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};
@@ -726,12 +1406,14 @@ ways are described in the following.
\node (g) at (-2, 1) {g};
\node (h) at (-2,-1) {h};
- \tikzstyle{every node}=[fill=red!20]
\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] {\from--\to};
+ \draw [->] (\from) -- (\to)
+ node[midway,fill=red!20] {\from--\to};
\end{tikzpicture}
\end{codeexample}
- \itemoption{swap}
+\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.
@@ -763,8 +1445,9 @@ ways are described in the following.
edge [loop below] node {1} ();
\end{tikzpicture}
\end{codeexample}
+\end{key}
- \itemoption{sloped}
+\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
@@ -780,7 +1463,10 @@ ways are described in the following.
\draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$};
\end{tikzpicture}
\end{codeexample}
- \itemoption{allow upside down}\opt{|=|\meta{true or false}}
+\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]
@@ -793,13 +1479,12 @@ ways are described in the following.
\draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$};
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
There exist styles for specifying positions a bit less ``technically'':
-\begin{itemize}
- \itemstyle{midway}
- is set to |pos=0.5|.
+\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] {|at end|}
@@ -810,19 +1495,31 @@ There exist styles for specifying positions a bit less ``technically'':
node[very near start] {|very near start|}
node[at start] {|at start|};
\end{codeexample}
- \itemstyle{near start}
- is set to |pos=0.25|.
- \itemstyle{near end}
- is set to |pos=0.75|.
- \itemstyle{very near start}
- is set to |pos=0.125|.
- \itemstyle{very near end}
- is set to |pos=0.875|.
- \itemstyle{at start}
- is set to |pos=0|.
- \itemstyle{at end}
- is set to |pos=1|.
-\end{itemize}
+\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}
@@ -882,8 +1579,7 @@ 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.
-\begin{itemize}
- \itemoption{label}|=|\opt{|[|\meta{options}|]|}\meta{angle}|:|\meta{text}
+\begin{key}{/tikz/label=\opt{|[|\meta{options}|]|}\meta{angle}|:|\meta{text}}
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
@@ -926,21 +1622,23 @@ for simple nodes.
nodes are added in the order they are given.
The following styles influence how labels are drawn:
- \begin{itemize}
- \itemoption{label distance}|=|\meta{distance}
+ \begin{key}{/tikz/label distance=\meta{distance} (initially 0pt)}
The \meta{distance} is additionally inserted between the main node
- and the label node. The default is |0pt|.
+ 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}
- \itemstyle{every label}
+ \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{itemize}
- \itemoption{pin}|=|\opt{|[|\meta{options}|]|}\meta{angle}|:|\meta{text}
+ \end{stylekey}
+\end{key}
+
+\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,
it also adds an edge from this node to the main node. This causes
@@ -952,46 +1650,48 @@ for simple nodes.
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{itemize}
- \itemoption{pin distance}|=|\meta{distance}
+ \begin{key}{/tikz/pin distance=\meta{distance} (initially 3ex)}
This \meta{distance} is used instead of the |label distance| for
- the distance between the main node and the label node. The default
- is |3ex|.
+ 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}
- \itemstyle{every pin}
+ \end{key}
+ \begin{stylekey}{/tikz/every pin (initially \normalfont draw=none,fill=none)}
This style is used in every node created by the |pin|
- option. The default is |draw=none,fill=none|.
- \itemstyle{every pin edge}
- This style is used in every edge created by the |pin| optins. The
- default is |help lines|.
-\begin{codeexample}[]
-\tikzstyle{every pin edge}=[<-,shorten <=1pt,snake=snake,line before snake=4pt]
-\tikz[pin distance=15mm]
+ option.
+ \end{stylekey}
+ \begin{stylekey}{/tikz/every pin edge (initially help lines)}
+ This style is used in every edge created by the |pin| optins.
+\begin{codeexample}[]
+\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}
- \itemoption{pin edge}|=|\meta{options}
+ \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. The default is empty.
+ 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}[]
-\tikzstyle{every pin edge}=[]
-\tikzstyle{initial}=[pin={[pin distance=5mm,
- pin edge={<-,shorten <=1pt}]left:start}]
-\tikz \node [circle,draw,initial] {my circle};
+\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{itemize}
-\end{itemize}
+ \end{key}
+\end{key}
\subsection{Connecting Nodes: Using Nodes as Coordinates}
@@ -1138,15 +1838,14 @@ are encountered on the path.
Instead of |every to|, the style |every edge| is installed at the
beginning of the main path.
- \begin{itemize}
- \itemstyle{every edge} this is is |draw| by default.
+ \begin{stylekey}{/tikz/every edge (inititially draw)}
+ Executed for each |edge|.
\begin{codeexample}[]
-\begin{tikzpicture}
- \tikzstyle{every to}=[draw,dashed]
+\begin{tikzpicture}[every to/.style={draw,dashed}]
\path (0,0) to (3,2);
\end{tikzpicture}
\end{codeexample}
- \end{itemize}
+ \end{stylekey}
\end{pathoperation}
@@ -1171,20 +1870,18 @@ To reference nodes in different pictures, proceed as follows:
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
- (currently, this is only pdf\TeX). With the pdf\TeX\ driver you also
- need to run \TeX\ twice.
+\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{itemize}
- \itemoption{remember picture}\opt{|=|\meta{true or 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.
+\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 remebering works, you may consider saying
\begin{codeexample}[code only]
@@ -1194,7 +1891,9 @@ Let us have a look at the effect of these options.
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.
- \itemoption{overlay}
+\end{key}
+
+\begin{key}{/tikz/overlay}
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
@@ -1210,11 +1909,12 @@ Let us have a look at the effect of these options.
pictures. Unless you know what you are doing, I suggest specifying
the |overlay| option with all pictures that contain references to
other pictures.
-\end{itemize}
+\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
@@ -1296,151 +1996,27 @@ page).
-\subsection{Predefined Shapes}
-
-\label{section-nodes-predefined}
-
-\label{section-the-shapes}
-
-\pgfname\ 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 the library section for the complete list of shapes.
-
-The exact behaviour of these 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{itemize}
- \itemoption{inner sep}|=|\meta{dimension}
- 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.'' The default |inner sep| is the size of
- a normal space.
-
-\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=examplefill] {default};
-\end{tikzpicture}
-\end{codeexample}
- \itemoption{inner xsep}|=|\meta{dimension}
- Specifies the inner separation in the $x$-direction, only.
- \itemoption{inner ysep}|=|\meta{dimension}
- Specifies the inner separation in the $y$-direction, only.
-
- \itemoption{outer sep}|=|\meta{dimension}
- 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.''
-
- 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). 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.
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[line width=5pt]
- (0,0) node[outer sep=0pt,fill=examplefill] (f) {filled}
- (2,0) node[inner sep=.5\pgflinewidth+2pt,draw] (d) {drawn};
-
- \draw[->] (1,-1) -- (f);
- \draw[->] (1,-1) -- (d);
-\end{tikzpicture}
-\end{codeexample}
- \itemoption{outer xsep}|=|\meta{dimension}
- Specifies the outer separation in the $x$-direction, only.
- \itemoption{outer ysep}|=|\meta{dimension}
- Specifies the outer separation in the $y$-direction, only.
-
- \itemoption{minimum height}|=|\meta{dimension}
- 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}
-
- \itemoption{minimum width}|=|\meta{dimension}
- 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}
- \itemoption{minimum size}|=|\meta{dimension}
- 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}
-
- \itemoption{aspect}|=|\meta{aspect ratio}
- sets a desired aspect ratio for the shape. For the |diamond| shape,
- this option sets the ratio between width and height of the shape.
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) node[aspect=1,diamond,draw] {aspect 1};
- \draw (0,-2) node[aspect=2,diamond,draw] {aspect 2};
-\end{tikzpicture}
-\end{codeexample}
-\end{itemize}
+\subsection{Late Code and Options}
-\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}
- \tikzstyle{every node}=[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=examplefill] (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);
-\end{tikzpicture}
-\end{codeexample}
+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. The present section describes ways of achieving
+these effects.
-\subsection{Executing Code After Nodes}
+\subsubsection{Executing Code After Nodes}
\label{section-nodes-executing}
It is possible to add a path right after a node using the option
|after node path|. The idea is that a style might use this option to
-add some additional stuff to the node that has just been typeset.
+add some additional stuff to the node that has just been
+typeset. Examples of such styles include the |label| option and the
+|pin| option.
-\begin{itemize}
- \itemoption{after node path}|=|\meta{path}
+\begin{key}{/tikz/after node path=\meta{path}}
The \meta{path} is added to the main path right after the node, as
if you had given the path thereafter. This option can only be given
inside the option list of a node and multiple calls of this option
@@ -1457,7 +2033,7 @@ add some additional stuff to the node that has just been typeset.
Note that in the above example, if we had written |\path| instead of
|\draw|, the circle would not have been drawn since the circle is
part of the main path, not part of the node itself.
-\end{itemize}
+\end{key}
\begin{command}{\tikzaddafternodepathoption\marg{code}}
This command allows you to specify that the \meta{code} should be
@@ -1467,6 +2043,43 @@ add some additional stuff to the node that has just been typeset.
\end{command}
+\subsection{Late Options}
+
+A \emph{late option} for a node is an option that is given a long time
+after the node has already been constructed.
+
+\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
+ the |after node path| option inside the \meta{options} (directly or
+ indirectly) does have the desired effect: The after node 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.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node (a) [draw,circle] {Hello};
+ \path (a) [late options={label=above:world}];
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
%%% Local Variables:
%%% mode: latex