Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-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{Matrices and Alignment}
12 \label{section-matrices}
13
14 \subsection{Overview}
15
16 When creating pictures, one often faces the problem of correctly aligning parts
17 of the picture. For example, you might wish that the |baseline|s of certain
18 nodes should be on the same line and some further nodes should be below these
19 nodes with, say, their centers on a vertical lines. There are different ways of
20 solving such problems. For example, by making clever use of anchors, nearly all
21 such alignment problems can be solved. However, this often leads to complicated
22 code. An often simpler way is to use \emph{matrices}, the use of which is
23 explained in the current section.
24
25 A \tikzname\ matrix is similar to \LaTeX's |{tabular}| or |{array}|
26 environment, only instead of text each cell contains a little picture or a
27 node. The sizes of the cells are automatically adjusted such that they are
28 large enough to contain all the cell contents.
29
30 Matrices are a powerful tool and they need to be handled with some care. For
31 impatient readers who skip the rest of this section: you \emph{must} end
32 \emph{every} row with |\\|. In particular, the last row \emph{must} be ended
33 with |\\|.
34
35 Many of the ideas implemented in \tikzname's matrix support are due to Mark
36 Wibrow -- many thanks to Mark at this point!
37
38
39 \subsection{Matrices are Nodes}
40
41 Matrices are special in many ways, but for most purposes matrices are treated
42 like nodes. This means, that you use the |node| path command to create a matrix
43 and you only use a special option, namely the |matrix| option, to signal that
44 the node will contain a matrix. Instead of the usual \TeX-box that makes up the
45 |text| part of the node's shape, the matrix is used. Thus, in particular, a
46 matrix can have a shape, this shape can be drawn or filled, it can be used in a
47 tree, and so on. Also, you can refer to the different anchors of a matrix.
48
49 \begin{key}{/tikz/matrix=\meta{true or false} (default true)}
50 This option can be passed to a |node| path command. It signals that the
51 node will contain a matrix.
52 %
53 \begin{codeexample}[]
54 \begin{tikzpicture}
55 \draw[help lines] (0,0) grid (4,2);
56 \node [matrix,fill=red!20,draw=blue,very thick] (my matrix) at (2,1)
57 {
58 \draw (0,0) circle (4mm); & \node[rotate=10] {Hello}; \\
59 \draw (0.2,0) circle (2mm); & \fill[red] (0,0) circle (3mm); \\
60 };
61
62 \draw [very thick,->] (0,0) |- (my matrix.west);
63 \end{tikzpicture}
64 \end{codeexample}
65 %
66 The exact syntax of the matrix is explained in the course of this section.
67 %
68 \begin{stylekey}{/tikz/every matrix (initially \normalfont empty)}
69 This style is used in every matrix.
70 \end{stylekey}
71 %
72 \begin{stylekey}{/tikz/every outer matrix (initially \normalfont empty)}
73 While the |every matrix| key also applies to the matrix contents, this
74 only applies to the outer node which holds the matrix.
75 \end{stylekey}
76 \end{key}
77
78 Even more so than nodes, matrices will often be the only object on a path.
79 Because of this, there is a special abbreviation for creating matrices:
80
81 \begin{command}{\matrix}
82 Inside |{tikzpicture}| this is an abbreviation for |\path node[matrix]|.
83 \end{command}
84
85 Even though matrices are nodes, some options do not have the same effect as for
86 normal nodes:
87 %
88 \begin{enumerate}
89 \item Rotations and scaling have no effect on a matrix as a whole (however,
90 you can still transform the contents of the cells normally). Before the
91 matrix is typeset, the rotational and scaling part of the
92 transformation matrix is reset.
93 \item For multi-part shapes you can only set the |text| part of the node.
94 \item All options starting with |text| such as |text width| have no effect.
95 \item If you place a matrix on a path, the matrix contents will be
96 collected into a macro, which tokenizes them. This means that |&| will
97 lose its meaning as an alignment character, resulting in an error. If
98 you need to place a matrix on a path, use |ampersand replacement| to
99 work around that problem.
100 \end{enumerate}
101
102
103 \subsection{Cell Pictures}
104 \label{section-tikz-cell-pictures}
105
106 A matrix consists of rows of \emph{cells}. Each row (including the last one!)
107 is ended by the command |\\|. The character |&| is used to separate cells.
108 Inside each cell, you must place commands for drawing a picture, called the
109 \emph{cell picture} in the following. (However, cell pictures are not enclosed
110 in a complete |{pgfpicture}| environment, they are a bit more light-weight. The
111 main difference is that cell pictures cannot have layers.) It is not necessary
112 to specify beforehand how many rows or columns there are going to be and if a
113 row contains less cell pictures than another line, empty cells are
114 automatically added as needed.
115
116
117 \subsubsection{Alignment of Cell Pictures}
118
119 For each cell picture a bounding box is computed. These bounding boxes and the
120 origins of the cell pictures determine how the cells are aligned. Let us start
121 with the rows: Consider the cell pictures on the first row. Each has a bounding
122 box and somewhere inside this bounding box the origin of the cell picture can
123 be found (the origin might even lie outside the bounding box, but let us ignore
124 this problem for the moment). The cell pictures are then shifted around such
125 that all origins lie on the same horizontal line. This may make it necessary to
126 shift some cell pictures upwards and others downwards, but it can be done and
127 this yields the vertical alignment of the cell pictures this row. The top of
128 the row is then given by the top of the ``highest'' cell picture in the row,
129 the bottom of the row is given by the bottom of the lowest cell picture. (To be
130 more precise, the height of the row is the maximum $y$-value of any of the
131 bounding boxes and the depth of the row is the negated minimum $y$-value of the
132 bounding boxes).
133 %
134 \begin{codeexample}[]
135 \begin{tikzpicture}
136 [every node/.style={draw=black,anchor=base,font=\huge}]
137
138 \matrix [draw=red]
139 {
140 \node {a}; \fill[blue] (0,0) circle (2pt); &
141 \node {X}; \fill[blue] (0,0) circle (2pt); &
142 \node {g}; \fill[blue] (0,0) circle (2pt); \\
143 };
144 \end{tikzpicture}
145 \end{codeexample}
146
147 Each row is aligned in this fashion: For each row the cell pictures
148 are vertically aligned such that the origins lie on the same
149 line. Then the second row is placed below the first row such that the
150 bottom of the first row touches the top of the second row (unless a
151 |row sep| is used to add a bit of space). Then the bottom of the
152 second row touches the top of the third row, and so on. Typically,
153 each row will have an individual height and depth.
154 %
155 \begin{codeexample}[]
156 \begin{tikzpicture}
157 [every node/.style={draw=black,anchor=base}]
158
159 \matrix [draw=red]
160 {
161 \node {a}; & \node {X}; & \node {g}; \\
162 \node {a}; & \node {X}; & \node {g}; \\
163 };
164
165 \matrix [row sep=3mm,draw=red] at (0,-2)
166 {
167 \node {a}; & \node {X}; & \node {g}; \\
168 \node {a}; & \node {X}; & \node {g}; \\
169 };
170 \end{tikzpicture}
171 \end{codeexample}
172
173 Let us now have a look at the columns. The rules for how the pictures on any
174 given column are aligned are very similar to the row alignment: Consider all
175 cell pictures in the first column. Each is shifted horizontally such that the
176 origins lie on the same vertical line. Then, the left end of the column is at
177 the left end of the bounding box that protrudes furthest to the left. The right
178 end of the column is at the right end of the bounding box that protrudes
179 furthest to the right. This fixes the horizontal alignment of the cell pictures
180 in the first column and the same happens the cell pictures in the other
181 columns. Then, the right end of the first column touches the left end of the
182 second column (unless |column sep| is used). The right end of the second column
183 touches the left end of the third column, and so on. (Internally, two columns
184 are actually used to achieve the desired horizontal alignment, but that is only
185 an implementation detail.)
186 %
187 \begin{codeexample}[]
188 \begin{tikzpicture}[every node/.style={draw}]
189 \matrix [draw=red]
190 {
191 \node[left] {Hallo}; \fill[blue] (0,0) circle (2pt); \\
192 \node {X}; \fill[blue] (0,0) circle (2pt); \\
193 \node[right] {g}; \fill[blue] (0,0) circle (2pt); \\
194 };
195 \end{tikzpicture}
196 \end{codeexample}
197
198 \begin{codeexample}[]
199 \begin{tikzpicture}[every node/.style={draw}]
200 \matrix [draw=red,column sep=1cm]
201 {
202 \node {8}; & \node{1}; & \node {6}; \\
203 \node {3}; & \node{5}; & \node {7}; \\
204 \node {4}; & \node{9}; & \node {2}; \\
205 };
206 \end{tikzpicture}
207 \end{codeexample}
208
209
210 \subsubsection{Setting and Adjusting Column and Row Spacing}
211
212 There are different ways of setting and adjusting the spacing between columns
213 and rows. First, you can use the options |column sep| and |row sep| to set a
214 default spacing for all rows and all columns. Second, you can add options to
215 the |&| character and the |\\| command to adjust the spacing between two
216 specific columns or rows. Additionally, you can specify whether the space
217 between two columns or rows should be considered between the origins of cells
218 in the column or row or between their borders.
219
220 \begin{key}{/tikz/column sep=\meta{spacing list}}
221 This option sets a default space that is added between every two columns.
222 This space can be positive or negative and is zero by default. The
223 \meta{spacing list} normally contains a single dimension like |2pt|.
224 %
225 \begin{codeexample}[]
226 \begin{tikzpicture}
227 \matrix [draw,column sep=1cm,nodes=draw]
228 {
229 \node(a) {123}; & \node (b) {1}; & \node {1}; \\
230 \node {12}; & \node {12}; & \node {1}; \\
231 \node(c) {1}; & \node (d) {123}; & \node {1}; \\
232 };
233 \draw [red,thick] (a.east) -- (a.east |- c)
234 (d.west) -- (d.west |- b);
235 \draw [<->,red,thick] (a.east) -- (d.west |- b)
236 node [above,midway] {1cm};
237 \end{tikzpicture}
238 \end{codeexample}
239 %
240 More generally, the \meta{spacing list} may contain a whole list of
241 numbers, separated by commas, and occurrences of the two key words
242 |between origins| and |between borders|. The effect of specifying such a
243 list is the following: First, all numbers occurring in the list are simply
244 added to compute the final spacing. Second, concerning the two keywords,
245 the last occurrence of one of the keywords is important. If the last
246 occurrence is |between borders| or if neither occurs, then the space is
247 inserted between the two columns normally. However, if the last occurs is
248 |between origins|, then the following happens: The distance between the
249 columns is adjusted such that the difference between the origins of all the
250 cells in the first column (remember that they all lie on straight line) and
251 the origins of all the cells in the second column is exactly the given
252 distance.
253
254 \emph{The }|between origins|\emph{ option can only be used for columns
255 mentioned in the first row, that is, you cannot specify this option for
256 columns introduced only in later rows.}
257 %
258 \begin{codeexample}[]
259 \begin{tikzpicture}
260 \matrix [draw,column sep={1cm,between origins},nodes=draw]
261 {
262 \node(a) {123}; & \node (b) {1}; & \node {1}; \\
263 \node {12}; & \node {12}; & \node {1}; \\
264 \node {1}; & \node {123}; & \node {1}; \\
265 };
266 \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {1cm};
267 \end{tikzpicture}
268 \end{codeexample}
269 %
270 \end{key}
271
272 \begin{key}{/tikz/row sep=\meta{spacing list}}
273 This option works like |column sep|, only for rows. Here, too, you can
274 specify whether the space is added between the lower end of the first row
275 and the upper end of the second row, or whether the space is computed
276 between the origins of the two rows.
277 %
278 \begin{codeexample}[]
279 \begin{tikzpicture}
280 \matrix [draw,row sep=1cm,nodes=draw]
281 {
282 \node (a) {123}; & \node {1}; & \node {1}; \\
283 \node (b) {12}; & \node {12}; & \node {1}; \\
284 \node {1}; & \node {123}; & \node {1}; \\
285 };
286 \draw [<->,red,thick] (a.south) -- (b.north) node [right,midway] {1cm};
287 \end{tikzpicture}
288 \end{codeexample}
289 %
290 \begin{codeexample}[]
291 \begin{tikzpicture}
292 \matrix [draw,row sep={1cm,between origins},nodes=draw]
293 {
294 \node (a) {123}; & \node {1}; & \node {1}; \\
295 \node (b) {12}; & \node {12}; & \node {1}; \\
296 \node {1}; & \node {123}; & \node {1}; \\
297 };
298 \draw [<->,red,thick] (a.center) -- (b.center) node [right,midway] {1cm};
299 \end{tikzpicture}
300 \end{codeexample}
301 %
302 \end{key}
303
304 The row-end command |\\| allows you to provide an optional argument, which must
305 be a dimension. This dimension will be added to the list in |row sep|. This
306 means that, firstly, any numbers you list in this argument will be added as an
307 extra row separation between the line being ended and the next line and,
308 secondly, you can use the keywords |between origins| and |between borders| to
309 locally overrule the standard setting for this line pair.
310 %
311 \begin{codeexample}[]
312 \begin{tikzpicture}
313 \matrix [row sep=1mm]
314 {
315 \draw (0,0) circle (2mm); & \draw (0,0) circle (2mm); \\
316 \draw (0,0) circle (2mm); & \draw (0,0) circle (2mm); \\[-1mm]
317 \draw (0,0) coordinate (a) circle (2mm); &
318 \draw (0,0) circle (2mm); \\[1cm,between origins]
319 \draw (0,0) coordinate (b) circle (2mm); &
320 \draw (0,0) circle (2mm); \\
321 };
322 \draw [<->,red,thick] (a.center) -- (b.center) node [right,midway] {1cm};
323 \end{tikzpicture}
324 \end{codeexample}
325
326 The cell separation character |&| also takes an optional argument, which must
327 also be a spacing list. This spacing list is added to the |column sep| having a
328 similar effect as the option for the |\\| command for rows.
329
330 This optional spacing list can only be given the first time a new column is
331 started (usually in the first row), subsequent usages of this option in later
332 rows have no effect.
333 %
334 \begin{codeexample}[]
335 \begin{tikzpicture}
336 \matrix [draw,nodes=draw,column sep=1mm]
337 {
338 \node {8}; &[2mm] \node{1}; &[-1mm] \node {6}; \\
339 \node {3}; & \node{5}; & \node {7}; \\
340 \node {4}; & \node{9}; & \node {2}; \\
341 };
342 \end{tikzpicture}
343 \end{codeexample}
344 %
345 \begin{codeexample}[]
346 \begin{tikzpicture}
347 \matrix [draw,nodes=draw,column sep=1mm]
348 {
349 \node {8}; &[2mm] \node(a){1}; &[1cm,between origins] \node(b){6}; \\
350 \node {3}; & \node {5}; & \node {7}; \\
351 \node {4}; & \node {9}; & \node {2}; \\
352 };
353 \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {11mm};
354 \end{tikzpicture}
355 \end{codeexample}
356 %
357 \begin{codeexample}[]
358 \begin{tikzpicture}
359 \matrix [draw,nodes=draw,column sep={1cm,between origins}]
360 {
361 \node (a) {8}; & \node (b) {1}; &[between borders] \node (c) {6}; \\
362 \node {3}; & \node {5}; & \node {7}; \\
363 \node {4}; & \node {9}; & \node {2}; \\
364 };
365 \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm};
366 \draw [<->,red,thick] (b.east) -- (c.west) node [above,midway] {10mm};
367 \end{tikzpicture}
368 \end{codeexample}
369
370
371 \subsubsection{Cell Styles and Options}
372
373 The following styles and options are useful for changing the appearance of all
374 cell pictures:
375
376 \begin{stylekey}{/tikz/every cell=\marg{row}\marg{column} (initially \normalfont empty)}
377 This style is installed at the beginning of each cell picture with the two
378 parameters being the current \meta{row} and \meta{column} of the cell. Note
379 that setting this style to |draw| will \emph{not} cause all nodes to be
380 drawn since the |draw| option has to be passed to each node individually.
381
382 Inside this style (and inside all cells), the current \meta{row} and
383 \meta{column} number are also accessible via the counters
384 |\pgfmatrixcurrentrow| and |\pgfmatrixcurrentcolumn|.
385 \end{stylekey}
386
387 \begin{key}{/tikz/cells=\meta{options}}
388 This key adds the \meta{options} to the style |every cell|. It is mainly
389 just a shorthand for the code |every cell/.append style=|\meta{options}.
390 \end{key}
391
392 \begin{key}{/tikz/nodes=\meta{options}}
393 This key adds the \meta{options} to the style |every node|. It is mainly
394 just a shorthand for the code |every node/.append style=|\meta{options}.
395
396 The main use of this option is the install some options for the nodes
397 \emph{inside} the matrix that should not apply to the matrix \emph{itself}.
398 %
399 \begin{codeexample}[]
400 \begin{tikzpicture}
401 \matrix [nodes={fill=blue!20,minimum size=5mm}]
402 {
403 \node {8}; & \node{1}; & \node {6}; \\
404 \node {3}; & \node{5}; & \node {7}; \\
405 \node {4}; & \node{9}; & \node {2}; \\
406 };
407 \end{tikzpicture}
408 \end{codeexample}
409 %
410 \end{key}
411
412 The next set of styles can be used to change the appearance of certain rows,
413 columns, or cells. If more than one of these styles is defined, they are
414 executed in the below order (the |every cell| style is executed before all of
415 the below).
416 %
417 \begin{stylekey}{/tikz/column \meta{number}}
418 This style is used for every cell in column \meta{number}.
419 \end{stylekey}
420
421 \begin{stylekey}{/tikz/every odd column}
422 This style is used for every cell in an odd column.
423 \end{stylekey}
424
425 \begin{stylekey}{/tikz/every even column}
426 This style is used for every cell in an even column.
427 \end{stylekey}
428
429 \begin{stylekey}{/tikz/row \meta{number}}
430 This style is used for every cell in row \meta{number}.
431 \end{stylekey}
432
433 \begin{stylekey}{/tikz/every odd row}
434 This style is used for every cell in an odd row.
435 \end{stylekey}
436
437 \begin{stylekey}{/tikz/every even row}
438 This style is used for every cell in an even row.
439 \end{stylekey}
440
441 \begin{stylekey}{/tikz/row \meta{row number} column \meta{column number}}
442 This style is used for the cell in row \meta{row number} and column
443 \meta{column number}.
444 \end{stylekey}
445 %
446 \begin{codeexample}[]
447 \begin{tikzpicture}
448 [row 1/.style={red},
449 column 2/.style={green!50!black},
450 row 3 column 3/.style={blue}]
451
452 \matrix
453 {
454 \node {8}; & \node{1}; & \node {6}; \\
455 \node {3}; & \node{5}; & \node {7}; \\
456 \node {4}; & \node{9}; & \node {2}; \\
457 };
458 \end{tikzpicture}
459 \end{codeexample}
460
461 You can use the |column |\meta{number} option to change the alignment for
462 different columns.
463 %
464 \begin{codeexample}[]
465 \begin{tikzpicture}
466 [column 1/.style={anchor=base west},
467 column 2/.style={anchor=base east},
468 column 3/.style={anchor=base}]
469 \matrix
470 {
471 \node {123}; & \node{456}; & \node {789}; \\
472 \node {12}; & \node{45}; & \node {78}; \\
473 \node {1}; & \node{4}; & \node {7}; \\
474 };
475 \end{tikzpicture}
476 \end{codeexample}
477
478 In some cases, it is desirable to include some automation in each column/row
479 separately. A typical example is to apply stripe-pattern to almost all columns
480 with exceptions. For these type of use-cases, nesting these keys can open up
481 a lot of possibilities; in the following example a ``feature comparison'' table
482 is demonstrated. It is intentionally made rather verbose and a bit redundant
483 to show how the column and row settings can be progressively overwritten to
484 create certain effects.
485
486 \begin{codeexample}[preamble={\usetikzlibrary{matrix,fit}}]
487 \begin{tikzpicture}[
488 font=\sffamily,
489 head color/.style args={#1/#2}{
490 row 1 column #1/.append style={nodes={fill=#2}}},
491 % swap order of row and column styles
492 matrix/inner style order={
493 every cell,
494 row, even odd row,
495 column, even odd column,
496 cell
497 }
498 ]
499
500 \matrix [
501 matrix of nodes, nodes in empty cells,
502 nodes={text width=2cm, align=center,
503 minimum height=1.5em, anchor=center},
504 % add striped row style
505 every even row/.style={nodes={fill=olive!50}},
506 % modify the feature column and header row
507 column 1/.style= {nodes={fill=olive, inner ysep=0}},
508 row 1/.style= {nodes={text depth=0.2ex, text=white}},
509 row 1 column 1/.style={nodes={fill=none, draw=none}},
510 head color/.list={2/orange,3/teal,4/cyan,5/magenta} % specify header colors
511 ] (m)
512 {
513 & Basic & Standard & Professional & Enterprise \\
514 Feature A & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
515 Feature B & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
516 Feature C & & & & $\bullet$ \\
517 Feature D & & $\bullet$ & $\bullet$ & $\bullet$ \\
518 Feature E & & & $\bullet$ & $\bullet$ \\
519 };
520 % Add emphasis on selection by the use of "fit" library
521 \node[fit={(m-1-4.north west) (m-6-4.south east)},
522 ultra thick, inner sep=0pt, rounded corners=1mm,
523 draw=cyan, label={[cyan,align=center]270:Popular\\Choice!}]{};
524 \end{tikzpicture}
525 \end{codeexample}
526
527 The order in which these styles are applied is configurable. You can also
528 install your own styles. The following styles (in fact, internally they are
529 |/.code| keys) wrap the styles introduced in the previous paragraph passing the
530 correct argument and ensuring that they are only called for even or odd rows.
531 However, it is not recommended to override these.
532
533 \begin{stylekey}{/tikz/matrix/inner style/every cell}
534 Wraps |/tikz/every cell|.
535 \end{stylekey}
536 \begin{stylekey}{/tikz/matrix/inner style/column}
537 Wraps |/tikz/column |\meta{number}.
538 \end{stylekey}
539 \begin{stylekey}{/tikz/matrix/inner style/even odd column}
540 Wraps |/tikz/every even column| and |/tikz/every odd column|.
541 \end{stylekey}
542 \begin{stylekey}{/tikz/matrix/inner style/row}
543 Wraps |/tikz/row |\meta{number}.
544 \end{stylekey}
545 \begin{stylekey}{/tikz/matrix/inner style/even odd row}
546 Wraps |/tikz/every even row| and |/tikz/every odd row|.
547 \end{stylekey}
548 \begin{stylekey}{/tikz/matrix/inner style/cell}
549 Wraps |/tikz/row |\meta{number}| column |\meta{number}.
550 \end{stylekey}
551
552 \begin{stylekey}{/tikz/matrix/inner style order}
553 The order in which these styles are applied to the matrix cells is
554 specified by this key. By default it is
555 %
556 \begin{codeexample}[code only]
557 \tikzset{
558 matrix/inner style order={
559 every cell,
560 column,
561 even odd column,
562 row,
563 even odd row,
564 cell,
565 },
566 }
567 \end{codeexample}
568 %
569 You can use this to install your own styles here, but only \emph{names} of
570 styles are permitted here. The style specification has to be placed
571 outside of |matrix/inner style order| and unless it is installed inside
572 |/tikz/matrix/inner style/|, it has to be fully qualified.
573 %
574 \begin{codeexample}[code only]
575 \tikzset{
576 my style/.code={%
577 \ifnum\pgfmatrixcurrentcolumn=2
578 \tikzset{font=\itshape}%
579 \fi
580 },
581 matrix/inner style order={
582 every cell,
583 even odd column,
584 even odd row,
585 column,
586 row,
587 cell,
588 /tikz/my style,
589 },
590 }
591 \end{codeexample}
592 %
593 \end{stylekey}
594
595 In many matrices all cell pictures have nearly the same code. For example,
596 cells typically start with |\node{| and end |};|. The following options allow
597 you to execute such code in all cells:
598
599 \begin{key}{/tikz/execute at begin cell=\meta{code}}
600 The code will be executed at the beginning of each nonempty cell.
601 \end{key}
602 %
603 \begin{key}{/tikz/execute at end cell=\meta{code}}
604 The code will be executed at the end of each nonempty cell.
605 \end{key}
606 %
607 \begin{key}{/tikz/execute at empty cell=\meta{code}}
608 The code will be executed inside each empty cell.
609 \end{key}
610 %
611 \begin{codeexample}[]
612 \begin{tikzpicture}
613 [matrix of nodes/.style={
614 execute at begin cell=\node\bgroup,
615 execute at end cell=\egroup;%
616 }]
617 \matrix [matrix of nodes]
618 {
619 8 & 1 & 6 \\
620 3 & 5 & 7 \\
621 4 & 9 & 2 \\
622 };
623 \end{tikzpicture}
624 \end{codeexample}
625 %
626 \begin{codeexample}[]
627 \begin{tikzpicture}
628 [matrix of nodes/.style={
629 execute at begin cell=\node\bgroup,
630 execute at end cell=\egroup;,%
631 execute at empty cell=\node{--};%
632 }]
633 \matrix [matrix of nodes]
634 {
635 8 & 1 & \\
636 3 & & 7 \\
637 & & 2 \\
638 };
639 \end{tikzpicture}
640 \end{codeexample}
641
642 The |matrix| library defines a number of styles that make use of the above
643 options.
644
645
646 \subsection{Anchoring a Matrix}
647
648 Since matrices are nodes, they can be anchored in the usual fashion using the
649 |anchor| option. However, there are two ways to influence this placement
650 further. First, the following option is often useful:
651
652 \begin{key}{/tikz/matrix anchor=\meta{anchor}}
653 This option has the same effect as |anchor|, but the option applies only to
654 the matrix itself, not to the cells inside. If you just say |anchor=north|
655 as an option to the matrix node, all nodes inside matrix will also have
656 this anchor, unless it is explicitly set differently for each node. By
657 comparison, |matrix anchor| sets the anchor for the matrix, but for the
658 nodes inside the value of |anchor| remain unchanged.
659 %
660 \begin{codeexample}[]
661 \begin{tikzpicture}
662 \matrix [matrix anchor=west] at (0,0)
663 {
664 \node {123}; \\ % still center anchor
665 \node {12}; \\
666 \node {1}; \\
667 };
668 \matrix [anchor=west] at (0,-2)
669 {
670 \node {123}; \\ % inherited west anchor
671 \node {12}; \\
672 \node {1}; \\
673 };
674 \end{tikzpicture}
675 \end{codeexample}
676 %
677 \end{key}
678
679 The second way to anchor a matrix is to use \emph{an anchor of a node inside
680 the matrix}. For this, the |anchor| option has a special effect when given as
681 an argument to a matrix:
682
683 \begin{key}{/tikz/anchor=\meta{anchor or node.anchor}}
684 Normally, the argument of this option refers to anchor of the matrix node,
685 which is the node that includes all of the stuff of the matrix. However,
686 you can also provide an argument of the form \meta{node}|.|\meta{anchor}
687 where \meta{node} must be node defined inside the matrix and \meta{anchor}
688 is an anchor of this node. In this case, the whole matrix is shifted around
689 in such a way that this particular anchor of this particular node lies at
690 the |at| position of the matrix. The same is true for |matrix anchor|.
691 %
692 \begin{codeexample}[]
693 \begin{tikzpicture}
694 \draw[help lines] (0,0) grid (3,2);
695 \matrix[matrix anchor=inner node.south,anchor=base,row sep=3mm] at (1,1)
696 {
697 \node {a}; & \node {b}; & \node {c}; & \node {d}; \\
698 \node {a}; & \node(inner node) {b}; & \node {c}; & \node {d}; \\
699 \node {a}; & \node {b}; & \node {c}; & \node {d}; \\
700 };
701 \draw (inner node.south) circle (1pt);
702 \end{tikzpicture}
703 \end{codeexample}
704 %
705 \end{key}
706
707
708 \subsection{Considerations Concerning Active Characters}
709
710 Even though \tikzname\ seems to use |&| to separate cells, \pgfname\ actually
711 uses a different command to separate cells, namely the command
712 |\pgfmatrixnextcell| and using a normal |&| character will normally fail. What
713 happens is that, \tikzname\ makes |&| an active character and then defines this
714 character to be equal to |\pgfmatrixnextcell|. In most situations this will
715 work nicely, but sometimes |&| cannot be made active; for instance because the
716 matrix is used in an argument of some macro or the matrix contains nodes that
717 contain normal |{tabular}| environments. In this case you can use the following
718 option to avoid having to type |\pgfmatrixnextcell| each time:
719
720 \begin{key}{/tikz/ampersand replacement=\meta{macro name or empty}}
721 If a macro name is provided, this macro will be defined to be equal to
722 |\pgfmatrixnextcell| inside matrices and |&| will not be made active. For
723 instance, you could say |ampersand replacement=\&| and then use |\&| to
724 separate columns as in the following example:
725 %
726 \begin{codeexample}[]
727 \tikz
728 \matrix [ampersand replacement=\&]
729 {
730 \draw (0,0) circle (4mm); \& \node[rotate=10] {Hello}; \\
731 \draw (0.2,0) circle (2mm); \& \fill[red] (0,0) circle (3mm); \\
732 };
733 \end{codeexample}
734 %
735 \end{key}
736
737
738 \subsection{Examples}
739
740 The following examples are adapted from code by Mark Wibrow. The first two
741 redraw pictures from Timothy van Zandt's PStricks documentation:
742 %
743 {\catcode`\|=12
744 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
745 \begin{tikzpicture}
746 \matrix [matrix of math nodes,row sep=1cm]
747 {
748 |(U)| U &[2mm] &[8mm] \\
749 & |(XZY)| X \times_Z Y & |(X)| X \\
750 & |(Y)| Y & |(Z)| Z \\
751 };
752 \begin{scope}[every node/.style={midway,auto,font=\scriptsize}]
753 \draw [double, dashed] (U) -- node {$x$} (X);
754 \draw (X) -- node {$p$} (X -| XZY.east)
755 (X) -- node {$f$} (Z)
756 -- node {$g$} (Y)
757 -- node {$q$} (XZY)
758 -- node {$y$} (U);
759 \end{scope}
760 \end{tikzpicture}
761 \end{codeexample}
762
763 \begin{codeexample}[
764 preamble={\usetikzlibrary{matrix}},
765 pre={\definecolor{graphicbackground}{rgb}{0.96,0.96,0.8}},
766 ]
767 \begin{tikzpicture}[>=stealth,->,shorten >=2pt,looseness=.5,auto]
768 \matrix [matrix of math nodes,
769 column sep={2cm,between origins},
770 row sep={3cm,between origins},
771 nodes={circle, draw, minimum size=7.5mm}]
772 {
773 & |(A)| A & \\
774 |(B)| B & |(E)| E & |(C)| C \\
775 & |(D)| D \\
776 };
777 \begin{scope}[every node/.style={font=\small\itshape}]
778 \draw (A) to [bend left] node [midway] {g} (B);
779 \draw (B) to [bend left] node [midway] {f} (A);
780 \draw (D) -- node [midway] {c} (B);
781 \draw (E) -- node [midway] {b} (B);
782 \draw (E) -- node [near end] {a} (C);
783 \draw [-,line width=8pt,draw=graphicbackground]
784 (D) to [bend right, looseness=1] (A);
785 \draw (D) to [bend right, looseness=1]
786 node [near start] {b} node [near end] {e} (A);
787 \end{scope}
788 \end{tikzpicture}
789 \end{codeexample}
790
791 \begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
792 \begin{tikzpicture}
793 \matrix (network)
794 [matrix of nodes,%
795 nodes in empty cells,
796 nodes={outer sep=0pt,circle,minimum size=4pt,draw},
797 column sep={1cm,between origins},
798 row sep={1cm,between origins}]
799 {
800 & & & \\
801 & & & \\
802 |[draw=none]| & |[xshift=1mm]| & |[xshift=-1mm]| \\
803 };
804 \foreach \a in {1,...,4}{
805 \draw (network-3-2) -- (network-2-\a);
806 \draw (network-3-3) -- (network-2-\a);
807 \draw [-stealth] ([yshift=5mm]network-1-\a.north) -- (network-1-\a);
808 \foreach \b in {1,...,4}
809 \draw (network-1-\a) -- (network-2-\b);
810 }
811 \draw [stealth-] ([yshift=-5mm]network-3-2.south) -- (network-3-2);
812 \draw [stealth-] ([yshift=-5mm]network-3-3.south) -- (network-3-3);
813 \end{tikzpicture}
814 \end{codeexample}
815
816 The following example is adapted from code written by Kjell Magne Fauske, which
817 is based on the following paper: K.~Bossley, M.~Brown, and C.~Harris,
818 Neurofuzzy identification of an autonomous underwater vehicle,
819 \emph{International Journal of Systems Science}, 1999, 30, 901--913.
820 %
821 \begin{codeexample}[preamble={\usetikzlibrary{arrows,shapes.geometric}}]
822 \begin{tikzpicture}
823 [auto,
824 decision/.style={diamond, draw=blue, thick, fill=blue!20,
825 text width=4.5em,align=flush center,
826 inner sep=1pt},
827 block/.style ={rectangle, draw=blue, thick, fill=blue!20,
828 text width=5em,align=center, rounded corners,
829 minimum height=4em},
830 line/.style ={draw, thick, -latex',shorten >=2pt},
831 cloud/.style ={draw=red, thick, ellipse,fill=red!20,
832 minimum height=2em}]
833
834 \matrix [column sep=5mm,row sep=7mm]
835 {
836 % row 1
837 \node [cloud] (expert) {expert}; &
838 \node [block] (init) {initialize model}; &
839 \node [cloud] (system) {system}; \\
840 % row 2
841 & \node [block] (identify) {identify candidate model}; & \\
842 % row 3
843 \node [block] (update) {update model}; &
844 \node [block] (evaluate) {evaluate candidate models}; & \\
845 % row 4
846 & \node [decision] (decide) {is best candidate}; & \\
847 % row 5
848 & \node [block] (stop) {stop}; & \\
849 };
850 \begin{scope}[every path/.style=line]
851 \path (init) -- (identify);
852 \path (identify) -- (evaluate);
853 \path (evaluate) -- (decide);
854 \path (update) |- (identify);
855 \path (decide) -| node [near start] {yes} (update);
856 \path (decide) -- node [midway] {no} (stop);
857 \path [dashed] (expert) -- (init);
858 \path [dashed] (system) -- (init);
859 \path [dashed] (system) |- (evaluate);
860 \end{scope}
861 \end{tikzpicture}
862 \end{codeexample}
863 }
864
865
866 %%% Local Variables:
867 %%% mode: latex
868 %%% TeX-master: "pgfmanual"
869 %%% End: