% 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: 
