summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex
blob: 29680fe657d697ffea72e1202d04b145365a9cb3 (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
383
384
385
386
387
388
389
390
391
392
393
% Copyright 2006 by Till Tantau and Mark Wibrow
%
% 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{Shape Library}

In addition to the standard shapes |rectangle|, |circle| and
|coordinate|, there exist a number of additional shapes defined in
different shape libraries. In the present section, these shapes are
described. 


\begin{pgflibrary}{shapes}
  This library packages just includes all of the libraries defined in
  the following. Note that it includes only those libraries starting
  with |shapes.|, more special-purpose libraries are described in
  dedicated sections.
\end{pgflibrary}


\subsection{Geometric Shapes}

\begin{pgflibrary}{shapes.geometric}
  This library defines different shapes that correspond to basic
  geometric objects like ellipses or polygons.
\end{pgflibrary}


\begin{shape}{diamond}
  This shape is a diamond tightly fitting the text box. The ratio
  between width and height is 1 by default, but can be changed by
  setting the shape aspect ratio (using the |aspect| option of
  \tikzname). The following figure shows the anchors this
  shape defines; the anchors |10| and |130| are example of border anchors.
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
  \node[name=s,shape=diamond,style=shape example] {Diamond\vrule width 1pt height 2cm};
  \foreach \anchor/\placement in
    {north west/above left, north/above, north east/above right, 
     west/left, center/above, east/right, 
     mid/above, 
     base/below,  
     south west/below left, south/below, south east/below right, 
     text/left, 10/right, 130/above}
     \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
       node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
\end{shape}

\begin{shape}{ellipse}
  This shape is an ellipse tightly fitting the text box, if no inner
  separation is given. The following figure shows the anchors this
  shape defines; the anchors |10| and |130| are example of border anchors.
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
  \node[name=s,shape=ellipse,style=shape example] {Ellipse\vrule width 1pt height 2cm};
  \foreach \anchor/\placement in
    {north west/above left, north/above, north east/above right, 
     west/left, center/above, east/right, 
     mid west/right, mid/above, mid east/left, 
     base west/left, base/below, base east/right, 
     south west/below left, south/below, south east/below right, 
     text/left, 10/right, 130/above}
     \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
       node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
\end{shape}




\begin{shape}{regular polygon}
  This shape is a regular polygon, which, by default, is drawn so that a side
  (rather than a corner) is always at the bottom. 
  
\begin{codeexample}[]
\begin{tikzpicture}
   \foreach \i in {5,...,8}
    	\node[regular polygon, regular polygon sides=\i, draw] at (\i,0)  {\i};
\end{tikzpicture}
\end{codeexample}

  Two points should be remembered regarding the dimensions of the
  polygon border. Firstly, the border is constructed using the incircle, that is, the
  circle that touches every side of the polygon border. The radius of
  the incircle is calculated to tightly fit the node contents.

\begin{codeexample}[]
\begin{tikzpicture}
  \foreach \a in {3,...,7}{
    \draw[gray!50] (\a*2,0)  circle(0.5cm);
    \node[regular polygon, regular polygon sides=\a, inner sep=0cm, draw] at (\a*2,0)
      {\tikz\fill[red!50] rectangle(0.707cm,0.707cm);};
   }  
\end{tikzpicture}
\end{codeexample}	
	
  Secondly, if the node is enlarged to any specified minimum size, 
  width or height, this is interpreted as the diameter of the the 
  circumcircle, that is, the circle that passes through all the 
  corners of the polygon border.

\begin{codeexample}[]
\begin{tikzpicture}
  \foreach \a in {3,...,7}{
    \draw[gray!50] (\a*2,0)  circle(0.5cm);
    \node[regular polygon, regular polygon sides=\a, minimum size=1cm, draw] at (\a*2,0) {};
   }  
\end{tikzpicture}
\end{codeexample}	

  There are \pgfname{} commands and \tikzname{} options to set the 
  number of sides for the polygon, and the rotation of the polygon 
  border. The \pgfname{} commands are as follows:
	
  \begin{command}{\pgfsetpolygonsides\marg{integer}}
    Set the number of sides for the polygon.
  \end{command}
  
  \begin{command}{\pgfsetpolygonrotate\marg{angle}}
    Rotate the border of the polygon independently of the node
    contents (but in addition to any concurrent coordinate or canvas
    transformation).
  \end{command}
  
  The corresponding \tikzname{} options are:

  \begin{itemize}
    \itemoption{regular polygon sides}|=|\meta{integer}
    set the number of points for the star.
    
    \itemoption{regular polygon rotate}|=|\meta{angle}
    rotate the border of the polygon independently of the node
    contents.
  \end{itemize}
  
  The anchors for the regular polygon shape are shown below:
   
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
  \node[name=s, shape=regular polygon, regular polygon sides=5, style=shape example, inner sep=.5cm] 
    {Regular Polygon\vrule width 1pt height 2cm};
  \foreach \anchor/\placement in
    {corner 1/above, corner 2/above, corner 3/left, corner 4/right, 
     corner 5/above, side 1/left,    side 2/left,   side 3/below,
     side 4/right,   side 5/right,   mid/right,     base/below, 
     center/above,   text/left,      75/above,      west/above, 
     east/above,     north/below,    south/above}
  \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
    node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
	
\end{shape}

\begin{shape}{star}
  This shape is a star, which by default (minus any transformations) is
  drawn with the first point pointing	upwards.
  A star should be thought of as having an set of ``inner points'' and
  and ``outer points''. These points form the principle anchors for the
  star, as shown below:	
  
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
  \node[name=s, shape=star, star points=5, star point ratio=1.5, style=shape example, inner sep=1.5cm] 
    {Star\vrule width 1pt height 2cm};
  \foreach \anchor/\placement in
     {inner point 1/above, inner point 2/above, inner point 3/below, 
      inner point 4/right, inner point 5/above, outer point 1/above, 
      outer point 2/above, outer point 3/left,  outer point 4/right, 
      outer point 5/above, mid/right,           base/below, 
      center/above,        text/left,           75/above}
  \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
    node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}

  The inner points of the border are based on the radius of the circle
  which tightly fits the node contents. 
  Any specified minimum size, width or height, is interpreted as the 
  diameter of the circle that passes through every outer point. 
  
  There are \pgfname{} commands and \tikzname{} options to set various
  parameters for the star, such as the number of points, the height of
  the points and the rotation of the star border. 
  
  The \pgfname{} commands are as follows:
  
  \begin{command}{\pgfsetstarpoints\marg{integer}}
    Sets the number of points for the star.
  \end{command}
  
  \begin{command}{\pgfsetstarpointheight\marg{distance}}
    Sets the height of the star points. This is the distance between the
    inner point and outer point radii. If the star is enlarged to some
    specified minimum size, the inner radius is increased to maintain
    the point height.	
  \end{command}
  
  \begin{command}{\pgfsetstarpointratio\marg{number}}
    Sets the ratio between the outer point and inner point radii.		
    If the star is enlarged to some specified minimum size, the
    inner radius is increased to maintain the ratio.	
  \end{command}
  
  \begin{command}{\pgfsetstarrotate\marg{angle}}
    Rotates the border of the star, independently of the node contents,
    but subject to any coordinate or canvas transformations.	
  \end{command}
  
  The corresponding \tikzname{} options are:
  
  \begin{itemize}
    \itemoption{star points}|=|\meta{integer}
    set the number of points for the star.
    
    \itemoption{star point height}|=|\meta{distance}
    set the height of the points for the star.
    
    \itemoption{star point ratio}|=|\meta{number}
    set the ratio between the outer point radius and the inner point
    radius.
    
    \itemoption{star rotate}|=|\meta{angle}
    rotate the star shape border indepently of the node contents.
    
  \end{itemize}
\end{shape}



\subsection{Symbol Shapes}

\begin{pgflibrary}{shapes.symbols}
  This library defines shapes that can be used for drawing symbols
  like a forbidden sign or a cloud.
\end{pgflibrary}



\begin{shape}{forbidden sign}
  This shape places the node inside a circle with a diagonal from the
  lower left to the upper right added. The circle is part of the
  background, the diagonal line part of the foreground path; thus, the
  diagonal line is on top of the text.
  
\begin{codeexample}[]
\begin{tikzpicture}
  \node [forbidden sign,line width=1ex,draw=red,fill=white] {Smoking};
\end{tikzpicture}
\end{codeexample}

  The shape inherits all anchors from the |circle| shape, see also the
  following figure:
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
  \node[name=s,shape=forbidden sign,style=shape example] {Forbidden\vrule width 1pt height 2cm};
  \foreach \anchor/\placement in
    {north west/above left, north/above, north east/above right, 
     west/left, center/above, east/right, 
     mid west/right, mid/above, mid east/left, 
     base west/left, base/below, base east/right, 
     south west/below left, south/below, south east/below right, 
     text/left, 10/right, 130/above}
     \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
       node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
\end{shape}



\subsection{Shapes with Multiple Text Parts}

\begin{pgflibrary}{shapes.multipart}
  This library defines general-purpose shapes that are composed of
  multiple (text) parts. 
\end{pgflibrary}


\begin{shape}{circle split}
  This shape is a multi-part shape consisting of a circle with a line
  in the middle. The upper part is the main part (the |text| part),
  the lower part is the |lower| part.
  
\begin{codeexample}[]
\begin{tikzpicture}
  \node [circle split,draw,double,fill=red!20]
  {
    $q_1$
    \nodepart{lower}
    $00$
  };
\end{tikzpicture}
\end{codeexample}

  The shape inherits all anchors from the |circle| shape and defines
  the |lower| anchor in addition. See also the
  following figure:
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
  \node[name=s,shape=circle split,style=shape example] {text\nodepart{lower}lower};
  \foreach \anchor/\placement in
    {north west/above left, north/above, north east/above right, 
     west/left, center/below, east/right, 
     mid west/right, mid/above, mid east/left, 
     base west/left, base/below, base east/right, 
     south west/below left, south/below, south east/below right, 
     text/left, lower/left, 130/above}
     \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
       node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
\end{shape}


\subsection{Miscellaneous Shapes}

\begin{pgflibrary}{shapes.misc}
  This library defines general-purpose shapes that do not fit in the
  previous categories.
\end{pgflibrary}



\begin{shape}{cross out}
  This shape ``crosses out'' the node. Its foreground path are simply
  two diagonal lines that between the corners of the node's bounding
  box. Here is an example:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \node [cross out,draw=red] at (1.5,1) {cross out};
\end{tikzpicture}
\end{codeexample}

  A useful application is inside text as in the following example:
\begin{codeexample}[]
Cross \tikz[baseline] \node [cross out,draw,anchor=text] {me}; out!  
\end{codeexample}

  This shape inherits all anchors from the |rectangle| shape, see also
  the following figure:
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
  \node[name=s,shape=cross out,style=shape example] {cross out\vrule width 1pt height 2cm};
  \foreach \anchor/\placement in
    {north west/above left, north/above, north east/above right, 
     west/left, center/above, east/right, 
     mid west/right, mid/above, mid east/left, 
     base west/left, base/below, base east/right, 
     south west/below left, south/below, south east/below right, 
     text/left, 10/right, 130/above}
     \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
       node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
\end{shape}

\begin{shape}{strike out}
  This shape is idential to the |cross out| shape, only its foreground
  path consists of a single line from the lower left to the upper
  right.
  
\begin{codeexample}[]
Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out!  
\end{codeexample}

  See the |cross out| shape for the anchors.
\end{shape}



%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "pgfmanual-pdftex-version"
%%% End: