Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-matrices.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Matrix Library}
12
13 \begin{tikzlibrary}{matrix}
14 This library package defines additional styles and options for creating
15 matrices. The basic matrix styles and options can be found in
16 Section~\ref{section-matrices}.
17 \end{tikzlibrary}
18
19
20 \subsection{Matrices of Nodes}
21
22 A \emph{matrix of nodes} is a \tikzname\ matrix in which each cell contains a
23 node. In this case it is bothersome having to write |\node{| at the beginning
24 of each cell and |};| at the end of each cell. The following key simplifies
25 typesetting such matrices.
26
27 \begin{key}{/tikz/matrix of nodes}
28 Conceptually, this key adds |\node{| at the beginning and |};| at the end
29 of each cell and sets the |anchor| of the node to |base|. Furthermore, it
30 adds the option |name| option to each node, where the name is set to
31 \meta{matrix name}|-|\meta{row number}|-|\meta{column number}. For
32 example, if the matrix has the name |my matrix|, then the node in the
33 upper left cell will get the name |my matrix-1-1|.
34 %
35 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
36 \begin{tikzpicture}
37 \matrix (magic) [matrix of nodes]
38 {
39 8 & 1 & 6 \\
40 3 & 5 & 7 \\
41 4 & 9 & 2 \\
42 };
43
44 \draw[thick,red,->] (magic-1-1) |- (magic-2-3);
45 \end{tikzpicture}
46 \end{codeexample}
47
48 You may wish to add options to certain nodes in the matrix. This can be
49 achieved in three ways.
50 %
51 \begin{enumerate}
52 \item You can modify, say, the |row 2 column 3| style to pass special
53 options to this particular cell.
54 %
55 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
56 \begin{tikzpicture}[row 2 column 3/.style=red]
57 \matrix [matrix of nodes]
58 {
59 8 & 1 & 6 \\
60 3 & 5 & 7 \\
61 4 & 9 & 2 \\
62 };
63 \end{tikzpicture}
64 \end{codeexample}
65 %
66 \item At the beginning of a cell, you can use a special syntax. If a
67 cell starts with a vertical bar, then everything between this bar
68 and the next bar is passed on to the |node| command.
69 %
70 {\catcode`\|=12
71 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
72 \begin{tikzpicture}
73 \matrix [matrix of nodes]
74 {
75 8 & 1 & 6 \\
76 3 & 5 & |[red]| 7 \\
77 4 & 9 & 2 \\
78 };
79 \end{tikzpicture}
80 \end{codeexample}
81 }
82 %
83 You can also use an option like \verb!|[red] (seven)|! to give a
84 different name to the node.
85
86 Note that the |&| character also takes an optional argument, which
87 is an extra column skip.
88 %
89 {\catcode`\|=12
90 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
91 \begin{tikzpicture}
92 \matrix [matrix of nodes]
93 {
94 8 &[1cm] 1 &[3mm] |[red]| 6 \\
95 3 & 5 & |[red]| 7 \\
96 4 & 9 & 2 \\
97 };
98 \end{tikzpicture}
99 \end{codeexample}
100 }
101 \item If your cell starts with a |\path| command or any command that
102 expands to |\path|, which includes |\draw|, |\node|, |\fill| and
103 others, the |\node{| startup code and the |};| code are suppressed.
104 This means that for this particular cell you can provide totally
105 different contents.
106 %
107 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
108 \begin{tikzpicture}
109 \matrix [matrix of nodes]
110 {
111 8 & 1 & 6 \\
112 3 & 5 & \node[red]{7}; \draw(0,0) circle(10pt);\\
113 4 & 9 & 2 \\
114 };
115 \end{tikzpicture}
116 \end{codeexample}
117 \end{enumerate}
118 \end{key}
119
120 \begin{key}{/tikz/matrix of math nodes}
121 This style is almost the same as the previous style, only |$| is added %$
122 at the beginning and at the end of each node, so math mode will be switched
123 on in all nodes.
124 %
125 {\catcode`\|=12
126 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
127 \begin{tikzpicture}
128 \matrix [matrix of math nodes]
129 {
130 a_8 & a_1 & a_6 \\
131 a_3 & a_5 & |[red]| a_7 \\
132 a_4 & a_9 & a_2 \\
133 };
134 \end{tikzpicture}
135 \end{codeexample}
136 }
137 \end{key}
138
139 \begin{key}{/tikz/nodes in empty cells=\meta{true or false} (default true)}
140 When set to |true|, a node (with empty contents) is put in empty cells.
141 Normally, empty cells are just, well, empty. The style can be used together
142 with both a |matrix of nodes| and a |matrix of math nodes|.
143 %
144 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
145 \begin{tikzpicture}
146 \matrix [matrix of math nodes,nodes={circle,draw}]
147 {
148 a_8 & & a_6 \\
149 a_3 & & a_7 \\
150 a_4 & a_9 & \\
151 };
152 \end{tikzpicture}
153 \end{codeexample}
154 %
155 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
156 \begin{tikzpicture}
157 \matrix [matrix of math nodes,nodes={circle,draw},nodes in empty cells]
158 {
159 a_8 & & a_6 \\
160 a_3 & & a_7 \\
161 a_4 & a_9 & \\
162 };
163 \end{tikzpicture}
164 \end{codeexample}
165 %
166 \end{key}
167
168
169 \subsection{End-of-Lines and End-of-Row Characters in Matrices of Nodes}
170
171 Special care must be taken about the usage of the |\\| command inside a matrix
172 of nodes. The reason is that this character is overloaded in \TeX: On the one
173 hand, it is used to denote the end of a line in normal text; on the other hand
174 it is used to denote the end of a row in a matrix. Now, if a matrix contains
175 node which in turn may have multiple lines, it is unclear which meaning of |\\|
176 should be used.
177
178 This problem arises only when you use the |text width| option of nodes. Suppose
179 you write a line like
180 %
181 \begin{codeexample}[code only]
182 \matrix [text width=5cm,matrix of nodes]
183 {
184 first row & upper line \\ lower line \\
185 second row & hmm \\
186 };
187 \end{codeexample}
188 %
189 This leaves \TeX\ trying to riddle out how many rows this matrix should have.
190 Do you want two rows with the upper right cell containing a two-line text. Or
191 did you mean a three row matrix with the second row having only one cell?
192
193 Since \TeX\ is not clairvoyant, the following rules are used:
194 %
195 \begin{enumerate}
196 \item Inside a matrix, the |\\| command, by default, signals the end of the
197 row, not the end of a line in a cell.
198 \item However, there is an exception to this rule: If a cell starts with a
199 \TeX-group (this is, with |{|), then inside this first group the |\\|
200 command retains the meaning of ``end of line'' character. Note that
201 this special rule works only for the first group in a cell and this
202 group must be at the beginning.
203 \end{enumerate}
204
205 The net effect of these rules is the following: Normally, |\\| is an end-of-row
206 indicator; if you want to use it as an end-of-line indicator in a cell, just
207 put the whole cell in curly braces. The following example illustrates the
208 difference:
209 %
210 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
211 \begin{tikzpicture}
212 \matrix [matrix of nodes,nodes={text width=16mm,draw}]
213 {
214 row 1 & upper line \\ lower line \\
215 row 2 & hmm \\
216 };
217 \end{tikzpicture}
218 \end{codeexample}
219 %
220 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
221 \begin{tikzpicture}
222 \matrix [matrix of nodes,nodes={text width=16mm,draw}]
223 {
224 row 1 & {upper line \\ lower line} \\
225 row 2 & hmm \\
226 };
227 \end{tikzpicture}
228 \end{codeexample}
229
230 Note that this system is not fool-proof. If you write things like |a&b{c\\d}\\|
231 in a matrix of nodes, an error will result (because the second cell did not
232 start with a brace, so |\\| retained its normal meaning and, thus, the second
233 cell contained the text |b{c|, which is not balanced with respect to the number
234 of braces).
235
236
237 \subsection{Delimiters}
238
239 Delimiters are parentheses or braces to the left and right of a formula or a
240 matrix. The |matrix| library offers options for adding such delimiters to a
241 matrix. However, delimiters can actually be added to any node that has the
242 standard anchors |north|, |south|, |north west| and so on. In particular, you
243 can add delimiters to any |rectangle| box. They are implemented by ``measuring
244 the height'' of the node and then adding a delimiter of the correct size to the
245 left or right using some after node magic.
246
247 \begin{key}{/tikz/left delimiter=\meta{delimiter}}
248 This option can be given to a any node that has the standard anchors
249 |north|, |south| and so on. The \meta{delimiter} can be any delimiter that
250 is acceptable to \TeX's |\left| command.
251 %
252 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
253 \begin{tikzpicture}
254 \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
255 {
256 a_8 & a_1 & a_6 \\
257 a_3 & a_5 & a_7 \\
258 a_4 & a_9 & a_2 \\
259 };
260 \end{tikzpicture}
261 \end{codeexample}
262
263 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
264 \begin{tikzpicture}
265 \node [fill=red!20,left delimiter=(,right delimiter=\}]
266 {$\displaystyle\int_0^1 x\,dx$};
267 \end{tikzpicture}
268 \end{codeexample}
269
270 \begin{stylekey}{/tikz/every delimiter (initially \normalfont empty)}
271 This style is executed for every delimiter. You can use it to shift or
272 color delimiters or do whatever.
273 \end{stylekey}
274
275 \begin{stylekey}{/tikz/every left delimiter (initially \normalfont empty)}
276 This style is additionally executed for every left delimiter.
277 %
278 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
279 \begin{tikzpicture}
280 [every left delimiter/.style={red,xshift=1ex},
281 every right delimiter/.style={xshift=-1ex}]
282 \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
283 {
284 a_8 & a_1 & a_6 \\
285 a_3 & a_5 & a_7 \\
286 a_4 & a_9 & a_2 \\
287 };
288 \end{tikzpicture}
289 \end{codeexample}
290 \end{stylekey}
291 \end{key}
292
293 \begin{key}{/tikz/right delimiter=\meta{delimiter}}
294 Works as above.
295 %
296 \begin{stylekey}{/tikz/every right delimiter (initially \normalfont empty)}
297 Works as above.
298 \end{stylekey}
299 \end{key}
300
301 \begin{key}{/tikz/above delimiter=\meta{delimiter}}
302 This option allows you to add a delimiter above the node. It is implemented
303 by rotating a left delimiter.
304 %
305 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
306 \begin{tikzpicture}
307 \matrix [matrix of math nodes,%
308 left delimiter=\|,right delimiter=\rmoustache,%
309 above delimiter=(,below delimiter=\}]
310 {
311 a_8 & a_1 & a_6 \\
312 a_3 & a_5 & a_7 \\
313 a_4 & a_9 & a_2 \\
314 };
315 \end{tikzpicture}
316 \end{codeexample}
317
318 \begin{stylekey}{/tikz/every above delimiter (initially \normalfont empty)}
319 Works as above.
320 \end{stylekey}
321 \end{key}
322
323 \begin{key}{/tikz/below delimiter=\meta{delimiter}}
324 Works as above.
325 \begin{stylekey}{/tikz/every below delimiter (initially \normalfont empty)}
326 Works as above.
327 \end{stylekey}
328 \end{key}
329
330
331 %%% Local Variables:
332 %%% mode: latex
333 %%% TeX-master: "pgfmanual-pdftex-version"
334 %%% End: