summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex
blob: d714b8fa86e45cec73f86feeefe6b9bd519bc364 (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
% Copyright 2006 by Till Tantau
%
% 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{Pattern Library}
\label{section-library-patterns}

\begin{pgflibrary}{patterns}
    The package defines patterns for filling areas.
\end{pgflibrary}


\newcommand\patternindex[1]{%
  \index{#1@\protect\texttt{#1} pattern}%
  \index{Patterns!#1@\protect\texttt{#1}}%
  \texttt{#1}&
  \begin{tikzpicture}[baseline=.5ex]

    % Background
    \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);
  \end{tikzpicture} \\[1ex]
}

\newcommand\patternindexinherentlycolored[1]{%
  \index{#1@\protect\texttt{#1} pattern}%
  \index{Patterns!#1@\protect\texttt{#1}}%
  \texttt{#1}&
  \begin{tikzpicture}[baseline=.5ex]

    % Background
    \pattern [path fading=west,pattern=checkerboard light gray]
      (0,0) rectangle (5cm,2em);

    \pattern [pattern=#1,pattern color=blue] (0,0) rectangle +(5cm,2em);
  \end{tikzpicture} \\[1ex]
}


\subsection{Form-Only Patterns}

\begin{tabular}{ll}
    \emph{Pattern name}
        & \emph{Example (pattern in black, blue, and red on faded checkerboard)} \\
    \patternindex{horizontal lines}
    \patternindex{vertical lines}
    \patternindex{north east lines}
    \patternindex{north west lines}
    \patternindex{grid}
    \patternindex{crosshatch}
    \patternindex{dots}
    \patternindex{crosshatch dots}
    \patternindex{fivepointed stars}
    \patternindex{sixpointed stars}
    \patternindex{bricks}
    \patternindex{checkerboard}
\end{tabular}


\subsection{Inherently Colored Patterns}

\begin{tabular}{ll}
    \emph{Pattern name} & \emph{Example} \\
    \patternindexinherentlycolored{checkerboard light gray}
    \patternindexinherentlycolored{horizontal lines light gray}
    \patternindexinherentlycolored{horizontal lines gray}
    \patternindexinherentlycolored{horizontal lines dark gray}
    \patternindexinherentlycolored{horizontal lines light blue}
    \patternindexinherentlycolored{horizontal lines dark blue}
    \patternindexinherentlycolored{crosshatch dots gray}
    \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
%%% TeX-master: "pgfmanual-pdftex-version"
%%% End: