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

\subsection{Style Options}
\label{sec:styles}
\subsubsection{All Supported Styles}
\PGFPlots\ provides many styles to customize its appearance and behavior. They can be defined and changed in any place where keys are allowed. Furthermore, own styles are defined easily.

\begin{handler}{{.style}=\marg{key-value-list}}
	Defines or redefines a style \meta{key}. A style is a normal key which will set all options in \meta{key-value-list} when it is set.

	Use	|\pgfplotsset{|\meta{key}|/.style={|\meta{key-value-list}|}}| to (re)define a style \meta{key} in the namespace |/pgfplots|.
\end{handler}

\begin{handler}{{.append style}=\marg{key-value-list}}
	Appends \meta{key-value-list} to an already existing style \meta{key}. This is the preferred method to change the predefined styles: if you only append, you maintain compatibility with future versions.

	Use	|\pgfplotsset{|\meta{key}|/.append style={|\meta{key-value-list}|}}| to append \meta{key-value-list} to the style \meta{key}. This will assume the prefix |/pgfplots|.
\end{handler}

\subsubsection*{Styles installed for linear/logarithmic axis}

\begin{stylekey}{/pgfplots/every axis (initially empty)}
 Installed at the beginning of every axis. \Tikz\ options inside of it will be used for anything inside of the axis rectangle and any axis descriptions.
\end{stylekey}

\begin{stylekey}{/pgfplots/every semilogx axis (initially empty)}
 Installed at the beginning of every plot with linear $x$~axis and logarithmic $y$~axis, but after `|every axis|'.
\end{stylekey}

\begin{stylekey}{/pgfplots/every semilogy axis (initially empty)}
 Likewise, but with interchanged roles for $x$~and~$y$.
\end{stylekey}

\begin{stylekey}{/pgfplots/every loglog axis (initially empty)}
 Installed at the beginning of every log--log plot.
\end{stylekey}

\begin{stylekey}{/pgfplots/every linear axis (initially empty)}
 Installed at the beginning of every plot with normal axis scaling.
\end{stylekey}

\subsubsection*{Styles installed for single plots}

\begin{stylekey}{/pgfplots/every axis plot (initially empty)}
	Installed for each plot. This style may contain options like samples, gnuplot parameters, error bars and it may contain options which affect the final drawing commands.
\end{stylekey}

\begin{stylekey}{/pgfplots/every axis plot post (initially empty)}
 This style is similar to |every axis plot| in that is applies to any drawing command in |\addplot|. However, it is set \emph{after} any user defined styles or |cycle list| options.
\begin{codeexample}[]
\begin{tikzpicture}
\pgfplotsset{
	every axis plot post/.append style=
		{mark=none}}

\begin{axis}[
	legend style={
		at={(0.03,0.97)},anchor=north west},
	domain=0:1]
	\addplot {x^2};
	\addplot {exp(x)};
	\legend{$x^2$,$e^x$}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{stylekey}

\begin{stylekey}{/pgfplots/every axis plot no \# (initially empty)}
 Used for every \#th plot where $\#=0,1,2,3,4,\dotsc$.
\end{stylekey}

\begin{stylekey}{/pgfplots/every forget plot (initially empty)}
 Used for every plot which has |forget plot| activated.
\end{stylekey}

\pgfplotsshortstylekey forget plot style=every forget plot\pgfeov

\subsubsection*{Styles for axis descriptions}

\begin{stylekey}{/pgfplots/every axis label (initially empty)}
 Used for all axis label (like |xlabel| and |ylabel|).
\end{stylekey}

\pgfplotsshortstylekey label style=every axis label\pgfeov

\begin{xystylekey}{/pgfplots/every axis \x\ label}
Used only for $x$, $y$, or $z$ labels, respectively and installed after
 `|every axis label|'.

 The initial settings are set by |xlabel absolute| and its variants (if the initial configuration |compat=pre 1.3| is active) or |xlabel near ticks| which provides the better spacing as it incorporates the tick label sizes to compute the position.

\paragraph{Attention:} These styles will be overwritten by |axis x line| and/or |axis y line|. Please remember to place your modifications after the axis line variations.
\end{xystylekey}

\pgfplotsshortxystylekeys \x\ label style,\x label style=every axis \x\ label\pgfeov

\begin{stylekey}{/pgfplots/every axis title}
 Used for any axis title. The |at=|\parg{x,y} syntax will place the title using |axis description cs|.

The initial setting is
\begin{codeexample}[code only]
\pgfplotsset{every axis title/.style={at={(0.5,1)},above,yshift=6pt}}
\end{codeexample}

To be more precise, the |yshift| doesn't use the hardcoded |6pt|: it uses the value of
\begin{key}{/pgfplots/every axis title shift=\marg{default shift} (initially 6pt)}
\end{key}
which can be reset if needed.
\end{stylekey}

\pgfplotsshortstylekey title style=every axis title\pgfeov

\begin{stylekey}{/pgfplots/every axis legend}
 Installed for each legend. As described for |axis description cs|, the legend's position can be placed using coordinates between $0$~and~$1$ (it employs |axis description cs| automatically).

 The initial setting is
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.style={
		cells={anchor=center},
		inner xsep=3pt,inner ysep=2pt,nodes={inner sep=2pt,text depth=0.15em},
		anchor=north east,
		shape=rectangle,
		fill=white,draw=black,
		at={(0.98,0.98)}}}
\end{codeexample}
\end{stylekey}

\pgfplotsshortstylekey legend style=every axis legend\pgfeov

\begin{stylekey}{/pgfplots/every legend image post}
	Allows to change the appearance of the small legend images \emph{after} the options of the plot style have been applied. Thus, legend formatting can be changed independently of the plot style using |every legend image post|.

	This key is also documented on page~\pageref{key:legendimagepost}.
\end{stylekey}
\pgfplotsshortstylekey legend image post style=every legend image post\pgfeov

\begin{stylekey}{/pgfplots/every legend to name picture}
	A style for use with |legend to image|, see the documentation therein.
\end{stylekey}

\begin{stylekey}{/pgfplots/every colorbar}
	A style to change the |colorbar|. See page~\pageref{key:every:colorbar} for the reference documentation of |every colorbar|.
\end{stylekey}

\pgfplotsshortstylekey colorbar style=every colorbar\pgfeov

\subsubsection*{Styles for axis lines}
\begin{xystylekey}{/pgfplots/every outer \x\ axis line (initially empty)}
	Installed for every axis line which lies on the outer box.

	If you want arrow heads, you may also need to check the |separate axis lines| boolean key.
\end{xystylekey}

\begin{xystylekey}{/pgfplots/every inner \x\ axis line (initially empty)}
	Installed for every axis line which is drawn using the |center| or |middle| options.
\end{xystylekey}

\begin{pgfplotsxykeylist}{%
	axis line style=\marg{key-value-list},
	inner axis line style=\marg{key-value-list},
	outer axis line style=\marg{key-value-list},
	\x\ axis line style=\marg{key-value-list}}
	These options modify parts of the axis line styles. They append options to |every inner x axis line| and |every outer x axis line| and the respective $y$/$z$ variants.
\end{pgfplotsxykeylist}

\noindent
Please refer to Section~\ref{pgfplots:page:axislines} on page~\pageref{pgfplots:page:axislines} for details about styles for axis lines.

\begin{stylekey}{/pgfplots/every 3d box foreground}
	Installed for the parts drawn by |3d box=complete|. This affects axis lines, tick lines and grid lines drawn in the \emph{foreground}. The background drawing operations have already been done when this style is evaluated.
\end{stylekey}

\pgfplotsshortstylekey 3d box foreground style=every 3d box foreground\pgfeov

\begin{stylekey}{/pgfplots/every colorbar sampled line}
	To be used in conjunction with |colorbar sampled line|, see the documentation therein.
\end{stylekey}
\pgfplotsshortstylekey colorbar sampled line style=every colorbar sampled line\pgfeov

\subsubsection*{Styles for ticks}

\begin{stylekey}{/pgfplots/every tick (initially very thin,gray)}
 Installed for each of the small tick \emph{lines}.
\end{stylekey}

\pgfplotsshortstylekey tick style=every tick\pgfeov

\begin{stylekey}{/pgfplots/every minor tick  (initially empty)}
 Used for each minor tick line, installed after `|every tick|'.
\end{stylekey}

\pgfplotsshortstylekey minor tick style=every minor tick\pgfeov

\begin{stylekey}{/pgfplots/every major tick (initially empty)}
 Used for each major tick line, installed after `|every tick|'.
\end{stylekey}

\pgfplotsshortstylekey major tick style=every major tick\pgfeov

\begin{stylekey}{/pgfplots/every tick label (initially empty)}
 Used for each $x$~and~$y$ tick labels.
\end{stylekey}

\pgfplotsshortxystylekeys tick label style,ticklabel style=every tick label\pgfeov

\begin{xystylekey}{/pgfplots/every \x\ tick label (initially empty)}
 Used for each $x$ (or $y$ or $z$, respectively) tick label, installed after `|every tick label|'.
\end{xystylekey}

\pgfplotsshortxystylekeys \x\ tick label style,\x ticklabel style=every \x\ tick label\pgfeov

\begin{xystylekey}{/pgfplots/every \x\ tick scale label}
 Configures placement and display of the nodes containing the order of magnitude of tick labels, see Section~\ref{sec:scaled:ticks} for more information about |scaled ticks|.

The initial settings are
\begin{codeexample}[code only]
\pgfplotsset{
	every x tick scale label/.style={at={(1,0)},yshift=-2em,left,inner sep=0pt},
	every y tick scale label/.style={at={(0,1)},above right,inner sep=0pt,yshift=0.3em},
	every z tick scale label/.style={
	  at={(zticklabel cs:1.2,-\pgfplotsvalueoflargesttickdimen z -0.3em)},
	  anchor=near zticklabel,inner sep=0pt},
	}
\end{codeexample}
\end{xystylekey}

\pgfplotsshortxystylekey \x\ tick scale label style=every \x\ tick scale label\pgfeov

\begin{xystylekey}{/pgfplots/every \x\ tick (initially empty)}
	Installed for tick \emph{lines} on either $x$ or $y$ axis.
\end{xystylekey}

\pgfplotsshortxystylekey \x tick style=every \x\ tick\pgfeov

\begin{xystylekey}{/pgfplots/every minor \x\ tick (initially empty)}
	Installed for minor tick lines on either $x$ or $y$ axis.
\end{xystylekey}

\pgfplotsshortxystylekey minor \x\ tick style=every minor \x\ tick\pgfeov

\begin{xystylekey}{/pgfplots/every major \x\ tick (initially empty)}
	Installed for major tick lines on either $x$ or $y$ axis.
\end{xystylekey}
\pgfplotsshortxystylekey major \x\ tick style=every major \x\ tick\pgfeov

\begin{xystylekey}{/pgfplots/every extra \x\ tick}
 Allows to configure the appearance of `|extra x ticks|'. This style is installed before touching the first extra $x$~tick. It is possible to set any option which affects tick or grid line generation.

The initial setting is
\begin{codeexample}[code only]
\pgfplotsset{
	every extra x tick/.style={/pgfplots/log identify minor tick positions=true},
	every extra y tick/.style={/pgfplots/log identify minor tick positions=true}}
\end{codeexample}

 Useful examples are shown below.
\begin{codeexample}[code only]
\pgfplotsset{every extra x tick/.append style={grid=major}}
\pgfplotsset{every extra x tick/.append style={major tick length=0pt}}
\pgfplotsset{every extra x tick/.append style={/pgf/number format=sci subscript}}
\pgfplotsset{extra x tick style={
		color=red,
		tickwidth=3mm,
		% the initial 'every tick style' defines a 'line width'.
		% this here redefines it:
		tick style={
			line width=2mm,
		},
	}
}
\end{codeexample}
\end{xystylekey}

\pgfplotsshortxystylekey extra \x\ tick style=every extra \x\ tick\pgfeov

\begin{stylekey}{/pgfplots/extra tick style=\marg{key-value-list}}
	An abbreviation which appends \meta{key-value-list} to |every extra x tick|, |every extra y tick| and |every extra z tick|.
\end{stylekey}



\subsubsection*{Styles for grid lines}

\begin{stylekey}{/pgfplots/every axis grid (initially thin,black!25)}
 Used for each grid line.
\end{stylekey}

\pgfplotsshortstylekey grid style=every axis grid\pgfeov

\begin{stylekey}{/pgfplots/every minor grid (initially empty)}
 Used for each minor grid line, installed after `|every axis grid|'.
\end{stylekey}

\pgfplotsshortstylekey minor grid style=every minor grid\pgfeov

\begin{stylekey}{/pgfplots/every major grid (initially empty)}
 Likewise, for major grid lines.
\end{stylekey}

\pgfplotsshortstylekey major grid style=every major grid\pgfeov

\begin{xystylekey}{/pgfplots/every axis \x\ grid (initially empty)}
	Used for each grid line in either $x$ or $y$ direction.
\end{xystylekey}

\pgfplotsshortxystylekey \x\ grid style=every axis \x\ grid\pgfeov

\begin{xystylekey}{/pgfplots/every minor \x\ grid (initially empty)}
	Used for each minor grid line in either $x$ or $y$ direction.
\end{xystylekey}

\pgfplotsshortxystylekey minor \x\ grid style=every minor \x\ grid\pgfeov

\begin{xystylekey}{/pgfplots/every major \x\ grid (initially empty)}
	Used for each major grid line in either $x$ or $y$ direction.
\end{xystylekey}

\pgfplotsshortxystylekey major \x\ grid style=every major \x\ grid\pgfeov

\subsubsection*{Styles for error bars}

\begin{stylekey}{/pgfplots/every error bar (initially thin)}
 Installed for every error bar. 
\end{stylekey}

\pgfplotsshortstylekey error bars/error bar style=every error bar\pgfeov

\subsubsection{(Re)Defining Own Styles}
\label{sec:styles:own}%
Use |\pgfplotsset{|\meta{style name}|/.style=|\marg{key-value-list}|}|
to create own styles. If \meta{style name} exists already, it will be replaced. Please note that it is \emph{not} possible to use the \Tikz-command |\tikzstyle|\marg{style name}|=[]| in this context\footnote{This was possible in a previous version and is still supported for backwards compatibility. But in some cases, it may not work as expected.}.
\begin{codeexample}[]
\pgfplotsset{my personal style/.style=
	{grid=major,font=\large}}

\begin{tikzpicture}
\begin{axis}[my personal style]
	\addplot coordinates {(0,0) (1,1)};	
\end{axis}
\end{tikzpicture}
\end{codeexample}