1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html >
<head><title>18 Design Principles</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="generator" content="TeX4ht (http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html)">
<meta name="originator" content="TeX4ht (http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html)">
<!-- html -->
<meta name="src" content="pgfmanual.tex">
<meta name="date" content="2005-10-23 18:34:00">
<link rel="stylesheet" type="text/css" href="pgfmanual.css">
</head><body
>
<div class="crosslinks"><p class="noindent">[<a
href="pgfmanualse19.html" >next</a>] [<a
href="#tailpgfmanualse18.html">tail</a>] [<a
href="pgfmanual.html#pgfmanualse18.html" >up</a>] </p></div>
<h3 class="sectionHead"><span class="titlemark">18 </span> <a
id="x19-18700018"></a>Design Principles</h3>
<!--l. 10--><p class="noindent">This section describes the basic layer of <span
class="cmcsc-10"><small
class="small-caps">P</small><small
class="small-caps">G</small><small
class="small-caps">F</small></span>. This layer is build on top of the system layer. Whereas the system
layer just provides the absolute minimum for drawing graphics, the basic layer provides numerous commands that
make it possible to create sophisticated graphics easily and also quickly.
<!--l. 16--><p class="indent"> The basic layer does not provide a convenient syntax for describing graphics, which is left to frontends like Ti<span
class="cmti-10">k</span>Z.
For this reason, the basic layer is typically used only by “other programs.” For example, the <span
class="cmcsc-10"><small
class="small-caps">B</small><small
class="small-caps">E</small><small
class="small-caps">A</small><small
class="small-caps">M</small><small
class="small-caps">E</small><small
class="small-caps">R</small> </span>package uses
the basic layer extensively, but does not need a convenient input syntax. Rather, speed and flexibility are needed
when <span
class="cmcsc-10"><small
class="small-caps">B</small><small
class="small-caps">E</small><small
class="small-caps">A</small><small
class="small-caps">M</small><small
class="small-caps">E</small><small
class="small-caps">R</small> </span>creates graphics.
<!--l. 23--><p class="indent"> The following basic design principles underlie the basic layer:
<ol type="1" class="enumerate1" >
<li class="enumerate" value="1"
><a
id="x19-187002x1"></a>Structuring into a core and several optional packages.
</li>
<li class="enumerate" value="2"
><a
id="x19-187004x2"></a>Consistently named <span class="TEX">T<span
class="E">E</span>X</span> macros for all graphics commands.
</li>
<li class="enumerate" value="3"
><a
id="x19-187006x3"></a>Path-centered description of graphics.
</li>
<li class="enumerate" value="4"
><a
id="x19-187008x4"></a>Coordinate transformation system.</li></ol>
<!--l. 33--><p class="noindent">
<h4 class="subsectionHead"><span class="titlemark">18.1 </span> <a
id="x19-18800018.1"></a>Core and Optional Packages</h4>
<!--l. 35--><p class="noindent">The basic layer consists of a <span
class="cmti-10">core package</span>, called <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgfcore</span></span></span>, which provides the most basic commands, and several
optional package like <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgfbaseshade</span></span></span> that offer more special-purpose commands.
<!--l. 39--><p class="indent"> You can include the core by saying <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\usepackage{pgfcore}</span></span></span> or, as a plain <span class="TEX">T<span
class="E">E</span>X</span> user, <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\input</span><span
class="cmtt-10"> pgfcore.tex</span></span></span>.
<!--l. 42--><p class="indent"> The following optional packages are provided by the basic layer:
<ul class="itemize1">
<li class="itemize"><span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgfbaseplot</span></span></span> provides commands for plotting functions.
</li>
<li class="itemize"><span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgfbaseshapes</span></span></span> provides commands for drawing shapes and nodes.
</li>
<li class="itemize"><span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgfbaseimage</span></span></span> provides commands for including external images. The <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">graphicx</span></span></span> package does a much
better job at this than the <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgfbaseimage</span></span></span> package does, so you should normally use <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\includegraphics</span></span></span>
and not <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfimage</span></span></span>. However, in some situations (like when masking is needed or when plain <span class="TEX">T<span
class="E">E</span>X</span> is
used) this package is needed.
</li>
<li class="itemize"><span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgfbaselayers</span></span></span> provides commands for creating layered graphics. Using layers you can later on say
that a certain path should be behind a path that was specified earlier.
</li>
<li class="itemize"><span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgfbasesnakes</span></span></span> provides commands for adding snaked lines to the path. Such lines are not straight
but rather wind in some specific fashion.</li></ul>
<!--l. 66--><p class="indent"> If you say <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\usepackage{pgf}</span></span></span> or <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\input</span><span
class="cmtt-10"> pgf.tex</span></span></span>, all of the optional packages are loaded (as well as the core
and the system layer).
<!--l. 70--><p class="noindent">
<h4 class="subsectionHead"><span class="titlemark">18.2 </span> <a
id="x19-18900018.2"></a>Communicating with the Basic Layer via Macros</h4>
<!--l. 72--><p class="noindent">In order to “communicate” with the basic layer you use long sequences of commands that start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgf</span></span></span>. You are
only allowed to give these commands inside a <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">{pgfpicture}</span></span></span> environment. (Note that <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">{tikzpicture}</span></span></span> opens a
<span class="obeylines-h"><span class="verb"><span
class="cmtt-10">{pgfpicture}</span></span></span> internally, so you can freely mix <span
class="cmcsc-10"><small
class="small-caps">P</small><small
class="small-caps">G</small><small
class="small-caps">F</small></span> commands and Ti<span
class="cmti-10">k</span>Z commands inside a <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">{tikzpicture}</span></span></span>.) It
is possible to “do other things” between the commands. For example, you might use one command
to move to a certain point, then have a complicated computation of the next point, and then move
there.
<!--l. 82--><p class="noindent"><div class="obeylines-v"></div><!--tex4ht:inline--><div class="tabular"><table class="tabular"
cellspacing="0" cellpadding="0"
frame="void" id="TBL-396-" ><colgroup id="TBL-396-1g"><col
id="TBL-396-1"><col
id="TBL-396-2"></colgroup><tr
valign="baseline" id="TBL-396-1-"><td align="left" style="white-space:nowrap; text-align:left;" id="TBL-396-1-1"
class="td11"> <object data="pgfmanual-469.svg" width="28.85274pt" height="28.85274pt" type="image/svg+xml"><p>SVG-Viewer needed.</p></object> </td><td align="left" style="white-space:nowrap; text-align:left;" id="TBL-396-1-2"
class="td11"> <table class="minipage"><tr><td><div class="obeylines-v">
<br><span
class="cmtt-8">\newdimen\myypos</span>
<br><span
class="cmtt-8">\begin{pgfpicture}</span>
<br><span
class="cmtt-8"> </span><span
class="cmtt-8"> \pgfpathmoveto{\pgfpoint{0cm}{\myypos}}</span>
<br><span
class="cmtt-8"> </span><span
class="cmtt-8"> \pgfpathlineto{\pgfpoint{1cm}{\myypos}}</span>
<br><span
class="cmtt-8"> </span><span
class="cmtt-8"> \advance</span><span
class="cmtt-8"> \myypos</span><span
class="cmtt-8"> by</span><span
class="cmtt-8"> 1cm</span>
<br><span
class="cmtt-8"> </span><span
class="cmtt-8"> \pgfpathlineto{\pgfpoint{1cm}{\myypos}}</span>
<br><span
class="cmtt-8"> </span><span
class="cmtt-8"> \pgfpathclose</span>
<br><span
class="cmtt-8"> </span><span
class="cmtt-8"> \pgfusepath{stroke}</span>
<br><span
class="cmtt-8">\end{pgfpicture}</span></div> </td></tr></table> </td>
</tr></table></div>
<!--l. 94--><p class="indent"> The following naming conventions are used in the basic layer:
<!--l. 96--><p class="indent">
<ol type="1" class="enumerate1" >
<li class="enumerate" value="1"
><a
id="x19-189002x1"></a>All commands and environments start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">pgf</span></span></span>.
</li>
<li class="enumerate" value="2"
><a
id="x19-189004x2"></a>All commands that specify a point (a coordinate) start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfpoint</span></span></span>.
</li>
<li class="enumerate" value="3"
><a
id="x19-189006x3"></a>All commands that extend the current path start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfpath</span></span></span>.
</li>
<li class="enumerate" value="4"
><a
id="x19-189008x4"></a>All commands that set/change a graphics parameter start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfset</span></span></span>.
</li>
<li class="enumerate" value="5"
><a
id="x19-189010x5"></a>All commands that use a previously declared object (like a path, image or shading) start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfuse</span></span></span>.
</li>
<li class="enumerate" value="6"
><a
id="x19-189012x6"></a>All commands having to do with coordinate transformations start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgftransform</span></span></span>.
</li>
<li class="enumerate" value="7"
><a
id="x19-189014x7"></a>All commands having to do with arrow tips start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfarrows</span></span></span>.
</li>
<li class="enumerate" value="8"
><a
id="x19-189016x8"></a>All commands for “quickly” extending or drawing a path start with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfpathq</span></span></span> or <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfusepathq</span></span></span>.</li></ol>
<!--l. 119--><p class="noindent">
<h4 class="subsectionHead"><span class="titlemark">18.3 </span> <a
id="x19-19000018.3"></a>Path-Centered Approach</h4>
<!--l. 121--><p class="noindent">In <span
class="cmcsc-10"><small
class="small-caps">P</small><small
class="small-caps">G</small><small
class="small-caps">F</small></span> the most important entity is the <span
class="cmti-10">path</span>. All graphics are composed of numerous paths that can be stroked,
filled, shaded, or clipped against. Paths can be closed or open, they can self-intersect and consist of unconnected
parts.
<!--l. 126--><p class="indent"> Paths are first <span
class="cmti-10">constructed </span>and then <span
class="cmti-10">used</span>. In order to construct a path, you can use commands
starting with <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfpath</span></span></span>. Each time such a command is called, the current path is extended in some
way.
<!--l. 131--><p class="indent"> Once a path has been completely constructed, you can use it using the command <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgfusepath</span></span></span>. Depending on
the parameters given to this command, the path will be stroked (drawn) or filled or subsequent drawings will be
clipped against this path.
<!--l. 139--><p class="noindent">
<h4 class="subsectionHead"><span class="titlemark">18.4 </span> <a
id="x19-19100018.4"></a>Coordinate Versus Canvas Transformations</h4>
<!--l. 143--><p class="noindent"><span
class="cmcsc-10"><small
class="small-caps">P</small><small
class="small-caps">G</small><small
class="small-caps">F</small></span> provides two transformation systems: <span
class="cmcsc-10"><small
class="small-caps">P</small><small
class="small-caps">G</small><small
class="small-caps">F</small></span>’s own <span
class="cmti-10">coordinate </span>transformation matrix and <span
class="cmcsc-10"><small
class="small-caps">P</small><small
class="small-caps">D</small><small
class="small-caps">F</small></span>’s or PostScript’s
<span
class="cmti-10">canvas </span>transformation matrix. These two systems are quite different. Whereas a scaling by a factor of, say, 2 of the
canvas causes <span
class="cmti-10">everything </span>to be scaled by this factor (including the thickness of lines and text), a scaling of
two in the coordinate system causes only the <span
class="cmti-10">coordinates </span>to be scaled, but not the line width nor
text.
<!--l. 152--><p class="indent"> By default, all transformations only apply to the coordinate transformation system. However, using the
command <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">\pgflowlevel</span></span></span> it is possible to apply a transformation to the canvas.
<!--l. 156--><p class="indent"> Coordinate transformations are often preferable over canvas transformations. Text and lines that are transformed
using canvas transformations suffer from differing sizes and lines whose thickness differs depending on whether the
line is horizontal or vertical. To appreciate the difference, consider the following two “circles” both of which
have been scaled in the <span
class="cmmi-10">x</span>-direction by a factor of 3 and by a factor of 0<span
class="cmmi-10">.</span>5 in the <span
class="cmmi-10">y</span>-direction. The left
circle uses a canvas transformation, the right uses <span
class="cmcsc-10"><small
class="small-caps">P</small><small
class="small-caps">G</small><small
class="small-caps">F</small></span>’s coordinate transformation (some viewers will
render the left graphic incorrectly since they do no apply the low-level transformation the way they
should):
<!--l. 182--><p class="indent"> <object data="pgfmanual-470.svg" width="448.1307pt" height="56.90549pt" type="image/svg+xml"><p>SVG-Viewer needed.</p></object>
<div class="crosslinks"><p class="noindent">[<a
href="pgfmanualse19.html" >next</a>] [<a
href="pgfmanualse18.html" >front</a>] [<a
href="pgfmanual.html#pgfmanualse18.html" >up</a>] </p></div>
<!--l. 8--><p class="indent"> <a
id="tailpgfmanualse18.html"></a>
</body></html>
|
