diff options
Diffstat (limited to 'graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex')
-rw-r--r-- | graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex | 453 |
1 files changed, 334 insertions, 119 deletions
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex index d714b8fa86..9c569fba34 100644 --- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex +++ b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex @@ -26,9 +26,9 @@ \pattern [path fading=west,pattern=checkerboard light gray] (0,0) rectangle (5cm,2em); - \pattern [pattern=#1,pattern color=black] (0,0) rectangle +(1.5cm,2em); - \pattern [pattern=#1,pattern color=blue] (1.75,0) rectangle +(1.5cm,2em); - \pattern [pattern=#1,pattern color=red] (3.5,0) rectangle +(1.5cm,2em); + \pattern [pattern=#1,pattern color=black] (0,0) rectangle +(1.5cm,2em); + \pattern [pattern=#1,pattern color=blue] (1.75,0) rectangle +(1.5cm,2em); + \pattern [pattern=#1,pattern color=red] (3.5,0) rectangle +(1.5cm,2em); \end{tikzpicture} \\[1ex] } @@ -81,6 +81,7 @@ \patternindexinherentlycolored{crosshatch dots light steel blue} \end{tabular} + \subsection{User-Defined Patterns} \label{section-library-patterns-meta} @@ -91,80 +92,81 @@ \end{pgflibrary} \emph{Caveat:} This library is currently experimental and might change without -notice. There are some known shortcomings that will hopefully be fixed in the +notice. There are some known shortcomings that will hopefully be fixed in the future. \begin{command}{\pgfdeclarepattern\marg{config}} - This command is used to declare a new pattern. In contrast to the normal + This command is used to declare a new pattern. In contrast to the normal patterns and in the spirit of |arrows.meta| this command takes a list of - keys and values to define the pattern. The following keys are available: - % -\begin{key}{/pgf/patterns/name=\meta{name}} - The name of the pattern by which it can be used later on. -\end{key} - % -\begin{key}{/pgf/patterns/type=\meta{type} (default uncolored)} - The type of the pattern maps to what was called ``form only'' and ``inherently colored'' in the language of the normal patterns. - The available choices are: - \begin{itemize} - \item |uncolored| the pattern will obey the surrounding color. - \item |colored| the pattern will have an intrinsic color. - \item |form only| synonym for |uncolored| - \item |inherently colored| synonym for |colored| - \end{itemize} -\end{key} - % -\begin{key}{/pgf/patterns/x=\meta{dimension} (default 1cm)} - Unit vector of the coordinate system in the $x$-direction. -\end{key} - % -\begin{key}{/pgf/patterns/y=\meta{dimension} (default 1cm)} - Unit vector of the coordinate system in the $y$-direction. -\end{key} - % -\begin{key}{/pgf/patterns/parameters=\meta{comma separated list} (default empty)} - A list of parameters that are passed to the pattern. This is usually a - list of TeX macros. It is very important that these macros are fully - expandable because the values they hold are being used for deduplication in - the PDF file. -\end{key} - % -\begin{key}{/pgf/patterns/defaults=\meta{comma separated list} (default empty)} - This list holds default assignments to the parameters passed to the - pattern. The default keys can then be found under the |/pgf/pattern keys/| - prefix. -\end{key} - % -\begin{key}{/pgf/patterns/bottom left=\meta{pgfpoint}} - Bottom left corner of the pattern's bounding box, e.g.\ - |\pgfqpoint{-.1pt}{-.1pt}|. -\end{key} - % -\begin{key}{/pgf/patterns/top right=\meta{pgfpoint}} - Top right corner of the pattern's bounding box, e.g.\ - |\pgfqpoint{3.1pt}{3.1pt}|. -\end{key} - % -\begin{key}{/pgf/patterns/tile size=\meta{pgfpoint}} - Width and height of a single of the pattern as a \pgfname\ point - specification, i.e. the $x$ coordinate is the width and the $y$ coordinate - is the height, e.g.\ |\pgfqpoint{3pt}{3pt}|. -\end{key} - % -\begin{key}{/pgf/patterns/tile transformation=\meta{pgftransformation} (default empty)} - A \pgfname\ transformation, e.g.\ |\pgftransformrotate{30}|. -\end{key} - % -\begin{key}{/pgf/patterns/code=\meta{code}} - The code should be \pgfname\ code than can be protocolled. It should not - contain any color code or nodes. -\end{key} - % -\begin{key}{/pgf/patterns/set up code=\meta{code} (default empty)} - This code can be set if parameters have to be preprocessed before the - actual pattern code can be run. -\end{key} + keys and values to define the pattern. The following keys are available: + % + \begin{key}{/pgf/patterns/name=\meta{name}} + The name of the pattern by which it can be used later on. + \end{key} + % + \begin{key}{/pgf/patterns/type=\meta{type} (default uncolored)} + The type of the pattern maps to what was called ``form only'' and + ``inherently colored'' in the language of the normal patterns. The + available choices are: + % + \begin{itemize} + \item |uncolored| the pattern will obey the surrounding color. + \item |colored| the pattern will have an intrinsic color. + \item |form only| synonym for |uncolored| + \item |inherently colored| synonym for |colored| + \end{itemize} + \end{key} + % + \begin{key}{/pgf/patterns/x=\meta{dimension} (default 1cm)} + Unit vector of the coordinate system in the $x$-direction. + \end{key} + % + \begin{key}{/pgf/patterns/y=\meta{dimension} (default 1cm)} + Unit vector of the coordinate system in the $y$-direction. + \end{key} + % + \begin{key}{/pgf/patterns/parameters=\meta{comma separated list} (default empty)} + A list of parameters that are passed to the pattern. This is usually a + list of \TeX\ macros. It is very important that these macros are fully + expandable because the values they hold are being used for + deduplication in the PDF file. + \end{key} + % + \begin{key}{/pgf/patterns/defaults=\meta{comma separated list} (default empty)} + This list holds default assignments to the parameters passed to the + pattern. The default keys can then be found under the + |/pgf/pattern keys/| prefix. + \end{key} + % + \begin{key}{/pgf/patterns/bottom left=\meta{pgfpoint}} + Bottom left corner of the pattern's bounding box, e.g.\ + |\pgfqpoint{-.1pt}{-.1pt}|. + \end{key} + % + \begin{key}{/pgf/patterns/top right=\meta{pgfpoint}} + Top right corner of the pattern's bounding box, e.g.\ + |\pgfqpoint{3.1pt}{3.1pt}|. + \end{key} % + \begin{key}{/pgf/patterns/tile size=\meta{pgfpoint}} + Width and height of a single of the pattern as a \pgfname\ point + specification, i.e. the $x$ coordinate is the width and the $y$ + coordinate is the height, e.g.\ |\pgfqpoint{3pt}{3pt}|. + \end{key} + % + \begin{key}{/pgf/patterns/tile transformation=\meta{pgftransformation} (default empty)} + A \pgfname\ transformation, e.g.\ |\pgftransformrotate{30}|. + \end{key} + % + \begin{key}{/pgf/patterns/code=\meta{code}} + The code should be \pgfname\ code that can be protocolled. It should not + contain any color code or nodes. + \end{key} + % + \begin{key}{/pgf/patterns/set up code=\meta{code} (default empty)} + This code can be set if parameters have to be preprocessed before the + actual pattern code can be run. + \end{key} \end{command} \begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}] @@ -213,46 +215,258 @@ future. \end{tikzpicture} \end{codeexample} +There are a couple of predefined \pgfname\ patterns which are similar +to their normal counterparts. + +\begin{pattern}{Lines} + The |Lines| pattern replaces the |horizontal lines|, |vertical lines|, + |north east lines|, and |north west lines| patterns. Unfortunately, due to + the way the old patterns are constructed, namely that they are not simply + related to each other by rotation, the |Lines| pattern cannot be used as a + drop-in replacement. + + However, the pattern options can be tuned to resemble the other versions + closely. The available parameters are: + % + \begin{key}{/pgf/pattern keys/distance (initially 3pt)} + Distance between lines. + \end{key} + % + \begin{key}{/pgf/pattern keys/angle (initially 0)} + By default the lines are horizontal. The whole pattern is rotated by + this angle. The rotation angle is measured in the mathematically + positive sense. + \end{key} + % + \begin{key}{/pgf/pattern keys/xshift (initially 0pt)} + Shifts the whole pattern in $x$-direction (before applying the + rotation). + \end{key} + % + \begin{key}{/pgf/pattern keys/yshift (initially 0pt)} + Shifts the whole pattern in $y$-direction (before applying the + rotation). + \end{key} + % + \begin{key}{/pgf/pattern keys/line width (initially \string\the\string\pgflinewidth)} + Thickness of the lines. + \end{key} + % + The following settings can be used to reproduce the other |... lines| + patterns. + % +\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}] +\begin{tikzpicture} + \draw[pattern={horizontal lines},pattern color=orange] + (0,0) rectangle +(1,1); + \draw[pattern={Lines[yshift=.5pt]},pattern color=blue] + (0,0) rectangle +(1,1); + + \draw[pattern={vertical lines},pattern color=orange] + (1,0) rectangle +(1,1); + \draw[pattern={Lines[angle=90,yshift=-.5pt]},pattern color=blue] + (1,0) rectangle +(1,1); + + \draw[pattern={north east lines},pattern color=orange] + (0,1) rectangle +(1,1); + \draw[pattern={Lines[angle=45,distance={3pt/sqrt(2)}]},pattern color=blue] + (0,1) rectangle +(1,1); + + \draw[pattern={north west lines},pattern color=orange] + (1,1) rectangle +(1,1); + \draw[pattern={Lines[angle=-45,distance={3pt/sqrt(2)}]},pattern color=blue] + (1,1) rectangle +(1,1); +\end{tikzpicture} +\end{codeexample} + % +\end{pattern} + +\begin{pattern}{Hatch} + The |Hatch| pattern replaces the |grid| and |crosshatch| patterns. + The |Hatch| pattern without options is a drop-in replacement for the + |grid| pattern. + % + \begin{key}{/pgf/pattern keys/distance (initially 3pt)} + Distance between crosses. + \end{key} + % + \begin{key}{/pgf/pattern keys/angle (initially 0)} + By default the lines are horizontal and vertical. The whole pattern is + rotated by this angle. The rotation angle is measured in the + mathematically positive sense. + \end{key} + % + \begin{key}{/pgf/pattern keys/xshift (initially 0pt)} + Shifts the whole pattern in $x$-direction (before applying the + rotation). + \end{key} + % + \begin{key}{/pgf/pattern keys/yshift (initially 0pt)} + Shifts the whole pattern in $y$-direction (before applying the + rotation). + \end{key} + % + \begin{key}{/pgf/pattern keys/line width (initially \string\the\string\pgflinewidth)} + Thickness of the lines. + \end{key} + % + The following settings can be used to reproduce the |grid| and + |crosshatch| patterns. + % +\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}] +\begin{tikzpicture} + \draw[pattern={grid},pattern color=orange] + (0,0) rectangle +(1,1); + \draw[pattern={Hatch},pattern color=blue] + (0,0) rectangle +(1,1); + + \draw[pattern={crosshatch},pattern color=orange] + (1,0) rectangle +(1,1); + \draw[pattern={Hatch[angle=45,distance={3pt/sqrt(2)},xshift=.1pt]}, + pattern color=blue] (1,0) rectangle +(1,1); +\end{tikzpicture} +\end{codeexample} + % +\end{pattern} + +\begin{pattern}{Dots} + The |Dots| pattern replaces the |dots| and |crosshatch dots| patterns. The + |Dots| pattern without options is a drop-in replacement for the |dots| + pattern. + % + \begin{key}{/pgf/pattern keys/distance (initially 3pt)} + Distance between dots. + \end{key} + % + \begin{key}{/pgf/pattern keys/angle (initially 0)} + By default the lines are arranged on a regular grid. The whole pattern + is rotated by this angle. The rotation angle is measured in the + mathematically positive sense. + \end{key} + % + \begin{key}{/pgf/pattern keys/xshift (initially 0pt)} + Shifts the whole pattern in $x$-direction (before applying the + rotation). + \end{key} + % + \begin{key}{/pgf/pattern keys/yshift (initially 0pt)} + Shifts the whole pattern in $y$-direction (before applying the + rotation). + \end{key} + % + \begin{key}{/pgf/pattern keys/radius (initially 0.5pt)} + Radius of the dots. + \end{key} + % + The following settings can be used to reproduce the |dots| and + |crosshatch dots| patterns. + % +\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}] +\begin{tikzpicture} + \draw[pattern={dots},pattern color=orange] + (0,0) rectangle +(1,1); + \draw[pattern={Dots},pattern color=blue] + (0,0) rectangle +(1,1); + + \draw[pattern={crosshatch dots},pattern color=orange] + (1,0) rectangle +(1,1); + \draw[pattern={Dots[angle=45,distance={3pt/sqrt(2)}]}, + pattern color=blue] (1,0) rectangle +(1,1); +\end{tikzpicture} +\end{codeexample} + % +\end{pattern} + +\begin{pattern}{Stars} + The |Stars| pattern replaces the |fivepointed stars| and |sixpointed stars| + patterns. However, the stars of the |Stars| pattern are constructed in a + fundamentally different fashion, so it can't be used as a drop-in + replacement. + % + \begin{key}{/pgf/pattern keys/distance (initially 3mm)} + Distance between stars. + \end{key} + % + \begin{key}{/pgf/pattern keys/angle (initially 0)} + By default the stars are arranged on a regular grid. The whole pattern + is rotated by this angle. The rotation angle is measured in the + mathematically positive sense. + \end{key} + % + \begin{key}{/pgf/pattern keys/xshift (initially 0pt)} + Shifts the whole pattern in $x$-direction (before applying the + rotation). + \end{key} + % + \begin{key}{/pgf/pattern keys/yshift (initially 0pt)} + Shifts the whole pattern in $y$-direction (before applying the + rotation). + \end{key} + % + \begin{key}{/pgf/pattern keys/radius (initially 1mm)} + Outer radius of the enclosing circle of the stars. + \end{key} + % + \begin{key}{/pgf/pattern keys/points (initially 5)} + Number of pointy ends of the stars. + \end{key} + % +\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}] +\begin{tikzpicture} + \draw[pattern={fivepointed stars},pattern color=orange] + (0,0) rectangle +(1,1); + \draw[pattern={Stars},pattern color=blue] + (0,0) rectangle +(1,1); + + \draw[pattern={sixpointed stars},pattern color=orange] + (1,0) rectangle +(1,1); + \draw[pattern={Stars[points=6]},pattern color=blue] + (1,0) rectangle +(1,1); +\end{tikzpicture} +\end{codeexample} + % +\end{pattern} + + \begin{command}{\tikzdeclarepattern\marg{config}} A pattern declared with |\pgfdeclarepattern| can only execute \pgfname\ - code. This command extends the functionality to also allow \tikzname\ - code. All the same keys of |\pgfdeclarepattern| are valid, but some of + code. This command extends the functionality to also allow \tikzname\ + code. All the same keys of |\pgfdeclarepattern| are valid, but some of them have been overloaded to give a more natural \tikzname\ syntax. % -\begin{key}{/tikz/patterns/bottom left=\meta{point}} - Instead of a \pgfname\ name point, this key takes a \tikzname\ point, e.g.\ - |(-.1,-.1)|. -\end{key} + \begin{key}{/tikz/patterns/bottom left=\meta{point}} + Instead of a \pgfname\ name point, this key takes a \tikzname\ point, + e.g.\ |(-.1,-.1)|. + \end{key} % -\begin{key}{/tikz/patterns/top right=\meta{point}} - Instead of a \pgfname\ name point, this key takes a \tikzname\ point, e.g.\ - |(3.1,3.1)|. -\end{key} + \begin{key}{/tikz/patterns/top right=\meta{point}} + Instead of a \pgfname\ name point, this key takes a \tikzname\ point, + e.g.\ |(3.1,3.1)|. + \end{key} % -\begin{key}{/tikz/patterns/tile size=\meta{point}} - Instead of a \pgfname\ name point, this key takes a \tikzname\ point, e.g.\ - |(3,3)|. -\end{key} + \begin{key}{/tikz/patterns/tile size=\meta{point}} + Instead of a \pgfname\ name point, this key takes a \tikzname\ point, + e.g.\ |(3,3)|. + \end{key} % -\begin{key}{/tikz/patterns/tile transformation=\meta{transformation}} - Instead of a \pgfname\ transformation, this key takes a list of keys and - value and extracts the resulting transformation from them, e.g.\ - |rotate=30|. -\end{key} + \begin{key}{/tikz/patterns/tile transformation=\meta{transformation}} + Instead of a \pgfname\ transformation, this key takes a list of keys + and value and extracts the resulting transformation from them, e.g.\ + |rotate=30|. + \end{key} In addition to the overloaded keys, some new keys have been added. % -\begin{key}{/tikz/patterns/bounding box=\meta{point} and \meta{point}} - This is a shorthand to set the bounding box. It will assign the first - point to |bottom left| and the second point to |top right|. -\end{key} - % -\begin{key}{/tikz/patterns/infer tile bounding box=\meta{dimension} (default 0pt)} - Instead of specifying the bounding box by hand, you can ask \tikzname\ to - infer the size of the bounding box for you. The \meta{dimension} parameter - is padding that is added around the bounding box. -\end{key} + \begin{key}{/tikz/patterns/bounding box=\meta{point} and \meta{point}} + This is a shorthand to set the bounding box. It will assign the first + point to |bottom left| and the second point to |top right|. + \end{key} % + \begin{key}{/tikz/patterns/infer tile bounding box=\meta{dimension} (default 0pt)} + Instead of specifying the bounding box by hand, you can ask \tikzname\ + to infer the size of the bounding box for you. The \meta{dimension} + parameter is padding that is added around the bounding box. + \end{key} \end{command} \begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}] @@ -280,7 +494,7 @@ future. \begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}] \tikzdeclarepattern{ - name=Stars, + name=mystars, type=uncolored, bounding box={(-5pt,-5pt) and (5pt,5pt)}, tile size={(\tikztilesize,\tikztilesize)}, @@ -301,49 +515,50 @@ future. } \begin{tikzpicture} - \draw[pattern=Stars,pattern color=blue] (0,0) rectangle ++(2,2); - \draw[pattern={Stars[points=7,tile size=15pt]}] (2,0) rectangle ++(2,2); - \draw[pattern={Stars[rotate=45]},pattern color=red] (0,2) rectangle ++(2,2); - \draw[pattern={Stars[rotate=30,points=4,radius=5pt]}] (2,2) rectangle ++(2,2); + \draw[pattern=mystars,pattern color=blue] (0,0) rectangle +(2,2); + \draw[pattern={mystars[points=7,tile size=15pt]}] (2,0) rectangle +(2,2); + \draw[pattern={mystars[rotate=45]},pattern color=red] (0,2) rectangle +(2,2); + \draw[pattern={mystars[rotate=30,points=4,radius=5pt]}] (2,2) rectangle +(2,2); \end{tikzpicture} \end{codeexample} Instead of macros you can also use \pgfname\ keys as parameters, if that is what you prefer. +% \begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}] \tikzdeclarepattern{ - name=lines, + name=mylines, parameters={ \pgfkeysvalueof{/pgf/pattern keys/size}, \pgfkeysvalueof{/pgf/pattern keys/angle}, \pgfkeysvalueof{/pgf/pattern keys/line width}, }, - bounding box={(-.1pt,-.1pt) and - (\pgfkeysvalueof{/pgf/pattern keys/size}+.1pt, - \pgfkeysvalueof{/pgf/pattern keys/size}+.1pt)}, + bounding box={ + (0,-0.5*\pgfkeysvalueof{/pgf/pattern keys/line width}) and + (\pgfkeysvalueof{/pgf/pattern keys/size}, + 0.5*\pgfkeysvalueof{/pgf/pattern keys/line width})}, tile size={(\pgfkeysvalueof{/pgf/pattern keys/size}, \pgfkeysvalueof{/pgf/pattern keys/size})}, tile transformation={rotate=\pgfkeysvalueof{/pgf/pattern keys/angle}}, defaults={ size/.initial=5pt, - angle/.initial=0, + angle/.initial=45, line width/.initial=.4pt, }, code={ - \draw[line width=\pgfkeysvalueof{/pgf/pattern keys/line width}] - (0,0) -- (\pgfkeysvalueof{/pgf/pattern keys/size}, - \pgfkeysvalueof{/pgf/pattern keys/size}); - } + \draw [line width=\pgfkeysvalueof{/pgf/pattern keys/line width}] + (0,0) -- (\pgfkeysvalueof{/pgf/pattern keys/size},0); + }, } \begin{tikzpicture} - \draw[pattern={lines[size=10pt,line width=.8pt,angle=10]}, + \draw[pattern={mylines[size=10pt,line width=.8pt,angle=10]}, pattern color=red] (0,0) rectangle ++(2,2); - \draw[pattern={lines[size= 5pt,line width=.8pt,angle=40]}, + \draw[pattern={mylines[size= 5pt,line width=.8pt,angle=40]}, pattern color=blue] (2,0) rectangle ++(2,2); - \draw[pattern={lines[size=10pt,line width=.4pt,angle=90]}, + \draw[pattern={mylines[size=10pt,line width=.4pt,angle=90]}, pattern color=green] (0,2) rectangle ++(2,2); - \draw[pattern={lines[size= 2pt,line width= 1pt,angle=70]}, + \draw[pattern={mylines[size= 2pt,line width= 1pt,angle=70]}, pattern color=orange] (2,2) rectangle ++(2,2); \end{tikzpicture} \end{codeexample} |