| 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{Design Principles} |
| 12 |
|
| 13 |
This section describes the design principles behind the \tikzname\ frontend, |
| 14 |
where \tikzname\ means ``\tikzname\ ist \emph{kein} Zeichenprogramm''. To use |
| 15 |
\tikzname, as a \LaTeX\ user say |\usepackage{tikz}| somewhere in the preamble, |
| 16 |
as a plain \TeX\ user say |\input tikz.tex|. \tikzname's job is to make your |
| 17 |
life easier by providing an easy-to-learn and easy-to-use syntax for describing |
| 18 |
graphics. |
| 19 |
|
| 20 |
The commands and syntax of \tikzname\ were influenced by several sources. The |
| 21 |
basic command names and the notion of path operations is taken from |
| 22 |
\textsc{metafont}, the option mechanism comes from \textsc{pstricks}, the |
| 23 |
notion of styles is reminiscent of \textsc{svg}, the graph syntax is taken from |
| 24 |
\textsc{graphviz}. To make it all work together, some compromises were |
| 25 |
necessary. I also added some ideas of my own, like coordinate transformations. |
| 26 |
|
| 27 |
The following basic design principles underlie \tikzname: |
| 28 |
% |
| 29 |
\begin{enumerate} |
| 30 |
\item Special syntax for specifying points. |
| 31 |
\item Special syntax for path specifications. |
| 32 |
\item Actions on paths. |
| 33 |
\item Key--value syntax for graphic parameters. |
| 34 |
\item Special syntax for nodes. |
| 35 |
\item Special syntax for trees. |
| 36 |
\item Special syntax for graphs. |
| 37 |
\item Grouping of graphic parameters. |
| 38 |
\item Coordinate transformation system. |
| 39 |
\end{enumerate} |
| 40 |
|
| 41 |
|
| 42 |
\subsection{Special Syntax For Specifying Points} |
| 43 |
|
| 44 |
\tikzname\ provides a special syntax for specifying points and coordinates. In |
| 45 |
the simplest case, you provide two \TeX\ dimensions, separated by commas, in |
| 46 |
round brackets as in |(1cm,2pt)|. |
| 47 |
|
| 48 |
You can also specify a point in polar coordinates by using a colon instead of a |
| 49 |
comma as in |(30:1cm)|, which means ``1cm in a 30 degrees direction''. |
| 50 |
|
| 51 |
If you do not provide a unit, as in |(2,1)|, you specify a point in \pgfname's |
| 52 |
$xy$-coordinate system. By default, the unit $x$-vector goes 1cm to the right |
| 53 |
and the unit $y$-vector goes 1cm upward. |
| 54 |
|
| 55 |
By specifying three numbers as in |(1,1,1)| you specify a point in \pgfname's |
| 56 |
$xyz$-coordinate system. |
| 57 |
|
| 58 |
It is also possible to use an anchor of a previously defined shape as in |
| 59 |
|(first node.south)|. |
| 60 |
|
| 61 |
You can add two plus signs before a coordinate as in |++(1cm,0pt)|. This means |
| 62 |
``1cm to the right of the last point used''. This allows you to easily specify |
| 63 |
relative movements. For example, |(1,0) ++(1,0) ++(0,1)| specifies the three |
| 64 |
coordinates |(1,0)|, then |(2,0)|, and |(2,1)|. |
| 65 |
|
| 66 |
Finally, instead of two plus signs, you can also add a single one. This also |
| 67 |
specifies a point in a relative manner, but it does not ``change'' the current |
| 68 |
point used in subsequent relative commands. For example, |(1,0) +(1,0) +(0,1)| |
| 69 |
specifies the three coordinates |(1,0)|, then |(2,0)|, and |(1,1)|. |
| 70 |
|
| 71 |
|
| 72 |
\subsection{Special Syntax For Path Specifications} |
| 73 |
|
| 74 |
When creating a picture using \tikzname, your main job is the specification of |
| 75 |
\emph{paths}. A path is a series of straight or curved lines, which need not be |
| 76 |
connected. \tikzname\ makes it easy to specify paths, partly using the syntax |
| 77 |
of \textsc{metapost}. For example, to specify a triangular path you use |
| 78 |
% |
| 79 |
\begin{codeexample}[code only] |
| 80 |
(5pt,0pt) -- (0pt,0pt) -- (0pt,5pt) -- cycle |
| 81 |
\end{codeexample} |
| 82 |
% |
| 83 |
and you get \tikz \draw (5pt,0pt) -- (0pt,0pt) -- (0pt,5pt) -- cycle; when you |
| 84 |
draw this path. |
| 85 |
|
| 86 |
|
| 87 |
\subsection{Actions on Paths} |
| 88 |
|
| 89 |
A path is just a series of straight and curved lines, but it is not yet |
| 90 |
specified what should happen with it. One can \emph{draw} a path, \emph{fill} a |
| 91 |
path, \emph{shade} it, \emph{clip} it, or do any combination of these. Drawing |
| 92 |
(also known as \emph{stroking}) can be thought of as taking a pen of a certain |
| 93 |
thickness and moving it along the path, thereby drawing on the canvas. Filling |
| 94 |
means that the interior of the path is filled with a uniform color. Obviously, |
| 95 |
filling makes sense only for \emph{closed} paths and a path is automatically |
| 96 |
closed prior to filling, if necessary. |
| 97 |
|
| 98 |
Given a path as in |\path (0,0) rectangle (2ex,1ex);|, you can draw it by |
| 99 |
adding the |draw| option as in |\path[draw] (0,0) rectangle (2ex,1ex);|, which |
| 100 |
yields \tikz \path[draw] (0,0) rectangle (2ex,1ex);. The |\draw| command is |
| 101 |
just an abbreviation for |\path[draw]|. To fill a path, use the |fill| option |
| 102 |
or the |\fill| command, which is an abbreviation for |\path[fill]|. The |
| 103 |
|\filldraw| command is an abbreviation for |\path[fill,draw]|. Shading is |
| 104 |
caused by the |shade| option (there are |\shade| and |\shadedraw| |
| 105 |
abbreviations) and clipping by the |clip| option. There is also a |\clip| |
| 106 |
command, which does the same as |\path[clip]|, but not commands like |
| 107 |
|\drawclip|. Use, say, |\draw[clip]| or |\path[draw,clip]| instead. |
| 108 |
|
| 109 |
All of these commands can only be used inside |{tikzpicture}| environments. |
| 110 |
|
| 111 |
\tikzname\ allows you to use different colors for filling and stroking. |
| 112 |
|
| 113 |
|
| 114 |
\subsection{Key--Value Syntax for Graphic Parameters} |
| 115 |
|
| 116 |
Whenever \tikzname\ draws or fills a path, a large number of graphic parameters |
| 117 |
influences the rendering. Examples include the colors used, the dashing |
| 118 |
pattern, the clipping area, the line width, and many others. In \tikzname, all |
| 119 |
these options are specified as lists of so called key--value pairs, as in |
| 120 |
|color=red|, that are passed as optional parameters to the path drawing and |
| 121 |
filling commands. This usage is similar to \textsc{pstricks}. For example, the |
| 122 |
following will draw a thick, red triangle; |
| 123 |
% |
| 124 |
\begin{codeexample}[] |
| 125 |
\tikz \draw[line width=2pt,color=red] (1,0) -- (0,0) -- (0,1) -- cycle; |
| 126 |
\end{codeexample} |
| 127 |
|
| 128 |
|
| 129 |
\subsection{Special Syntax for Specifying Nodes} |
| 130 |
|
| 131 |
\tikzname\ introduces a special syntax for adding text or, more generally, |
| 132 |
nodes to a graphic. When you specify a path, add nodes as in the following |
| 133 |
example: |
| 134 |
% |
| 135 |
\begin{codeexample}[] |
| 136 |
\tikz \draw (1,1) node {text} -- (2,2); |
| 137 |
\end{codeexample} |
| 138 |
% |
| 139 |
Nodes are inserted at the current position of the path, but either \emph{after} |
| 140 |
(the default) or \emph{before} the complete path is rendered. When special |
| 141 |
options are given, as in |\draw (1,1) node[circle,draw] {text};|, the text is |
| 142 |
not just put at the current position. Rather, it is surrounded by a circle and |
| 143 |
this circle is ``drawn''. |
| 144 |
|
| 145 |
You can add a name to a node for later reference either by using the option |
| 146 |
|name=|\meta{node name} or by stating the node name in parentheses outside the |
| 147 |
text as in |node[circle](name){text}|. |
| 148 |
|
| 149 |
Predefined shapes include |rectangle|, |circle|, and |ellipse|, but it is |
| 150 |
possible (though a bit challenging) to define new shapes. |
| 151 |
|
| 152 |
|
| 153 |
\subsection{Special Syntax for Specifying Trees} |
| 154 |
|
| 155 |
The ``node syntax'' can also be used to draw trees: A |node| can be followed by |
| 156 |
any number of children, each introduced by the keyword |child|. The children |
| 157 |
are nodes themselves, each of which may have children in turn. |
| 158 |
% |
| 159 |
\begin{codeexample}[] |
| 160 |
\begin{tikzpicture} |
| 161 |
\node {root} |
| 162 |
child {node {left}} |
| 163 |
child {node {right} |
| 164 |
child {node {child}} |
| 165 |
child {node {child}} |
| 166 |
}; |
| 167 |
\end{tikzpicture} |
| 168 |
\end{codeexample} |
| 169 |
% |
| 170 |
Since trees are made up from nodes, it is possible to use options to modify the |
| 171 |
way trees are drawn. Here are two examples of the above tree, redrawn with |
| 172 |
different options: |
| 173 |
% |
| 174 |
\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,trees}}] |
| 175 |
\begin{tikzpicture} |
| 176 |
[edge from parent fork down, sibling distance=15mm, level distance=15mm, |
| 177 |
every node/.style={fill=red!30,rounded corners}, |
| 178 |
edge from parent/.style={red,-{Circle[open]},thick,draw}] |
| 179 |
\node {root} |
| 180 |
child {node {left}} |
| 181 |
child {node {right} |
| 182 |
child {node {child}} |
| 183 |
child {node {child}} |
| 184 |
}; |
| 185 |
\end{tikzpicture} |
| 186 |
\end{codeexample} |
| 187 |
|
| 188 |
\begin{codeexample}[] |
| 189 |
\begin{tikzpicture} |
| 190 |
[parent anchor=east,child anchor=west,grow=east, |
| 191 |
sibling distance=15mm, level distance=15mm, |
| 192 |
every node/.style={ball color=red,circle,text=white}, |
| 193 |
edge from parent/.style={draw,dashed,thick,red}] |
| 194 |
\node {root} |
| 195 |
child {node {left}} |
| 196 |
child {node {right} |
| 197 |
child {node {child}} |
| 198 |
child {node {child}} |
| 199 |
}; |
| 200 |
\end{tikzpicture} |
| 201 |
\end{codeexample} |
| 202 |
|
| 203 |
|
| 204 |
\subsection{Special Syntax for Graphs} |
| 205 |
|
| 206 |
The |\node| command gives you fine control over where nodes should be placed, |
| 207 |
what text they should use, and what they should look like. However, when you |
| 208 |
draw a graph, you typically need to create numerous fairly similar nodes that |
| 209 |
only differ with respect to the name they show. In these cases, the |graph| |
| 210 |
syntax can be used, which is another syntax layer build ``on top'' of the node |
| 211 |
syntax. |
| 212 |
% |
| 213 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 214 |
\tikz \graph [grow down, branch right] { |
| 215 |
root -> { left, right -> {child, child} } |
| 216 |
}; |
| 217 |
\end{codeexample} |
| 218 |
% |
| 219 |
The syntax of the |graph| command extends the so-called \textsc{dot}-notation |
| 220 |
used in the popular \textsc{graphviz} program. |
| 221 |
|
| 222 |
Depending on the version of \TeX\ you use (it must allow you to call Lua code, |
| 223 |
which is the case for Lua\TeX), you can also ask \tikzname\ to do automatically |
| 224 |
compute good positions for the nodes of a graph using one of several integrated |
| 225 |
\emph{graph drawing algorithms}. |
| 226 |
|
| 227 |
|
| 228 |
\subsection{Grouping of Graphic Parameters} |
| 229 |
|
| 230 |
Graphic parameters should often apply to several path drawing or filling |
| 231 |
commands. For example, we may wish to draw numerous lines all with the same |
| 232 |
line width of 1pt. For this, we put these commands in a |{scope}| environment |
| 233 |
that takes the desired graphic options as an optional parameter. Naturally, the |
| 234 |
specified graphic parameters apply only to the drawing and filling commands |
| 235 |
inside the environment. Furthermore, nested |{scope}| environments or |
| 236 |
individual drawing commands can override the graphic parameters of outer |
| 237 |
|{scope}| environments. In the following example, three red lines, two green |
| 238 |
lines, and one blue line are drawn: |
| 239 |
% |
| 240 |
\begin{codeexample}[] |
| 241 |
\begin{tikzpicture} |
| 242 |
\begin{scope}[color=red] |
| 243 |
\draw (0mm,10mm) -- (10mm,10mm); |
| 244 |
\draw (0mm, 8mm) -- (10mm, 8mm); |
| 245 |
\draw (0mm, 6mm) -- (10mm, 6mm); |
| 246 |
\end{scope} |
| 247 |
\begin{scope}[color=green] |
| 248 |
\draw (0mm, 4mm) -- (10mm, 4mm); |
| 249 |
\draw (0mm, 2mm) -- (10mm, 2mm); |
| 250 |
\draw[color=blue] (0mm, 0mm) -- (10mm, 0mm); |
| 251 |
\end{scope} |
| 252 |
\end{tikzpicture} |
| 253 |
\end{codeexample} |
| 254 |
|
| 255 |
The |{tikzpicture}| environment itself also behaves like a |{scope}| |
| 256 |
environment, that is, you can specify graphic parameters using an optional |
| 257 |
argument. These optional apply to all commands in the picture. |
| 258 |
|
| 259 |
|
| 260 |
\subsection{Coordinate Transformation System} |
| 261 |
|
| 262 |
\tikzname\ supports both \pgfname's \emph{coordinate} transformation system to |
| 263 |
perform transformations as well as \emph{canvas} transformations, a more |
| 264 |
low-level transformation system. (For details on the difference between |
| 265 |
coordinate transformations and canvas transformations see |
| 266 |
Section~\ref{section-design-transformations}.) |
| 267 |
|
| 268 |
The syntax is set up in such a way that it is harder to use canvas |
| 269 |
transformations than coordinate transformations. There are two reasons for |
| 270 |
this: First, the canvas transformation must be used with great care and often |
| 271 |
results in ``bad'' graphics with changing line width and text in wrong sizes. |
| 272 |
Second, \pgfname\ loses track of where nodes and shapes are positioned when |
| 273 |
canvas transformations are used. So, in almost all circumstances, you should |
| 274 |
use coordinate transformations rather than canvas transformations. |