Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-xxcolor.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Extended Color Support}
12
13 This section documents the package \texttt{xxcolor}, which is currently
14 distributed as part of \pgfname. This package extends the \texttt{xcolor}
15 package, written by Uwe Kern, which in turn extends the \texttt{color} package.
16 I hope that the commands in \texttt{xxcolor} will some day migrate to
17 \texttt{xcolor}, such that this package becomes superfluous.
18
19 The main aim of the \texttt{xxcolor} package is to provide an environment
20 inside which all colors are ``washed out'' or ``dimmed''. This is useful in
21 numerous situations and must typically be achieved in a roundabout manner if
22 such an environment is not available.
23
24 \begin{environment}{{colormixin}\marg{mix-in specification}}
25 The mix-in specification is applied to all colors inside the environment.
26 At the beginning of the environment, the mix-in is applied to the current
27 color, i.e., the color that was in effect before the environment started.
28 A mix-in specification is a number between 0 and 100 followed by an
29 exclamation mark and a color name. When a |\color| command is encountered
30 inside a mix-in environment, the number states what percentage of the
31 desired color should be used. The rest is ``filled up'' with the color
32 given in the mix-in specification. Thus, a mix-in specification like
33 |90!blue| will mix in 10\% of blue into everything, whereas |25!white| will
34 make everything nearly white.
35 %
36 \begin{codeexample}[width=4cm,preamble={\usepackage{xxcolor}}]
37 \begin{minipage}{3.5cm}\raggedright
38 \color{red}Red text,%
39 \begin{colormixin}{25!white}
40 washed-out red text,
41 \color{blue} washed-out blue text,
42 \begin{colormixin}{25!black}
43 dark washed-out blue text,
44 \color{green} dark washed-out green text,%
45 \end{colormixin}
46 back to washed-out blue text,%
47 \end{colormixin}
48 and back to red.
49 \end{minipage}%
50 \end{codeexample}
51 %
52 \end{environment}
53
54 Note that the environment only changes colors that have been installed using
55 the standard \LaTeX\ |\color| command. In particular, the colors in images are
56 not changed. There is, however, some support offered by the commands
57 |\pgfuseimage| and |\pgfuseshading|. If the first command is invoked inside a
58 |colormixin| environment with the parameter, say, |50!black| on an image with
59 the name |foo|, the command will first check whether there is also a defined
60 image with the name |foo.!50!black|. If so, this image is used instead. This
61 allows you to provide a different image for this case. If you nest |colormixin|
62 environments, the different mix-ins are all appended. For example, inside the
63 inner environment of the above example, |\pgfuseimage{foo}| would first check
64 whether there exists an image named |foo.!25!white!25!black|.
65
66 \begin{command}{\colorcurrentmixin}
67 Expands to the current accumulated mix-in. Each nesting of a |colormixin|
68 adds a mix-in to this list.
69 %
70 \begin{codeexample}[preamble={\usepackage{xxcolor}
71 \usepackage{calc}}]
72 \begin{minipage}{\linewidth-6pt}\raggedright
73 \begin{colormixin}{75!white}
74 \colorcurrentmixin\ should be ``!75!white''\par
75 \begin{colormixin}{75!black}
76 \colorcurrentmixin\ should be ``!75!black!75!white''\par
77 \begin{colormixin}{50!white}
78 \colorcurrentmixin\ should be ``!50!white!75!black!75!white''\par
79 \end{colormixin}
80 \end{colormixin}
81 \end{colormixin}
82 \end{minipage}
83 \end{codeexample}
84 %
85 \end{command}