summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex266
1 files changed, 266 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex
index 281dee5b5de..d714b8fa86e 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex
@@ -81,6 +81,272 @@
\patternindexinherentlycolored{crosshatch dots light steel blue}
\end{tabular}
+\subsection{User-Defined Patterns}
+\label{section-library-patterns-meta}
+
+\noindent\emph{by Mark Wibrow}
+
+\begin{pgflibrary}{patterns.meta}
+ Define your own patterns with a syntax similar to |arrows.meta|.
+\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
+future.
+
+\begin{command}{\pgfdeclarepattern\marg{config}}
+ 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}
+ %
+\end{command}
+
+\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
+\pgfdeclarepattern{
+ name=hatch,
+ parameters={\hatchsize,\hatchangle,\hatchlinewidth},
+ bottom left={\pgfpoint{-.1pt}{-.1pt}},
+ top right={\pgfpoint{\hatchsize+.1pt}{\hatchsize+.1pt}},
+ tile size={\pgfpoint{\hatchsize}{\hatchsize}},
+ tile transformation={\pgftransformrotate{\hatchangle}},
+ code={
+ \pgfsetlinewidth{\hatchlinewidth}
+ \pgfpathmoveto{\pgfpoint{-.1pt}{-.1pt}}
+ \pgfpathlineto{\pgfpoint{\hatchsize+.1pt}{\hatchsize+.1pt}}
+ \pgfpathmoveto{\pgfpoint{-.1pt}{\hatchsize+.1pt}}
+ \pgfpathlineto{\pgfpoint{\hatchsize+.1pt}{-.1pt}}
+ \pgfusepath{stroke}
+ }
+}
+
+\tikzset{
+ hatch size/.store in=\hatchsize,
+ hatch angle/.store in=\hatchangle,
+ hatch line width/.store in=\hatchlinewidth,
+ hatch size=5pt,
+ hatch angle=0pt,
+ hatch line width=.5pt,
+}
+
+\begin{tikzpicture}
+\foreach \r in {1,...,4}
+ \draw [pattern=hatch, pattern color=red]
+ (\r*3,0) rectangle ++(2,2);
+
+\foreach \r in {1,...,4}
+ \draw [pattern=hatch, pattern color=green, hatch size=2pt]
+ (\r*3,3) rectangle ++(2,2);
+
+\foreach \r in {1,...,4}
+ \draw [pattern=hatch, pattern color=blue, hatch size=10pt, hatch angle=21]
+ (\r*3,6) rectangle ++(2,2);
+
+\foreach \r in {1,...,4}
+ \draw [pattern=hatch, pattern color=orange, hatch line width=2pt]
+ (\r*3,9) rectangle ++(2,2);
+\end{tikzpicture}
+\end{codeexample}
+
+\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
+ 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/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 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}
+ %
+\end{command}
+
+\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
+\tikzdeclarepattern{
+ name=flower,
+ type=colored,
+ bottom left={(-.1pt,-.1pt)},
+ top right={(10.1pt,10.1pt)},
+ tile size={(10pt,10pt)},
+ code={
+ \tikzset{x=1pt,y=1pt}
+ \path [draw=green] (5,2.5) -- (5, 7.5);
+ \foreach \i in {0,60,...,300}
+ \path [fill=pink, shift={(5,7.5)}, rotate=-\i]
+ (0,0) .. controls ++(120:4) and ++(60:4) .. (0,0);
+ \path [fill=red] (5,7.5) circle [radius=1];
+ \foreach \i in {-45,45}
+ \path [fill=green, shift={(5,2.5)}, rotate=-\i]
+ (0,0) .. controls ++(120:4) and ++(60:4) .. (0,0);
+ }
+}
+
+\tikz\draw [pattern=flower] circle [radius=1];
+\end{codeexample}
+
+\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
+\tikzdeclarepattern{
+ name=Stars,
+ type=uncolored,
+ bounding box={(-5pt,-5pt) and (5pt,5pt)},
+ tile size={(\tikztilesize,\tikztilesize)},
+ parameters={\tikzstarpoints,\tikzstarradius,\tikzstarrotate,\tikztilesize},
+ tile transformation={rotate=\tikzstarrotate},
+ defaults={
+ points/.store in=\tikzstarpoints,points=5,
+ radius/.store in=\tikzstarradius,radius=3pt,
+ rotate/.store in=\tikzstarrotate,rotate=0,
+ tile size/.store in=\tikztilesize,tile size=10pt,
+ },
+ code={
+ \pgfmathparse{180/\tikzstarpoints}\let\a=\pgfmathresult
+ \fill (90:\tikzstarradius) \foreach \i in {1,...,\tikzstarpoints}{
+ -- (90+2*\i*\a-\a:\tikzstarradius/2) -- (90+2*\i*\a:\tikzstarradius)
+ } -- cycle;
+ }
+}
+
+\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);
+\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,
+ 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)},
+ 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,
+ 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});
+ }
+}
+
+\begin{tikzpicture}
+ \draw[pattern={lines[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]},
+ pattern color=blue] (2,0) rectangle ++(2,2);
+ \draw[pattern={lines[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]},
+ pattern color=orange] (2,2) rectangle ++(2,2);
+\end{tikzpicture}
+\end{codeexample}
%%% Local Variables:
%%% mode: latex