summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex
diff options
context:
space:
mode:
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.tex453
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}