diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-mindmaps.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-library-mindmaps.tex | 523 |
1 files changed, 523 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-mindmaps.tex b/graphics/pgf/base/doc/pgfmanual-en-library-mindmaps.tex new file mode 100644 index 0000000000..646f12bf6c --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-library-mindmaps.tex @@ -0,0 +1,523 @@ +% Copyright 2019 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{Mindmap Drawing Library} + +\begin{tikzlibrary}{mindmap} + This packages provides styles for drawing mindmap diagrams. +\end{tikzlibrary} + + +\subsection{Overview} + +This library is intended to make the creation of mindmaps or concept maps +easier. A \emph{mindmap} is a graphical representation of a concept together +with related concepts and annotations. Mindmaps are, essentially, trees, +possibly with a few extra edges added, but they are usually drawn in a special +way: The root concept is placed in the middle of the page and is drawn as a +huge circle, ellipse, or cloud. The related concepts then ``leave'' this root +concept via branch-like tendrils. + +The |mindmap| library of \tikzname\ produces mindmaps that look a bit different +from the standard mindmaps: While the big root concept is still a circle, +related concepts are also depicted as (smaller) circles. The related concepts +are linked to the root concept via organic-looking connections. The overall +effect is visually rather pleasing, but readers may not immediately think of a +mindmap when they see a picture created with this library. + +Although it is not strictly necessary, you will usually create mindmaps using +\tikzname's tree mechanism and some of the styles and macros of the package +work best when used inside trees. However, it is still possible and sometimes +necessary to treat parts of a mindmap as a graph with arbitrary edges and this +is also possible. + + +\subsection{The Mindmap Style} + +Every mindmap should be put in a scope or a picture where the |mindmap| style +is used. This style installs some internal settings. + +\begin{stylekey}{/tikz/mindmap} + Use this style with all pictures or at least scopes that contain a mindmap. + It installs a whole bunch of settings that are useful for drawing mindmaps. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\tikz[mindmap,concept color=red!50] + \node [concept] {Root concept} + child[grow=right] {node[concept] {Child concept}}; +\end{codeexample} + % + The sizes of concepts are predefined in such a way that a medium-size + mindmap will fit on an A4 page (more or less). + % + \begin{stylekey}{/tikz/every mindmap} + This style is included by the |mindmap| style. Change this style to add + special settings to your mindmaps. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\tikz[large mindmap,concept color=red!50] + \node [concept] {Root concept} + child[grow=right] {node[concept] {Child concept}}; +\end{codeexample} + \end{stylekey} + + \paragraph{Remark:} + Note that |mindmap| redefines |font| sizes and |sibling angle| depending on + the current concept level (i.e.\ inside of |level 1 concept|, + |level 2 concept| etc.). Thus, if you need to redefine these variables, use + + |level 1 concept/.append style={font=\small}| + + \noindent or + + |level 2 concept/.append style={sibling distance=90}| + + \noindent \emph{after} the |mindmap| style. +\end{stylekey} + +\begin{stylekey}{/tikz/small mindmap} + This style includes the |mindmap| style, but additionally changes the + default size of concepts, fonts and distances so that a medium-sized + mindmap will fit on an A5 page (A5 pages are half as large as A4 pages). + Mindmaps with |small mindmap| will also fit onto a standard frame of the + |beamer| package. +\end{stylekey} + +\begin{stylekey}{/tikz/large mindmap} + This style includes the |mindmap| style, but additionally changes the + default size of concepts, fonts and distances so that a medium-sized + mindmap will fit on an A3 page (A3 pages are twice as large as A4 pages). +\end{stylekey} + +\begin{stylekey}{/tikz/huge mindmap} + This style causes concepts to be even bigger and it is best used with A2 + paper and above. +\end{stylekey} + + +\subsection{Concepts Nodes} + +The basic entities of mindmaps are called \emph{concepts} in \tikzname. A +concept is a node of style |concept| and it must be circular for some of the +connection macros to work. + + +\subsubsection{Isolated Concepts} + +The following styles influence how isolated concepts are rendered: + +\begin{stylekey}{/tikz/concept} + This style should be used with all nodes that are concepts, although some + styles like |extra concept| install this style automatically. + + Basically, this style makes the concept node circular and installs a + uniform color called |concept color|, see below. Additionally, the style + |every concept| is called. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\tikz[mindmap,concept color=red!50] \node [concept] {Some concept}; +\end{codeexample} + + \begin{stylekey}{/tikz/every concept} + In order to change the appearance of concept nodes, you should change + this style. Note, however, that the color of a concept should be + uniform for some of the connection bar stuff to work, so you should not + change the color or the draw/fill state of concepts using this option. + It is mostly useful for changing the text color and font. + \end{stylekey} + + \begin{key}{/tikz/concept color=\meta{color}} + This option tells \tikzname\ which color should be used for filling and + stroking concepts. The difference between this option and just setting + |every concept| to the desired color is that this option allows + \tikzname\ to keep track of the colors used for concepts. This is + important when you \emph{change} the color between two connected + concepts. In this case, \tikzname\ can automatically create a shading + that provides a smooth transition between the old and the new concept + color; we will come back to this in the next section. + \end{key} +\end{stylekey} + +\begin{stylekey}{/tikz/extra concept} + This style is intended for concepts that are not part of the ``mindmap + tree'', but stand beside it. Typically, they will have a subdued color or + be smaller. In order to have these concepts appear in a uniform way and in + order to indicate in the code that these concepts are additional, you can + use this style. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\begin{tikzpicture}[mindmap,concept color=blue!80] + \node [concept] {Root concept}; + \node [extra concept] at (10,0) {extra concept}; +\end{tikzpicture} +\end{codeexample} + % + \begin{stylekey}{/tikz/every extra concept} + Change this style to change the appearance of extra concepts. + \end{stylekey} +\end{stylekey} + + +\subsubsection{Concepts in Trees} + +As pointed out earlier, \tikzname\ assumes that your mindmap is built using the +|child| facilities of \tikzname. There are numerous options that influence how +concepts are rendered at the different levels of a tree. + +\begin{stylekey}{/tikz/root concept} + This style is used for the roots of mindmap trees. By adding something to + this, you can change how the root of a mindmap will be rendered. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\tikz + [root concept/.append style={concept color=blue!80,minimum size=3.5cm}, + mindmap] + \node [concept] {Root concept}; +\end{codeexample} + + Note that styles like |large mindmap| redefine these styles, so you should + add something to this style only inside the picture. +\end{stylekey} + +\begin{stylekey}{/tikz/level 1 concept} + The |mindmap| style adds this style to the |level 1| style. This means that + the first level children of a mindmap tree will use this style. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\tikz + [root concept/.append style={concept color=blue!80}, + level 1 concept/.append style={concept color=red!50}, + mindmap] + \node [concept] {Root concept} + child[grow=30] {node[concept] {child}} + child[grow=0 ] {node[concept] {child}}; +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/tikz/level 2 concept} + Works like |level 1 concept|, only for second level children. +\end{stylekey} + +\begin{stylekey}{/tikz/level 3 concept} + Works like |level 1 concept|. +\end{stylekey} + +\begin{stylekey}{/tikz/level 4 concept} + Works like |level 1 concept|. Note that there are no fifth and higher level + styles, you need to modify |level 5| directly in such cases. +\end{stylekey} + +\begin{key}{/tikz/concept color=\meta{color}} + We saw already that this option is used to change the color of concepts. We + now have a look at its effect when used on child nodes of a concept. + Normally, this option simply changes the color of the children. However, + when the option is given as an option to the |child| operation (and not to + the |node| operation and also not as an option to all children via the + |level 1| style), \tikzname\ will smoothly change the concept color from + the parent's color to the color of the child concept. + + Here is an example: + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\tikz[mindmap,concept color=blue!80] + \node [concept] {Root concept} + child[concept color=red,grow=30] {node[concept] {Child concept}} + child[concept color=orange,grow=0] {node[concept] {Child concept}}; +\end{codeexample} + + In order to have a concept color which changes with the hierarchy level, a + tiny bit of magic is needed: +% FIXME: is this a bug in the software!? The root concept is black!? +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\tikz[mindmap,text=white, + root concept/.style={concept color=blue}, + level 1 concept/.append style= + {every child/.style={concept color=blue!50}}] + \node [concept] {Root concept} + child[grow=30] {node[concept] {child}} + child[grow=0 ] {node[concept] {child}}; +\end{codeexample} + % +\end{key} + + +\subsection{Connecting Concepts} + +\subsubsection{Simple Connections} + +The easiest way to connect two concepts is to draw a line between them. In +order to give such lines a consistent appearance, it is recommendable to use +the following style when drawing such lines: + +\begin{stylekey}{/tikz/concept connection} + This style can be used for lines between two concepts. Feel free to + redefine this style. +\end{stylekey} + +A problem arises when you need to connect concepts after the main mindmap has +been drawn. In this case you will want the connection lines to lie +\emph{behind} the main mindmap. However, you can draw the lines only after the +coordinates of the concepts have been determined. In this case you should place +the connecting lines on a background layer as in the following example: + +\begin{codeexample}[preamble={\usetikzlibrary{backgrounds,mindmap}}] +\begin{tikzpicture} + [root concept/.append style={concept color=blue!20,minimum size=2cm}, + level 1 concept/.append style={sibling angle=45}, + mindmap] + \node [concept] {Root concept} + [clockwise from=45] + child { node[concept] (c1) {child}} + child { node[concept] (c2) {child}} + child { node[concept] (c3) {child}}; + \begin{pgfonlayer}{background} + \draw [concept connection] (c1) edge (c2) + edge (c3) + (c2) edge (c3); + \end{pgfonlayer} +\end{tikzpicture} +\end{codeexample} + + +\subsubsection{The Circle Connection Bar Decoration} + +Instead of a simple line between two concepts, you can also add a bar between +the two nodes that has slightly organic ends. These bars are also used by +default as the edges from parents in the mindmap tree. + +For the drawing of the bars a special decoration is used, which is defined in +the |mindmap| library: + +\begin{decoration}{circle connection bar} + This decoration can be used to connect two circles. The start of the + to-be-decorated path should lie on the border of the first circle, the end + should lie on the border of the second circle. The following two decoration + keys should be initialized with the sizes of the circles: + % + \begin{itemize} + \item |start radius| + \item |end radius| + \end{itemize} + % + Furthermore, the following two decoration keys influence the decoration: + % + \begin{itemize} + \item |amplitude| + \item |angle| + \end{itemize} + % + The decoration turns a straight line into a path that starts on the border + of the first circle at the specified angle relative to the line connecting + the centers of the circles. The path then changes into a rectangle whose + thickness is given by the amplitude. Finally, the path ends with the same + angles on the second circle. + + Here is an example that should make this clearer: + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\begin{tikzpicture} + [decoration={start radius=1cm,end radius=.5cm,amplitude=2mm,angle=30}] + \fill[blue!20] (0,0) circle (1cm); + \fill[red!20] (2.5,0) circle (.5cm); + + \filldraw [draw=red,fill=black, + decorate,decoration=circle connection bar] (1,0) -- (2,0); +\end{tikzpicture} +\end{codeexample} + + As can be seen, the decorated path consists of three parts and is not + really useful for drawing. However, if you fill the decorated path only, + and if you use the same color as for the circles, the result is better. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\begin{tikzpicture} + [blue!50,decoration={start radius=1cm, + end radius=.5cm,amplitude=2mm,angle=30}] + \fill (0,0) circle (1cm); + \fill (2.5,0) circle (.5cm); + + \fill [decorate,decoration=circle connection bar] (1,0) -- (2,0); +\end{tikzpicture} +\end{codeexample} + + In the above example you may notice the small white line between the + circles and the decorated path. This is due to rounding errors. + Unfortunately, for larger distances, the errors can accumulate quite + strongly, especially since \tikzname\ and \TeX\ are not very good at + computing square roots. For this reason, it is a good idea to make the + circles slightly larger to cover up such problems. When using nodes of + shape |circle|, you can just add the |draw| option with a |line width| of + one or two points (for very large distances you may need line width up to + 4pt). + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\begin{tikzpicture} + [blue!50,decoration={start radius=1cm, + end radius=.5cm,amplitude=2mm,angle=30}] + \fill (0,0) circle (1cm+1pt); + \fill (2.4,0) circle (.5cm+1pt); + + \fill [decorate,decoration=circle connection bar] (1,0) -- (1.9,0); +\end{tikzpicture} +\end{codeexample} + + % FIXME: this paragraph appears to be deprecated: + %Note the slightly strange |outer sep=0pt|. This is needed so that + %the decorated path lies on the border of the filled circle, not on the + %border of the stroked circle (which is slightly larger and this + %slightly larger size is exactly what we wish to use to cover up the + %rounding errors). +\end{decoration} + + +\subsubsection{The Circle Connection Bar To-Path} + +The |circle connection bar| decoration is a bit complicated to use. Especially +specifying the radii is quite bothersome (the amplitude and the angle can be +set once and for all). For this reason, the |mindmap| library defines a special +to-path that performs the necessary computations for you. + +\begin{stylekey}{/tikz/circle connection bar} + This style installs a rather involved to-path. Unlike normal to-paths, this + path requires that the start and the target of the to-path are named nodes + of shape |circle| -- if this is not the case, this path will produce + errors. + + Assuming that the start and the target are circles, the to-path will first + compute the radii of these circles (by measuring the distance from the + |center| anchor to some anchor on the border) and will set the + |start circle| keys accordingly. Next, the |fill| option is set to the + |concept color| while |draw=none| is set. The decoration is set to + |circle connection bar|. Finally, the following style is included: + % + \begin{stylekey}{/tikz/every circle connection bar} + Redefine this style to change the appearance of circle connection bar + to-paths. + \end{stylekey} + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\begin{tikzpicture}[concept color=blue!50,blue!50,outer sep=0pt] + \node (n1) at (0,0) [circle,minimum size=2cm,fill,draw,thick] {}; + \node (n2) at (2.5,0) [circle,minimum size=1cm,fill,draw,thick] {}; + + \path (n1) to[circle connection bar] (n2); +\end{tikzpicture} +\end{codeexample} + % + Note that it is not a good idea to have more than one |to| operation + together with the option |circle connection bar| in a single |\path|. Use + the |edge| operation, instead, for creating multiple connections and this + operation creates a new scope for each edge. +\end{stylekey} + +In a mindmap we sometimes want colors to change from one concept color to +another. Then, the connection bar should, ideally, consist of a smooth +transition between these two colors. Getting this right using shadings is a bit +tricky if you try this ``by hand'', so the |mindmap| library provides a +special option for facilitating this procedure. + +\begin{key}{/tikz/circle connection bar switch color=|from (|\meta{first color}|) to (|\meta{second color}|)|} + This style works similarly to the |circle connection bar|. The only + difference is that instead of filling the path with a single color a + shading is used. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\begin{tikzpicture}[outer sep=0pt] + \node (n1) at (0,0) [circle,minimum size=2cm,fill,draw,thick,red] {}; + \node (n2) at (30:2.5) [circle,minimum size=1cm,fill,draw,thick,blue] {}; + + \path (n1) to[circle connection bar switch color=from (red) to (blue)] (n2); +\end{tikzpicture} +\end{codeexample} + % +\end{key} + + +\subsubsection{Tree Edges} + +Most of the time, concepts in a mindmap are connected automatically when the +mindmap is built as a tree. The reason is that the |mindmap| installs a +|circle connection bar| path as the |edge from parent path|. Also, the +|mindmap| option takes care of things like setting the correct |draw| and +|outer sep| settings and some other stuff. + +In detail, the |mindmap| option sets the |edge from parent path| to a path that +uses the to-path |circle connection bar| to connect the parent node and the +child node. The |concept color| option (locally) changes this by using +|circle connection bar switch color| instead with the from-color set to the old +(parent's) concept color and the to-color set to the new (child's) concept +color. This means that when you provide the |concept color| option to a |child| +command, the color will change from the parent's concept color to the specified +color. + +Let us now build a tree that way. Please note that we pass the |concept color| +to the respective |child| and not to a |node| under it. +% +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\begin{tikzpicture} + \path[mindmap,concept color=black,text=white] + node[concept] {Computer Science} + [clockwise from=0] + % note that `sibling angle' can only be defined in + % `level 1 concept/.append style={}' + child[concept color=green!50!black] { + node[concept] {practical} + [clockwise from=90] + child { node[concept] {algorithms} } + child { node[concept] {data structures} } + child { node[concept] {pro\-gramming languages} } + child { node[concept] {software engineer\-ing} } + } + % note that the `concept color' is passed to the `child'(!) + child[concept color=blue] { + node[concept] {applied} + [clockwise from=-30] + child { node[concept] {databases} } + child { node[concept] {WWW} } + } + child[concept color=red] { node[concept] {technical} } + child[concept color=orange] { node[concept] {theoretical} }; +\end{tikzpicture} +\end{codeexample} + + +\subsection{Adding Annotations} + +An \emph{annotation} is some text outside a mindmap that, unlike an extra +concept, simply explains something in the mindmap. The following style is +mainly intended to help readers of the code see that a node in an annotation +node. + +\begin{stylekey}{/tikz/annotation} + This style indicates that a node is an annotation node. It includes the + style |every annotation|, which allows you to change this style in a + convenient fashion. + % +\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}] +\begin{tikzpicture} + [mindmap,concept color=blue!80, + every annotation/.style={fill=red!20}] + \node [concept] (root) {Root concept}; + + \node [annotation,right] at (root.east) + {The root concept is, in general, the most important concept.}; +\end{tikzpicture} +\end{codeexample} + % + \begin{stylekey}{/tikz/every annotation} + This style is included by |annotation|. + \end{stylekey} +\end{stylekey} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: |