diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex | 832 |
1 files changed, 832 insertions, 0 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 new file mode 100644 index 00000000000..e118bf98449 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex @@ -0,0 +1,832 @@ +% Copyright 2005 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Nodes} + +\label{section-nodes} + +\subsection{Nodes and Their Shapes} + +\tikzname\ offers an easy way of adding so-called \emph{nodes} to your +pictures. In the simplest case, a node is just some text that is +placed at some coordinate. However, a node can also have a border +drawn around it or have a more complex background and +foreground. Indeed, some nodes do not have a text at all, but consist +solely of the background. You can name nodes so that you can reference +their coordinates later in the picture. However, \emph{nodes cannot be + referenced across different pictures}. + +There are no special \TeX\ commands for adding a node to a picture; rather, +there is path operation called |node| for this. Nodes are created +whenever \tikzname\ encounters |node| or |coordinate| at a point on a +path where it would expect a normal path operation (like |-- (1,1)| or +|sin (1,1)|). It is also possible to give node specifications +\emph{inside} certain path operations as explained later. + +The node operation is typically followed by some options, which apply +only to the node. Then, you can optionally \emph{name} the node by +providing a name in 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. + +\begin{codeexample}[] +\tikz \fill[fill=examplefill] + (0,0) node {first node} + -- (1,1) node {second node} + -- (0,2) node {third node}; +\end{codeexample} + +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). + + The |(|\meta{name}|)| is a name for later reference and it is + optional. You may also add the option |name=|\meta{name} to the + \meta{option} list; it has the same effect. + + \begin{itemize} + \itemoption{name}|=|\meta{node name} + assigns a name to the node for later reference. Since this is a + ``high-level'' name (drivers never know of it), you can use spaces, + number, letters, or whatever you like when naming a node. Thus, you + can name a node just |1| or perhaps |start of chart| or even + |y_1|. Your node name should \emph{not} contain any punctuation like + a dot, a comma, or a colon since these are used to detect what kind + of coordinate you mean when you reference a node. + \end{itemize} + + The \meta{options} is an optional list of options that \emph{apply + only to the node} and have no effect outside. The other way round, + most ``outside'' options also apply to the node, but not all. For + example, the ``outside'' rotation does not apply to nodes (unless some + special options are used, sigh). Also, the outside path action, like + |draw| or |fill|, never applies to the node and must be given in the + node (unless some special other options are used, deep sigh). + + As mentioned before, we can add a border and even a background to a + node: +\begin{codeexample}[] +\tikz \fill[fill=examplefill] + (0,0) node {first node} + -- (1,1) node[draw] {second node} + -- (0,2) node[fill=red!20,draw,double,rounded corners] {third node}; +\end{codeexample} + + The ``border'' is actually just a special case of a much more general + mechanism. Each node has a certain \emph{shape} which, by default, is + a rectangle. However, we can also ask \tikzname\ to use a circle shape + instead or an ellipse shape (you have to include |pgflibraryshapes| 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}; +\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 state of a + finite automaton 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. + + 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 + not given inside a node but somewhere outside, the shape of all + nodes in the current scope.% + \indexoption{\meta{shape name}} + + Since this option is used often, you can leave out the + |shape=|. When \tikzname\ encounters an option like |circle| + that it does not know, it will, after everything else has failed, + check whether this option is the name of some shape. If so, that + shape is selected as if you had said |shape=|\meta{shape name}. + + By default, the following shapes are available: |rectangle|, + |circle|, |coordinate|, 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} + + The following styles influences how nodes are rendered: + \begin{itemize} + \itemstyle{every node} + This style is installed at the beginning of every node. +\begin{codeexample}[] +\begin{tikzpicture} + \tikzstyle{every node}=[draw] + \draw (0,0) node {A} -- (1,1) node {B}; +\end{tikzpicture} +\end{codeexample} + + \itemstyle{every \meta{shape} node} + 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] + \draw (0,0) node[rectangle] {A} -- (1,1) node[circle] {B}; +\end{tikzpicture} +\end{codeexample} + \end{itemize} +\end{pathoperation} + +The is a special syntax for specifying ``light-weighed'' 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}|){}|, + + where the |at| part might be missing. +\end{pathoperation} + + + +\subsection{Multi-Part Nodes} + +Most nodes just have a single simple text label. However, nodes of a +more complicated shapes 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 +to be drawn at the different positions, and so on. + +Both \pgfname\ and \tikzname\ support such multipart nodes. On the +lower level, \pgfname\ provides a system for specifying that a shape +consists of several parts. On the \tikzname\ level, you specify the +different node parts by using the following command: + +\begin{command}{\nodepart\marg{part name}} + This command can only be used inside the \meta{text} argument of a + |node| path operation. It works a little bit like a |\part| command + in \LaTeX. It will stop the typesetting of whatever node part was + typeset until now and then start putting all following text into the + node part named \meta{part name}---until another |\partname| is + encountered or until the node \meta{text} ends. + +\begin{codeexample}[] +\begin{tikzpicture} + \node [state with output,draw,double,fill=red!20] + { + % No \nodepart has been used, yet. So, the following is put in the + % ``text'' node part by default. + $q_1$ + \nodepart{output} % Ok, end ``text'' part, start ``output'' part + $00$ + }; % output part ended. +\end{tikzpicture} +\end{codeexample} + + You will have to lookup which parts are defined by a shape. + + The following styles influences node parts: + \begin{itemize} + \itemstyle{every \meta{part name} node part} + This style is installed at the beginning of every node part named + \meta{part name}. +\begin{codeexample}[] +\tikzstyle{every output node part}=[red] +\tikz \node [state with output,draw] {$q_1$ \nodepart{output} $00$}; +\end{codeexample} + \end{itemize} +\end{command} + + + +\subsection{Options for the Text in Nodes} + +The simplest option for the text in nodes is its color. Normally, this +color is just the last color installed using |color=|, possibly +inherited from another scope. However, it is possible to specificly +set the color used for text using the following option: + +\begin{itemize} + \itemoption{text}|=|\meta{color} + Sets the color to be used for text labels. A |color=| option + will immediately override this option. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[red] (0,0) -- +(1,1) node[above] {red}; + \draw[text=red] (1,0) -- +(1,1) node[above] {red}; + \draw (2,0) -- +(1,1) node[above,red] {red}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +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} + Sets the font used for text labels. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[font=\itshape] (1,0) -- +(1,1) node[above] {italic}; +\end{tikzpicture} +\end{codeexample} + A perhaps more useful example is the following: + +\begin{codeexample}[] +\tikzstyle{every text node part}=[font=\itshape] +\tikzstyle{every output node part}=[font=\footnotesize] +\tikzstyle{every state with output node}=[draw] +\tikz \node [state with output] {state \nodepart{output} output}; +\end{codeexample} +\end{itemize} + + +Normally, when a node is typeset, all the text you give in the braces +is but in one long line (in an |\hbox|, to be precise) and the node +will become as wide as necessary. + +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} + 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). + + If the node text is not as wide as \meta{dimension}, it will + nevertheless be put in a box of this width. If it is larger, line + breaking will be done. + + By default, when this option is given, a ragged right border will be + used. This is sensible since, typically, these boxes are narrow and + justifying the text looks ugly. +\begin{codeexample}[] +\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 + only with pretty broad nodes. +{% +\hbadness=10000 +\begin{codeexample}[] +\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text justified] + {This is a demonstration text for showing how line breaking works.}; +\end{codeexample} +} + In the above example, \TeX\ complains (rightfully) about three very + badly typeset lines. (For this manual I asked \TeX\ to stop + complaining by using |\hbadness=10000|, but this is a foul deed, + indeed.) + \itemoption{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. +\begin{codeexample}[] +\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 + 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. +\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. +\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} + + + +\subsection{Placing Nodes Using Anchors} + +When you place a node at some coordinate, the node is centered on this +coordinate by default. This is often undesirable and it would be +better to have the node to the right or above the actual coordinate. + +\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 +positions in the shape. For example to upper right corner is called, +well, not ``upper right anchor,'' but the |north east| anchor of the +shape. The center of the shape has an anchor called |center| on top of +it, and so on. Here are some examples (a complete list is given in +Section~\ref{section-the-shapes}). + +\medskip\noindent +\begin{tikzpicture} + \path node[minimum height=2cm,minimum width=5cm,fill=blue!25](x) {Big node}; + \fill (x.north) circle (2pt) node[above] {|north|} + (x.north east) circle (2pt) node[above] {|north east|} + (x.north west) circle (2pt) node[above] {|north west|} + (x.west) circle (2pt) node[left] {|west|} + (x.east) circle (2pt) node[right] {|east|} + (x.base) circle (2pt) node[below] {|base|}; +\end{tikzpicture} + +Now, when you place a node at a certain coordinate, you can ask \tikzname\ +to place the node shifted around in such a way that a certain +anchor is at the coordinate. In the following example, we ask \tikzname\ +to shift the first node such that its |north east| anchor is at +coordinate |(0,0)| and that the |west| anchor of the second node is at +coordinate |(1,1)|. + +\begin{codeexample}[] +\tikz \draw (0,0) node[anchor=north east] {first node} + rectangle (1,1) node[anchor=west] {second node}; +\end{codeexample} + +Since the default anchor is |center|, the default 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 + name} lies on the current coordinate. + + The only anchor that is present in all shapes is |center|. However, + most shapes will at least define anchors in all ``compass + directions.'' Furthermore, the standard shapes also define a |base| + anchor, as well as |base west| and |base east|, for placing things on + the baseline of the text. + + The standard shapes also define a |mid| anchor (and |mid west| and + |mid east|). This anchor is half the height of the character ``x'' + above the base line. This anchor is useful for vertically centering + multiple nodes that have different heights and depth. Here is an + example: +\begin{codeexample}[] +\begin{tikzpicture}[scale=3,transform shape] + % First, center alignment -> wobbles + \draw[anchor=center] (0,1) node{x} -- (0.5,1) node{y} -- (1,1) node{t}; + % Second, base alignment -> no wobble, but too high + \draw[anchor=base] (0,.5) node{x} -- (0.5,.5) node{y} -- (1,.5) node{t}; + % Third, mid alignment + \draw[anchor=mid] (0,0) node{x} -- (0.5,0) node{y} -- (1,0) node{t}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +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, + the node is additionally shifted upwards by the given + \meta{offset}. +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above] {above}; +\end{codeexample} +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above=2pt] {above}; +\end{codeexample} + \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}. +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above left] {above left}; +\end{codeexample} +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above left=2pt] {above left}; +\end{codeexample} + \itemoption{above right}\opt{|=|\meta{offset}} + does the same as |anchor=south west|. +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above right] {above right}; +\end{codeexample} + \itemoption{left}\opt{|=|\meta{offset}} + does the same as |anchor=east|. +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[left] {left}; +\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} + + +\subsection{Transformations} + +It is possible to transform nodes, but, by default, transformations do +not apply to nodes. The reason is that you usually do \emph{not} want +your text to be scaled or rotated even if the main graphic is +transformed. Scaling text is evil, rotating slightly less so. + +However, sometimes you \emph{do} wish to transform a node, for +example, it certainly sometimes makes sense to rotate a node by +90 degrees. There are two ways in which you can achieve this: + +\begin{enumerate} +\item + You can use the following option: + \begin{itemize} + \itemoption{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} +\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); + \draw (1,0) node{A} + (2,0) node[rotate=90,scale=1.5] {B}; + \draw[rotate=30] (1,0) node{A} + (2,0) node[rotate=90,scale=1.5] {B}; + \draw[rotate=60] (1,0) node[transform shape] {A} + (2,0) node[transform shape,rotate=90,scale=1.5] {B}; +\end{tikzpicture} +\end{codeexample} +\end{enumerate} + + + +\subsection{Placing Nodes on a Line or Curve} + +Until now, we always placed node on a coordinate that is mentioned in +the path. Often, however, we wish to place nodes on ``the middle'' of +a line and we do not wish to compute these coordinates ``by hand.'' +To facilitate such placements, \tikzname\ allows you to specify that a +certain node should be somewhere ``on'' a line. There are two ways of +specifying this: Either explicitly by using the |pos| option or +implicitly by placing the node ``inside'' a path operation. These two +ways are described in the following. + + + +\subsubsection{Explicit Use of the Position Option} + +\label{section-pos-option} + +\begin{itemize} + \itemoption{pos}|=|\meta{fraction} + When this option is given, the node is not anchored on the last + coordinate. Rather, it is anchored on some point on the line from + the previous coordinate to the current point. The \meta{fraction} + dictates how ``far'' on the line the point should be. A + \meta{fraction} or 0 is the previous coordinate, 1 is the current + one, everything else is in between. In particular, 0.5 is the + middle. + + Now, what is ``the previous line''? This depends on the previous + path construction operation. + + In the simplest case, the previous path operation was a ``line-to'' + operation, that is, a |--|\meta{coordinate} operation: +\begin{codeexample}[] +\tikz \draw (0,0) -- (3,1) + node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; +\end{codeexample} + + The next case is the curve-to operation (the |..| operation). In this + case, the ``middle'' of the curve, that is, the position |0.5| is + not necessarily the point at the exact half distance on the + line. Rather, it is some point at ``time'' 0.5 of a point traveling + from the start of the curve, where it is at time 0, to the end of + the curve, which it reaches at time 0.5. The ``speed'' of the point + depends on the length of the support vectors (the vectors that + connect the start and end points to the control points). The exact + math is a bit complicated (depending on your point of view, of + course); you may wish to consult a good book on computer graphics + and Bézier curves if you are intrigued. +\begin{codeexample}[] + \tikz \draw (0,0) .. controls +(right:3.5cm) and +(right:3.5cm) .. (0,3) + \foreach \p in {0,0.125,...,1} {node[pos=\p]{\p}}; +\end{codeexample} + + Another interesting case are the horizontal/vertical line-to operations + \verb!|-! and \verb!-|!. For them, the position (or time) |0.5| is + exactly the corner point. + +\begin{codeexample}[] +\tikz \draw (0,0) |- (3,1) + node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; +\end{codeexample} + +\begin{codeexample}[] +\tikz \draw (0,0) -| (3,1) + node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; +\end{codeexample} + + For all other path construction operations, \emph{the position + placement does not work}, currently. This will hopefully change in + the future (especially for the arc operation). + \itemoption{sloped} + This option causes the node to be rotated such that a horizontal + line becomes a tangent to the curve. The rotation will always be + done in such a way that text is never ``upside down.'' If you really + need upside down text, use |[rotate=180]|. +\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}}; +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture}[->] + \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$}; + \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + +There exist styles for specifying positions a bit less ``technically'': +\begin{itemize} + \itemstyle{midway} + is set to |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|}; +\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} + + +\subsubsection{Implicit Use of the Position Option} + +When you wish to place a node on the line |(0,0) -- (1,1)|, +it is natural to specify the node not following the |(1,1)|, but +``somewhere in the middle.'' This is, indeed, possible and you can +write |(0,0) -- node{a} (1,1)| to place a node midway between |(0,0)| and +|(1,1)|. + +What happens is the following: The syntax of the line-to path +operation is actually |--| +\opt{|node|\meta{node specification}}\meta{coordinate}. (It is even +possible to give multiple nodes in this way.) When the optional +|node| is encountered, that is, +when the |--| is directly followed by |node|, then the +specification(s) are read and ``stored away.'' Then, after the +\meta{coordinate} has finally been reached, they are inserted again, +but with the |pos| option set. + +There are two things to note about this: When a node specification is +``stored,'' its catcodes become fixed. This means that you cannot use +overly complicated verbatim text in them. If you really need, say, a +verbatim text, you will have to put it in a normal node following the +coordinate and add the |pos| option. + +Second, which |pos| is chosen for the node? The position is inherited +from the surrounding scope. However, this holds only for nodes +specified in this implicit way. Thus, if you add the option +|[near end]| to a scope, this does not mean that \emph{all} nodes given +in this scope will be put on near the end of lines. Only the nodes +for which an implicit |pos| is added will be placed near the +end. Typically, this is what you want. Here are some examples that +should make this clearer: + +\begin{codeexample}[] +\begin{tikzpicture}[near end] + \draw (0cm,4em) -- (3cm,4em) node{A}; + \draw (0cm,3em) -- node{B} (3cm,3em); + \draw (0cm,2em) -- node[midway] {C} (3cm,2em); + \draw (0cm,1em) -- (3cm,1em) node[midway] {D} ; +\end{tikzpicture} +\end{codeexample} + +Like the line-to operation, the curve-to operation |..| also allows you to +specify nodes ``inside'' the operation. After both the first |..| and +also after the second |..| you can place node specifications. Like for +the |--| operation, these will be collected and then reinserted after +the operation with the |pos| option set. + + +\subsection{Connecting Nodes} + +Once you have defined a node and given it a name, you can use this +name to reference it. This can be done in two ways, see also +Section~\ref{section-node-coordinates}. Suppose you have said +|\path(0,0) node(x) {Hello World!};| in order to define a node named |x|. +\begin{enumerate} +\item + Once the node |x| has been defined, you can use + |(x.|\meta{anchor}|)| wherever you would normally use a normal + coordinate. This will yield the position at which the given + \meta{anchor} is in the picture. Note that transformations do not + apply to this coordinate, that is, |(x.north)| will be the northern + anchor of |x| even if you have said |scale=3| or |xshift=4cm|. This + is usually what you would expect. +\item + You can also just use |(x)| as a coordinate. In most cases, this + gives the same coordinate as |(x.center)|. Indeed, if the |shape| of + |x| is |coordinate|, then |(x)| and |(x.center)| have exactly the + same effect. + + However, for most other shapes, some path construction operations like + |--| try to be ``clever'' when this they are asked to draw a line + from such a coordinate or to such a coordinate. When you say + |(x)--(1,1)|, the |--| path operation will not draw a line from the center + of |x|, but \emph{from the border} of |x| in the direction going + towards |(1,1)|. Likewise, |(1,1)--(x)| will also have the line + end on the border in the direction coming from |(1,1)|. + + In addition to |--|, the curve-to path operation |..| and the path + operations \verb!-|! and \verb!|-! will also handle nodes without + anchors correctly. Here is an example, see also + Section~\ref{section-node-coordinates}: +\begin{codeexample}[] +\begin{tikzpicture} + \path (0,0) node (x) {Hello World!} + (3,1) node[circle,draw](y) {$\int_1^2 x \mathrm d x$}; + + \draw[->,blue] (x) -- (y); + \draw[->,red] (x) -| node[near start,below] {label} (y); + \draw[->,orange] (x) .. controls +(up:1cm) and +(left:1cm) .. node[above,sloped] {label} (y); +\end{tikzpicture} +\end{codeexample} +\end{enumerate} + + + + + +\subsection{Predefined Shapes} +\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. Currently, +the package |pgflibraryshapes| defines +\begin{itemize} +\item + |ellipse|. +\end{itemize} + +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} +\end{itemize} + +\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} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |