Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-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}
12 \label{section-base-matrices}
13
14 \begin{pgfmodule}{matrix}
15 The present section documents the commands of this module.
16 \end{pgfmodule}
17
18 \subsection{Overview}
19
20 Matrices are a mechanism for aligning several so-called cell pictures
21 horizontally and vertically. The resulting alignment is placed in a normal node
22 and the command for creating matrices, |\pgfmatrix|, takes options very similar
23 to the |\pgfnode| command.
24
25 In the following, the basic idea behind the alignment mechanism is explained
26 first. Then the command |\pgfmatrix| is explained. At the end of the section,
27 additional ways of modifying the width of columns and rows are discussed.
28
29
30 \subsection{Cell Pictures and Their Alignment}
31
32 A matrix consists of rows of \emph{cells}. Cells are separated using the
33 special command |\pgfmatrixnextcell|, rows are ended using the command
34 |\pgfmatrixendrow| (the command |\\| is set up to mean the same as
35 |\pgfmatrixendrow| by default). Each cell contains a \emph{cell picture},
36 although cell pictures are not complete pictures as they lack layers. However,
37 each cell picture has its own bounding box like a normal picture does. These
38 bounding boxes are important for the alignment as explained in the following.
39
40 Each cell picture will have an origin somewhere in the picture (or even outside
41 the picture). The position of these origins are important for the alignment: On
42 each row the origins will be on the same horizontal line and for each column
43 the origins will also be on the same vertical line. These two requirements mean
44 that the cell pictures may need to be shifted around so that the origins wind
45 up on the same lines. The top of a row is given by the top of the cell picture
46 whose bounding box's maximum $y$-position is largest. Similarly, the bottom of
47 a row is given by the bottom of the cell picture whose bounding box's minimum
48 $y$-position is the most negative. Similarly, the left end of a column is given
49 by the left end of the cell whose bounding box's $x$-position is the most
50 negative; and similarly for the right end of a column.
51 %
52 \begin{codeexample}[]
53 \begin{tikzpicture}[x=3mm,y=3mm,fill=blue!50]
54 \def\atorig#1{\node[black] at (0,0) {\tiny #1};}
55
56 \pgfmatrix{rectangle}{center}{mymatrix}
57 {\pgfusepath{}}{\pgfpointorigin}{}
58 {
59 \fill (0,-3) rectangle (1,1);\atorig1 \pgfmatrixnextcell
60 \fill (-1,0) rectangle (1,1);\atorig2 \pgfmatrixnextcell
61 \fill (-1,-2) rectangle (0,0);\atorig3 \pgfmatrixnextcell
62 \fill (-1,-1) rectangle (0,3);\atorig4 \\
63 \fill (-1,0) rectangle (4,1);\atorig5 \pgfmatrixnextcell
64 \fill (0,-1) rectangle (1,1);\atorig6 \pgfmatrixnextcell
65 \fill (0,0) rectangle (1,4);\atorig7 \pgfmatrixnextcell
66 \fill (-1,-1) rectangle (0,0);\atorig8 \\
67 }
68 \end{tikzpicture}
69 \end{codeexample}
70
71
72 \subsection{The Matrix Command}
73
74 All matrices are typeset using the following command:
75
76 \begin{command}{\pgfmatrix\marg{shape}\marg{anchor}\marg{name}\marg{usage}\marg{shift}\marg{pre-code}\marg{matrix cells}}
77 This command creates a node that contains a matrix. The name of the node is
78 \meta{name}, its shape is \meta{shape} and the node is anchored at
79 \meta{anchor}.
80
81 The \meta{matrix cell} parameter contains the cells of the matrix. In each
82 cell drawing commands may be given, which create a so-called cell picture.
83 For each cell picture a bounding box is computed and the cells are aligned
84 according to the rules outlined in the previous section.
85
86 The resulting matrix is used as the |text| box of the node. As for a normal
87 node, the \meta{usage} commands are applied, so that the path(s) of the
88 resulting node is (are) stroked or filled or whatever.
89
90
91 \medskip
92 \textbf{Specifying the cells and rows.\ }
93 Even though this command uses |\halign| internally, there are two special
94 rules for indicating cells:
95 %
96 \begin{enumerate}
97 \item Cells in the same row must be separated using the macro
98 |\pgfmatrixnextcell| rather than |&|. Using |&| will result in an
99 error message.
100
101 However, you can make |&| an active character and have it expand to
102 |\pgfmatrixnextcell|. This way, it will ``look'' as if |&| is used.
103 \item Rows are ended using the command |\pgfmatrixendrow|, but |\\| is
104 set up to mean the same by default. However, some environments like
105 |{minipage}| redefine |\\|, so it is good to have
106 |\pgfmatrixendrow| as a ``fallback''.
107 \item Every row \emph{including the last row} must be ended using the
108 command |\\| or |\pgfmatrixendrow|.
109 \end{enumerate}
110
111 Both |\pgfmatrixnextcell| and |\pgfmatrixendrow| (and, thus, also |\\|)
112 take an optional argument as explained in the
113 Section~\ref{section-matrix-spacing}
114 %
115 \begin{codeexample}[]
116 \begin{tikzpicture}
117 \pgfmatrix{rectangle}{center}{mymatrix}
118 {\pgfusepath{}}{\pgfpointorigin}{}
119 {
120 \node {a}; \pgfmatrixnextcell \node {b}; \pgfmatrixendrow
121 \node {c}; \pgfmatrixnextcell \node {d}; \pgfmatrixendrow
122 }
123 \end{tikzpicture}
124 \end{codeexample}
125
126
127 \medskip
128 \textbf{Anchoring matrices at nodes inside the matrix.\ }
129 The parameter \meta{shift} is an additional negative shift for the node.
130 Normally, such a shift could be given beforehand (that is, the shift could
131 be preapplied to the current transformation matrix). However, when
132 \meta{shift} is evaluated, you can refer to \emph{temporary} positions of
133 nodes inside the matrix. In detail, the following happens: When the matrix
134 has been typeset, all nodes in the matrix temporarily get assigned their
135 positions in the matrix box. The origin of this coordinate system is at the
136 left baseline end of the matrix box, which corresponds to the |text|
137 anchor. The position \meta{shift} is then interpreted inside this
138 coordinate system and then used for shifting.
139
140 This allows you to use the parameter \meta{shift} in the following way: If
141 you use |text| as the \meta{anchor} and specify
142 |\pgfpointanchor{inner node}{some anchor}| for the parameter \meta{shift},
143 where |inner node| is a node that is created in the matrix, then the whole
144 matrix will be shifted such that |inner node.some anchor| lies at the
145 origin of the whole picture.
146
147
148 \medskip
149 \textbf{Rotations and scaling.\ }
150 The matrix node is never rotated or scaled, because the current coordinate
151 transformation matrix is reset (except for the translational part) at the
152 beginning of |\pgfmatrix|. This is intentional and will not change in the
153 future. If you need to rotate or scale the matrix, you must install an
154 appropriate canvas transformation yourself.
155
156 However, nodes and stuff inside the cell pictures can be rotated and scaled
157 normally.
158
159
160 \medskip
161 \textbf{Callbacks.\ }
162 At the beginning and at the end of each cell the special macros
163 |\pgfmatrixbegincode|, |\pgfmatrixendcode| and possibly
164 |\pgfmatrixemptycode| are called. The effect is explained in
165 Section~\ref{section-matrix-callbacks}.
166
167
168 \medskip
169 \textbf{Executing extra code.\ }
170 The parameter \meta{pre-code} is executed at the beginning of the outermost
171 \TeX-group enclosing the matrix node. It is inside this \TeX-group, but
172 outside the matrix itself. It can be used for different purposes:
173 %
174 \begin{enumerate}
175 \item It can be used to simplify the next cell macro. For example,
176 saying |\let\&=\pgfmatrixnextcell| allows you to use |\&| instead
177 of |\pgfmatrixnextcell|. You can also set the catcode of |&| to
178 active.
179 \item It can be used to issue an |\aftergroup| command. This allows you
180 to regain control after the |\pgfmatrix| command. (If you do not
181 know the |\aftergroup| command, you are probably blessed with a
182 simple and happy life.)
183 \end{enumerate}
184
185
186 \medskip
187 \textbf{Special considerations concerning macro expansion.\ }
188 As said before, the matrix is typeset using |\halign| internally. This
189 command does a lot of strange and magic things like expanding the first
190 macro of every cell in a most unusual manner. Here are some effects you may
191 wish to be aware of:
192 %
193 \begin{itemize}
194 \item It is not necessary to actually mention |\pgfmatrixnextcell| or
195 |\pgfmatrixendrow| inside the \meta{matrix cells}. It suffices that
196 the macros inside \meta{matrix cells} expand to these macros
197 sooner or later.
198 \item In particular, you can define clever macros that insert columns
199 and rows as needed for special effects.
200 \end{itemize}
201 \end{command}
202
203
204 \subsection{Row and Column Spacing}
205 \label{section-matrix-spacing}
206
207 It is possible to control the space between columns and rows rather detailedly.
208 Two commands are important for the row spacing and two commands for the column
209 spacing.
210
211 \begin{command}{\pgfsetmatrixcolumnsep\marg{sep list}}
212 This macro sets the default separation list for columns. The details of the
213 format of this list are explained in the description of the next command.
214 \end{command}
215
216 \begin{command}{\pgfmatrixnextcell\opt{\oarg{additional sep list}}}
217 This command has two purposes: First, it is used to separate cells. Second,
218 by providing the optional argument \meta{additional sep list} you can
219 modify the spacing between the columns that are separated by this command.
220
221 The optional \meta{additional sep list} may only be provided when the
222 |\pgfmatrixnextcell| command starts a new column. Normally, this will only
223 be the case in the first row, but sometimes a later row has more elements
224 than the first row. In this case, the |\pgfmatrixnextcell| commands that
225 start the new columns in the later row may also have the optional argument.
226 Once a column has been started, subsequent uses of this optional argument
227 for the column have no effect.
228
229 To determine the space between the two columns that are separated by
230 |\pgfmatrixnextcell|, the following algorithm is executed:
231 %
232 \begin{enumerate}
233 \item Both the default separation list (as set up by
234 |\pgfsetmatrixcolumnsep|) and the \meta{additional sep list} are
235 processed, in this order. If the \meta{additional sep list}
236 argument is missing, only the default separation list is processed.
237 \item Both lists may contain dimensions, separated by commas, as well
238 as occurrences of the keywords |between origins| and
239 |between borders|.
240 \item All dimensions occurring in either list are added together to
241 arrive at a dimension $d$.
242 \item The last occurrence of either of the keywords is located. If
243 neither keyword is present, we proceed as if |between borders| were
244 present.
245 \end{enumerate}
246 %
247 At the end of the algorithm, a dimension $d$ has been computed and one of
248 the two \emph{modes} |between borders| and |between origins| has been
249 determined. Depending on which mode has been determined, the following
250 happens:
251 %
252 \begin{itemize}
253 \item For the |between borders| mode, an additional horizontal space of
254 $d$ is added between the two columns. Note that $d$ may be
255 negative.
256 \item For the |between origins| mode, the spacing between the two
257 columns is computed differently: Recall that the origins of the
258 cell pictures in both pictures lie on two vertical lines. The
259 spacing between the two columns is set up such that the horizontal
260 distance between these two lines is exactly $d$.
261
262 This mode may only be used between columns \emph{already introduced
263 in the first row}.
264 \end{itemize}
265 %
266 All of the above rules boil down to the following effects:
267 %
268 \begin{itemize}
269 \item A default spacing between columns should be set up using
270 |\pgfsetmatrixcolumnsep|. For example, you might say
271 |\pgfsetmatrixcolumnsep{5pt}| to have columns spaced apart by
272 |5pt|. You could say
273 %
274 \begin{verbatim}
275 \pgfsetmatrixcolumnsep{1cm,between origins}
276 \end{verbatim}
277 %
278 to specify that horizontal space between the origins of cell
279 pictures in adjacent columns should be 1cm by default -- regardless
280 of the actual size of the cell pictures.
281 \item You can now use the optional argument of |\pgfmatrixnextcell| to
282 locally overrule the spacing between two columns. By saying
283 |\pgfmatrixnextcell[5pt]| you \emph{add} 5pt to the space between
284 of the two columns, regardless of the mode.
285
286 You can also (locally) change the spacing mode for these two
287 columns. For example, even if the normal spacing mode is
288 |between origins|, you can say
289 %
290 \begin{verbatim}
291 \pgfmatrixnextcell[5pt,between borders]
292 \end{verbatim}
293 %
294 to locally change the mode for these columns to |between borders|.
295 \end{itemize}
296 %
297 \begin{codeexample}[]
298 \begin{tikzpicture}[every node/.style=draw]
299 \pgfsetmatrixcolumnsep{1mm}
300 \pgfmatrix{rectangle}{center}{mymatrix}
301 {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
302 {
303 \node {8}; \&[2mm] \node{1}; \&[-1mm] \node {6}; \\
304 \node {3}; \& \node{5}; \& \node {7}; \\
305 \node {4}; \& \node{9}; \& \node {2}; \\
306 }
307 \end{tikzpicture}
308 \end{codeexample}
309 %
310 \begin{codeexample}[]
311 \begin{tikzpicture}[every node/.style=draw]
312 \pgfsetmatrixcolumnsep{1mm}
313 \pgfmatrix{rectangle}{center}{mymatrix}
314 {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
315 {
316 \node {8}; \&[2mm] \node(a){1}; \&[1cm,between origins] \node(b){6}; \\
317 \node {3}; \& \node {5}; \& \node {7}; \\
318 \node {4}; \& \node {9}; \& \node {2}; \\
319 }
320 \draw [<->,red,thick,every node/.style=] (a.center) -- (b.center)
321 node [above,midway] {11mm};
322 \end{tikzpicture}
323 \end{codeexample}
324 %
325 \begin{codeexample}[]
326 \begin{tikzpicture}[every node/.style=draw]
327 \pgfsetmatrixcolumnsep{1cm,between origins}
328 \pgfmatrix{rectangle}{center}{mymatrix}
329 {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
330 {
331 \node (a) {8}; \& \node (b) {1}; \&[between borders] \node (c) {6}; \\
332 \node {3}; \& \node {5}; \& \node {7}; \\
333 \node {4}; \& \node {9}; \& \node {2}; \\
334 }
335 \begin{scope}[every node/.style=]
336 \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm};
337 \draw [<->,red,thick] (b.east) -- (c.west) node [above,midway]
338 {10mm};
339 \end{scope}
340 \end{tikzpicture}
341 \end{codeexample}
342 %
343 \end{command}
344
345 The mechanism for the between-row-spacing is the same, only the commands are
346 called differently.
347
348 \begin{command}{\pgfsetmatrixrowsep\marg{sep list}}
349 This macro sets the default separation list for rows.
350 \end{command}
351
352 \begin{command}{\pgfmatrixendrow\opt{\oarg{additional sep list}}}
353 This command ends a line. The optional \meta{additional sep list} is used
354 to determine the spacing between the row being ended and the next row. The
355 modes and the computation of $d$ is done in the same way as for columns.
356 For the last row the optional argument has no effect.
357
358 Inside matrices (and only there) the command |\\| is set up to mean the
359 same as this command.
360 \end{command}
361
362
363 \subsection{Callbacks}
364 \label{section-matrix-callbacks}
365
366 There are three macros that get called at the beginning and end of cells. By
367 redefining these macros, which are empty by default, you can change the
368 appearance of cells in a very general manner.
369
370 \begin{command}{\pgfmatrixemptycode}
371 This macro is executed for empty cells. This means that \pgfname\ uses some
372 macro magic to determine whether a cell is empty (it immediately ends with
373 |\pgfmatrixemptycode| or |\pgfmatrixendrow|) and, if so, put this macro
374 inside the cell.
375 %
376 \begin{codeexample}[]
377 \begin{tikzpicture}
378 \def\pgfmatrixemptycode{\node{empty};}
379 \pgfmatrix{rectangle}{center}{mymatrix}
380 {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
381 {
382 \node {a}; \& \& \node {b}; \\
383 \& \node{c}; \& \node {d}; \& \\
384 }
385 \end{tikzpicture}
386 \end{codeexample}
387 %
388 As can be seen, the macro is not executed for empty cells at the end of row
389 when columns are added only later on.
390 \end{command}
391
392 \begin{command}{\pgfmatrixbegincode}
393 This macro is executed at the beginning of non-empty cells.
394 Correspondingly, |\pgfmatrixendcode| is added at the end of every non-empty
395 cell.
396 %
397 \begin{codeexample}[]
398 \begin{tikzpicture}
399 \def\pgfmatrixbegincode{\node[draw]\bgroup}
400 \def\pgfmatrixendcode{\egroup;}
401 \pgfmatrix{rectangle}{center}{mymatrix}
402 {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
403 {
404 a \& b \& c \\
405 d \& \& e \\
406 }
407 \end{tikzpicture}
408 \end{codeexample}
409 %
410 Note that between |\pgfmatrixbegincode| and |\pgfmatrixendcode| there will
411 \emph{not} only be the contents of the cell. Rather, \pgfname\ will add
412 some (invisible) commands for book-keeping purposes that involve |\let| and
413 |\gdef|. In particular, it is not a good idea to have |\pgfmatrixbegincode|
414 end with |\csname| and |\pgfmatrixendcode| start with |\endcsname|.
415 \end{command}
416
417 \begin{command}{\pgfmatrixendcode}
418 See the explanation above.
419 \end{command}
420
421 The following two counters allow you to access the current row and current
422 column in a callback:
423
424 \begin{command}{\pgfmatrixcurrentrow}
425 This counter stores the current row of the current cell of the matrix. Do
426 not even think about changing this counter.
427 \end{command}
428
429 \begin{command}{\pgfmatrixcurrentcolumn}
430 This counter stores the current column of the current cell of the matrix.
431 \end{command}
432
433
434 %%% Local Variables:
435 %%% mode: latex
436 %%% TeX-master: "pgfmanual"
437 %%% End: