summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex
blob: fe8d58ad4327c905bc8e37ab72a139dc2f6b354f (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

\subsection{About Options: Preliminaries}
\PGFPlots\ knowns a whole lot of key--value options which can be (re-)defined to activate desired features or modified to apply some fine tuning.

\noindent Most keys can be used like
\begin{codeexample}[code only]
\begin{tikzpicture}
\begin{axis}[key=value,key2=value2]
...
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent which changes them for the complete axis. Some keys can be changed for each plot:
\begin{codeexample}[code only]
\begin{tikzpicture}
\begin{axis}
\addplot[key=value,key2=value2] ... ;
\addplot+[key=value,key2=value2] ... ; % keeps the keys which would have been used by default
\end{axis}
\end{tikzpicture}
\end{codeexample}

The basic engine to manage key--value pairs is |pgfkeys| which is part of \pgfname. This engine always has a key name and a key ``path'', which is somehow similar to file name and directory of files. The common ``directory'' (key path) of \PGFPlots\ is `|/pgfplots/|'. Although the key definitions below provide this full path, it is always (well, almost always) enough to skipt this prefix -- \PGFPlots\ uses it automatically. The same holds for the prefixes `|/tikz/|' which are common for all \Tikz\ drawing options and `|/pgf/|' which are for the (more or less) low--level commands of \pgfname. All these prefixes can be omitted.

One important concept is the concept of styles. A style is a key which contains one or more other keys. It can be redefined or modified until it is actually used by the internal routines. Each single component of \Tikz\ and \PGFPlots\ can be configured with styles.

For example,
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={line width=1pt}}
\end{codeexample}
\noindent
sets the line width for every axis to |1pt|. 

There are several other styles predefined to modify the appearance, see section~\ref{sec:styles}.

\begin{command}{\pgfplotsset\marg{key-value-list}}
	Defines or sets all options in \marg{key-value-list}.
	
	It is a shortcut for |\pgfqkeys{/pgfplots}|\marg{key-value-list}, that means it inserts the prefix |/pgfplots| to any option which has no full path.

	This command can be used to define default options for the complete document or a part of the document. For example, 
\begin{codeexample}[code only]
\pgfplotsset{
	cycle list={%
		{red, mark=*}, {blue,mark=*},
		{red, mark=x}, {blue,mark=x},
		{red, mark=square*}, {blue,mark=square*},
		{red, mark=triangle*}, {blue,mark=triangle*},
		{red, mark=diamond*}, {blue,mark=diamond*},
		{red, mark=pentagon*}, {blue,mark=pentagon*}
	},
	legend style={
		at={(0.5,-0.2)},
		anchor=north,
		legend columns=2,
		cells={anchor=west},
		font=\footnotesize,
		rounded corners=2pt,
	},
	xlabel=$x$,ylabel=$f(x)$
}
\end{codeexample}
	can be used to set document--wise styles for line specifications, the legend's style and axis labels.

	You can also define new styles (collections of key--value--pairs) with |/.style| and |/.append style|.
\begin{codeexample}[code only]
\pgfplotsset{
	My Style 1/.style={xlabel=$x$, legend entries={1,2,3} },
	My Style 2/.style={xlabel=$X$, legend entries={4,5,6} }
}
\end{codeexample}
	The |/.style| and |/.append style| key handlers are described in section~\ref{sec:styles} in more detail.
\end{command}

\begin{handler}{{.code}=\marg{\TeX\ code}}
	Occasionally, the \PGFPlots\ user interface offers to replace parts of its routines. This is accomplished using so called ``code keys''. What it means is to replace the original key and its behavior with new \marg{\TeX\ code}. Inside of \marg{\TeX\ code}, any command can be used. Furthermore, the |#1| pattern will be the argument provided to the key.

\begin{codeexample}[]
\pgfplotsset{
	My Code/.code={I've been invoked with `#1'}}
\pgfplotsset{My Code={this here}}
\end{codeexample}
	The example defines a (new) key named |My Code|. Essentially, it is nothing else but a |\newcommand|, plugged into the key-value interface. The second statement ``invokes'' the code key.	
\end{handler}

\begin{handler}{{.code 2 args}=\marg{\TeX\ code}}
	As |/.code|, but this handler defines a key which accepts two arguments. When the so defined key is used, the two arguments are available as |#1| and |#2|.
\end{handler}

\begin{handler}{{.cd}}
	Each key has a fully qualified name with a (long) prefix, like |/pgfplots/xmin|. However, if the ``current directory'' is |/pgfplots|, it suffices to write just |xmin|. The |/.cd| key handler changes the ``current directory'' in this way.

	The prefixes |/tikz/| and |/pgfplots/| are checked automatically for any argument provided to |\begin{axis}|\oarg{options}  or |\addplot|. So, you won't need to worry about them, just leave them away -- and look closer in case the package doesn't identify the option.
\end{handler}

\subsubsection{Pgfplots Options and \Tikz\ Options}
This section is more or less technical and can be skipped unless one really wants to know more about this topic.

\Tikz\ options and \PGFPlots\ options can be mixed inside of the axis arguments and in any of the associated styles. For example,
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={
	legend columns=3,font=\Large}}
\end{codeexample}
\noindent
assigns the `|legend columns|' option (a \PGFPlots\ option) and uses `|font|' for drawing the legend (a \Tikz\ option). The point is: |legend columns| needs to be known \emph{before} the legend is typeset whereas |font| needs to be active when the legend is typeset. \PGFPlots\ sorts out any key dependencies automatically:

The axis environments will process any known \PGFPlots\ options, and all `|every|'--styles will be parsed for \PGFPlots\ options. Every unknown option is supposed to be a \Tikz\ option and will be forward to the associated \Tikz\ drawing commands. For example, the `|font=\Large|' above will be used as argument to the legend matrix, and the `|font=\Large|' argument in 
\begin{codeexample}[code only]
\pgfplotsset{every axis label/.append style={
	ylabel=Error,xlabel=Dof,font=\Large}}
\end{codeexample}
will be used in the nodes for axis labels (but not the axis title, for example).

It is an error if you assign incompatible options to axis labels, for example `|xmin|' and `|xmax|' can't be set inside of `|every axis label|'.