summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex134
1 files changed, 103 insertions, 31 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex
index 4bb3de3da93..57cf67f4abb 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex
@@ -21,11 +21,10 @@
A \emph{matrix of nodes} is a \tikzname\ matrix in which each cell
contains a node. In this case it is bothersome having to write
|\node{| at the beginning of each cell and |};| at the end of each
-cell. The following style simplifies typesetting such matrices.
+cell. The following key simplifies typesetting such matrices.
-\begin{itemize}
- \itemstyle{matrix of nodes}
- Conceptually, this style adds |\node{| at the beginning and |};| at
+\begin{key}{/tikz/matrix of nodes}
+ Conceptually, this key adds |\node{| at the beginning and |};| at
the end of each cell and sets the |anchor| of the node to
|base|. Furthermore, it adds the option |name| option to each node,
where the name is set to \meta{matrix name}|-|\meta{row
@@ -49,12 +48,11 @@ cell. The following style simplifies typesetting such matrices.
be achieved in three ways.
\begin{enumerate}
\item You can modify, say, the
- |row 2 column 5| option to pass special options to this particular
+ |row 2 column 5| style to pass special options to this particular
cell.
\begin{codeexample}[]
-\begin{tikzpicture}
- \tikzstyle{row 2 column 3}=[red]
+\begin{tikzpicture}[row 2 column 3/.style=red]
\matrix [matrix of nodes]
{
8 & 1 & 6 \\
@@ -98,7 +96,7 @@ cell. The following style simplifies typesetting such matrices.
}
\item If your cell starts with a |\path| command or any command that
expands to |\path|, which includes |\draw|, |\node|, |\fill| and
- other, the |\node{| startup code and the |};| code are
+ others, the |\node{| startup code and the |};| code are
suppressed. This means that for this particular cell you can
provide a totally different contents.
@@ -113,7 +111,9 @@ cell. The following style simplifies typesetting such matrices.
\end{tikzpicture}
\end{codeexample}
\end{enumerate}
- \itemstyle{matrix of math nodes}
+\end{key}
+
+\begin{key}{/tikz/matrix of math nodes}
This style is almost the same as the previous style, only |$| is %$
added at the beginning and at the end of each node, so math mode
will be switched on in all nodes.
@@ -129,7 +129,9 @@ cell. The following style simplifies typesetting such matrices.
\end{tikzpicture}
\end{codeexample}
}
- \itemoption{nodes in empty cells}\opt{|=|\meta{true or false}}
+\end{key}
+
+\begin{key}{/tikz/nodes in empty cells=\meta{true or false} (default true)}
When set to |true|, a node (with an empty contents) is put in empty
cells. Normally, empty cells are just, well, empty. The style can be
used together with both a |matrix of nodes| and a
@@ -154,8 +156,72 @@ cell. The following style simplifies typesetting such matrices.
};
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+\end{key}
+
+\subsection{End-of-Lines and End-of-Row Characters in Matrices of Nodes}
+
+Special care must be taken about the usage of the |\\| command inside
+a matrix of nodes. The reason is that this character is overloaded in
+\TeX: On the one hand, it is used to denote the end of a line in
+normal text; on the other hand it is used to denote the end of a row
+in a matrix. Now, if a matrix contains node which in turn may have
+multiple lines, it is unclear which meaning of |\\| should be used.
+
+This problem arises only when you use the |text width| option of
+nodes. Suppose you write a line like
+\begin{codeexample}[code only]
+\matrix [text width=5cm,matrix of nodes]
+{
+ first row & upper line \\ lower line \\
+ second row & hmm \\
+};
+\end{codeexample}
+This leaves \TeX\ trying to riddle out how many rows this matrix
+should have. Do you want two rows with the upper right cell containing
+a two-line text. Or did you mean a three row matrix with the second
+row having only one cell?
+
+Since \TeX\ is not clairvoyant, the following rules are used:
+\begin{enumerate}
+\item Inside a matrix, the |\\| command, by default, signals the end
+ of the row, not the end of a line in a cell.
+\item However, there is an exception to this rule: If a cell
+ starts with a \TeX-group (this is, with |{|), % }
+ then inside this first group the |\\| command retains the meaning of
+ ``end of line'' character. Note that this special rule works only
+ for the first group in a cell and this group must be at the
+ beginning.
+\end{enumerate}
+
+The net effect of these rules is the following: Normally, |\\| is an
+end-of-row indicator; if you want to use it as an end-of-line
+indicator in a cell, just put the whole cell in curly braces. The
+following example illustrates the difference:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of nodes,nodes={text width=16mm,draw}]
+ {
+ row 1 & upper line \\ lower line \\
+ row 2 & hmm \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of nodes,nodes={text width=16mm,draw}]
+ {
+ row 1 & {upper line \\ lower line} \\
+ row 2 & hmm \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+Note that this system is not fool-proof. If you write things like
+|a&b{c\\d}\\| in a matrix of nodes, an error will result (because the
+second cell did not start with a brace, so |\\| retained its normal
+meaning and, thus, the second cell contained the text |b{c|, which is
+not balanced with respect to the number of braces).
\subsection{Delimiters}
@@ -168,8 +234,7 @@ box. They are implemented by ``measuring the height'' of the node and
then adding a delimiter of the correct size to the left or right using
some after node magic.
-\begin{itemize}
- \itemoption{left delimiter}|=|\meta{delimiter}
+\begin{key}{/tikz/left delimiter=\meta{delimiter}}
This option can be given to a any node that has the standard anchors
|north|, |south| and so on. The \meta{delimiter} can be any
delimiter that is acceptable to \TeX's |\left| command.
@@ -191,16 +256,17 @@ some after node magic.
\end{tikzpicture}
\end{codeexample}
- \itemstyle{every delimiter}
- This style is executed for every delimiter. You can use it to shift
- or color delimiters or do whatever.
+ \begin{stylekey}{/tikz/every delimiter (initially \normalfont empyt)}
+ This style is executed for every delimiter. You can use it to shift
+ or color delimiters or do whatever.
+ \end{stylekey}
- \itemstyle{every left delimiter}
- This style is additionally executed for every left delimiter.
+ \begin{stylekey}{/tikz/every left delimiter (initially \normalfont empty)}
+ This style is additionally executed for every left delimiter.
\begin{codeexample}[]
\begin{tikzpicture}
- \tikzstyle{every left delimiter}=[red,xshift=1ex]
- \tikzstyle{every right delimiter}=[xshift=-1ex]
+ [every left delimiter/.style={red,xshift=1ex},
+ every right delimiter/.style={xshift=-1ex}]
\matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
{
a_8 & a_1 & a_6 \\
@@ -209,14 +275,18 @@ some after node magic.
};
\end{tikzpicture}
\end{codeexample}
+ \end{stylekey}
+\end{key}
- \itemoption{right delimiter}|=|\meta{delimiter}
+\begin{key}{/tikz/right delimiter=\meta{delimiter}}
Works as above.
+ \begin{stylekey}{/tikz/every right delimiter (initially \normalfont empty)}
+ Works as above.
+ \end{stylekey}
+\end{key}
- \itemstyle{every right delimiter}
- Works as above.
- \itemoption{above delimiter}|=|\meta{delimiter}
+\begin{key}{/tikz/above delimiter=\meta{delimiter}}
This option allows you to add a delimiter above the node. It is
implementing by rotating a left delimiter.
\begin{codeexample}[]
@@ -232,15 +302,17 @@ some after node magic.
\end{tikzpicture}
\end{codeexample}
- \itemstyle{every above delimiter}
- Works as above.
-
- \itemoption{below delimiter}|=|\meta{delimiter}
- works as above.
+ \begin{stylekey}{/tikz/every above delimiter (initially \normalfont empty)}
+ Works as above.
+ \end{stylekey}
+\end{key}
- \itemstyle{every below delimiter}
+\begin{key}{/tikz/below delimiter=\meta{delimiter}}
Works as above.
-\end{itemize}
+ \begin{stylekey}{/tikz/every below delimiter (initially \normalfont empty)}
+ Works as above.
+ \end{stylekey}
+\end{key}