Commit | Line | Data |
---|---|---|
94249313 RS |
1 | @c This is part of the Emacs manual. |
2 | @c Copyright (C) 1987,93,94,95,1997,2001 Free Software Foundation, Inc. | |
3 | @c See file emacs.texi for copying conditions. | |
4 | @node X Resources, Antinews, Command Arguments, Top | |
5 | @appendix X Resources | |
6 | ||
7 | Some aspects of Emacs behavior can be customized using X resources, | |
8 | as is usual for programs that use X. X resources are the only way to | |
9 | customize tool-bar menus, pop-up menus and tooltip windows, since they | |
10 | are implemented by general-purpose libraries that always handle | |
11 | customization this way. This appendix describes the X resources | |
12 | that Emacs recognizes and what they mean. | |
13 | ||
14 | @node Display X | |
15 | @appendixsec Specifying the Display Name | |
16 | @cindex display name (X Window System) | |
17 | @cindex @env{DISPLAY} environment variable | |
18 | ||
19 | The environment variable @env{DISPLAY} tells all X clients, including | |
20 | Emacs, where to display their windows. Its value is set by default | |
21 | in ordinary circumstances, when you start an X server and run jobs | |
22 | locally. Occasionally you may need to specify the display yourself; for | |
23 | example, if you do a remote login and want to run a client program | |
24 | remotely, displaying on your local screen. | |
25 | ||
26 | With Emacs, the main reason people change the default display is to | |
27 | let them log into another system, run Emacs on that system, but have the | |
28 | window displayed at their local terminal. You might need to log in | |
29 | to another system because the files you want to edit are there, or | |
30 | because the Emacs executable file you want to run is there. | |
31 | ||
32 | The syntax of the @env{DISPLAY} environment variable is | |
33 | @samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the | |
34 | host name of the X Window System server machine, @var{display} is an | |
35 | arbitrarily-assigned number that distinguishes your server (X terminal) | |
36 | from other servers on the same machine, and @var{screen} is a | |
37 | rarely-used field that allows an X server to control multiple terminal | |
38 | screens. The period and the @var{screen} field are optional. If | |
39 | included, @var{screen} is usually zero. | |
40 | ||
41 | For example, if your host is named @samp{glasperle} and your server is | |
42 | the first (or perhaps the only) server listed in the configuration, your | |
43 | @env{DISPLAY} is @samp{glasperle:0.0}. | |
44 | ||
45 | You can specify the display name explicitly when you run Emacs, either | |
46 | by changing the @env{DISPLAY} variable, or with the option @samp{-d | |
47 | @var{display}} or @samp{--display=@var{display}}. Here is an example: | |
48 | ||
49 | @smallexample | |
50 | emacs --display=glasperle:0 & | |
51 | @end smallexample | |
52 | ||
53 | You can inhibit the direct use of the window system and GUI with the | |
54 | @samp{-nw} option. It tells Emacs to display using ordinary ASCII on | |
55 | its controlling terminal. This is also an initial option. | |
56 | ||
57 | Sometimes, security arrangements prevent a program on a remote system | |
58 | from displaying on your local system. In this case, trying to run Emacs | |
59 | produces messages like this: | |
60 | ||
61 | @smallexample | |
62 | Xlib: connection to "glasperle:0.0" refused by server | |
63 | @end smallexample | |
64 | ||
65 | @noindent | |
66 | You might be able to overcome this problem by using the @code{xhost} | |
67 | command on the local system to give permission for access from your | |
68 | remote machine. | |
69 | ||
70 | @node Font X | |
71 | @appendixsec Font Specification Options | |
72 | @cindex font name (X Window System) | |
73 | ||
74 | By default, Emacs displays text in the font named @samp{9x15}, which | |
75 | makes each character nine pixels wide and fifteen pixels high. You can | |
76 | specify a different font on your command line through the option | |
77 | @samp{-fn @var{name}} (or @samp{--font}, which is an alias for | |
78 | @samp{-fn}). | |
79 | ||
80 | @table @samp | |
81 | @item -fn @var{name} | |
82 | @opindex -fn | |
83 | @itemx --font=@var{name} | |
84 | @opindex --font | |
85 | @cindex specify default font from the command line | |
86 | Use font @var{name} as the default font. | |
87 | @end table | |
88 | ||
89 | Under X, each font has a long name which consists of eleven words or | |
90 | numbers, separated by dashes. Some fonts also have shorter | |
91 | nicknames---@samp{9x15} is such a nickname. You can use either kind of | |
92 | name. You can use wildcard patterns for the font name; then Emacs lets | |
93 | X choose one of the fonts that match the pattern. Here is an example, | |
94 | which happens to specify the font whose nickname is @samp{6x13}: | |
95 | ||
96 | @smallexample | |
97 | emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" & | |
98 | @end smallexample | |
99 | ||
100 | @noindent | |
101 | You can also specify the font in your @file{.Xdefaults} file: | |
102 | ||
103 | @smallexample | |
104 | emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 | |
105 | @end smallexample | |
106 | ||
107 | A long font name has the following form: | |
108 | ||
109 | @smallexample | |
110 | -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} | |
111 | @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset} | |
112 | @end smallexample | |
113 | ||
114 | @table @var | |
115 | @item maker | |
116 | This is the name of the font manufacturer. | |
117 | @item family | |
118 | This is the name of the font family---for example, @samp{courier}. | |
119 | @item weight | |
120 | This is normally @samp{bold}, @samp{medium} or @samp{light}. Other | |
121 | words may appear here in some font names. | |
122 | @item slant | |
123 | This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique), | |
124 | @samp{ri} (reverse italic), or @samp{ot} (other). | |
125 | @item widthtype | |
126 | This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed} | |
127 | or @samp{normal}. Other words may appear here in some font names. | |
128 | @item style | |
129 | This is an optional additional style name. Usually it is empty---most | |
130 | long font names have two hyphens in a row at this point. | |
131 | @item pixels | |
132 | This is the font height, in pixels. | |
133 | @item height | |
134 | This is the font height on the screen, measured in tenths of a printer's | |
135 | point---approximately 1/720 of an inch. In other words, it is the point | |
136 | size of the font, times ten. For a given vertical resolution, | |
137 | @var{height} and @var{pixels} are proportional; therefore, it is common | |
138 | to specify just one of them and use @samp{*} for the other. | |
139 | @item horiz | |
140 | This is the horizontal resolution, in pixels per inch, of the screen for | |
141 | which the font is intended. | |
142 | @item vert | |
143 | This is the vertical resolution, in pixels per inch, of the screen for | |
144 | which the font is intended. Normally the resolution of the fonts on | |
145 | your system is the right value for your screen; therefore, you normally | |
146 | specify @samp{*} for this and @var{horiz}. | |
147 | @item spacing | |
148 | This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} | |
149 | (character cell). | |
150 | @item width | |
151 | This is the average character width, in pixels, multiplied by ten. | |
152 | @item charset | |
153 | This is the character set that the font depicts. | |
154 | Normally you should use @samp{iso8859-1}. | |
155 | @end table | |
156 | ||
157 | @cindex listing system fonts | |
158 | You will probably want to use a fixed-width default font---that is, | |
159 | a font in which all characters have the same width. Any font with | |
160 | @samp{m} or @samp{c} in the @var{spacing} field of the long name is a | |
161 | fixed-width font. Here's how to use the @code{xlsfonts} program to | |
162 | list all the fixed-width fonts available on your system: | |
163 | ||
164 | @example | |
165 | xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" | |
166 | xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' | |
167 | xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' | |
168 | @end example | |
169 | ||
170 | @noindent | |
171 | To see what a particular font looks like, use the @code{xfd} command. | |
172 | For example: | |
173 | ||
174 | @example | |
175 | xfd -fn 6x13 | |
176 | @end example | |
177 | ||
178 | @noindent | |
179 | displays the entire font @samp{6x13}. | |
180 | ||
181 | While running Emacs, you can set the font of the current frame | |
182 | (@pxref{Frame Parameters}) or for a specific kind of text | |
183 | (@pxref{Faces}). | |
184 | ||
185 | @node Colors X | |
186 | @appendixsec Window Color Options | |
187 | @cindex color of window | |
188 | @cindex text colors, from command line | |
189 | ||
190 | @findex list-colors-display | |
191 | @cindex available colors | |
192 | On a color display, you can specify which color to use for various | |
193 | parts of the Emacs display. To find out what colors are available on | |
194 | your system, type @kbd{M-x list-colors-display}, or press | |
195 | @kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu. | |
196 | If you do not specify colors, on windowed displays the default for the | |
197 | background is white and the default for all other colors is black. On a | |
198 | monochrome display, the foreground is black, the background is white, | |
199 | and the border is gray if the display supports that. On terminals, the | |
200 | background is usually black and the foreground is white. | |
201 | ||
202 | Here is a list of the command-line options for specifying colors: | |
203 | ||
204 | @table @samp | |
205 | @item -fg @var{color} | |
206 | @opindex -fg | |
207 | @itemx --foreground-color=@var{color} | |
208 | @opindex --foreground-color | |
209 | @cindex foreground color, command-line argument | |
210 | Specify the foreground color. @var{color} should be a standard color | |
211 | name, or a numeric specification of the color's red, green, and blue | |
212 | components as in @samp{#4682B4} or @samp{RGB:46/82/B4}. | |
213 | @item -bg @var{color} | |
214 | @opindex -bg | |
215 | @itemx --background-color=@var{color} | |
216 | @opindex --background-color | |
217 | @cindex background color, command-line argument | |
218 | Specify the background color. | |
219 | @item -bd @var{color} | |
220 | @opindex -bd | |
221 | @itemx --border-color=@var{color} | |
222 | @opindex --border-color | |
223 | @cindex border color, command-line argument | |
224 | Specify the color of the border of the X window. | |
225 | @item -cr @var{color} | |
226 | @opindex -cr | |
227 | @itemx --cursor-color=@var{color} | |
228 | @opindex --cursor-color | |
229 | @cindex cursor color, command-line argument | |
230 | Specify the color of the Emacs cursor which indicates where point is. | |
231 | @item -ms @var{color} | |
232 | @opindex -ms | |
233 | @itemx --mouse-color=@var{color} | |
234 | @opindex --mouse-color | |
235 | @cindex mouse pointer color, command-line argument | |
236 | Specify the color for the mouse cursor when the mouse is in the Emacs window. | |
237 | @item -r | |
238 | @opindex -r | |
239 | @itemx -rv | |
240 | @opindex -rv | |
241 | @itemx --reverse-video | |
242 | @opindex --reverse-video | |
243 | @cindex reverse video, command-line argument | |
244 | Reverse video---swap the foreground and background colors. | |
245 | @end table | |
246 | ||
247 | For example, to use a coral mouse cursor and a slate blue text cursor, | |
248 | enter: | |
249 | ||
250 | @example | |
251 | emacs -ms coral -cr 'slate blue' & | |
252 | @end example | |
253 | ||
254 | You can reverse the foreground and background colors through the | |
255 | @samp{-rv} option or with the X resource @samp{reverseVideo}. | |
256 | ||
257 | The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on | |
258 | text-only terminals as well as on window systems. | |
259 | ||
260 | @node Window Size X | |
261 | @appendixsec Options for Window Geometry | |
262 | @cindex geometry of Emacs window | |
263 | @cindex position and size of Emacs frame | |
264 | @cindex width and height of Emacs frame | |
265 | ||
266 | The @samp{--geometry} option controls the size and position of the | |
267 | initial Emacs frame. Here is the format for specifying the window | |
268 | geometry: | |
269 | ||
270 | @table @samp | |
271 | @item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} | |
272 | @opindex -g | |
273 | Specify window size @var{width} and @var{height} (measured in character | |
274 | columns and lines), and positions @var{xoffset} and @var{yoffset} | |
275 | (measured in pixels). | |
276 | ||
277 | @item --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} | |
278 | @opindex --geometry | |
279 | This is another way of writing the same thing. | |
280 | @end table | |
281 | ||
282 | @noindent | |
283 | @code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus | |
284 | sign before @var{xoffset} means it is the distance from the left side of | |
285 | the screen; a minus sign means it counts from the right side. A plus | |
286 | sign before @var{yoffset} means it is the distance from the top of the | |
287 | screen, and a minus sign there indicates the distance from the bottom. | |
288 | The values @var{xoffset} and @var{yoffset} may themselves be positive or | |
289 | negative, but that doesn't change their meaning, only their direction. | |
290 | ||
291 | Emacs uses the same units as @code{xterm} does to interpret the geometry. | |
292 | The @var{width} and @var{height} are measured in characters, so a large font | |
293 | creates a larger frame than a small font. (If you specify a proportional | |
294 | font, Emacs uses its maximum bounds width as the width unit.) The | |
295 | @var{xoffset} and @var{yoffset} are measured in pixels. | |
296 | ||
297 | Since the mode line and the echo area occupy the last 2 lines of the | |
298 | frame, the height of the initial text window is 2 less than the height | |
299 | specified in your geometry. In non-X-toolkit versions of Emacs, the | |
300 | menu bar also takes one line of the specified number. But in the X | |
301 | toolkit version, the menu bar is additional and does not count against | |
302 | the specified height. The tool bar, if present, is also additional. | |
303 | ||
304 | You do not have to specify all of the fields in the geometry | |
305 | specification. | |
306 | ||
307 | If you omit both @var{xoffset} and @var{yoffset}, the window manager | |
308 | decides where to put the Emacs frame, possibly by letting you place | |
309 | it with the mouse. For example, @samp{164x55} specifies a window 164 | |
310 | columns wide, enough for two ordinary width windows side by side, and 55 | |
311 | lines tall. | |
312 | ||
313 | The default width for Emacs is 80 characters and the default height is | |
314 | 40 lines. You can omit either the width or the height or both. If | |
315 | you start the geometry with an integer, Emacs interprets it as the | |
316 | width. If you start with an @samp{x} followed by an integer, Emacs | |
317 | interprets it as the height. Thus, @samp{81} specifies just the width; | |
318 | @samp{x45} specifies just the height. | |
319 | ||
320 | If you start with @samp{+} or @samp{-}, that introduces an offset, | |
321 | which means both sizes are omitted. Thus, @samp{-3} specifies the | |
322 | @var{xoffset} only. (If you give just one offset, it is always | |
323 | @var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the | |
324 | @var{yoffset}, placing the frame near the bottom left of the screen. | |
325 | ||
326 | You can specify a default for any or all of the fields in | |
327 | @file{.Xdefaults} file, and then override selected fields with a | |
328 | @samp{--geometry} option. | |
329 | ||
330 | @node Borders X | |
331 | @appendixsec Internal and External Borders | |
332 | @cindex borders (X Window System) | |
333 | ||
334 | An Emacs frame has an internal border and an external border. The | |
335 | internal border is an extra strip of the background color around the | |
336 | text portion of the frame. Emacs itself draws the internal border. | |
337 | The external border is added by the window manager outside the frame; | |
338 | depending on the window manager you use, it may contain various boxes | |
339 | you can click on to move or iconify the window. | |
340 | ||
341 | @table @samp | |
342 | @item -ib @var{width} | |
343 | @opindex -ib | |
344 | @itemx --internal-border=@var{width} | |
345 | @opindex --internal-border | |
346 | @cindex border width, command-line argument | |
347 | Specify @var{width} as the width of the internal border, in pixels. | |
348 | ||
349 | @item -bw @var{width} | |
350 | @opindex -bw | |
351 | @itemx --border-width=@var{width} | |
352 | @opindex --border-width | |
353 | Specify @var{width} as the width of the main border, in pixels. | |
354 | @end table | |
355 | ||
356 | When you specify the size of the frame, that does not count the | |
357 | borders. The frame's position is measured from the outside edge of the | |
358 | external border. | |
359 | ||
360 | Use the @samp{-ib @var{n}} option to specify an internal border | |
361 | @var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to | |
362 | specify the width of the external border (though the window manager may | |
363 | not pay attention to what you specify). The default width of the | |
364 | external border is 2. | |
365 | ||
366 | @node Title X | |
367 | @appendixsec Frame Titles | |
368 | ||
369 | An Emacs frame may or may not have a specified title. The frame | |
370 | title, if specified, appears in window decorations and icons as the | |
371 | name of the frame. If an Emacs frame has no specified title, the | |
372 | default title has the form @samp{@var{invocation-name}@@@var{machine}} | |
373 | (if there is only one frame) or the selected window's buffer name (if | |
374 | there is more than one frame). | |
375 | ||
376 | You can specify a title for the initial Emacs frame with a command | |
377 | line option: | |
378 | ||
379 | @table @samp | |
380 | @item -title @var{title} | |
381 | @opindex --title | |
382 | @itemx --title=@var{title} | |
383 | @itemx -T @var{title} | |
384 | @opindex -T | |
385 | @cindex frame title, command-line argument | |
386 | Specify @var{title} as the title for the initial Emacs frame. | |
387 | @end table | |
388 | ||
389 | The @samp{--name} option (@pxref{Resources X}) also specifies the title | |
390 | for the initial Emacs frame. | |
391 | ||
392 | @node Icons X | |
393 | @appendixsec Icons | |
394 | @cindex icons (X Window System) | |
395 | ||
396 | Most window managers allow the user to ``iconify'' a frame, removing | |
397 | it from sight, and leaving a small, distinctive ``icon'' window in its | |
398 | place. Clicking on the icon window makes the frame itself appear again. | |
399 | If you have many clients running at once, you can avoid cluttering up | |
400 | the screen by iconifying most of the clients. | |
401 | ||
402 | @table @samp | |
403 | @item -i | |
404 | @opindex -i | |
405 | @itemx --icon-type | |
406 | @opindex --icon-type | |
407 | @cindex Emacs icon, a gnu | |
408 | Use a picture of a gnu as the Emacs icon. | |
409 | ||
410 | @item -iconic | |
411 | @opindex --iconic | |
412 | @itemx --iconic | |
413 | @cindex start iconified, command-line argument | |
414 | Start Emacs in iconified state. | |
415 | @end table | |
416 | ||
417 | The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon | |
418 | window containing a picture of the GNU gnu. If omitted, Emacs lets the | |
419 | window manager choose what sort of icon to use---usually just a small | |
420 | rectangle containing the frame's title. | |
421 | ||
422 | The @samp{-iconic} option tells Emacs to begin running as an icon, | |
423 | rather than showing a frame right away. In this situation, the icon | |
424 | is the only indication that Emacs has started; the text frame doesn't | |
425 | appear until you deiconify it. | |
426 | ||
427 | @node Resources X | |
428 | @appendixsec X Resources | |
429 | @cindex resources | |
430 | ||
431 | @cindex X resources, @file{~/.Xdefaults} file | |
432 | Programs running under the X Window System organize their user options | |
433 | under a hierarchy of classes and resources. You can specify default | |
434 | values for these options in your X resources file, usually named | |
435 | @file{~/.Xdefaults}. | |
436 | ||
437 | Each line in the file specifies a value for one option or for a | |
438 | collection of related options, for one program or for several programs | |
439 | (optionally even for all programs). | |
440 | ||
441 | @cindex Registry (MS-Windows) | |
442 | @cindex @file{.Xdefaults} file, and MS-Windows | |
443 | MS-Windows systems don't support @file{~/.Xdefaults} files, but | |
444 | Emacs compiled for Windows looks for X resources in the Windows | |
445 | Registry, under the keys @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} | |
446 | and @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}. | |
447 | ||
448 | Programs define named resources with particular meanings. They also | |
449 | define how to group resources into named classes. For instance, in | |
450 | Emacs, the @samp{internalBorder} resource controls the width of the | |
451 | internal border, and the @samp{borderWidth} resource controls the width | |
452 | of the external border. Both of these resources are part of the | |
453 | @samp{BorderWidth} class. Case distinctions are significant in these | |
454 | names. | |
455 | ||
456 | In @file{~/.Xdefaults}, you can specify a value for a single resource | |
457 | on one line, like this: | |
458 | ||
459 | @example | |
460 | emacs.borderWidth: 2 | |
461 | @end example | |
462 | ||
463 | @noindent | |
464 | Or you can use a class name to specify the same value for all resources | |
465 | in that class. Here's an example: | |
466 | ||
467 | @example | |
468 | emacs.BorderWidth: 2 | |
469 | @end example | |
470 | ||
471 | If you specify a value for a class, it becomes the default for all | |
472 | resources in that class. You can specify values for individual | |
473 | resources as well; these override the class value, for those particular | |
474 | resources. Thus, this example specifies 2 as the default width for all | |
475 | borders, but overrides this value with 4 for the external border: | |
476 | ||
477 | @example | |
478 | emacs.BorderWidth: 2 | |
479 | emacs.borderWidth: 4 | |
480 | @end example | |
481 | ||
482 | The order in which the lines appear in the file does not matter. | |
483 | Also, command-line options always override the X resources file. | |
484 | ||
485 | The string @samp{emacs} in the examples above is also a resource | |
486 | name. It actually represents the name of the executable file that you | |
487 | invoke to run Emacs. If Emacs is installed under a different name, it | |
488 | looks for resources under that name instead of @samp{emacs}. | |
489 | ||
490 | @table @samp | |
491 | @item -name @var{name} | |
492 | @opindex --name | |
493 | @itemx --name=@var{name} | |
494 | @cindex resource name, command-line argument | |
495 | Use @var{name} as the resource name (and the title) for the initial | |
496 | Emacs frame. This option does not affect subsequent frames, but Lisp | |
497 | programs can specify frame names when they create frames. | |
498 | ||
499 | If you don't specify this option, the default is to use the Emacs | |
500 | executable's name as the resource name. | |
501 | ||
502 | @item -xrm @var{resource-values} | |
503 | @opindex --xrm | |
504 | @itemx --xrm=@var{resource-values} | |
505 | @cindex resource values, command-line argument | |
506 | Specify X resource values for this Emacs job (see below). | |
507 | @end table | |
508 | ||
509 | For consistency, @samp{-name} also specifies the name to use for | |
510 | other resource values that do not belong to any particular frame. | |
511 | ||
512 | The resources that name Emacs invocations also belong to a class; its | |
513 | name is @samp{Emacs}. If you write @samp{Emacs} instead of | |
514 | @samp{emacs}, the resource applies to all frames in all Emacs jobs, | |
515 | regardless of frame titles and regardless of the name of the executable | |
516 | file. Here is an example: | |
517 | ||
518 | @example | |
519 | Emacs.BorderWidth: 2 | |
520 | Emacs.borderWidth: 4 | |
521 | @end example | |
522 | ||
523 | You can specify a string of additional resource values for Emacs to | |
524 | use with the command line option @samp{-xrm @var{resources}}. The text | |
525 | @var{resources} should have the same format that you would use inside a file | |
526 | of X resources. To include multiple resource specifications in | |
527 | @var{resources}, put a newline between them, just as you would in a file. | |
528 | You can also use @samp{#include "@var{filename}"} to include a file full | |
529 | of resource specifications. Resource values specified with @samp{-xrm} | |
530 | take precedence over all other resource specifications. | |
531 | ||
532 | The following table lists the resource names that designate options | |
533 | for Emacs, each with the class that it belongs to: | |
534 | ||
535 | @table @asis | |
536 | @item @code{background} (class @code{Background}) | |
537 | Background color name. | |
538 | ||
539 | @item @code{bitmapIcon} (class @code{BitmapIcon}) | |
540 | Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window | |
541 | manager choose an icon if @samp{off}. | |
542 | ||
543 | @item @code{borderColor} (class @code{BorderColor}) | |
544 | Color name for the external border. | |
545 | ||
546 | @item @code{borderWidth} (class @code{BorderWidth}) | |
547 | Width in pixels of the external border. | |
548 | ||
549 | @item @code{cursorColor} (class @code{Foreground}) | |
550 | Color name for text cursor (point). | |
551 | ||
552 | @item @code{font} (class @code{Font}) | |
553 | Font name for text (or fontset name, @pxref{Fontsets}). | |
554 | ||
555 | @item @code{foreground} (class @code{Foreground}) | |
556 | Color name for text. | |
557 | ||
558 | @item @code{geometry} (class @code{Geometry}) | |
559 | Window size and position. Be careful not to specify this resource as | |
560 | @samp{emacs*geometry}, because that may affect individual menus as well | |
561 | as the Emacs frame itself. | |
562 | ||
563 | If this resource specifies a position, that position applies only to the | |
564 | initial Emacs frame (or, in the case of a resource for a specific frame | |
565 | name, only that frame). However, the size, if specified here, applies to | |
566 | all frames. | |
567 | ||
568 | @item @code{iconName} (class @code{Title}) | |
569 | Name to display in the icon. | |
570 | ||
571 | @item @code{internalBorder} (class @code{BorderWidth}) | |
572 | Width in pixels of the internal border. | |
573 | ||
574 | @item @code{lineSpacing} (class @code{LineSpacing}) | |
575 | @cindex line spacing | |
576 | @cindex leading | |
577 | Additional space (@dfn{leading}) between lines, in pixels. | |
578 | ||
579 | @item @code{menuBar} (class @code{MenuBar}) | |
580 | Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}. | |
581 | ||
582 | @item @code{toolBar} (class @code{ToolBar}) | |
583 | Number of lines to reserve for the tool bar. A zero value suppresses | |
584 | the tool bar. If the value is non-zero and | |
585 | @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size | |
586 | will be changed automatically so that all tool bar items are visible. | |
587 | ||
588 | @item @code{minibuffer} (class @code{Minibuffer}) | |
589 | If @samp{none}, don't make a minibuffer in this frame. | |
590 | It will use a separate minibuffer frame instead. | |
591 | ||
592 | @item @code{paneFont} (class @code{Font}) | |
593 | @cindex font for menus | |
594 | Font name for menu pane titles, in non-toolkit versions of Emacs. | |
595 | ||
596 | @item @code{pointerColor} (class @code{Foreground}) | |
597 | Color of the mouse cursor. | |
598 | ||
599 | @ignore | |
600 | @item @code{privateColormap} (class @code{PrivateColormap}) | |
601 | If @samp{on}, use a private color map, in the case where the ``default | |
602 | visual'' of class PseudoColor and Emacs is using it. | |
603 | @end ignore | |
604 | ||
605 | @item @code{reverseVideo} (class @code{ReverseVideo}) | |
606 | Switch foreground and background default colors if @samp{on}, use colors as | |
607 | specified if @samp{off}. | |
608 | ||
609 | @item @code{screenGamma} (class @code{ScreenGamma}) | |
610 | @cindex gamma correction | |
611 | Gamma correction for colors, equivalent to the frame parameter | |
612 | @code{screen-gamma}. | |
613 | ||
614 | @item @code{selectionFont} (class @code{Font}) | |
615 | Font name for pop-up menu items, in non-toolkit versions of Emacs. (For | |
616 | toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif | |
617 | Resources}.) | |
618 | ||
619 | @item @code{synchronous} (class @code{Synchronous}) | |
620 | @cindex debugging X problems | |
621 | @cindex synchronous X mode | |
622 | Run Emacs in synchronous mode if @samp{on}. Synchronous mode is | |
623 | useful for debugging X problems. | |
624 | ||
625 | @item @code{title} (class @code{Title}) | |
626 | Name to display in the title bar of the initial Emacs frame. | |
627 | ||
628 | @item @code{verticalScrollBars} (class @code{ScrollBars}) | |
629 | Give frames scroll bars if @samp{on}; don't have scroll bars if | |
630 | @samp{off}. | |
631 | @end table | |
632 | ||
633 | Here are resources for controlling the appearance of particular faces | |
634 | (@pxref{Faces}): | |
635 | ||
636 | @table @code | |
637 | @item @var{face}.attributeFont | |
638 | Font for face @var{face}. | |
639 | @item @var{face}.attributeForeground | |
640 | Foreground color for face @var{face}. | |
641 | @item @var{face}.attributeBackground | |
642 | Background color for face @var{face}. | |
643 | @item @var{face}.attributeUnderline | |
644 | Underline flag for face @var{face}. Use @samp{on} or @samp{true} for | |
645 | yes. | |
646 | @item @var{face}.attributeFamily | |
647 | Font family for face @var{face}. | |
648 | @item @var{face}.attributeWidth | |
649 | Relative proportional width of the font to use for face @var{face}. | |
650 | It should be one of @code{ultra-condensed}, @code{extra-condensed}, | |
651 | @code{condensed}, @code{semi-condensed}, @code{normal}, | |
652 | @code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or | |
653 | @code{ultra-expanded}. | |
654 | @item @var{face}.attributeHeight | |
655 | Height of the font to use for face @var{face}: either an integer | |
656 | specifying the height in units of 1/10@dmn{pt}, or a floating point | |
657 | number that specifies a scale factor to scale the underlying face's | |
658 | default font, or a function to be called with the default height which | |
659 | will return a new height. | |
660 | @item @var{face}.attributeWeight | |
661 | A weight to use for the face @var{face}. It must be one of | |
662 | @code{ultra-bold}, @code{extra-bold}, @code{bold}, | |
663 | @code{semi-bold}, @code{normal}, @code{semi-light}, @code{light}, | |
664 | @code{extra-light}, @code{ultra-light}. | |
665 | @item @var{face}.attributeSlant | |
666 | The slant to use for the font of face @var{face}. It must be one of | |
667 | @code{italic}, @code{oblique}, @code{normal}, | |
668 | @code{reverse-italic}, or @code{reverse-oblique}. | |
669 | @item @var{face}.attributeStrikeThrough | |
670 | Whether the face @var{face} should be drawn with a line striking | |
671 | through the characters. | |
672 | @item @var{face}.attributeOverline | |
673 | Whether the characters in the face @var{face} should be overlined. | |
674 | @item @var{face}.attributeBox | |
675 | Whether to draw a box around the characters in face @var{face}. | |
676 | @item @var{face}.attributeInverse | |
677 | Whether to display the characters in face @var{face} in inverse | |
678 | video. | |
679 | @item @var{face}.attributeStipple | |
680 | The name of a pixmap data file to use for the stipple pattern, or | |
681 | @code{false} to not use stipple for the face @var{face}. | |
682 | @item @var{face}.attributeBackgroundPixmap | |
683 | The background pixmap for the face @var{face}. Should be a name of a | |
684 | pixmap file or @code{false}. | |
685 | @item @var{face}.attributeBold | |
686 | Whether to draw the characters in the face @var{face} as bold. | |
687 | @item @var{face}.attributeItalic | |
688 | Whether to draw the characters in the face @var{face} as italic. | |
689 | @end table | |
690 | ||
691 | @node Lucid Resources | |
692 | @appendixsec Lucid Menu X Resources | |
693 | @cindex Menu X Resources (Lucid widgets) | |
694 | @cindex Lucid Widget X Resources | |
695 | ||
696 | If the Emacs installed at your site was built to use the X toolkit | |
697 | with the Lucid menu widgets, then the menu bar is a separate widget and | |
698 | has its own resources. The resource names contain @samp{pane.menubar} | |
699 | (following, as always, the name of the Emacs invocation, or @samp{Emacs}, | |
700 | which stands for all Emacs invocations). Specify them like this: | |
701 | ||
702 | @example | |
703 | Emacs.pane.menubar.@var{resource}: @var{value} | |
704 | @end example | |
705 | ||
706 | @noindent | |
707 | For example, to specify the font @samp{8x16} for the menu-bar items, | |
708 | write this: | |
709 | ||
710 | @example | |
711 | Emacs.pane.menubar.font: 8x16 | |
712 | @end example | |
713 | ||
714 | @noindent | |
715 | Resources for @emph{non-menubar} toolkit pop-up menus have | |
716 | @samp{menu*}, in like fashion. For example, to specify the font | |
717 | @samp{8x16} for the pop-up menu items, write this: | |
718 | ||
719 | @example | |
720 | Emacs.menu*.font: 8x16 | |
721 | @end example | |
722 | ||
723 | @noindent | |
724 | For dialog boxes, use @samp{dialog} instead of @samp{menu}: | |
725 | ||
726 | @example | |
727 | Emacs.dialog*.font: 8x16 | |
728 | @end example | |
729 | ||
730 | @noindent | |
731 | Experience shows that on some systems you may need to add | |
732 | @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On | |
733 | some other systems, you must not add @samp{shell.}. | |
734 | ||
735 | Here is a list of the specific resources for menu bars and pop-up menus: | |
736 | ||
737 | @table @code | |
738 | @item font | |
739 | Font for menu item text. | |
740 | @item foreground | |
741 | Color of the foreground. | |
742 | @item background | |
743 | Color of the background. | |
744 | @item buttonForeground | |
745 | In the menu bar, the color of the foreground for a selected item. | |
746 | @item horizontalSpacing | |
747 | Horizontal spacing in pixels between items. Default is 3. | |
748 | @item verticalSpacing | |
749 | Vertical spacing in pixels between items. Default is 1. | |
750 | @item arrowSpacing | |
751 | Horizontal spacing between the arrow (which indicates a submenu) and | |
752 | the associated text. Default is 10. | |
753 | @item shadowThickness | |
754 | Thickness of shadow line around the widget. | |
755 | @item margin | |
756 | The margin of the menu bar, in characters. The default of 4 makes the | |
757 | menu bar appear like the LessTif/Motif one. | |
758 | @end table | |
759 | ||
760 | @node LessTif Resources | |
761 | @appendixsec LessTif Menu X Resources | |
762 | @cindex Menu X Resources (LessTif widgets) | |
763 | @cindex LessTif Widget X Resources | |
764 | ||
765 | If the Emacs installed at your site was built to use the X toolkit | |
766 | with the LessTif or Motif widgets, then the menu bar, the dialog | |
767 | boxes, the pop-up menus, and the file-selection box are separate | |
768 | widgets and have their own resources. | |
769 | ||
770 | The resource names for the menu bar contain @samp{pane.menubar} | |
771 | (following, as always, the name of the Emacs invocation, or | |
772 | @samp{Emacs}, which stands for all Emacs invocations). Specify them | |
773 | like this: | |
774 | ||
775 | @smallexample | |
776 | Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value} | |
777 | @end smallexample | |
778 | ||
779 | Each individual string in the menu bar is a subwidget; the subwidget's | |
780 | name is the same as the menu item string. For example, the word | |
781 | @samp{File} in the menu bar is part of a subwidget named | |
782 | @samp{emacs.pane.menubar.File}. Most likely, you want to specify the | |
783 | same resources for the whole menu bar. To do this, use @samp{*} instead | |
784 | of a specific subwidget name. For example, to specify the font | |
785 | @samp{8x16} for the menu-bar items, write this: | |
786 | ||
787 | @smallexample | |
788 | Emacs.pane.menubar.*.fontList: 8x16 | |
789 | @end smallexample | |
790 | ||
791 | @noindent | |
792 | This also specifies the resource value for submenus. | |
793 | ||
794 | Each item in a submenu in the menu bar also has its own name for X | |
795 | resources; for example, the @samp{File} submenu has an item named | |
796 | @samp{Save (current buffer)}. A resource specification for a submenu | |
797 | item looks like this: | |
798 | ||
799 | @smallexample | |
800 | Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value} | |
801 | @end smallexample | |
802 | ||
803 | @noindent | |
804 | For example, here's how to specify the font for the @samp{Save (current | |
805 | buffer)} item: | |
806 | ||
807 | @smallexample | |
808 | Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16 | |
809 | @end smallexample | |
810 | ||
811 | @noindent | |
812 | For an item in a second-level submenu, such as @samp{Complete Word} | |
813 | under @samp{Spell Checking} under @samp{Tools}, the resource fits this | |
814 | template: | |
815 | ||
816 | @smallexample | |
817 | Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value} | |
818 | @end smallexample | |
819 | ||
820 | @noindent | |
821 | For example, | |
822 | ||
823 | @smallexample | |
824 | Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value} | |
825 | @end smallexample | |
826 | ||
827 | @noindent | |
828 | (This should be one long line.) | |
829 | ||
830 | It's impossible to specify a resource for all the menu-bar items | |
831 | without also specifying it for the submenus as well. So if you want the | |
832 | submenu items to look different from the menu bar itself, you must ask | |
833 | for that in two steps. First, specify the resource for all of them; | |
834 | then, override the value for submenus alone. Here is an example: | |
835 | ||
836 | @smallexample | |
837 | Emacs.pane.menubar.*.fontList: 8x16 | |
838 | Emacs.pane.menubar.popup_*.fontList: 8x16 | |
839 | @end smallexample | |
840 | ||
841 | @noindent | |
842 | For LessTif pop-up menus, use @samp{menu*} instead of | |
843 | @samp{pane.menubar}. For example, to specify the font @samp{8x16} for | |
844 | the pop-up menu items, write this: | |
845 | ||
846 | @smallexample | |
847 | Emacs.menu*.fontList: 8x16 | |
848 | @end smallexample | |
849 | ||
850 | @noindent | |
851 | For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}: | |
852 | ||
853 | @example | |
854 | Emacs.dialog*.fontList: 8x16 | |
855 | Emacs.dialog*.foreground: hotpink | |
856 | @end example | |
857 | ||
858 | To specify resources for the LessTif file-selection box, use | |
859 | @samp{fsb*}, like this: | |
860 | ||
861 | @example | |
862 | Emacs.fsb*.fontList: 8x16 | |
863 | @end example | |
864 | ||
865 | @iftex | |
866 | @medbreak | |
867 | @end iftex | |
868 | Here is a list of the specific resources for LessTif menu bars and | |
869 | pop-up menus: | |
870 | ||
871 | @table @code | |
872 | @item armColor | |
873 | The color to show in an armed button. | |
874 | @item fontList | |
875 | The font to use. | |
876 | @item marginBottom | |
877 | @itemx marginHeight | |
878 | @itemx marginLeft | |
879 | @itemx marginRight | |
880 | @itemx marginTop | |
881 | @itemx marginWidth | |
882 | Amount of space to leave around the item, within the border. | |
883 | @item borderWidth | |
884 | The width of the border around the menu item, on all sides. | |
885 | @item shadowThickness | |
886 | The width of the border shadow. | |
887 | @item bottomShadowColor | |
888 | The color for the border shadow, on the bottom and the right. | |
889 | @item topShadowColor | |
890 | The color for the border shadow, on the top and the left. | |
891 | @end table |