Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-design.tex

raw
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.