Commit | Line | Data |
---|---|---|
94249313 | 1 | @c This is part of the Emacs manual. |
ab422c4d PE |
2 | @c Copyright (C) 1987, 1993-1995, 1997, 2001-2013 Free Software |
3 | @c Foundation, Inc. | |
94249313 | 4 | @c See file emacs.texi for copying conditions. |
abb9615e | 5 | @node X Resources |
82f6e63d | 6 | @appendix X Options and Resources |
94249313 | 7 | |
82f6e63d | 8 | You can customize some X-related aspects of Emacs behavior using X |
06848b82 CY |
9 | resources, as is usual for programs that use X. |
10 | ||
11 | When Emacs is compiled with GTK+ support, the appearance of various | |
12 | graphical widgets, such as the menu-bar, scroll-bar, and dialog boxes, | |
13 | is determined by | |
e8fd09cc JD |
14 | @ifnottex |
15 | ``GTK resources'', which we will also describe. | |
16 | @end ifnottex | |
17 | @iftex | |
06848b82 | 18 | ``GTK resources''. |
e8fd09cc | 19 | @end iftex |
06848b82 CY |
20 | When Emacs is built without GTK+ support, the appearance of these |
21 | widgets is determined by additional X resources. | |
e8fd09cc | 22 | |
06848b82 CY |
23 | On MS-Windows, you can customize some of the same aspects using the |
24 | system registry (@pxref{MS-Windows Registry}). | |
405f4489 RS |
25 | |
26 | @menu | |
82f6e63d RS |
27 | * Resources:: Using X resources with Emacs (in general). |
28 | * Table of Resources:: Table of specific X resources that affect Emacs. | |
405f4489 | 29 | * Lucid Resources:: X resources for Lucid menus. |
5d85cfe6 | 30 | * Motif Resources:: X resources for Motif and LessTif menus. |
488dd4c4 | 31 | * GTK resources:: Resources for GTK widgets. |
405f4489 RS |
32 | @end menu |
33 | ||
113c2ede | 34 | @node Resources |
94249313 RS |
35 | @appendixsec X Resources |
36 | @cindex resources | |
4fc31427 RS |
37 | @cindex X resources |
38 | @cindex @file{~/.Xdefaults} file | |
39 | @cindex @file{~/.Xresources} file | |
94249313 | 40 | |
9b7e4229 RS |
41 | Programs running under the X Window System organize their user |
42 | options under a hierarchy of classes and resources. You can specify | |
ac36a8f1 CY |
43 | default values for these options in your @dfn{X resource file}, |
44 | usually named @file{~/.Xdefaults} or @file{~/.Xresources}. Changes in | |
45 | this file do not take effect immediately, because the X server stores | |
46 | its own list of resources; to update it, use the command | |
47 | @command{xrdb}---for instance, @samp{xrdb ~/.Xdefaults}. | |
94249313 | 48 | |
8034735f | 49 | @cindex registry, setting resources (MS-Windows) |
9eb25ee8 | 50 | (MS-Windows systems do not support X resource files; on such systems, |
ac36a8f1 | 51 | Emacs looks for X resources in the Windows Registry, first under the |
8034735f EZ |
52 | key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs}, which affects only |
53 | the current user and override the system-wide settings, and then under | |
54 | the key @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}, which affects | |
55 | all users of the system. The menu and scroll bars are native widgets | |
56 | on MS-Windows, so they are only customizable via the system-wide | |
57 | settings in the Display Control Panel. You can also set resources | |
58 | using the @samp{-xrm} command line option, as explained below.) | |
94249313 | 59 | |
ac36a8f1 | 60 | Each line in the X resource file specifies a value for one option or |
06848b82 CY |
61 | for a collection of related options. The order in which the lines |
62 | appear in the file does not matter. Each resource specification | |
ac36a8f1 CY |
63 | consists of a @dfn{program name} and a @dfn{resource name}. Case |
64 | distinctions are significant in each of these names. Here is an | |
65 | example: | |
94249313 RS |
66 | |
67 | @example | |
06848b82 | 68 | emacs.cursorColor: dark green |
94249313 RS |
69 | @end example |
70 | ||
ac36a8f1 CY |
71 | The program name is the name of the executable file to which the |
72 | resource applies. For Emacs, this is normally @samp{emacs}. To | |
73 | specify a definition that applies to all instances of Emacs, | |
74 | regardless of the name of the Emacs executable, use @samp{Emacs}. | |
75 | ||
76 | The resource name is the name of a program setting. For instance, | |
06848b82 CY |
77 | Emacs recognizes a @samp{cursorColor} resource that controls the color |
78 | of the text cursor. | |
ac36a8f1 CY |
79 | |
80 | Resources are grouped into named classes. For instance, the | |
06848b82 CY |
81 | @samp{Foreground} class contains the @samp{cursorColor}, |
82 | @samp{foreground} and @samp{pointerColor} resources (@pxref{Table of | |
83 | Resources}). Instead of using a resource name, you can use a class | |
84 | name to specify the default value for all resources in that class, | |
85 | like this: | |
94249313 RS |
86 | |
87 | @example | |
06848b82 | 88 | emacs.Foreground: dark green |
94249313 | 89 | @end example |
91ed7ea8 CY |
90 | |
91 | Emacs does not process X resources at all if you set the variable | |
06848b82 CY |
92 | @code{inhibit-x-resources} to a non-@code{nil} value. If you invoke |
93 | Emacs with the @samp{-Q} (or @samp{--quick}) command-line option, | |
94 | @code{inhibit-x-resources} is automatically set to @code{t} | |
95 | (@pxref{Initial Options}). | |
e8fd09cc JD |
96 | |
97 | @ifnottex | |
91ed7ea8 CY |
98 | In addition, you can use the following command-line options to |
99 | override the X resources file: | |
94249313 RS |
100 | |
101 | @table @samp | |
102 | @item -name @var{name} | |
103 | @opindex --name | |
104 | @itemx --name=@var{name} | |
105 | @cindex resource name, command-line argument | |
ac36a8f1 CY |
106 | This option sets the program name of the initial Emacs frame to |
107 | @var{name}. It also sets the title of the initial frame to | |
108 | @var{name}. This option does not affect subsequent frames. | |
94249313 RS |
109 | |
110 | If you don't specify this option, the default is to use the Emacs | |
ac36a8f1 CY |
111 | executable's name as the program name. |
112 | ||
113 | For consistency, @samp{-name} also specifies the name to use for other | |
114 | resource values that do not belong to any particular frame. | |
115 | ||
116 | The resources that name Emacs invocations also belong to a class, | |
117 | named @samp{Emacs}. If you write @samp{Emacs} instead of | |
118 | @samp{emacs}, the resource applies to all frames in all Emacs jobs, | |
119 | regardless of frame titles and regardless of the name of the | |
120 | executable file. | |
94249313 RS |
121 | |
122 | @item -xrm @var{resource-values} | |
123 | @opindex --xrm | |
124 | @itemx --xrm=@var{resource-values} | |
125 | @cindex resource values, command-line argument | |
ac36a8f1 CY |
126 | This option specifies X resource values for the present Emacs job. |
127 | ||
128 | @var{resource-values} should have the same format that you would use | |
129 | inside a file of X resources. To include multiple resource | |
130 | specifications in @var{resource-values}, put a newline between them, | |
131 | just as you would in a file. You can also use @samp{#include | |
132 | "@var{filename}"} to include a file full of resource specifications. | |
133 | Resource values specified with @samp{-xrm} take precedence over all | |
134 | other resource specifications. | |
94249313 | 135 | @end table |
ac36a8f1 | 136 | @end ifnottex |
94249313 | 137 | |
82f6e63d RS |
138 | @node Table of Resources |
139 | @appendixsec Table of X Resources for Emacs | |
140 | ||
06848b82 CY |
141 | This table lists the X resource names that Emacs recognizes, |
142 | excluding those that control the appearance of graphical widgets like | |
143 | the menu bar: | |
94249313 RS |
144 | |
145 | @table @asis | |
146 | @item @code{background} (class @code{Background}) | |
06848b82 | 147 | Background color (@pxref{Colors}). |
94249313 RS |
148 | |
149 | @item @code{bitmapIcon} (class @code{BitmapIcon}) | |
33ed493b | 150 | Tell the window manager to display the Emacs icon if @samp{on}; don't |
06848b82 | 151 | do so if @samp{off}. @xref{Icons X}, for a description of the icon. |
94249313 | 152 | |
06848b82 | 153 | @ifnottex |
94249313 | 154 | @item @code{borderColor} (class @code{BorderColor}) |
06848b82 CY |
155 | Color of the frame's external border. This has no effect if Emacs is |
156 | compiled with GTK+ support. | |
94249313 RS |
157 | |
158 | @item @code{borderWidth} (class @code{BorderWidth}) | |
06848b82 CY |
159 | Width of the frame's external border, in pixels. This has no effect |
160 | if Emacs is compiled with GTK+ support. | |
e8fd09cc | 161 | @end ifnottex |
94249313 RS |
162 | |
163 | @item @code{cursorColor} (class @code{Foreground}) | |
06848b82 CY |
164 | Text cursor color. If this resource is specified when Emacs starts |
165 | up, Emacs sets its value as the background color of the @code{cursor} | |
166 | face (@pxref{Faces}). | |
94249313 | 167 | |
ed0fb1f1 | 168 | @item @code{cursorBlink} (class @code{CursorBlink}) |
06848b82 CY |
169 | If the value of this resource is @samp{off} or @samp{false} or |
170 | @samp{0} at startup, Emacs disables Blink Cursor mode (@pxref{Cursor | |
171 | Display}). | |
ed0fb1f1 | 172 | |
94249313 | 173 | @item @code{font} (class @code{Font}) |
06848b82 | 174 | Font name for the @code{default} face (@pxref{Fonts}). You can also |
ac36a8f1 CY |
175 | specify a fontset name (@pxref{Fontsets}). |
176 | ||
177 | @item @code{fontBackend} (class @code{FontBackend}) | |
06848b82 CY |
178 | Comma-delimited list of backend(s) to use for drawing fonts, in order |
179 | of precedence. For instance, the value @samp{x,xft} tells Emacs to | |
ac36a8f1 | 180 | draw fonts using the X core font driver, falling back on the Xft font |
06848b82 CY |
181 | driver if that fails. Normally, you should leave this resource unset, |
182 | in which case Emacs tries using all available font backends. | |
94249313 RS |
183 | |
184 | @item @code{foreground} (class @code{Foreground}) | |
06848b82 | 185 | Default foreground color for text. |
94249313 RS |
186 | |
187 | @item @code{geometry} (class @code{Geometry}) | |
06848b82 CY |
188 | Window size and position. The value should be a size and position |
189 | specification, of the same form as in the @samp{-g} or | |
190 | @samp{--geometry} command-line option (@pxref{Window Size X}). | |
94249313 | 191 | |
06848b82 CY |
192 | The size applies to all frames in the Emacs session, but the position |
193 | applies only to the initial Emacs frame (or, in the case of a resource | |
194 | for a specific frame name, only that frame). | |
195 | ||
196 | ||
197 | Be careful not to specify this resource as @samp{emacs*geometry}, as | |
198 | that may affect individual menus as well as the main Emacs frame. | |
94249313 | 199 | |
e1556251 | 200 | @item @code{fullscreen} (class @code{Fullscreen}) |
cf225974 | 201 | The desired fullscreen size. The value can be one of @code{fullboth}, |
06848b82 CY |
202 | @code{maximized}, @code{fullwidth} or @code{fullheight}, which |
203 | correspond to the command-line options @samp{-fs}, @samp{-mm}, | |
204 | @samp{-fw}, and @samp{-fh} (@pxref{Window Size X}). Note that this | |
205 | applies to the initial frame only. | |
e1556251 | 206 | |
06848b82 | 207 | @ifnottex |
94249313 RS |
208 | @item @code{iconName} (class @code{Title}) |
209 | Name to display in the icon. | |
210 | ||
211 | @item @code{internalBorder} (class @code{BorderWidth}) | |
06848b82 CY |
212 | Width of the internal frame border, in pixels. |
213 | @end ifnottex | |
94249313 RS |
214 | |
215 | @item @code{lineSpacing} (class @code{LineSpacing}) | |
216 | @cindex line spacing | |
06848b82 | 217 | Additional space between lines, in pixels. |
94249313 RS |
218 | |
219 | @item @code{menuBar} (class @code{MenuBar}) | |
d90a6f50 | 220 | @cindex menu bar |
06848b82 CY |
221 | If the value of this resource is @samp{off} or @samp{false} or |
222 | @samp{0}, Emacs disables Menu Bar mode at startup (@pxref{Menu Bars}). | |
94249313 | 223 | |
e8fd09cc | 224 | @ifnottex |
94249313 | 225 | @item @code{minibuffer} (class @code{Minibuffer}) |
06848b82 CY |
226 | If @samp{none}, Emacs will not make a minibuffer in this frame; it |
227 | will use a separate minibuffer frame instead. | |
94249313 RS |
228 | |
229 | @item @code{paneFont} (class @code{Font}) | |
230 | @cindex font for menus | |
231 | Font name for menu pane titles, in non-toolkit versions of Emacs. | |
e8fd09cc | 232 | @end ifnottex |
94249313 RS |
233 | |
234 | @item @code{pointerColor} (class @code{Foreground}) | |
06848b82 CY |
235 | Color of the mouse cursor. This has no effect in many graphical |
236 | desktop environments, as they do not let Emacs change the mouse cursor | |
237 | this way. | |
94249313 | 238 | |
e8fd09cc | 239 | @ifnottex |
94249313 RS |
240 | @item @code{privateColormap} (class @code{PrivateColormap}) |
241 | If @samp{on}, use a private color map, in the case where the ``default | |
242 | visual'' of class PseudoColor and Emacs is using it. | |
94249313 RS |
243 | |
244 | @item @code{reverseVideo} (class @code{ReverseVideo}) | |
245 | Switch foreground and background default colors if @samp{on}, use colors as | |
246 | specified if @samp{off}. | |
247 | ||
248 | @item @code{screenGamma} (class @code{ScreenGamma}) | |
249 | @cindex gamma correction | |
250 | Gamma correction for colors, equivalent to the frame parameter | |
251 | @code{screen-gamma}. | |
252 | ||
73271565 JD |
253 | @item @code{scrollBarWidth} (class @code{ScrollBarWidth}) |
254 | @cindex scrollbar width | |
255 | The scroll bar width in pixels, equivalent to the frame parameter | |
06848b82 CY |
256 | @code{scroll-bar-width}. Do not set this resource if Emacs is |
257 | compiled with GTK+ support. | |
258 | @end ifnottex | |
73271565 | 259 | |
e8fd09cc | 260 | @ifnottex |
02e740dc | 261 | @item @code{selectionFont} (class @code{SelectionFont}) |
94249313 | 262 | Font name for pop-up menu items, in non-toolkit versions of Emacs. (For |
5d85cfe6 | 263 | toolkit versions, see @ref{Lucid Resources}, also see @ref{Motif |
94249313 RS |
264 | Resources}.) |
265 | ||
02e740dc DL |
266 | @item @code{selectionTimeout} (class @code{SelectionTimeout}) |
267 | Number of milliseconds to wait for a selection reply. | |
268 | If the selection owner doesn't reply in this time, we give up. | |
269 | A value of 0 means wait as long as necessary. | |
270 | ||
94249313 RS |
271 | @item @code{synchronous} (class @code{Synchronous}) |
272 | @cindex debugging X problems | |
273 | @cindex synchronous X mode | |
274 | Run Emacs in synchronous mode if @samp{on}. Synchronous mode is | |
275 | useful for debugging X problems. | |
e8fd09cc | 276 | @end ifnottex |
94249313 RS |
277 | |
278 | @item @code{title} (class @code{Title}) | |
279 | Name to display in the title bar of the initial Emacs frame. | |
280 | ||
4fc31427 | 281 | @item @code{toolBar} (class @code{ToolBar}) |
d90a6f50 | 282 | @cindex tool bar |
06848b82 CY |
283 | If the value of this resource is @samp{off} or @samp{false} or |
284 | @samp{0}, Emacs disables Tool Bar mode at startup (@pxref{Tool Bars}). | |
4fc31427 | 285 | |
d90a6f50 DL |
286 | @item @code{useXIM} (class @code{UseXIM}) |
287 | @cindex XIM | |
288 | @cindex X input methods | |
289 | @cindex input methods, X | |
06848b82 CY |
290 | Disable use of X input methods (XIM) if @samp{false} or @samp{off}. |
291 | This is only relevant if your Emacs is built with XIM support. It | |
292 | might be useful to turn off XIM on slow X client/server links. | |
d90a6f50 | 293 | |
94249313 RS |
294 | @item @code{verticalScrollBars} (class @code{ScrollBars}) |
295 | Give frames scroll bars if @samp{on}; don't have scroll bars if | |
296 | @samp{off}. | |
10214524 | 297 | |
e8fd09cc | 298 | @ifnottex |
10214524 | 299 | @item @code{visualClass} (class @code{VisualClass}) |
06848b82 CY |
300 | The @dfn{visual class} for X color display. If specified, the value |
301 | should start with one of @samp{TrueColor}, @samp{PseudoColor}, | |
302 | @samp{DirectColor}, @samp{StaticColor}, @samp{GrayScale}, and | |
303 | @samp{StaticGray}, followed by @samp{-@var{depth}}, where @var{depth} | |
304 | is the number of color planes. | |
e8fd09cc | 305 | @end ifnottex |
94249313 RS |
306 | @end table |
307 | ||
06848b82 CY |
308 | You can also use X resources to customize individual Emacs faces |
309 | (@pxref{Faces}). For example, setting the resource | |
310 | @samp{@var{face}.attributeForeground} is equivalent to customizing the | |
311 | @samp{foreground} attribute of the face @var{face}. However, we | |
312 | recommend customizing faces from within Emacs, instead of using X | |
313 | resources. @xref{Face Customization}. | |
94249313 | 314 | |
06848b82 | 315 | @ifnottex |
94249313 | 316 | @node Lucid Resources |
1ecb2d3f | 317 | @appendixsec Lucid Menu And Dialog X Resources |
94249313 | 318 | @cindex Menu X Resources (Lucid widgets) |
1ecb2d3f | 319 | @cindex Dialog X Resources (Lucid widgets) |
94249313 RS |
320 | @cindex Lucid Widget X Resources |
321 | ||
06848b82 CY |
322 | If Emacs is compiled with the X toolkit support using Lucid widgets, |
323 | you can use X resources to customize the appearance of the menu bar, | |
324 | pop-up menus, and dialog boxes. The resources for the menu bar fall | |
325 | in the @samp{pane.menubar} class (following, as always, either the | |
326 | name of the Emacs executable or @samp{Emacs} for all Emacs | |
327 | invocations). The resources for the pop-up menu are in the | |
328 | @samp{menu*} class. The resources for dialog boxes are in the | |
329 | @samp{dialog*} class. | |
94249313 | 330 | |
06848b82 CY |
331 | For example, to display menu bar entries with the @samp{Courier-12} |
332 | font (@pxref{Fonts}), write this: | |
94249313 RS |
333 | |
334 | @example | |
06848b82 | 335 | Emacs.pane.menubar.font: Courier-12 |
94249313 RS |
336 | @end example |
337 | ||
338 | @noindent | |
06848b82 CY |
339 | Lucid widgets can display multilingual text in your locale. To enable |
340 | this, specify a @code{fontSet} resource instead of a @code{font} | |
341 | resource. @xref{Fontsets}. If both @code{font} and @code{fontSet} | |
342 | resources are specified, the @code{fontSet} resource is used. | |
e8fd09cc | 343 | |
06848b82 | 344 | Here is a list of resources for menu bars, pop-up menus, and dialogs: |
94249313 RS |
345 | |
346 | @table @code | |
347 | @item font | |
348 | Font for menu item text. | |
0d0e15c3 JD |
349 | @item fontSet |
350 | Fontset for menu item text. | |
94249313 | 351 | @item foreground |
06848b82 | 352 | Foreground color. |
94249313 | 353 | @item background |
06848b82 | 354 | Background color. |
94249313 | 355 | @item buttonForeground |
06848b82 | 356 | Foreground color for a selected item. |
e8fd09cc | 357 | @ifnottex |
94249313 RS |
358 | @item horizontalSpacing |
359 | Horizontal spacing in pixels between items. Default is 3. | |
360 | @item verticalSpacing | |
f2daf7e9 | 361 | Vertical spacing in pixels between items. Default is 2. |
94249313 RS |
362 | @item arrowSpacing |
363 | Horizontal spacing between the arrow (which indicates a submenu) and | |
364 | the associated text. Default is 10. | |
365 | @item shadowThickness | |
06848b82 CY |
366 | Thickness of shadow lines for 3D buttons, arrows, and other graphical |
367 | elements. Default is 1. | |
e8fd09cc | 368 | @end ifnottex |
94249313 | 369 | @item margin |
06848b82 | 370 | Margin of the menu bar, in characters. Default is 1. |
94249313 RS |
371 | @end table |
372 | ||
5d85cfe6 UM |
373 | @node Motif Resources |
374 | @appendixsec Motif Menu X Resources | |
375 | @cindex Menu X Resources (Motif widgets) | |
376 | @cindex Motif Widget X Resources | |
94249313 | 377 | |
5d85cfe6 UM |
378 | If Emacs is compiled with the X toolkit support using Motif or |
379 | LessTif widgets, you can use X resources to customize the appearance | |
380 | of the menu bar, pop-up menus, and dialog boxes. However, the | |
381 | resources are organized differently from Lucid widgets. | |
94249313 | 382 | |
06848b82 CY |
383 | The resource names for the menu bar are in the @samp{pane.menubar} |
384 | class, and they must be specified in this form: | |
94249313 RS |
385 | |
386 | @smallexample | |
387 | Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value} | |
388 | @end smallexample | |
389 | ||
06848b82 CY |
390 | @noindent |
391 | For pop-up menus, the resources are in the @samp{menu*} class, instead | |
392 | of @samp{pane.menubar}. For dialog boxes, they are in @samp{dialog}. | |
393 | In each case, each individual menu string is a subwidget; the | |
394 | subwidget's name is the same as the menu item string. For example, | |
395 | the @samp{File} menu in the menu bar is a subwidget named | |
396 | @samp{emacs.pane.menubar.File}. | |
397 | ||
398 | Typically, you want to specify the same resources for the whole menu | |
399 | bar. To do this, use @samp{*} instead of a specific subwidget name. | |
400 | For example, to specify the font @samp{8x16} for all menu bar items, | |
401 | including submenus, write this: | |
94249313 RS |
402 | |
403 | @smallexample | |
404 | Emacs.pane.menubar.*.fontList: 8x16 | |
405 | @end smallexample | |
406 | ||
06848b82 CY |
407 | Each item in a submenu also has its own name for X resources; for |
408 | example, the @samp{File} submenu has an item named @samp{Save (current | |
409 | buffer)}. A resource specification for a submenu item looks like | |
410 | this: | |
94249313 RS |
411 | |
412 | @smallexample | |
413 | Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value} | |
414 | @end smallexample | |
415 | ||
416 | @noindent | |
417 | For example, here's how to specify the font for the @samp{Save (current | |
418 | buffer)} item: | |
419 | ||
420 | @smallexample | |
421 | Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16 | |
422 | @end smallexample | |
423 | ||
424 | @noindent | |
425 | For an item in a second-level submenu, such as @samp{Complete Word} | |
426 | under @samp{Spell Checking} under @samp{Tools}, the resource fits this | |
427 | template: | |
428 | ||
429 | @smallexample | |
430 | Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value} | |
431 | @end smallexample | |
432 | ||
433 | @noindent | |
434 | For example, | |
435 | ||
436 | @smallexample | |
437 | Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value} | |
438 | @end smallexample | |
439 | ||
440 | @noindent | |
441 | (This should be one long line.) | |
177c0ea7 | 442 | |
06848b82 CY |
443 | If you want the submenu items to look different from the menu bar |
444 | itself, you must first specify the resource for all of them, then | |
445 | override the value for submenus alone. Here is an example: | |
94249313 RS |
446 | |
447 | @smallexample | |
448 | Emacs.pane.menubar.*.fontList: 8x16 | |
449 | Emacs.pane.menubar.popup_*.fontList: 8x16 | |
450 | @end smallexample | |
451 | ||
06848b82 | 452 | To specify resources for the LessTif file-selection box, use |
94249313 RS |
453 | @samp{fsb*}, like this: |
454 | ||
455 | @example | |
456 | Emacs.fsb*.fontList: 8x16 | |
457 | @end example | |
458 | ||
06848b82 | 459 | Here is a list of resources for LessTif menu bars and pop-up menus: |
94249313 RS |
460 | |
461 | @table @code | |
462 | @item armColor | |
463 | The color to show in an armed button. | |
464 | @item fontList | |
465 | The font to use. | |
466 | @item marginBottom | |
467 | @itemx marginHeight | |
468 | @itemx marginLeft | |
469 | @itemx marginRight | |
470 | @itemx marginTop | |
471 | @itemx marginWidth | |
472 | Amount of space to leave around the item, within the border. | |
473 | @item borderWidth | |
474 | The width of the border around the menu item, on all sides. | |
475 | @item shadowThickness | |
476 | The width of the border shadow. | |
477 | @item bottomShadowColor | |
478 | The color for the border shadow, on the bottom and the right. | |
479 | @item topShadowColor | |
480 | The color for the border shadow, on the top and the left. | |
481 | @end table | |
e8fd09cc | 482 | @end ifnottex |
488dd4c4 | 483 | |
488dd4c4 JD |
484 | @node GTK resources |
485 | @appendixsec GTK resources | |
06848b82 CY |
486 | @cindex GTK+ resources |
487 | @cindex resource files for GTK | |
488 | @cindex @file{~/.gtkrc-2.0} file | |
489 | @cindex @file{~/.emacs.d/gtkrc} file | |
e8fd09cc | 490 | |
06848b82 | 491 | If Emacs is compiled with GTK+ toolkit support, the simplest way to |
1df7defd | 492 | customize its GTK+ widgets (e.g., menus, dialogs, tool bars and |
06848b82 CY |
493 | scroll bars) is to choose an appropriate GTK+ theme, for example with |
494 | the GNOME theme selector. | |
495 | ||
496 | In GTK+ version 2, you can also use @dfn{GTK+ resources} to | |
497 | customize the appearance of GTK+ widgets used by Emacs. These | |
498 | resources are specified in either the file @file{~/.emacs.d/gtkrc} | |
499 | (for Emacs-specific GTK+ resources), or @file{~/.gtkrc-2.0} (for | |
500 | general GTK+ resources). We recommend using @file{~/.emacs.d/gtkrc}, | |
501 | since GTK+ seems to ignore @file{~/.gtkrc-2.0} when running GConf with | |
1df7defd | 502 | GNOME@. Note, however, that some GTK themes may override |
06848b82 CY |
503 | customizations in @file{~/.emacs.d/gtkrc}; there is nothing we can do |
504 | about this. GTK+ resources do not affect aspects of Emacs unrelated | |
505 | to GTK+ widgets, such as fonts and colors in the main Emacs window; | |
506 | those are governed by normal X resources (@pxref{Resources}). | |
507 | ||
508 | The following sections describe how to customize GTK+ resources for | |
509 | Emacs. For details about GTK+ resources, see the GTK+ API document at | |
336d2ce2 | 510 | @uref{http://developer.gnome.org/gtk2/stable/gtk2-Resource-Files.html}. |
e8fd09cc | 511 | |
06848b82 CY |
512 | In GTK+ version 3, GTK+ resources have been replaced by a completely |
513 | different system. The appearance of GTK+ widgets is now determined by | |
514 | CSS-like style files: @file{gtk-3.0/gtk.css} in the GTK+ installation | |
515 | directory, and @file{~/.themes/@var{theme}/gtk-3.0/gtk.css} for local | |
516 | style settings (where @var{theme} is the name of the current GTK+ | |
517 | theme). Therefore, the description of GTK+ resources in this section | |
518 | does not apply to GTK+ 3. For details about the GTK+ 3 styling | |
519 | system, see | |
520 | @uref{http://developer.gnome.org/gtk3/3.0/GtkCssProvider.html}. | |
e8fd09cc | 521 | |
06848b82 CY |
522 | @menu |
523 | * GTK Resource Basics:: Basic usage of GTK+ resources. | |
524 | * GTK Widget Names:: How GTK+ widgets are named. | |
525 | * GTK Names in Emacs:: GTK widgets used by Emacs. | |
526 | * GTK styles:: What can be customized in a GTK widget. | |
527 | @end menu | |
e8fd09cc | 528 | |
06848b82 CY |
529 | @node GTK Resource Basics |
530 | @appendixsubsec GTK Resource Basics | |
e8fd09cc | 531 | |
06848b82 CY |
532 | In a GTK+ 2 resource file (usually @file{~/.emacs.d/gtkrc}), the |
533 | simplest kinds of resource settings simply assign a value to a | |
534 | variable. For example, putting the following line in the resource | |
535 | file changes the font on all GTK+ widgets to @samp{courier-12}: | |
e8fd09cc JD |
536 | |
537 | @smallexample | |
06848b82 | 538 | gtk-font-name = "courier 12" |
e8fd09cc | 539 | @end smallexample |
c6aea8f8 | 540 | |
06848b82 CY |
541 | @noindent |
542 | Note that in this case the font name must be supplied as a GTK font | |
543 | pattern (also called a @dfn{Pango font name}), not as a | |
1df7defd | 544 | Fontconfig-style font name or XLFD@. @xref{Fonts}. |
e8fd09cc | 545 | |
06848b82 CY |
546 | To customize widgets you first define a @dfn{style}, and then apply |
547 | the style to the widgets. Here is an example that sets the font for | |
548 | menus (@samp{#} characters indicate comments): | |
e8fd09cc JD |
549 | |
550 | @smallexample | |
06848b82 CY |
551 | # @r{Define the style @samp{my_style}.} |
552 | style "my_style" | |
e8fd09cc JD |
553 | @{ |
554 | font_name = "helvetica bold 14" | |
555 | @} | |
556 | ||
06848b82 CY |
557 | # @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{my_style}.} |
558 | widget "*emacs-menuitem*" style "my_style" | |
e8fd09cc JD |
559 | @end smallexample |
560 | ||
561 | @noindent | |
06848b82 CY |
562 | The widget name in this example contains wildcards, so the style is |
563 | applied to all widgets matching @samp{*emacs-menuitem*}. The widgets | |
564 | are named by the way they are contained, from the outer widget to the | |
565 | inner widget. Here is another example that applies @samp{my_style} | |
566 | specifically to the Emacs menu bar: | |
e8fd09cc JD |
567 | |
568 | @smallexample | |
06848b82 | 569 | widget "Emacs.pane.menubar.*" style "my_style" |
e8fd09cc JD |
570 | @end smallexample |
571 | ||
572 | Here is a more elaborate example, showing how to change the parts of | |
573 | the scroll bar: | |
574 | ||
575 | @smallexample | |
576 | style "scroll" | |
577 | @{ | |
06848b82 CY |
578 | fg[NORMAL] = "red"@ @ @ @ @ # @r{Arrow color.} |
579 | bg[NORMAL] = "yellow"@ @ # @r{Thumb and background around arrow.} | |
580 | bg[ACTIVE] = "blue"@ @ @ @ # @r{Trough color.} | |
581 | bg[PRELIGHT] = "white"@ # @r{Thumb color when the mouse is over it.} | |
e8fd09cc JD |
582 | @} |
583 | ||
584 | widget "*verticalScrollBar*" style "scroll" | |
585 | @end smallexample | |
583a618e | 586 | |
06848b82 | 587 | @node GTK Widget Names |
488dd4c4 JD |
588 | @appendixsubsec GTK widget names |
589 | @cindex GTK widget names | |
590 | ||
06848b82 CY |
591 | A GTK+ widget is specified by a @dfn{widget name} and a @dfn{widget |
592 | class}. The widget name refers to a specific widget | |
1df7defd PE |
593 | (e.g., @samp{emacs-menuitem}), while the widget class refers to a |
594 | collection of similar widgets (e.g., @samp{GtkMenuItem}). A widget | |
06848b82 | 595 | always has a class, but need not have a name. |
488dd4c4 | 596 | |
10214524 RS |
597 | @dfn{Absolute names} are sequences of widget names or widget |
598 | classes, corresponding to hierarchies of widgets embedded within | |
599 | other widgets. For example, if a @code{GtkWindow} named @code{top} | |
600 | contains a @code{GtkVBox} named @code{box}, which in turn contains | |
601 | a @code{GtkMenuBar} called @code{menubar}, the absolute class name | |
602 | of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and | |
603 | its absolute widget name is @code{top.box.menubar}. | |
488dd4c4 | 604 | |
06848b82 CY |
605 | GTK+ resource files can contain two types of commands for specifying |
606 | widget appearances: | |
10214524 | 607 | |
06848b82 CY |
608 | @table @code |
609 | @item widget | |
610 | specifies a style for widgets based on the class name, or just the | |
611 | class. | |
10214524 | 612 | |
06848b82 CY |
613 | @item widget_class |
614 | specifies a style for widgets based on the class name. | |
10214524 RS |
615 | @end table |
616 | ||
617 | @noindent | |
06848b82 CY |
618 | See the previous subsection for examples of using the @code{widget} |
619 | command; the @code{widget_class} command is used similarly. Note that | |
620 | the widget name/class and the style must be enclosed in double-quotes, | |
621 | and these commands must be at the top level in the GTK+ resource file. | |
488dd4c4 | 622 | |
06848b82 CY |
623 | As previously noted, you may specify a widget name or class with |
624 | shell wildcard syntax: @samp{*} matches zero or more characters and | |
625 | @samp{?} matches one character. This example assigns a style to all | |
626 | widgets: | |
488dd4c4 JD |
627 | |
628 | @smallexample | |
06848b82 | 629 | widget "*" style "my_style" |
488dd4c4 JD |
630 | @end smallexample |
631 | ||
10214524 RS |
632 | @node GTK Names in Emacs |
633 | @appendixsubsec GTK Widget Names in Emacs | |
488dd4c4 JD |
634 | @cindex GTK widget names |
635 | @cindex GTK widget classes | |
636 | ||
06848b82 | 637 | The GTK+ widgets used by an Emacs frame are listed below: |
488dd4c4 | 638 | |
06848b82 CY |
639 | @table @asis |
640 | @item @code{Emacs} (class @code{GtkWindow}) | |
641 | @table @asis | |
642 | @item @code{pane} (class @code{GtkVBox}) | |
643 | @table @asis | |
644 | @item @code{menubar} (class @code{GtkMenuBar}) | |
645 | @table @asis | |
646 | @item [menu item widgets] | |
647 | @end table | |
648 | @item [unnamed widget] (class @code{GtkHandleBox}) | |
649 | @table @asis | |
650 | @item @code{emacs-toolbar} (class @code{GtkToolbar}) | |
651 | @table @asis | |
652 | @item [tool bar item widgets] | |
653 | @end table | |
654 | @end table | |
655 | @item @code{emacs} (class @code{GtkFixed}) | |
656 | @table @asis | |
657 | @item @code{verticalScrollBar} (class @code{GtkVScrollbar}) | |
658 | @end table | |
659 | @end table | |
660 | @end table | |
661 | @end table | |
488dd4c4 JD |
662 | |
663 | @noindent | |
06848b82 CY |
664 | The contents of Emacs windows are drawn in the @code{emacs} widget. |
665 | Note that even if there are multiple Emacs windows, each scroll bar | |
666 | widget is named @code{verticalScrollBar}. | |
488dd4c4 | 667 | |
06848b82 | 668 | For example, here are two different ways to set the menu bar style: |
488dd4c4 JD |
669 | |
670 | @smallexample | |
06848b82 CY |
671 | widget "Emacs.pane.menubar.*" style "my_style" |
672 | widget_class "GtkWindow.GtkVBox.GtkMenuBar.*" style "my_style" | |
488dd4c4 JD |
673 | @end smallexample |
674 | ||
06848b82 CY |
675 | For GTK+ dialogs, Emacs uses a widget named @code{emacs-dialog}, of |
676 | class @code{GtkDialog}. For file selection, Emacs uses a widget named | |
677 | @code{emacs-filedialog}, of class @code{GtkFileSelection}. | |
488dd4c4 | 678 | |
06848b82 CY |
679 | Because the widgets for pop-up menus and dialogs are free-standing |
680 | windows and not ``contained'' in the @code{Emacs} widget, their GTK+ | |
681 | absolute names do not start with @samp{Emacs}. To customize these | |
682 | widgets, use wildcards like this: | |
488dd4c4 JD |
683 | |
684 | @smallexample | |
685 | widget "*emacs-dialog*" style "my_dialog_style" | |
686 | widget "*emacs-filedialog* style "my_file_style" | |
687 | widget "*emacs-menuitem* style "my_menu_style" | |
688 | @end smallexample | |
689 | ||
06848b82 | 690 | If you want to apply a style to all menus in Emacs, use this: |
488dd4c4 JD |
691 | |
692 | @smallexample | |
693 | widget_class "*Menu*" style "my_menu_style" | |
694 | @end smallexample | |
695 | ||
696 | @node GTK styles | |
697 | @appendixsubsec GTK styles | |
698 | @cindex GTK styles | |
699 | ||
06848b82 | 700 | Here is an example of two GTK+ style declarations: |
488dd4c4 JD |
701 | |
702 | @smallexample | |
488dd4c4 JD |
703 | pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" |
704 | ||
705 | style "default" | |
706 | @{ | |
707 | font_name = "helvetica 12" | |
708 | ||
709 | bg[NORMAL] = @{ 0.83, 0.80, 0.73 @} | |
710 | bg[SELECTED] = @{ 0.0, 0.55, 0.55 @} | |
711 | bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @} | |
712 | bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @} | |
713 | bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @} | |
714 | ||
715 | fg[NORMAL] = "black" | |
716 | fg[SELECTED] = @{ 0.9, 0.9, 0.9 @} | |
717 | fg[ACTIVE] = "black" | |
718 | fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @} | |
719 | ||
720 | base[INSENSITIVE] = "#777766" | |
721 | text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @} | |
722 | ||
723 | bg_pixmap[NORMAL] = "background.xpm" | |
724 | bg_pixmap[INSENSITIVE] = "background.xpm" | |
725 | bg_pixmap[ACTIVE] = "background.xpm" | |
177c0ea7 | 726 | bg_pixmap[PRELIGHT] = "<none>" |
488dd4c4 JD |
727 | |
728 | @} | |
729 | ||
730 | style "ruler" = "default" | |
731 | @{ | |
732 | font_name = "helvetica 8" | |
733 | @} | |
734 | ||
735 | @end smallexample | |
736 | ||
10214524 | 737 | The style @samp{ruler} inherits from @samp{default}. This way you can build |
488dd4c4 JD |
738 | on existing styles. The syntax for fonts and colors is described below. |
739 | ||
10214524 RS |
740 | As this example shows, it is possible to specify several values for |
741 | foreground and background depending on the widget's @dfn{state}. The | |
742 | possible states are: | |
743 | ||
488dd4c4 JD |
744 | @table @code |
745 | @item NORMAL | |
746 | This is the default state for widgets. | |
747 | @item ACTIVE | |
748 | This is the state for a widget that is ready to do something. It is | |
1df7defd | 749 | also for the trough of a scroll bar, i.e., @code{bg[ACTIVE] = "red"} |
488dd4c4 JD |
750 | sets the scroll bar trough to red. Buttons that have been pressed but |
751 | not released yet (``armed'') are in this state. | |
752 | @item PRELIGHT | |
4a446de9 RS |
753 | This is the state for a widget that can be manipulated, when the mouse |
754 | pointer is over it---for example when the mouse is over the thumb in | |
755 | the scroll bar or over a menu item. When the mouse is over a button | |
756 | that is not pressed, the button is in this state. | |
488dd4c4 | 757 | @item SELECTED |
4a446de9 RS |
758 | This is the state for data that has been selected by the user. It can |
759 | be selected text or items selected in a list. This state is not used | |
760 | in Emacs. | |
488dd4c4 JD |
761 | @item INSENSITIVE |
762 | This is the state for widgets that are visible, but they can not be | |
10214524 RS |
763 | manipulated in the usual way---for example, buttons that can't be |
764 | pressed, and disabled menu items. To display disabled menu items in | |
765 | yellow, use @code{fg[INSENSITIVE] = "yellow"}. | |
488dd4c4 JD |
766 | @end table |
767 | ||
10214524 | 768 | Here are the things that can go in a style declaration: |
488dd4c4 JD |
769 | |
770 | @table @code | |
771 | @item bg[@var{state}] = @var{color} | |
10214524 RS |
772 | This specifies the background color for the widget. Note that |
773 | editable text doesn't use @code{bg}; it uses @code{base} instead. | |
488dd4c4 JD |
774 | |
775 | @item base[@var{state}] = @var{color} | |
10214524 RS |
776 | This specifies the background color for editable text. In Emacs, this |
777 | color is used for the background of the text fields in the file | |
778 | dialog. | |
488dd4c4 JD |
779 | |
780 | @item bg_pixmap[@var{state}] = "@var{pixmap}" | |
10214524 RS |
781 | This specifies an image background (instead of a background color). |
782 | @var{pixmap} should be the image file name. GTK can use a number of | |
1df7defd | 783 | image file formats, including XPM, XBM, GIF, JPEG and PNG@. If you |
10214524 RS |
784 | want a widget to use the same image as its parent, use |
785 | @samp{<parent>}. If you don't want any image, use @samp{<none>}. | |
786 | @samp{<none>} is the way to cancel a background image inherited from a | |
787 | parent style. | |
788 | ||
789 | You can't specify the file by its absolute file name. GTK looks for | |
790 | the pixmap file in directories specified in @code{pixmap_path}. | |
791 | @code{pixmap_path} is a colon-separated list of directories within | |
792 | double quotes, specified at the top level in a @file{gtkrc} file | |
1df7defd | 793 | (i.e., not inside a style definition; see example above): |
488dd4c4 JD |
794 | |
795 | @smallexample | |
796 | pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" | |
797 | @end smallexample | |
798 | ||
799 | @item fg[@var{state}] = @var{color} | |
10214524 RS |
800 | This specifies the foreground color for widgets to use. It is the |
801 | color of text in menus and buttons, and the color for the arrows in | |
802 | the scroll bar. For editable text, use @code{text}. | |
488dd4c4 JD |
803 | |
804 | @item text[@var{state}] = @var{color} | |
177c0ea7 | 805 | This is the color for editable text. In Emacs, this color is used for the |
488dd4c4 JD |
806 | text fields in the file dialog. |
807 | ||
808 | @item font_name = "@var{font}" | |
81c45292 | 809 | This specifies the font for text in the widget. @var{font} is a |
06848b82 CY |
810 | GTK-style (or Pango) font name, like @samp{Sans Italic 10}. |
811 | @xref{Fonts}. The names are case insensitive. | |
488dd4c4 JD |
812 | @end table |
813 | ||
8863a584 CY |
814 | There are three ways to specify a color: a color name, an RGB |
815 | triplet, or a GTK-style RGB triplet. @xref{Colors}, for a description | |
816 | of color names and RGB triplets. Color names should be enclosed with | |
1df7defd PE |
817 | double quotes, e.g., @samp{"red"}. RGB triplets should be written |
818 | without double quotes, e.g., @samp{#ff0000}. GTK-style RGB triplets | |
06848b82 | 819 | have the form @w{@code{@{ @var{r}, @var{g}, @var{b} @}}}, where |
f99f1641 PE |
820 | @var{r}, @var{g} and @var{b} are either integers in the range 0--65535 |
821 | or floats in the range 0.0--1.0. |