% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Matrix Library}

\begin{tikzlibrary}{matrix}
  This library packages defines additional styles and options for
  creating matrices.
\end{tikzlibrary}


\subsection{Matrices of Nodes}

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.

\begin{itemize}
  \itemstyle{matrix of nodes}
  Conceptually, this style 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
    number}|-|\meta{column number}. For  example, if the matrix has
  the name |my matrix|, then the node in  the upper left cell will get
  the name |my matrix-1-1|. 
\begin{codeexample}[]
\begin{tikzpicture}
  \matrix (magic) [matrix of nodes]
  {
    8 & 1 & 6 \\
    3 & 5 & 7 \\
    4 & 9 & 2 \\
  };

  \draw[thick,red,->] (magic-1-1) |- (magic-2-3);
\end{tikzpicture}
\end{codeexample}

  You may wish to add options to certain nodes in the matrix. This can
  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
    cell.

\begin{codeexample}[]
\begin{tikzpicture}
  \tikzstyle{row 2 column 3}=[red]
  \matrix [matrix of nodes]
  {
    8 & 1 & 6 \\
    3 & 5 & 7 \\
    4 & 9 & 2 \\
  };
\end{tikzpicture}
\end{codeexample}
    
  \item At the beginning of a cell, you can use a special syntax. If a
    cell starts with a vertical bar, then everything between this bar
    and the next bar is passed on to the |node| command.
{\catcode`\|=12
\begin{codeexample}[]
\begin{tikzpicture}
  \matrix [matrix of nodes]
  {
    8 & 1 &         6 \\
    3 & 5 & |[red]| 7 \\
    4 & 9 &         2 \\
  };
\end{tikzpicture}
\end{codeexample}
}
  You can also use an option like \verb!|[red] (seven)|! to give a
  different name to the node.

  Note that the |&| character also takes an optional argument, which
  is an extra column skip.
{\catcode`\|=12  
\begin{codeexample}[]
\begin{tikzpicture}
  \matrix [matrix of nodes]
  {
    8 &[1cm] 1 &[3mm] |[red]| 6 \\
    3 &      5 &      |[red]| 7 \\
    4 &      9 &              2 \\
  };
\end{tikzpicture}
\end{codeexample}
}
  \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
    suppressed. This means that for this particular cell you can
    provide a totally different contents.

\begin{codeexample}[]
\begin{tikzpicture}
  \matrix [matrix of nodes]
  {
    8 & 1 & 6 \\
    3 & 5 & \node[red]{7}; \draw(0,0) circle(10pt);\\
    4 & 9 & 2 \\
  };
\end{tikzpicture}
\end{codeexample}
  \end{enumerate}
  \itemstyle{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.
{\catcode`\|=12
\begin{codeexample}[]
\begin{tikzpicture}
  \matrix [matrix of math nodes]
  {
    a_8 & a_1 &         a_6 \\
    a_3 & a_5 & |[red]| a_7 \\
    a_4 & a_9 &         a_2 \\
  };
\end{tikzpicture}
\end{codeexample}
}
  \itemoption{nodes in empty cells}\opt{|=|\meta{true or false}}
  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
  |matrix of math nodes|.
\begin{codeexample}[]
\begin{tikzpicture}
  \matrix [matrix of math nodes,nodes={circle,draw}]
  {
    a_8 &     & a_6 \\
    a_3 &     & a_7 \\
    a_4 & a_9 &     \\
  };
\end{tikzpicture}
\end{codeexample}
\begin{codeexample}[]
\begin{tikzpicture}
  \matrix [matrix of math nodes,nodes={circle,draw},nodes in empty cells]
  {
    a_8 &     & a_6 \\
    a_3 &     & a_7 \\
    a_4 & a_9 &     \\
  };
\end{tikzpicture}
\end{codeexample}
\end{itemize}


\subsection{Delimiters}

Delimiters are parantheses or braces to the left and right of a
formula or a matrix. The matrix library offers options for adding such
delimiters to a matrix. However, delimiters can actually be added to
any node that has the standard anchors |north|, |south|, |north west|
and so on. In particular, you can add delimiters to any |rectangle|
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}
  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.
\begin{codeexample}[]
\begin{tikzpicture}
  \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
  {
    a_8 & a_1 & a_6 \\
    a_3 & a_5 & a_7 \\
    a_4 & a_9 & a_2 \\
  };
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \node [fill=red!20,left delimiter=(,right delimiter=\}]
    {$\displaystyle\int_0^1 x\,dx$};
\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.

  \itemstyle{every left delimiter}
  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]
  \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
  {
    a_8 & a_1 & a_6 \\
    a_3 & a_5 & a_7 \\
    a_4 & a_9 & a_2 \\
  };
\end{tikzpicture}
\end{codeexample}

  \itemoption{right delimiter}|=|\meta{delimiter}
  Works as above.

  \itemstyle{every right delimiter}
  Works as above.

  \itemoption{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}[]
\begin{tikzpicture}
  \matrix [matrix of math nodes,%
           left delimiter=\|,right delimiter=\rmoustache,%
           above delimiter=(,below delimiter=\}]
  {
    a_8 & a_1 & a_6 \\
    a_3 & a_5 & a_7 \\
    a_4 & a_9 & a_2 \\
  };
\end{tikzpicture}
\end{codeexample}

  \itemstyle{every above delimiter}
  Works as above.

  \itemoption{below delimiter}|=|\meta{delimiter}
  works as above.

  \itemstyle{every below delimiter}
  Works as above.
\end{itemize}



%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "pgfmanual-pdftex-version"
%%% End: 
