xresources.texi 41.7 KB
Newer Older
1
@c This is part of the Emacs manual.
2 3
@c Copyright (C) 1987, 1993-1995, 1997, 2001-2011
@c   Free Software Foundation, Inc.
4
@c See file emacs.texi for copying conditions.
5
@node X Resources, Antinews, Emacs Invocation, Top
6
@appendix X Options and Resources
7

8
  You can customize some X-related aspects of Emacs behavior using X
9 10
resources, as is usual for programs that use X.  On MS-Windows, you
can customize some of the same aspects using the system registry.
11
@xref{MS-Windows Registry}.
12

13
  When Emacs is built using an ``X toolkit'', such as Lucid or
Jan Djärv's avatar
Jan Djärv committed
14 15 16
LessTif, you need to use X resources to customize the appearance of
the widgets, including the menu-bar, scroll-bar, and dialog boxes.
This is because the libraries that implement these don't provide for
17
customization through Emacs.  GTK+ widgets use a separate system of
Jan Djärv's avatar
Jan Djärv committed
18 19 20 21 22 23 24 25 26 27 28
@ifnottex
``GTK resources'', which we will also describe.
@end ifnottex
@iftex
``GTK resources.''  In this chapter we describe the most commonly used
resource specifications.  For full documentation, see the online
manual.

@c Add xref for LessTif/Motif menu resources.
@end iftex

Richard M. Stallman's avatar
Richard M. Stallman committed
29 30

@menu
31 32 33
* Resources::           Using X resources with Emacs (in general).
* Table of Resources::  Table of specific X resources that affect Emacs.
* Face Resources::      X resources for customizing faces.
Richard M. Stallman's avatar
Richard M. Stallman committed
34 35
* Lucid Resources::     X resources for Lucid menus.
* LessTif Resources::   X resources for LessTif and Motif menus.
Jan Djärv's avatar
Jan Djärv committed
36
* GTK resources::       Resources for GTK widgets.
Richard M. Stallman's avatar
Richard M. Stallman committed
37 38
@end menu

39
@node Resources
40 41
@appendixsec X Resources
@cindex resources
42 43 44
@cindex X resources
@cindex @file{~/.Xdefaults} file
@cindex @file{~/.Xresources} file
45

46 47
  Programs running under the X Window System organize their user
options under a hierarchy of classes and resources.  You can specify
48 49 50 51 52
default values for these options in your @dfn{X resource file},
usually named @file{~/.Xdefaults} or @file{~/.Xresources}.  Changes in
this file do not take effect immediately, because the X server stores
its own list of resources; to update it, use the command
@command{xrdb}---for instance, @samp{xrdb ~/.Xdefaults}.
53 54

@cindex Registry (MS-Windows)
55 56 57
  (MS-Windows systems do not support X resource files; on Windows,
Emacs looks for X resources in the Windows Registry, first under the
key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} and then under the key
Karl Berry's avatar
Karl Berry committed
58 59 60
@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}.  The menu and scroll
bars are native widgets on MS-Windows, so they are only customizable
via the system-wide settings in the Display Control Panel.  You can
61 62
also set resources using the @samp{-xrm} command line option, as
explained below.)
63

64 65 66 67 68
  Each line in the X resource file specifies a value for one option or
for a collection of related options.  Each resource specification
consists of a @dfn{program name} and a @dfn{resource name}.  Case
distinctions are significant in each of these names.  Here is an
example:
69 70 71 72 73

@example
emacs.borderWidth: 2
@end example

74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
@ifnottex
  The program name is the name of the executable file to which the
resource applies.  For Emacs, this is normally @samp{emacs}.  To
specify a definition that applies to all instances of Emacs,
regardless of the name of the Emacs executable, use @samp{Emacs}.

  The resource name is the name of a program setting.  For instance,
Emacs recognizes a @samp{borderWidth} resource that controls the width
of the external border for graphical frames.

  Resources are grouped into named classes.  For instance, the
@samp{BorderWidth} class contains both the @samp{borderWidth} resource
(which we just described), as well as the @samp{internalBorder}
resource, which controls the width of the internal border for
graphical frames.  Instead of using a resource name, you can use a
class name to specify the same value for all resources in that class.
Here's an example:
91 92 93 94 95 96 97

@example
emacs.BorderWidth: 2
@end example

  If you specify a value for a class, it becomes the default for all
resources in that class.  You can specify values for individual
98 99 100 101
resources as well; these override the class value, for those
particular resources.  The following example specifies 2 as the
default width for all borders, but overrides this value with 4 for the
external border:
102 103 104 105 106

@example
emacs.BorderWidth: 2
emacs.borderWidth: 4
@end example
Jan Djärv's avatar
Jan Djärv committed
107
@end ifnottex
108 109

  The order in which the lines appear in the file does not matter.
110 111 112 113 114 115 116 117 118
One way to experiment with the effect of different resource settings
is to use the @code{editres} program.  See the @code{editres} man page
for more details.

  Emacs does not process X resources at all if you set the variable
@code{inhibit-x-resources} to a non-@code{nil} value, or if you
specify the @samp{-Q} (or @samp{--quick}) command-line argument
(@pxref{Initial Options}).  (The @samp{-Q} argument automatically sets
@code{inhibit-x-resources} to @code{t}.)
Jan Djärv's avatar
Jan Djärv committed
119 120

@ifnottex
121 122
  In addition, you can use the following command-line options to
override the X resources file:
123 124 125 126 127 128

@table @samp
@item -name @var{name}
@opindex --name
@itemx --name=@var{name}
@cindex resource name, command-line argument
129 130 131
This option sets the program name of the initial Emacs frame to
@var{name}.  It also sets the title of the initial frame to
@var{name}.  This option does not affect subsequent frames.
132 133

If you don't specify this option, the default is to use the Emacs
134 135 136 137 138 139 140 141 142 143
executable's name as the program name.

For consistency, @samp{-name} also specifies the name to use for other
resource values that do not belong to any particular frame.

The resources that name Emacs invocations also belong to a class,
named @samp{Emacs}.  If you write @samp{Emacs} instead of
@samp{emacs}, the resource applies to all frames in all Emacs jobs,
regardless of frame titles and regardless of the name of the
executable file.
144 145 146 147 148

@item -xrm @var{resource-values}
@opindex --xrm
@itemx --xrm=@var{resource-values}
@cindex resource values, command-line argument
149 150 151 152 153 154 155 156 157
This option specifies X resource values for the present Emacs job.

@var{resource-values} should have the same format that you would use
inside a file of X resources.  To include multiple resource
specifications in @var{resource-values}, put a newline between them,
just as you would in a file.  You can also use @samp{#include
"@var{filename}"} to include a file full of resource specifications.
Resource values specified with @samp{-xrm} take precedence over all
other resource specifications.
158
@end table
159
@end ifnottex
160

161 162 163 164
@node Table of Resources
@appendixsec Table of X Resources for Emacs

  This table lists the resource names that designate options for
165 166
Emacs, not counting those for the appearance of the menu bar, each
with the class that it belongs to:
167 168 169 170 171

@table @asis
@item @code{background} (class @code{Background})
Background color name.

Jan Djärv's avatar
Jan Djärv committed
172
@ifnottex
173 174 175
@item @code{bitmapIcon} (class @code{BitmapIcon})
Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
manager choose an icon if @samp{off}.
Jan Djärv's avatar
Jan Djärv committed
176
@end ifnottex
177 178 179 180

@item @code{borderColor} (class @code{BorderColor})
Color name for the external border.

Jan Djärv's avatar
Jan Djärv committed
181
@ifnottex
182 183
@item @code{borderWidth} (class @code{BorderWidth})
Width in pixels of the external border.
Jan Djärv's avatar
Jan Djärv committed
184
@end ifnottex
185 186 187 188

@item @code{cursorColor} (class @code{Foreground})
Color name for text cursor (point).

Jan Djärv's avatar
Jan Djärv committed
189
@ifnottex
190 191 192
@item @code{cursorBlink} (class @code{CursorBlink})
Specifies whether to make the cursor blink. The default is @samp{on}.  Use
@samp{off} or @samp{false} to turn cursor blinking off.
Jan Djärv's avatar
Jan Djärv committed
193
@end ifnottex
194

195
@item @code{font} (class @code{Font})
Chong Yidong's avatar
Chong Yidong committed
196
Font name for the @code{default} font.  @xref{Fonts}.  You can also
197 198 199 200 201 202 203 204 205 206
specify a fontset name (@pxref{Fontsets}).

@item @code{fontBackend} (class @code{FontBackend})
The backend(s) to use for drawing fonts; if multiple backends are
specified, they must be comma-delimited and given in order of
precedence.  On X, for instance, the value @samp{x,xft} tells Emacs to
draw fonts using the X core font driver, falling back on the Xft font
driver if that fails.  Normally, you can leave this resource unset, in
which case Emacs tries using all font backends available on your
graphical device.
207 208 209 210 211 212 213 214 215 216 217 218 219 220

@item @code{foreground} (class @code{Foreground})
Color name for text.

@item @code{geometry} (class @code{Geometry})
Window size and position.  Be careful not to specify this resource as
@samp{emacs*geometry}, because that may affect individual menus as well
as the Emacs frame itself.

If this resource specifies a position, that position applies only to the
initial Emacs frame (or, in the case of a resource for a specific frame
name, only that frame).  However, the size, if specified here, applies to
all frames.

Jan Djärv's avatar
Jan Djärv committed
221
@ifnottex
222
@item @code{fullscreen} (class @code{Fullscreen})
223
The desired fullscreen size.  The value can be one of @code{fullboth},
224 225
@code{maximized}, @code{fullwidth} or @code{fullheight}, which correspond to
the command-line options @samp{-fs}, @samp{-mm}, @samp{-fw}, and @samp{-fh}
226
(@pxref{Window Size X}).
227

Jan Djärv's avatar
Jan Djärv committed
228 229
Note that this applies to the initial frame only.
@end ifnottex
230

231 232 233 234 235 236 237 238 239 240 241 242
@item @code{iconName} (class @code{Title})
Name to display in the icon.

@item @code{internalBorder} (class @code{BorderWidth})
Width in pixels of the internal border.

@item @code{lineSpacing} (class @code{LineSpacing})
@cindex line spacing
@cindex leading
Additional space (@dfn{leading}) between lines, in pixels.

@item @code{menuBar} (class @code{MenuBar})
Dave Love's avatar
Dave Love committed
243
@cindex menu bar
Jan Djärv's avatar
Jan Djärv committed
244 245 246 247 248 249 250 251
Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
@ifnottex
@xref{Lucid Resources}, and @ref{LessTif Resources},
@end ifnottex
@iftex
@xref{Lucid Resources},
@end iftex
for how to control the appearance of the menu bar if you have one.
252

Jan Djärv's avatar
Jan Djärv committed
253
@ifnottex
254 255 256 257 258 259 260
@item @code{minibuffer} (class @code{Minibuffer})
If @samp{none}, don't make a minibuffer in this frame.
It will use a separate minibuffer frame instead.

@item @code{paneFont} (class @code{Font})
@cindex font for menus
Font name for menu pane titles, in non-toolkit versions of Emacs.
Jan Djärv's avatar
Jan Djärv committed
261
@end ifnottex
262 263 264 265

@item @code{pointerColor} (class @code{Foreground})
Color of the mouse cursor.

Jan Djärv's avatar
Jan Djärv committed
266
@ifnottex
267 268 269 270 271 272 273
@item @code{privateColormap} (class @code{PrivateColormap})
If @samp{on}, use a private color map, in the case where the ``default
visual'' of class PseudoColor and Emacs is using it.

@item @code{reverseVideo} (class @code{ReverseVideo})
Switch foreground and background default colors if @samp{on}, use colors as
specified if @samp{off}.
Jan Djärv's avatar
Jan Djärv committed
274
@end ifnottex
275 276 277 278 279 280

@item @code{screenGamma} (class @code{ScreenGamma})
@cindex gamma correction
Gamma correction for colors, equivalent to the frame parameter
@code{screen-gamma}.

Jan Djärv's avatar
Reorder  
Jan Djärv committed
281 282 283 284 285
@item @code{scrollBarWidth} (class @code{ScrollBarWidth})
@cindex scrollbar width
The scroll bar width in pixels, equivalent to the frame parameter
@code{scroll-bar-width}.

Jan Djärv's avatar
Jan Djärv committed
286
@ifnottex
Dave Love's avatar
Dave Love committed
287
@item @code{selectionFont} (class @code{SelectionFont})
288 289 290 291
Font name for pop-up menu items, in non-toolkit versions of Emacs.  (For
toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
Resources}.)

Dave Love's avatar
Dave Love committed
292 293 294 295 296
@item @code{selectionTimeout} (class @code{SelectionTimeout})
Number of milliseconds to wait for a selection reply.
If the selection owner doesn't reply in this time, we give up.
A value of 0 means wait as long as necessary.

297 298 299 300 301
@item @code{synchronous} (class @code{Synchronous})
@cindex debugging X problems
@cindex synchronous X mode
Run Emacs in synchronous mode if @samp{on}.  Synchronous mode is
useful for debugging X problems.
Jan Djärv's avatar
Jan Djärv committed
302
@end ifnottex
303 304 305 306

@item @code{title} (class @code{Title})
Name to display in the title bar of the initial Emacs frame.

307
@item @code{toolBar} (class @code{ToolBar})
Dave Love's avatar
Dave Love committed
308
@cindex tool bar
309
Number of lines to reserve for the tool bar.  A zero value suppresses
310 311 312
the tool bar.  For the Emacs tool bar (i.e. not Gtk+), if the value is 
non-zero and @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's
size will be changed automatically so that all tool bar items are visible.
313 314 315
  If the value of @code{auto-resize-tool-bars} is @code{grow-only},
the tool bar expands automatically, but does not contract automatically.
To contract the tool bar, you must redraw the frame by entering @kbd{C-l}.
316 317
For the Gtk+ tool bar, any non-zero value means on and
@code{auto-resize-tool-bars} has no effect.
318

Dave Love's avatar
Dave Love committed
319 320 321 322 323 324 325 326 327
@item @code{useXIM} (class @code{UseXIM})
@cindex XIM
@cindex X input methods
@cindex input methods, X
Turn off use of X input methods (XIM) if @samp{false} or @samp{off}.
This is only relevant if your Emacs is actually built with XIM
support.  It is potentially useful to turn off XIM for efficiency,
especially slow X client/server links.

328 329 330
@item @code{verticalScrollBars} (class @code{ScrollBars})
Give frames scroll bars if @samp{on}; don't have scroll bars if
@samp{off}.
331

Jan Djärv's avatar
Jan Djärv committed
332
@ifnottex
333 334 335 336 337 338 339 340 341 342
@item @code{visualClass} (class @code{VisualClass})
Specify the ``visual'' that X should use.  This tells X how to handle
colors.

The value should start with one of @samp{TrueColor},
@samp{PseudoColor}, @samp{DirectColor}, @samp{StaticColor},
@samp{GrayScale}, and @samp{StaticGray}, followed by
@samp{-@var{depth}}, where @var{depth} is the number of color planes.
Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo}
program outputs information saying which ones.
Jan Djärv's avatar
Jan Djärv committed
343
@end ifnottex
344 345
@end table

346 347 348
@node Face Resources
@appendixsec X Resources for Faces

349
  You can use resources to customize the appearance of particular
350
faces (@pxref{Faces}):
351 352 353 354 355 356 357 358 359

@table @code
@item @var{face}.attributeForeground
Foreground color for face @var{face}.
@item @var{face}.attributeBackground
Background color for face @var{face}.
@item @var{face}.attributeUnderline
Underline flag for face @var{face}.  Use @samp{on} or @samp{true} for
yes.
360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379
@item @var{face}.attributeStrikeThrough
@itemx @var{face}.attributeOverline
@itemx @var{face}.attributeBox
@itemx @var{face}.attributeInverse
Likewise, for other boolean font attributes.
@item @var{face}.attributeStipple
The name of a pixmap data file to use for the stipple pattern, or
@code{false} to not use stipple for the face @var{face}.
@item @var{face}.attributeBackgroundPixmap
The background pixmap for the face @var{face}.  Should be a name of a
pixmap file or @code{false}.
@item @var{face}.attributeFont
Font name (full XFD name or valid X abbreviation) for face @var{face}.
Instead of this, you can specify the font through separate attributes.
@end table

  Instead of using @code{attributeFont} to specify a font name, you can
select a font through these separate attributes:

@table @code
380 381 382 383 384 385 386 387
@item @var{face}.attributeFamily
Font family for face @var{face}.
@item @var{face}.attributeHeight
Height of the font to use for face @var{face}: either an integer
specifying the height in units of 1/10@dmn{pt}, or a floating point
number that specifies a scale factor to scale the underlying face's
default font, or a function to be called with the default height which
will return a new height.
388 389 390 391 392 393
@item @var{face}.attributeWidth
@itemx @var{face}.attributeWeight
@itemx @var{face}.attributeSlant
Each of these resources corresponds to a like-named font attribute,
and you write the resource value the same as the symbol you would use
for the font attribute value.
394
@item @var{face}.attributeBold
395 396
Bold flag for face @var{face}---instead of @code{attributeWeight}.  Use @samp{on} or @samp{true} for
yes.
397
@item @var{face}.attributeItalic
398
Italic flag for face @var{face}---instead of @code{attributeSlant}.
399 400 401
@end table

@node Lucid Resources
402
@appendixsec Lucid Menu And Dialog X Resources
403
@cindex Menu X Resources (Lucid widgets)
404
@cindex Dialog X Resources (Lucid widgets)
405 406
@cindex Lucid Widget X Resources

Jan Djärv's avatar
Jan Djärv committed
407
@ifnottex
408 409 410 411 412 413 414 415 416 417 418
  If the Emacs installed at your site was built to use the X toolkit
with the Lucid menu widgets, then the menu bar is a separate widget and
has its own resources.  The resource names contain @samp{pane.menubar}
(following, as always, the name of the Emacs invocation, or @samp{Emacs},
which stands for all Emacs invocations).  Specify them like this:

@example
Emacs.pane.menubar.@var{resource}:  @var{value}
@end example

@noindent
419
For example, to specify the font @samp{Courier-12} for the menu-bar items,
420
write this:
Jan Djärv's avatar
Jan Djärv committed
421 422 423 424 425 426
@end ifnottex
@iftex
   If the Emacs installed at your site was built to use the X toolkit
with the Lucid menu widgets, then the menu bar is a separate widget
and has its own resources.  The resource specifications start with
@samp{Emacs.pane.menubar}---for instance, to specify the font
427
@samp{Courier-12} for the menu-bar items, write this:
Jan Djärv's avatar
Jan Djärv committed
428
@end iftex
429 430

@example
431
Emacs.pane.menubar.font:  Courier-12
432 433 434
@end example

@noindent
435 436
To specify a font, use fontconfig font names as values to the @code{font}
resource, or old style names:
437 438

@example
439
Emacs.pane.menubar.font: lucidasanstypewriter-10
440 441 442
@end example

@noindent
443 444
Emacs first tries to open the font as an old style font, and if that fails
as an fontconfig font.  In rare cases, Emacs might do the wrong thing.
445

446
@noindent
447 448
The Lucid menus can display multilingual text in your locale with old style
fonts.  For more information about fontsets see the man page for
Jan Djärv's avatar
Jan Djärv committed
449 450 451 452 453 454 455
@code{XCreateFontSet}.  To enable multilingual menu text you specify a
@code{fontSet} resource instead of the font resource.  If both
@code{font} and @code{fontSet} resources are specified, the
@code{fontSet} resource is used.

  Thus, to specify @samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*}
for both the popup and menu bar menus, write this:
456 457

@example
Jan Djärv's avatar
Jan Djärv committed
458
Emacs*menu*fontSet:  -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*
459 460
@end example

461 462 463 464 465 466
@noindent
Resources for @emph{non-menubar} toolkit pop-up menus have
@samp{menu*} instead of @samp{pane.menubar}.  For example, to specify
the font @samp{8x16} for the pop-up menu items, write this:

@example
467
Emacs.menu*.font:       8x16
468 469 470 471 472 473
@end example

@noindent
For dialog boxes, use @samp{dialog*}:

@example
474
Emacs.dialog*.font: Sans-12
475 476
@end example

477
@noindent
Jan Djärv's avatar
Jan Djärv committed
478 479 480
The @samp{*menu*} as a wildcard matches @samp{pane.menubar} and
@samp{menu@dots{}}.

481 482
Experience shows that on some systems you may need to add
@samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}.  On
Jan Djärv's avatar
Jan Djärv committed
483 484
some other systems, you must not add @samp{shell.}.  The generic wildcard
approach should work on both kinds of systems.
485 486 487 488 489 490

  Here is a list of the specific resources for menu bars and pop-up menus:

@table @code
@item font
Font for menu item text.
491 492
@item fontSet
Fontset for menu item text.
493 494 495 496 497 498
@item foreground
Color of the foreground.
@item background
Color of the background.
@item buttonForeground
In the menu bar, the color of the foreground for a selected item.
Jan Djärv's avatar
Jan Djärv committed
499
@ifnottex
500 501 502
@item horizontalSpacing
Horizontal spacing in pixels between items.  Default is 3.
@item verticalSpacing
503
Vertical spacing in pixels between items.  Default is 2.
504 505 506 507
@item arrowSpacing
Horizontal spacing between the arrow (which indicates a submenu) and
the associated text.  Default is 10.
@item shadowThickness
508 509 510 511 512 513 514 515 516
Thickness of shadow line around the widget.  Default is 1.

Also determines the thickness of shadow lines around other objects,
for instance 3D buttons and arrows.  If you have the impression that
the arrows in the menus do not stand out clearly enough or that the
difference between ``in'' and ``out'' buttons is difficult to see, set
this to 2.  If you have no problems with visibility, the default
probably looks better.  The background color may also have some effect
on the contrast.
Jan Djärv's avatar
Jan Djärv committed
517
@end ifnottex
518
@item margin
519
The margin of the menu bar, in characters.  Default is 1.
520 521
@end table

Jan Djärv's avatar
Jan Djärv committed
522
@ifnottex
523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591
@node LessTif Resources
@appendixsec LessTif Menu X Resources
@cindex Menu X Resources (LessTif widgets)
@cindex LessTif Widget X Resources

  If the Emacs installed at your site was built to use the X toolkit
with the LessTif or Motif widgets, then the menu bar, the dialog
boxes, the pop-up menus, and the file-selection box are separate
widgets and have their own resources.

  The resource names for the menu bar contain @samp{pane.menubar}
(following, as always, the name of the Emacs invocation, or
@samp{Emacs}, which stands for all Emacs invocations).  Specify them
like this:

@smallexample
Emacs.pane.menubar.@var{subwidget}.@var{resource}:  @var{value}
@end smallexample

  Each individual string in the menu bar is a subwidget; the subwidget's
name is the same as the menu item string.  For example, the word
@samp{File} in the menu bar is part of a subwidget named
@samp{emacs.pane.menubar.File}.  Most likely, you want to specify the
same resources for the whole menu bar.  To do this, use @samp{*} instead
of a specific subwidget name.  For example, to specify the font
@samp{8x16} for the menu-bar items, write this:

@smallexample
Emacs.pane.menubar.*.fontList:  8x16
@end smallexample

@noindent
This also specifies the resource value for submenus.

  Each item in a submenu in the menu bar also has its own name for X
resources; for example, the @samp{File} submenu has an item named
@samp{Save (current buffer)}.  A resource specification for a submenu
item looks like this:

@smallexample
Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
@end smallexample

@noindent
For example, here's how to specify the font for the @samp{Save (current
buffer)} item:

@smallexample
Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
@end smallexample

@noindent
For an item in a second-level submenu, such as @samp{Complete Word}
under @samp{Spell Checking} under @samp{Tools}, the resource fits this
template:

@smallexample
Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
@end smallexample

@noindent
For example,

@smallexample
Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value}
@end smallexample

@noindent
(This should be one long line.)
592

593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654
  It's impossible to specify a resource for all the menu-bar items
without also specifying it for the submenus as well.  So if you want the
submenu items to look different from the menu bar itself, you must ask
for that in two steps.  First, specify the resource for all of them;
then, override the value for submenus alone.  Here is an example:

@smallexample
Emacs.pane.menubar.*.fontList:  8x16
Emacs.pane.menubar.popup_*.fontList: 8x16
@end smallexample

@noindent
For LessTif pop-up menus, use @samp{menu*} instead of
@samp{pane.menubar}.  For example, to specify the font @samp{8x16} for
the pop-up menu items, write this:

@smallexample
Emacs.menu*.fontList:  8x16
@end smallexample

@noindent
For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}:

@example
Emacs.dialog*.fontList: 8x16
Emacs.dialog*.foreground: hotpink
@end example

To specify resources for the LessTif file-selection box, use
@samp{fsb*}, like this:

@example
Emacs.fsb*.fontList: 8x16
@end example

@iftex
@medbreak
@end iftex
  Here is a list of the specific resources for LessTif menu bars and
pop-up menus:

@table @code
@item armColor
The color to show in an armed button.
@item fontList
The font to use.
@item marginBottom
@itemx marginHeight
@itemx marginLeft
@itemx marginRight
@itemx marginTop
@itemx marginWidth
Amount of space to leave around the item, within the border.
@item borderWidth
The width of the border around the menu item, on all sides.
@item shadowThickness
The width of the border shadow.
@item bottomShadowColor
The color for the border shadow, on the bottom and the right.
@item topShadowColor
The color for the border shadow, on the top and the left.
@end table
Jan Djärv's avatar
Jan Djärv committed
655
@end ifnottex
Jan Djärv's avatar
Jan Djärv committed
656 657 658 659


@node GTK resources
@appendixsec GTK resources
Jan Djärv's avatar
Jan Djärv committed
660 661 662
@iftex
  The most common way to customize the GTK widgets Emacs uses (menus, dialogs
tool bars and scroll bars) is by choosing an appropriate theme, for example
663 664 665 666 667
with the GNOME theme selector.  

You can also do Emacs specific customization
by inserting GTK style directives in the file @file{~/.emacs.d/gtkrc},
but only if you have a Gtk+ version earlier than 3 (i.e. 2).   Some GTK
Jan Djärv's avatar
Jan Djärv committed
668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713
themes ignore customizations in @file{~/.emacs.d/gtkrc} so not everything
works with all themes.  To customize Emacs font, background, faces, etc., use
the normal X resources (@pxref{Resources}).  We will present some examples of
customizations here, but for a more detailed description, see the online manual

  The first example is just one line.  It changes the font on all GTK widgets
to courier with size 12:

@smallexample
gtk-font-name = "courier 12"
@end smallexample

  The thing to note is that the font name is not an X font name, like
-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*, but a Pango font name.  A Pango
font name is basically of the format "family style size", where the style
is optional as in the case above.  A name with a style could be for example:

@smallexample
gtk-font-name = "helvetica bold 10"
@end smallexample

  To customize widgets you first define a style and then apply the style to
the widgets.  Here is an example that sets the font for menus, but not
for other widgets:

@smallexample
# @r{Define the style @samp{menufont}.}
style "menufont"
@{
  font_name = "helvetica bold 14"  # This is a Pango font name
@}

# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
widget "*emacs-menuitem*" style "menufont"
@end smallexample

The widget name in this example contains wildcards, so the style will be
applied to all widgets that match "*emacs-menuitem*".  The widgets are
named by the way they are contained, from the outer widget to the inner widget.
So to apply the style "my_style" (not shown) with the full, absolute name, for
the menubar and the scroll bar in Emacs we use:

@smallexample
widget "Emacs.pane.menubar" style "my_style"
widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
@end smallexample
714

Jan Djärv's avatar
Jan Djärv committed
715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796
But to avoid having to type it all, wildcards are often used.  @samp{*}
matches zero or more characters and @samp{?} matches one character.  So "*"
matches all widgets.

  Each widget has a class (for example GtkMenuItem) and a name (emacs-menuitem).
You can assign styles by name or by class.  In this example we have used the
class:

@smallexample
style "menufont"
@{
  font_name = "helvetica bold 14"
@}

widget_class "*GtkMenuBar" style "menufont"
@end smallexample

@noindent
The names and classes for the GTK widgets Emacs uses are:

@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
@item @code{emacs-filedialog}
@tab @code{GtkFileSelection}
@item @code{emacs-dialog}
@tab @code{GtkDialog}
@item @code{Emacs}
@tab @code{GtkWindow}
@item @code{pane}
@tab @code{GtkVHbox}
@item @code{emacs}
@tab @code{GtkFixed}
@item @code{verticalScrollBar}
@tab @code{GtkVScrollbar}
@item @code{emacs-toolbar}
@tab @code{GtkToolbar}
@item @code{menubar}
@tab @code{GtkMenuBar}
@item @code{emacs-menuitem}
@tab anything in menus
@end multitable

  GTK absolute names are quite strange when it comes to menus
and dialogs.  The names do not start with @samp{Emacs}, as they are
free-standing windows and not contained (in the GTK sense) by the
Emacs GtkWindow.  To customize the dialogs and menus, use wildcards like this:

@smallexample
widget "*emacs-dialog*" style "my_dialog_style"
widget "*emacs-filedialog* style "my_file_style"
widget "*emacs-menuitem* style "my_menu_style"
@end smallexample

  If you specify a customization in @file{~/.emacs.d/gtkrc}, then it
automatically applies only to Emacs, since other programs don't read
that file.  For example, the drop down menu in the file dialog can not
be customized by any absolute widget name, only by an absolute class
name.  This is because the widgets in the drop down menu do not
have names and the menu is not contained in the Emacs GtkWindow.  To
have all menus in Emacs look the same, use this in
@file{~/.emacs.d/gtkrc}:

@smallexample
widget_class "*Menu*" style "my_menu_style"
@end smallexample

  Here is a more elaborate example, showing how to change the parts of
the scroll bar:

@smallexample
style "scroll"
@{
  fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
  bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
  bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
  bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
@}

widget "*verticalScrollBar*" style "scroll"
@end smallexample
@end iftex

@ifnottex
Jan Djärv's avatar
Jan Djärv committed
797 798 799 800 801
@cindex GTK resources and customization
@cindex resource files for GTK
@cindex @file{~/.gtkrc-2.0} file
@cindex @file{~/.emacs.d/gtkrc} file

Jan Djärv's avatar
Jan Djärv committed
802
  If Emacs was built to use the GTK widget set, then the menu bar, tool bar,
803 804 805 806 807 808 809
scroll bar and the dialogs are customized with the standard GTK
customization file, @file{~/.gtkrc-2.0}, or with the Emacs specific
file @file{~/.emacs.d/gtkrc}.  We recommend that you use
@file{~/.emacs.d/gtkrc} for customizations, since @file{~/.gtkrc-2.0}
seems to be ignored when running GConf with GNOME.  These files apply
only to GTK widget features.  To customize Emacs font, background,
faces, etc., use the normal X resources (@pxref{Resources}).
Jan Djärv's avatar
Jan Djärv committed
810

811
  Some GTK themes override these mechanisms, which means that using
812
these mechanisms will not work to customize them.
813

814 815 816 817
  In these files you first define a style and say what it means; then
you specify to apply the style to various widget types (@pxref{GTK
widget names}).  Here is an example of how to change the font for
Emacs menus:
Jan Djärv's avatar
Jan Djärv committed
818 819

@smallexample
Jan Djärv's avatar
Jan Djärv committed
820
# @r{Define the style @samp{menufont}.}
Jan Djärv's avatar
Jan Djärv committed
821 822 823 824 825
style "menufont"
@{
  font_name = "helvetica bold 14"  # This is a Pango font name
@}

Jan Djärv's avatar
Jan Djärv committed
826
# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
Jan Djärv's avatar
Jan Djärv committed
827
widget "*emacs-menuitem*" style "menufont"
828 829 830 831
@end smallexample

  Here is a more elaborate example, showing how to change the parts of
the scroll bar:
832

833 834 835
@smallexample
style "scroll"
@{
836 837 838 839
  fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
  bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
  bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
  bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
840 841 842
@}

widget "*verticalScrollBar*" style "scroll"
Jan Djärv's avatar
Jan Djärv committed
843 844
@end smallexample

845 846 847 848
  There are also parameters that affect GTK as a whole.  For example,
the property @code{gtk-font-name} sets the default font for GTK.  You
must use Pango font names (@pxref{GTK styles}).  A GTK resources file
that just sets a default font looks like this:
Jan Djärv's avatar
Jan Djärv committed
849 850 851 852 853

@smallexample
gtk-font-name = "courier 12"
@end smallexample

854 855 856 857 858 859
  The GTK resources file is fully described in the GTK API document.
This can be found in
@file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html},
where @file{prefix} is the directory in which the GTK libraries were
installed (usually @file{/usr} or @file{/usr/local}).  You can also
find the document online, at
Jan Djärv's avatar
Jan Djärv committed
860 861 862 863
@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.

@menu
* GTK widget names::      How widgets in GTK are named in general.
864
* GTK Names in Emacs::    GTK widget names in Emacs.
Jan Djärv's avatar
Jan Djärv committed
865 866 867 868 869 870 871
* GTK styles::            What can be customized in a GTK widget.
@end menu

@node GTK widget names
@appendixsubsec GTK widget names
@cindex GTK widget names

872 873 874 875 876
  A GTK widget is specified by its @dfn{widget class} and
@dfn{widget name}.  The widget class is the type of the widget: for
example, @code{GtkMenuBar}.  The widget name is the name given to a
specific widget.  A widget always has a class, but need not have a
name.
Jan Djärv's avatar
Jan Djärv committed
877

878 879 880 881 882 883 884
  @dfn{Absolute names} are sequences of widget names or widget
classes, corresponding to hierarchies of widgets embedded within
other widgets.  For example, if a @code{GtkWindow} named @code{top}
contains a @code{GtkVBox} named @code{box}, which in turn contains
a @code{GtkMenuBar} called @code{menubar}, the absolute class name
of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and
its absolute widget name is @code{top.box.menubar}.
Jan Djärv's avatar
Jan Djärv committed
885 886 887

  When assigning a style to a widget, you can use the absolute class
name or the absolute widget name.
888 889 890 891 892 893 894 895 896 897 898 899 900

  There are two commands to specify changes for widgets:

@table @asis
@item @code{widget_class}
specifies a style for widgets based on the absolute class name.

@item @code{widget}
specifies a style for widgets based on the absolute class name,
or just the class.
@end table

@noindent
Richard M. Stallman's avatar
Richard M. Stallman committed
901 902
You must specify the class and the style in double-quotes, and put
these commands at the top level in the GTK customization file, like
903
this:
Jan Djärv's avatar
Jan Djärv committed
904 905 906 907 908 909 910 911 912 913 914

@smallexample
style "menufont"
@{
  font_name = "helvetica bold 14"
@}

widget "top.box.menubar" style "menufont"
widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont"
@end smallexample

915 916 917
  Matching of absolute names uses shell wildcard syntax: @samp{*}
matches zero or more characters and @samp{?} matches one character.
This example assigns @code{base_style} to all widgets:
Jan Djärv's avatar
Jan Djärv committed
918 919 920 921 922 923

@smallexample
widget "*" style "base_style"
@end smallexample

  Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar}
924 925
and the corresponding absolute widget name @code{top.box.menubar}, all
these examples specify @code{my_style} for the menu bar:
Jan Djärv's avatar
Jan Djärv committed
926 927 928 929 930 931 932 933 934 935 936

@smallexample
widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
widget_class "GtkWindow.*.GtkMenuBar" style "my_style"
widget_class "*GtkMenuBar" style "my_style"
widget "top.box.menubar" style "my_style"
widget "*box*menubar" style "my_style"
widget "*menubar" style "my_style"
widget "*menu*" style "my_style"
@end smallexample

937 938
@node GTK Names in Emacs
@appendixsubsec GTK Widget Names in Emacs
Jan Djärv's avatar
Jan Djärv committed
939 940 941
@cindex GTK widget names
@cindex GTK widget classes

942 943 944 945 946 947
  In Emacs, the top level widget for a frame is a @code{GtkWindow}
that contains a @code{GtkVBox}.  The @code{GtkVBox} contains the
@code{GtkMenuBar} and a @code{GtkFixed} widget.  The vertical scroll
bars, @code{GtkVScrollbar}, are contained in the @code{GtkFixed}
widget.  The text you write in Emacs is drawn in the @code{GtkFixed}
widget.
Jan Djärv's avatar
Jan Djärv committed
948 949 950 951 952 953 954 955 956 957 958 959 960 961 962

  Dialogs in Emacs are @code{GtkDialog} widgets.  The file dialog is a
@code{GtkFileSelection} widget.

@noindent
To set a style for the menu bar using the absolute class name, use:

@smallexample
widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
@end smallexample

@noindent
For the scroll bar, the absolute class name is:

@smallexample
963
widget_class
Jan Djärv's avatar
Jan Djärv committed
964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981
  "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar"
     style "my_style"
@end smallexample

@noindent
The names for the emacs widgets, and their classes, are:

@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
@item @code{emacs-filedialog}
@tab @code{GtkFileSelection}
@item @code{emacs-dialog}
@tab @code{GtkDialog}
@item @code{Emacs}
@tab @code{GtkWindow}
@item @code{pane}
@tab @code{GtkVHbox}
@item @code{emacs}
@tab @code{GtkFixed}
982
@item @code{verticalScrollBar}
Jan Djärv's avatar
Jan Djärv committed
983
@tab @code{GtkVScrollbar}
984 985 986 987
@item @code{emacs-toolbar}
@tab @code{GtkToolbar}
@item @code{menubar}
@tab @code{GtkMenuBar}
Jan Djärv's avatar
Jan Djärv committed
988 989 990 991 992 993 994 995 996
@item @code{emacs-menuitem}
@tab anything in menus
@end multitable

@noindent
Thus, for Emacs you can write the two examples above as:

@smallexample
widget "Emacs.pane.menubar" style "my_style"
997
widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
Jan Djärv's avatar
Jan Djärv committed
998 999 1000
@end smallexample

  GTK absolute names are quite strange when it comes to menus
1001
and dialogs.  The names do not start with @samp{Emacs}, as they are
Jan Djärv's avatar
Jan Djärv committed
1002 1003 1004 1005 1006 1007 1008 1009 1010
free-standing windows and not contained (in the GTK sense) by the
Emacs GtkWindow.  To customize the dialogs and menus, use wildcards like this:

@smallexample
widget "*emacs-dialog*" style "my_dialog_style"
widget "*emacs-filedialog* style "my_file_style"
widget "*emacs-menuitem* style "my_menu_style"
@end smallexample

1011 1012 1013 1014
  If you specify a customization in @file{~/.emacs.d/gtkrc}, then it
automatically applies only to Emacs, since other programs don't read
that file.  For example, the drop down menu in the file dialog can not
be customized by any absolute widget name, only by an absolute class
Richard M. Stallman's avatar
Richard M. Stallman committed
1015
name.  This is because the widgets in the drop down menu do not
1016 1017 1018
have names and the menu is not contained in the Emacs GtkWindow.  To
have all menus in Emacs look the same, use this in
@file{~/.emacs.d/gtkrc}:
Jan Djärv's avatar
Jan Djärv committed
1019 1020 1021 1022 1023 1024 1025 1026 1027 1028

@smallexample
widget_class "*Menu*" style "my_menu_style"
@end smallexample

@node GTK styles
@appendixsubsec GTK styles
@cindex GTK styles

  In a GTK style you specify the appearance widgets shall have.  You
1029 1030 1031 1032 1033 1034 1035 1036
can specify foreground and background color, background pixmap and
font.  The edit widget (where you edit the text) in Emacs is a GTK
widget, but trying to specify a style for the edit widget will have no
effect.  This is so that Emacs compiled for GTK is compatible with
Emacs compiled for other X toolkits.  The settings for foreground,
background and font for the edit widget is taken from the X resources;
@pxref{Resources}.  Here is an example of two style declarations,
@samp{default} and @samp{ruler}:
Jan Djärv's avatar
Jan Djärv committed
1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061

@smallexample
pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"

style "default"
@{
  font_name = "helvetica 12"

  bg[NORMAL] = @{ 0.83, 0.80, 0.73 @}
  bg[SELECTED] = @{ 0.0, 0.55, 0.55 @}
  bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @}
  bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @}
  bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @}

  fg[NORMAL] = "black"
  fg[SELECTED] = @{ 0.9, 0.9, 0.9 @}
  fg[ACTIVE] = "black"
  fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @}

  base[INSENSITIVE] = "#777766"
  text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @}

  bg_pixmap[NORMAL] = "background.xpm"
  bg_pixmap[INSENSITIVE] = "background.xpm"
  bg_pixmap[ACTIVE] = "background.xpm"
1062
  bg_pixmap[PRELIGHT] = "<none>"
Jan Djärv's avatar
Jan Djärv committed
1063 1064 1065 1066 1067 1068 1069 1070 1071 1072

@}

style "ruler" = "default"
@{
  font_name = "helvetica 8"
@}

@end smallexample

1073
  The style @samp{ruler} inherits from @samp{default}.  This way you can build
Jan Djärv's avatar
Jan Djärv committed
1074 1075
on existing styles.  The syntax for fonts and colors is described below.

1076 1077 1078 1079
  As this example shows, it is possible to specify several values for
foreground and background depending on the widget's @dfn{state}.  The
possible states are:

Jan Djärv's avatar
Jan Djärv committed
1080 1081 1082 1083 1084
@table @code
@item NORMAL
This is the default state for widgets.
@item ACTIVE
This is the state for a widget that is ready to do something.  It is
1085
also for the trough of a scroll bar, i.e.  @code{bg[ACTIVE] = "red"}
Jan Djärv's avatar
Jan Djärv committed
1086 1087 1088
sets the scroll bar trough to red.  Buttons that have been pressed but
not released yet (``armed'') are in this state.
@item PRELIGHT
1089 1090 1091 1092
This is the state for a widget that can be manipulated, when the mouse
pointer is over it---for example when the mouse is over the thumb in
the scroll bar or over a menu item.  When the mouse is over a button
that is not pressed, the button is in this state.
Jan Djärv's avatar
Jan Djärv committed
1093
@item SELECTED
1094 1095 1096
This is the state for data that has been selected by the user.  It can
be selected text or items selected in a list.  This state is not used
in Emacs.
Jan Djärv's avatar
Jan Djärv committed
1097 1098
@item INSENSITIVE
This is the state for widgets that are visible, but they can not be
1099 1100 1101
manipulated in the usual way---for example, buttons that can't be
pressed, and disabled menu items.  To display disabled menu items in
yellow, use @code{fg[INSENSITIVE] = "yellow"}.
Jan Djärv's avatar
Jan Djärv committed
1102 1103
@end table

1104
  Here are the things that can go in a style declaration:
Jan Djärv's avatar
Jan Djärv committed
1105 1106 1107

@table @code
@item bg[@var{state}] = @var{color}
1108 1109
This specifies the background color for the widget.  Note that
editable text doesn't use @code{bg}; it uses @code{base} instead.
Jan Djärv's avatar
Jan Djärv committed
1110 1111

@item base[@var{state}] = @var{color}
1112 1113 1114
This specifies the background color for editable text.  In Emacs, this
color is used for the background of the text fields in the file
dialog.
Jan Djärv's avatar
Jan Djärv committed
1115 1116

@item bg_pixmap[@var{state}] = "@var{pixmap}"
1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129
This specifies an image background (instead of a background color).
@var{pixmap} should be the image file name.  GTK can use a number of
image file formats, including XPM, XBM, GIF, JPEG and PNG.  If you
want a widget to use the same image as its parent, use
@samp{<parent>}.  If you don't want any image, use @samp{<none>}.
@samp{<none>} is the way to cancel a background image inherited from a
parent style.

You can't specify the file by its absolute file name.  GTK looks for
the pixmap file in directories specified in @code{pixmap_path}.
@code{pixmap_path} is a colon-separated list of directories within
double quotes, specified at the top level in a @file{gtkrc} file
(i.e. not inside a style definition; see example above):
Jan Djärv's avatar
Jan Djärv committed
1130 1131 1132 1133 1134 1135

@smallexample
pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
@end smallexample

@item fg[@var{state}] = @var{color}
1136 1137 1138
This specifies the foreground color for widgets to use.  It is the
color of text in menus and buttons, and the color for the arrows in
the scroll bar.  For editable text, use @code{text}.
Jan Djärv's avatar
Jan Djärv committed
1139 1140

@item text[@var{state}] = @var{color}
1141
This is the color for editable text.  In Emacs, this color is used for the
Jan Djärv's avatar
Jan Djärv committed
1142 1143 1144
text fields in the file dialog.

@item font_name = "@var{font}"
1145
This specifies the font for text in the widget.  @var{font} is a
1146 1147 1148
Pango font name, for example @samp{Sans Italic 10}, @samp{Helvetica
Bold 12}, @samp{Courier 14}, @samp{Times 18}.  See below for exact
syntax.  The names are case insensitive.
Jan Djärv's avatar
Jan Djärv committed
1149 1150
@end table

1151 1152
  There are three ways to specify a color: by name, in hexadecimal
form, and with an RGB triplet.
Jan Djärv's avatar
Jan Djärv committed
1153 1154 1155 1156 1157

@noindent
A color name is written within double quotes, for example @code{"red"}.

@noindent
1158 1159 1160
Hexadecimal form is the same as in X:
@code{#@var{rrrr}@var{gggg}@var{bbbb}}, where all three color specs
must have the same number of hex digits (1, 2, 3 or 4).
Jan Djärv's avatar
Jan Djärv committed
1161 1162

@noindent
1163 1164 1165
An RGB triplet looks like @code{@{ @var{r}, @var{g}, @var{b} @}},
where @var{r}, @var{g} and @var{b} are either integers in the range
0-65535 or floats in the range 0.0-1.0.
Jan Djärv's avatar
Jan Djärv committed
1166 1167

  Pango font names have the form ``@var{family-list} @var{style-options}
1168
@var{size}.''
Jan Djärv's avatar
Jan Djärv committed
1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180
@cindex Pango font name
@noindent
@var{family-list} is a comma separated list of font families optionally
terminated by a comma.  This way you can specify several families and the
first one found will be used.  @var{family} corresponds to the second part in
an X font name, for example in

@smallexample
-adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1
@end smallexample

@noindent
1181
the family name is @samp{times}.
Jan Djärv's avatar
Jan Djärv committed
1182 1183 1184 1185 1186 1187 1188 1189

@noindent
@var{style-options} is a whitespace separated list of words where each word
is a style, variant, weight, or stretch.  The default value for all of
these is @code{normal}.

@noindent
A `style' corresponds to the fourth part of an X font name.  In X font
1190 1191 1192
names it is the character @samp{r}, @samp{i} or @samp{o}; in Pango
font names the corresponding values are @code{normal}, @code{italic},
or @code{oblique}.
Jan Djärv's avatar
Jan Djärv committed
1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212

@noindent
A `variant' is either @code{normal} or @code{small-caps}.
Small caps is a font with the lower case characters replaced by
smaller variants of the capital characters.

@noindent
Weight describes the ``boldness'' of a font.  It corresponds to the third
part of an X font name.  It is one of @code{ultra-light}, @code{light},
@code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}.

@noindent
Stretch gives the width of the font relative to other designs within a
family.  It corresponds to the fifth part of an X font name.  It is one of
@code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
@code{semi-condensed}, @code{normal}, @code{semi-expanded},
@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.

@noindent
@var{size} is a decimal number that describes the font size in points.
Jan Djärv's avatar
Jan Djärv committed
1213
@end ifnottex