summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse30.html
blob: aa5c9e695135fe364dfc2f07b24f47fac3d6dbc8 (plain)
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
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"  
  "http://www.w3.org/TR/html4/loose.dtd">  
<html > 
<head><title>30 Layered Graphics</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-11-15 18:41:00"> 
<link rel="stylesheet" type="text/css" href="pgfmanual.css"> 
</head><body 
>
   <div class="crosslinks"><p class="noindent">[<a 
href="pgfmanualse31.html" >next</a>] [<a 
href="pgfmanualse29.html" >prev</a>] [<a 
href="pgfmanualse29.html#tailpgfmanualse29.html" >prev-tail</a>] [<a 
href="#tailpgfmanualse30.html">tail</a>] [<a 
href="pgfmanual.html#pgfmanualse30.html" >up</a>] </p></div>
   <h3 class="sectionHead"><span class="titlemark">30   </span> <a 
 id="x31-29800030"></a>Layered Graphics</h3>
<!--l. 12--><p class="noindent">
     <dl class="description"><dt class="description">
<span 
class="colorbox" id="colorbox376"><span 
class="cmtt-10">\usepackage{</span><span 
class="cmtt-10">pgfbaselayers</span><span 
class="cmtt-10">} % </span><span class="LATEX"><span 
class="cmtt-10">L</span><span class="A"><span 
class="cmtt-10">A</span></span><span class="TEX"><span 
class="cmtt-10">T</span><span 
class="E"><span 
class="cmtt-10">E</span></span><span 
class="cmtt-10">X</span></span></span></span> </dt><dd 
class="description">
<a 
 id="dx31-298001"></a>
<a 
 id="dx31-298002"></a>
     </dd><dt class="description">
<span 
class="colorbox" id="colorbox377"><span 
class="cmtt-10">\input </span><span 
class="cmtt-10">pgfbaselayers</span><span 
class="cmtt-10">.tex   % plain </span><span class="TEX"><span 
class="cmtt-10">T</span><span 
class="E"><span 
class="cmtt-10">E</span></span><span 
class="cmtt-10">X</span></span></span> </dt><dd 
class="description">
     </dd><dt class="description">
<span 
class="colorbox" id="colorbox378"><span 
class="cmtt-10">\input </span><span 
class="cmtt-10">pgfbaselayers</span><span 
class="cmtt-10">.tex   % Con</span><span class="TEX"><span 
class="cmtt-10">T</span><span 
class="E"><span 
class="cmtt-10">E</span></span><span 
class="cmtt-10">X</span></span><span 
class="cmtt-10">t</span></span> </dt><dd 
class="description">
     <!--l. 13--><p class="noindent">This package provides a commands and environments for composing a picture from multiple layers.
     The package is loaded automatically by <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">pgf</span></span></span>, but you can load it manually if you have only included
     <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">pgfcore</span></span></span>. </dd></dl>
<!--l. 21--><p class="noindent">
   <h4 class="subsectionHead"><span class="titlemark">30.1   </span> <a 
 id="x31-29900030.1"></a>Overview</h4>
<!--l. 23--><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>&nbsp;provides a layering mechanism for composing graphics from multiple layers. (This mechanism is not be
confused with the conceptual &#8220;software layers&#8221; the <span 
class="cmcsc-10"><small 
class="small-caps">P</small><small 
class="small-caps">G</small><small 
class="small-caps">F</small></span>&nbsp;system is composed of.) Layers are often used in graphic
programs. The idea is that you can draw on the different layers in any order. So you might start drawing something
on the &#8220;background&#8221; layer, then something on the &#8220;foreground&#8221; layer, then something on the &#8220;middle&#8221; layer, and
then something on the background layer once more, and so on. At the end, no matter in which ordering you drew on
the different layers, the layers are &#8220;stacked on top of each other&#8221; in a fixed ordering to produce the final
picture. Thus, anything drawn on the middle layer would come on top of everything of the background
layer.
<!--l. 36--><p class="indent">   Normally, you do not need to use different layers since you will have little trouble &#8220;ordering&#8221; your graphic
commands in such a way that layers are superfluous. However, in certain situations you only &#8220;know&#8221; what you
should draw behind something else after the &#8220;something else&#8221; has been drawn.
<!--l. 42--><p class="indent">   For example, suppose you wish to draw a yellow background behind your picture. The background should be as
large as the bounding box of the picture, plus a little border. If you know the size of the bounding box of the picture
at its beginning, this is easy to accomplish. However, in general this is not the case and you need to
create a &#8220;background&#8221; layer in addition to the standard &#8220;main&#8221; layer. Then, at the end of the picture,
when the bounding box has been established, you can add a rectangle of the appropriate size to the
picture.
<!--l. 53--><p class="noindent">
   <h4 class="subsectionHead"><span class="titlemark">30.2   </span> <a 
 id="x31-30000030.2"></a>Declaring Layers</h4>
<!--l. 55--><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>&nbsp;layers are referenced using names. The standard layer, which is a bit special in certain ways, is called <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">main</span></span></span>.
If nothing else is specified, all graphic commands are added to the <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">main</span></span></span> layer. You can declare a new layer using the
following command:
<!--l. 60--><p class="indent">
     <dl class="description"><dt class="description">
<span 
class="colorbox" id="colorbox379"><span 
class="cmtt-10">\pgfdeclarelayer</span><span 
class="cmtt-10">{</span><span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">name</span><span 
class="cmsy-10">&gt;</span><span 
class="cmtt-10">}</span></span> </dt><dd 
class="description">
<a 
 id="dx31-300001"></a>
     <!--l. 61--><p class="noindent">This command declares a layer named <span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">name</span><span 
class="cmsy-10">&gt; </span>for later use. Mainly, this will setup some internal
     bookkeeping. </dd></dl>
                                                                                         
                                                                                         
<!--l. 65--><p class="indent">   The next step toward using a layer is to tell <span 
class="cmcsc-10"><small 
class="small-caps">P</small><small 
class="small-caps">G</small><small 
class="small-caps">F</small></span>&nbsp;which layers will be part of the actual picture
and which will be their ordering. Thus, it is possible to have more layers declared than are actually
used.
<!--l. 70--><p class="indent">
     <dl class="description"><dt class="description">
<span 
class="colorbox" id="colorbox380"><span 
class="cmtt-10">\pgfsetlayers</span><span 
class="cmtt-10">{</span><span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">layer list</span><span 
class="cmsy-10">&gt;</span><span 
class="cmtt-10">}</span></span> </dt><dd 
class="description">
<a 
 id="dx31-300002"></a>
     <!--l. 71--><p class="noindent">This command, which should be used <span 
class="cmti-10">outside </span>a <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">{pgfpicture}</span></span></span> environment, tells <span 
class="cmcsc-10"><small 
class="small-caps">P</small><small 
class="small-caps">G</small><small 
class="small-caps">F</small></span>&nbsp;which layers will be
     used in pictures. They are stacked on top of each other in the order given. The layer <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">main</span></span></span> should always be
     part of the list. Here is an example:
     <!--l. 76--><p class="noindent"><div class="obeylines-v"></div><!--tex4ht:inline--><div class="tabular"><table class="tabular" 
cellspacing="0" cellpadding="0"  
frame="void" id="TBL-567-" ><colgroup id="TBL-567-1g"><col 
id="TBL-567-1"></colgroup><tr  
 valign="baseline" id="TBL-567-1-"><td  align="left" style="white-space:nowrap; text-align:left;" id="TBL-567-1-1"  
class="td11">  <table class="minipage"><tr><td><div class="obeylines-v">
<br><span 
class="cmtt-8">\pgfdeclarelayer{background}</span>
<br><span 
class="cmtt-8">\pgfdeclarelayer{foreground}</span>
<br><span 
class="cmtt-8">\pgfsetlayers{background,main,foreground}</span></div>                                                                     </td></tr></table> </td>
</tr></table></div>
     </dd></dl>
<!--l. 84--><p class="noindent">
   <h4 class="subsectionHead"><span class="titlemark">30.3   </span> <a 
 id="x31-30100030.3"></a>Using Layers</h4>
<!--l. 86--><p class="noindent">Once the layers of your picture have been declared, you can start to &#8220;fill&#8221; them. As said before, all graphics
commands are normally added to the <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">main</span></span></span> layer. Using the <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">{pgfonlayer}</span></span></span> environment, you can tell <span 
class="cmcsc-10"><small 
class="small-caps">P</small><small 
class="small-caps">G</small><small 
class="small-caps">F</small></span>&nbsp;that
certain commands should, instead, be added to the given layer.
<!--l. 92--><p class="indent">
     <dl class="description"><dt class="description">
<span 
class="colorbox" id="colorbox381"><span 
class="cmtt-10">\begin{</span><span 
class="cmtt-10">pgfonlayer</span><span 
class="cmtt-10">}{</span><span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">layer name</span><span 
class="cmsy-10">&gt;</span><span 
class="cmtt-10">}</span></span> </dt><dd 
class="description">
     </dd><dt class="description">
<span 
class="colorbox" id="colorbox382"><span 
class="cmtt-10">&nbsp;</span><span 
class="cmtt-10">&nbsp;</span><span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">environment contents</span><span 
class="cmsy-10">&gt;</span></span> </dt><dd 
class="description">
     </dd><dt class="description">
<span 
class="colorbox" id="colorbox383"><span 
class="cmtt-10">\end{</span><span 
class="cmtt-10">pgfonlayer</span><span 
class="cmtt-10">}</span></span> </dt><dd 
class="description">
<a 
 id="dx31-301001"></a>
<a 
 id="dx31-301002"></a>
     <!--l. 93--><p class="noindent">The whole <span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">environment contents</span><span 
class="cmsy-10">&gt; </span>is added to the layer with the name <span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">layer name</span><span 
class="cmsy-10">&gt;</span>. This environment
     can be used anywhere inside a picture. Thus, even if it is used inside a <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">{pgfscope}</span></span></span> or a <span class="TEX">T<span 
class="E">E</span>X</span>&nbsp;group,
     the contents will still be added to the &#8220;whole&#8221; picture. Using this environment multiple times inside
     the same picture will cause the <span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">environment contents</span><span 
class="cmsy-10">&gt; </span>to accumulate.
     <!--l. 100--><p class="noindent"><span 
class="cmti-10">Note: </span>You can <span 
class="cmti-10">not  </span>add anything to the <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">main</span></span></span> layer using this environment. The only way to add
     anything to the main layer is to give graphic commands outside all <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10">{pgfonlayer}</span></span></span> environments.
                                                                                         
                                                                                         
     <!--l. 105--><p class="noindent"><div class="obeylines-v"></div><!--tex4ht:inline--><div class="tabular"><table class="tabular" 
cellspacing="0" cellpadding="0"  
frame="void" id="TBL-568-" ><colgroup id="TBL-568-1g"><col 
id="TBL-568-1"><col 
id="TBL-568-2"></colgroup><tr  
 valign="baseline" id="TBL-568-1-"><td  align="left" style="white-space:nowrap; text-align:left;" id="TBL-568-1-1"  
class="td11">  &nbsp;<object data="pgfmanual-646.svg" width="76.87369 " height="76.87369 " type="image/svg+xml"><p>SVG-Viewer needed.</p></object>&nbsp;  </td><td  align="left" style="white-space:nowrap; text-align:left;" id="TBL-568-1-2"  
class="td11">  <table class="minipage"><tr><td><div class="obeylines-v">
<br><span 
class="cmtt-8">\pgfdeclarelayer{background</span><span 
class="cmtt-8">&nbsp;layer}</span>
<br><span 
class="cmtt-8">\pgfdeclarelayer{foreground</span><span 
class="cmtt-8">&nbsp;layer}</span>
<br><span 
class="cmtt-8">\pgfsetlayers{background</span><span 
class="cmtt-8">&nbsp;layer,main,foreground</span><span 
class="cmtt-8">&nbsp;layer}</span>
<br><span 
class="cmtt-8">\begin{tikzpicture}</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;</span><span 
class="cmsltt-10x-x-80">%</span><span 
class="cmsltt-10x-x-80">&nbsp;On</span><span 
class="cmsltt-10x-x-80">&nbsp;main</span><span 
class="cmsltt-10x-x-80">&nbsp;layer:</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\fill[blue]</span><span 
class="cmtt-8">&nbsp;(0,0)</span><span 
class="cmtt-8">&nbsp;circle</span><span 
class="cmtt-8">&nbsp;(1cm);</span>
<br>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\begin{pgfonlayer}{background</span><span 
class="cmtt-8">&nbsp;layer}</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\fill[yellow]</span><span 
class="cmtt-8">&nbsp;(-1,-1)</span><span 
class="cmtt-8">&nbsp;rectangle</span><span 
class="cmtt-8">&nbsp;(1,1);</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\end{pgfonlayer}</span>
<br>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\begin{pgfonlayer}{foreground</span><span 
class="cmtt-8">&nbsp;layer}</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\node[white]</span><span 
class="cmtt-8">&nbsp;{foreground};</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\end{pgfonlayer}</span>
<br>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\begin{pgfonlayer}{background</span><span 
class="cmtt-8">&nbsp;layer}</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\fill[black]</span><span 
class="cmtt-8">&nbsp;(-.8,-.8)</span><span 
class="cmtt-8">&nbsp;rectangle</span><span 
class="cmtt-8">&nbsp;(.8,.8);</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\end{pgfonlayer}</span>
<br>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;</span><span 
class="cmsltt-10x-x-80">%</span><span 
class="cmsltt-10x-x-80">&nbsp;On</span><span 
class="cmsltt-10x-x-80">&nbsp;main</span><span 
class="cmsltt-10x-x-80">&nbsp;layer</span><span 
class="cmsltt-10x-x-80">&nbsp;again:</span>
<br><span 
class="cmtt-8">&nbsp;</span><span 
class="cmtt-8">&nbsp;\fill[blue!50]</span><span 
class="cmtt-8">&nbsp;(-.5,-1)</span><span 
class="cmtt-8">&nbsp;rectangle</span><span 
class="cmtt-8">&nbsp;(.5,1);</span>
<br><span 
class="cmtt-8">\end{tikzpicture}</span></div>                                                                                             </td></tr></table> </td>
</tr></table></div>
     </dd></dl>
<!--l. 131--><p class="indent">
     <dl class="description"><dt class="description">
<span 
class="colorbox" id="colorbox384"><span 
class="cmtt-10">\pgfonlayer</span><span 
class="cmtt-10">{</span><span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">layer name</span><span 
class="cmsy-10">&gt;</span><span 
class="cmtt-10">}</span></span> </dt><dd 
class="description">
     </dd><dt class="description">
<span 
class="colorbox" id="colorbox385"><span 
class="cmtt-10">&nbsp;</span><span 
class="cmtt-10">&nbsp;</span><span 
class="cmsy-10">&lt;</span><span 
class="cmti-10">environment contents</span><span 
class="cmsy-10">&gt;</span></span> </dt><dd 
class="description">
     </dd><dt class="description">
<span 
class="colorbox" id="colorbox386"><span 
class="cmtt-10">\endpgfonlayer</span></span> </dt><dd 
class="description">
<a 
 id="dx31-301003"></a>
<a 
 id="dx31-301004"></a>
     <!--l. 132--><p class="noindent">This is the plain <span class="TEX">T<span 
class="E">E</span>X</span>&nbsp;version of the environment. </dd></dl>
                                                                                         
                                                                                         
                                                                                         
                                                                                         
                                                                                         
                                                                                         
   <div class="crosslinks"><p class="noindent">[<a 
href="pgfmanualse31.html" >next</a>] [<a 
href="pgfmanualse29.html" >prev</a>] [<a 
href="pgfmanualse29.html#tailpgfmanualse29.html" >prev-tail</a>] [<a 
href="pgfmanualse30.html" >front</a>] [<a 
href="pgfmanual.html#pgfmanualse30.html" >up</a>] </p></div>
<!--l. 8--><p class="indent">   <a 
 id="tailpgfmanualse30.html"></a>   
</body></html>