summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/ChildSpec.lua
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/ChildSpec.lua')
-rw-r--r--Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/ChildSpec.lua227
1 files changed, 227 insertions, 0 deletions
diff --git a/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/ChildSpec.lua b/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/ChildSpec.lua
new file mode 100644
index 00000000000..272af54e55e
--- /dev/null
+++ b/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/ChildSpec.lua
@@ -0,0 +1,227 @@
+-- Copyright 2012 by Till Tantau
+--
+-- This file may be distributed an/or modified
+--
+-- 1. under the LaTeX Project Public License and/or
+-- 2. under the GNU Public License
+--
+-- See the file doc/generic/pgf/licenses/LICENSE for more information
+
+-- @release $Header: /cvsroot/pgf/pgf/generic/pgf/graphdrawing/lua/pgf/gd/trees/ChildSpec.lua,v 1.4 2013/05/23 20:01:29 tantau Exp $
+
+
+
+---
+-- @section subsection {Specifying Missing Children}
+--
+-- \label{section-gd-missing-children}
+--
+-- In the present section we discuss keys for specifying missing children
+-- in a tree. For many certain kind of trees, in particular for binary
+-- trees, there are not just ``a certain number of children'' at each
+-- node, but, rather, there is a designated ``first'' (or ``left'') child
+-- and a ``second'' (or ``right'') child. Even if one of these children
+-- is missing and a node actually has only one child, the single child will
+-- still be a ``first'' or ``second'' child and this information should
+-- be taken into consideration when drawing a tree.
+--
+-- The first useful key for specifying missing children is
+-- |missing number of children| which allows you to state how many
+-- children there are, at minimum.
+--
+-- Once the minimum number of children has been set, we still need a way
+-- of specifying ``missing first children'' or, more generally, missing
+-- children that are not ``at the end'' of the list of children. For
+-- this, there are three methods:
+--
+-- \begin{enumerate}
+-- \item When you use the |child| syntax, you can use the |missing| key
+-- with the |child| command to indicate a missing child:
+-- \begin{codeexample}[]
+-- \tikz [binary tree layout, level distance=5mm]
+-- \node {a}
+-- child { node {b}
+-- child { node {c}
+-- child { node {d} }
+-- } }
+-- child { node {e}
+-- child [missing]
+-- child { node {f}
+-- child [missing]
+-- child { node {g}
+-- } } };
+-- \end{codeexample}
+-- \item When using the |graph| syntax, you can use an ``empty node'',
+-- which really must be completely empty and may not even contain a
+-- slash, to indicate a missing node:
+-- \begin{codeexample}[]
+-- \tikz [binary tree layout, level distance=5mm]
+-- \graph { a -> { b -> c -> d, e -> { , f -> { , g} } } };
+-- \end{codeexample}
+-- \item You can simply specify the index of a child directly using
+-- the key |desired child index|.
+-- \end{enumerate}
+--
+-- @end
+
+
+-- Imports
+local declare = require("pgf.gd.interface.InterfaceToAlgorithms").declare
+
+
+
+---
+--
+declare {
+ key = "minimum number of children",
+ type = "number",
+ initial = "0",
+
+ summary = [["
+ Specifies how many children a tree node must have at least. If
+ there are less, ``virtual'' children are added.
+ "]],
+ documentation = [["
+ When this key is set to |2| or more, the following happens: We first
+ compute a spanning tree for the graph, see
+ Section~\ref{subsection-gd-spanning-tree}. Then, whenever a node is
+ not a leaf in this spanning tree (when it has at least one child),
+ we add ``virtual'' or ``dummy'' nodes as children of the node until
+ the total number of real and dummy children is at least
+ \meta{number}. If there where at least \meta{number} children at the
+ beginning, nothing happens.
+
+ The new children are added after the existing children. This means
+ that, for instance, in a tree with \meta{number} set to |2|, for
+ every node with a single child, this child will be the first child
+ and the second child will be missing.
+ "]],
+ examples = [["
+ \tikz \graph [binary tree layout,level distance=5mm]
+ { a -> { b->c->d, e->f->g } };
+ "]]
+}
+
+---
+
+declare {
+ key = "desired child index",
+ type = "number",
+
+ summary = [["
+ Pass this key to a node to tell the graph drawing engine which child
+ number you ``desired'' for the node. Whenever all desires for the
+ children of a node are conflict-free, they will all be met; children
+ for which no desired indices were given will remain at their
+ position, whenever possible, but will ``make way'' for children with
+ a desired position.
+ "]],
+ documentation = [["
+ In detail, the following happens: We first
+ determine the total number of children (real or dummy) needed, which
+ is the maximum of the actual number of children, of the
+ \texttt{minimum number of children}, and of the highest desired
+ child index. Then we go over all children that have a desired child
+ index and put they at this position. If the position is already
+ taken (because some other child had the same desired index), the
+ next free position is used with a wrap-around occurring at the
+ end. Next, all children without a desired index are place using the
+ same mechanism, but they want to be placed at the position they had
+ in the original spanning tree.
+
+ While all of this might sound a bit complicated, the application of
+ the key in a binary tree is pretty straightforward: To indicate that
+ a node is a ``right'' child in a tree, just add \texttt{desired child index=2}
+ to it. This will make it a second child, possibly causing the fist
+ child to be missing. If there are two nodes specified as children of
+ a node, by saying \texttt{desired child index=}\meta{number} for one
+ of them, you will cause it be first or second child, depending on
+ \meta{number}, and cause the \emph{other} child to become the other
+ child.
+
+ Since |desired child index=2| is a bit long, the following shortcuts
+ are available: |first|, |second|, |third|, and |fourth|.
+ You might wonder why |second| is used rather than |right|. The
+ reason is that trees may also grow left and right and, additionally,
+ the |right| and |left| keys are already in use for
+ anchoring. Naturally, you can locally redefine them, if you want.
+ "]],
+ examples = {
+ [["
+ \tikz \graph [binary tree layout, level distance=5mm]
+ { a -> b[second] };
+ "]],
+ [["
+ \tikz \graph [binary tree layout, level distance=5mm]
+ { a -> { b[second], c} };
+ "]],
+ [["
+ \tikz \graph [binary tree layout, level distance=5mm]
+ { a -> { b, c[first]} };
+ "]],
+ [["
+ \tikz \graph [binary tree layout, level distance=5mm]
+ { a -> { b[second], c[second]} };
+ "]],
+ [["
+ \tikz \graph [binary tree layout, level distance=5mm]
+ { a -> { b[third], c[first], d} };
+ "]]
+ }
+}
+
+
+---
+
+declare {
+ key = "first",
+ use = {
+ { key = "desired child index", value = 1},
+ },
+
+ summary = [["
+ A shorthand for setting the desired child number to |1|.
+ "]]
+ }
+
+---
+
+declare {
+ key = "second",
+ use = {
+ { key = "desired child index", value = 2},
+ },
+
+ summary = [["
+ A shorthand for setting the desired child number to |2|.
+ "]]
+ }
+
+
+---
+
+declare {
+ key = "third",
+ use = {
+ { key = "desired child index", value = 3},
+ },
+
+ summary = [["
+ A shorthand for setting the desired child number to |3|.
+ "]]
+ }
+
+
+---
+
+declare {
+ key = "fourth",
+ use = {
+ { key = "desired child index", value = 4}
+ },
+
+ summary = [["
+ A shorthand for setting the desired child number to |4|.
+ "]]
+ }
+