TikZ and PGF Manual

The present section documents the commands of this module.

This command creates a node that contains a matrix. The name of the node is ⟨name⟩, its shape is ⟨shape⟩ and the node is anchored at ⟨anchor⟩.

The ⟨matrix cell⟩ parameter contains the cells of the matrix. In each cell drawing commands may be given, which create a so-called cell picture. For each cell picture a bounding box is computed and the cells are aligned according to the rules outlined in the previous section.

The resulting matrix is used as the text box of the node. As for a normal node, the ⟨usage⟩ commands are applied, so that the path(s) of the resulting node is (are) stroked or filled or whatever.

Specifying the cells and rows. Even though this command uses \halign internally, there are two special rules for indicating cells:

• 1. Cells in the same row must be separated using the macro \pgfmatrixnextcell rather than &. Using & will result in an error message.

  However, you can make & an active character and have it expand to \pgfmatrixnextcell. This way, it will “look” as if & is used.

• 2. Rows are ended using the command \pgfmatrixendrow, but \\ is set up to mean the same by default. However, some environments like {minipage} redefine \\, so it is good to have \pgfmatrixendrow as a “fallback”.

• 3. Every row including the last row must be ended using the command \\ or \pgfmatrixendrow.

Both \pgfmatrixnextcell and \pgfmatrixendrow (and, thus, also \\) take an optional argument as explained in the Section 107.4

Anchoring matrices at nodes inside the matrix. The parameter ⟨shift⟩ is an additional negative shift for the node. Normally, such a shift could be given beforehand (that is, the shift could be preapplied to the current transformation matrix). However, when ⟨shift⟩ is evaluated, you can refer to temporary positions of nodes inside the matrix. In detail, the following happens: When the matrix has been typeset, all nodes in the matrix temporarily get assigned their positions in the matrix box. The origin of this coordinate system is at the left baseline end of the matrix box, which corresponds to the text anchor. The position ⟨shift⟩ is then interpreted inside this coordinate system and then used for shifting.

This allows you to use the parameter ⟨shift⟩ in the following way: If you use text as the ⟨anchor⟩ and specify \pgfpointanchor{inner node}{some anchor} for the parameter ⟨shift⟩, where inner node is a node that is created in the matrix, then the whole matrix will be shifted such that inner node.some anchor lies at the origin of the whole picture.

Rotations and scaling. The matrix node is never rotated or scaled, because the current coordinate transformation matrix is reset (except for the translational part) at the beginning of \pgfmatrix. This is intentional and will not change in the future. If you need to rotate or scale the matrix, you must install an appropriate canvas transformation yourself.

However, nodes and stuff inside the cell pictures can be rotated and scaled normally.

Callbacks. At the beginning and at the end of each cell the special macros \pgfmatrixbegincode, \pgfmatrixendcode and possibly \pgfmatrixemptycode are called. The effect is explained in Section 107.5.

Executing extra code. The parameter ⟨pre-code⟩ is executed at the beginning of the outermost TeX-group enclosing the matrix node. It is inside this TeX-group, but outside the matrix itself. It can be used for different purposes:

• 1. It can be used to simplify the next cell macro. For example, saying \let\&=\pgfmatrixnextcell allows you to use \& instead of \pgfmatrixnextcell. You can also set the catcode of & to active.

• 2. It can be used to issue an \aftergroup command. This allows you to regain control after the \pgfmatrix command. (If you do not know the \aftergroup command, you are probably blessed with a simple and happy life.)

Special considerations concerning macro expansion. As said before, the matrix is typeset using \halign internally. This command does a lot of strange and magic things like expanding the first macro of every cell in a most unusual manner. Here are some effects you may wish to be aware of:

• • It is not necessary to actually mention \pgfmatrixnextcell or \pgfmatrixendrow inside the ⟨matrix cells⟩. It suffices that the macros inside ⟨matrix cells⟩ expand to these macros sooner or later.

• • In particular, you can define clever macros that insert columns and rows as needed for special effects.

This macro sets the default separation list for columns. The details of the format of this list are explained in the description of the next command.

This command has two purposes: First, it is used to separate cells. Second, by providing the optional argument ⟨additional sep list⟩ you can modify the spacing between the columns that are separated by this command.

The optional ⟨additional sep list⟩ may only be provided when the \pgfmatrixnextcell command starts a new column. Normally, this will only be the case in the first row, but sometimes a later row has more elements than the first row. In this case, the \pgfmatrixnextcell commands that start the new columns in the later row may also have the optional argument. Once a column has been started, subsequent uses of this optional argument for the column have no effect.

To determine the space between the two columns that are separated by \pgfmatrixnextcell, the following algorithm is executed:

• 1. Both the default separation list (as set up by \pgfsetmatrixcolumnsep) and the ⟨additional sep list⟩ are processed, in this order. If the ⟨additional sep list⟩ argument is missing, only the default separation list is processed.

• 2. Both lists may contain dimensions, separated by commas, as well as occurrences of the keywords between origins and between borders.

• 3. All dimensions occurring in either list are added together to arrive at a dimension \(d\).

• 4. The last occurrence of either of the keywords is located. If neither keyword is present, we proceed as if between borders were present.

At the end of the algorithm, a dimension \(d\) has been computed and one of the two modes between borders and between origins has been determined. Depending on which mode has been determined, the following happens:

• • For the between borders mode, an additional horizontal space of \(d\) is added between the two columns. Note that \(d\) may be negative.

• • For the between origins mode, the spacing between the two columns is computed differently: Recall that the origins of the cell pictures in both pictures lie on two vertical lines. The spacing between the two columns is set up such that the horizontal distance between these two lines is exactly \(d\).

  This mode may only be used between columns already introduced in the first row.

All of the above rules boil down to the following effects:

• • A default spacing between columns should be set up using \pgfsetmatrixcolumnsep. For example, you might say \pgfsetmatrixcolumnsep{5pt} to have columns spaced apart by 5pt. You could say

  \pgfsetmatrixcolumnsep{1cm,between origins}
  

  to specify that horizontal space between the origins of cell pictures in adjacent columns should be 1cm by default – regardless of the actual size of the cell pictures.

• • You can now use the optional argument of \pgfmatrixnextcell to locally overrule the spacing between two columns. By saying \pgfmatrixnextcell[5pt] you add 5pt to the space between of the two columns, regardless of the mode.

  You can also (locally) change the spacing mode for these two columns. For example, even if the normal spacing mode is between origins, you can say

  \pgfmatrixnextcell[5pt,between borders]
  

  to locally change the mode for these columns to between borders.

This macro sets the default separation list for rows.

This command ends a line. The optional ⟨additional sep list⟩ is used to determine the spacing between the row being ended and the next row. The modes and the computation of \(d\) is done in the same way as for columns. For the last row the optional argument has no effect.

Inside matrices (and only there) the command \\ is set up to mean the same as this command.

This macro is executed for empty cells. This means that pgf uses some macro magic to determine whether a cell is empty (it immediately ends with \pgfmatrixemptycode or \pgfmatrixendrow) and, if so, put this macro inside the cell.

As can be seen, the macro is not executed for empty cells at the end of row when columns are added only later on.

This macro is executed at the beginning of non-empty cells. Correspondingly, \pgfmatrixendcode is added at the end of every non-empty cell.

Note that between \pgfmatrixbegincode and \pgfmatrixendcode there will not only be the contents of the cell. Rather, pgf will add some (invisible) commands for book-keeping purposes that involve \let and \gdef. In particular, it is not a good idea to have \pgfmatrixbegincode end with \csname and \pgfmatrixendcode start with \endcsname.

See the explanation above.

This counter stores the current row of the current cell of the matrix. Do not even think about changing this counter.

This counter stores the current column of the current cell of the matrix.