1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1987,93,94,95,1997,2001,03 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node X Resources, Antinews, Emacs Invocation, Top
5 @appendix X Options and Resources
7 You can customize some X-related aspects of Emacs behavior using X
8 resources, as is usual for programs that use X. On MS-Windows, you
9 can customize some of the same aspects using the system registry.
10 @xref{MS-Windows Registry}.
12 When Emacs is built using an `X toolkit', such as Lucid or LessTif,
13 you need to use X resources to customize the appearance of the
14 widgets, including the menu-bar, scroll-bar, and dialog boxes. This
15 is because the libraries that implement these don't provide for
16 customization through Emacs. GTK+ widgets use a separate system of
17 `GTK resources', which we will also describe.
20 * Resources:: Using X resources with Emacs (in general).
21 * Table of Resources:: Table of specific X resources that affect Emacs.
22 * Face Resources:: X resources for customizing faces.
23 * Lucid Resources:: X resources for Lucid menus.
24 * LessTif Resources:: X resources for LessTif and Motif menus.
25 * GTK resources:: Resources for GTK widgets.
29 @appendixsec X Resources
32 @cindex @file{~/.Xdefaults} file
33 @cindex @file{~/.Xresources} file
35 Programs running under the X Window System organize their user
36 options under a hierarchy of classes and resources. You can specify
37 default values for these options in your X resources file, usually
38 named @file{~/.Xdefaults} or @file{~/.Xresources}.
39 If changes in @file{~/.Xdefaults} do not
40 take effect, it is because your X server stores its own list of
41 resources; to update them, use the shell command @command{xrdb}---for
42 instance, @samp{xrdb ~/.Xdefaults}.
44 Each line in the file specifies a value for one option or for a
45 collection of related options, for one program or for several programs
46 (optionally even for all programs).
48 @cindex Registry (MS-Windows)
49 MS-Windows systems don't support @file{~/.Xdefaults} files, but
50 Emacs compiled for Windows looks for X resources in the Windows
51 Registry, under the key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs}
52 and then under the key @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}.
53 The menu and scrollbars are native widgets on MS-Windows, so they are
54 only customizable via the system-wide settings in the Display Control
57 Programs define named resources with particular meanings. They also
58 define how to group resources into named classes. For instance, in
59 Emacs, the @samp{internalBorder} resource controls the width of the
60 internal border, and the @samp{borderWidth} resource controls the width
61 of the external border. Both of these resources are part of the
62 @samp{BorderWidth} class. Case distinctions are significant in these
65 Every resource definition is associated with a specific program
66 name---the name of the executable file that you ran. For Emacs, that
67 is normally @samp{emacs}. To specify a definition for all instances
68 of Emacs, regardless of their names, use @samp{Emacs}.
70 In @file{~/.Xdefaults}, you can specify a value for a single resource
71 on one line, like this:
78 Or you can use a class name to specify the same value for all resources
79 in that class. Here's an example:
85 If you specify a value for a class, it becomes the default for all
86 resources in that class. You can specify values for individual
87 resources as well; these override the class value, for those particular
88 resources. Thus, this example specifies 2 as the default width for all
89 borders, but overrides this value with 4 for the external border:
96 The order in which the lines appear in the file does not matter.
97 Also, command-line options always override the X resources file.
98 Here is a list of X command-line options and their corresponding
102 @item -name @var{name}
104 @itemx --name=@var{name}
105 @cindex resource name, command-line argument
106 Use @var{name} as the resource name (and the title) for the initial
107 Emacs frame. This option does not affect subsequent frames, but Lisp
108 programs can specify frame names when they create frames.
110 If you don't specify this option, the default is to use the Emacs
111 executable's name as the resource name.
113 @item -xrm @var{resource-values}
115 @itemx --xrm=@var{resource-values}
116 @cindex resource values, command-line argument
117 Specify X resource values for this Emacs job (see below).
120 For consistency, @samp{-name} also specifies the name to use for
121 other resource values that do not belong to any particular frame.
123 The resources that name Emacs invocations also belong to a class; its
124 name is @samp{Emacs}. If you write @samp{Emacs} instead of
125 @samp{emacs}, the resource applies to all frames in all Emacs jobs,
126 regardless of frame titles and regardless of the name of the executable
127 file. Here is an example:
134 You can specify a string of additional resource values for Emacs to
135 use with the command line option @samp{-xrm @var{resources}}. The text
136 @var{resources} should have the same format that you would use inside a file
137 of X resources. To include multiple resource specifications in
138 @var{resources}, put a newline between them, just as you would in a file.
139 You can also use @samp{#include "@var{filename}"} to include a file full
140 of resource specifications. Resource values specified with @samp{-xrm}
141 take precedence over all other resource specifications.
143 One way to experiment with the effect of different resource settings
144 is to use the @code{editres} program. Select @samp{Get Tree} from the
145 @samp{Commands} menu, then click on an Emacs frame. This will display
146 a tree showing the structure of X toolkit widgets used in an Emacs
147 frame. Select one of them, such as @samp{menubar}, then select
148 @samp{Show Resource Box} from the @samp{Commands} menu. This displays
149 a list of all the meaningful X resources and allows you to edit them.
150 Changes take effect immediately if you click on the @samp{Apply} button.
151 (See the @code{editres} man page for more details.)
153 @node Table of Resources
154 @appendixsec Table of X Resources for Emacs
156 This table lists the resource names that designate options for
157 Emacs, not counting those for the appearance of the menu bar, each
158 with the class that it belongs to:
161 @item @code{background} (class @code{Background})
162 Background color name.
164 @item @code{bitmapIcon} (class @code{BitmapIcon})
165 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
166 manager choose an icon if @samp{off}.
168 @item @code{borderColor} (class @code{BorderColor})
169 Color name for the external border.
171 @item @code{borderWidth} (class @code{BorderWidth})
172 Width in pixels of the external border.
174 @item @code{cursorColor} (class @code{Foreground})
175 Color name for text cursor (point).
177 @item @code{font} (class @code{Font})
178 Font name for text (or fontset name, @pxref{Fontsets}).
180 @item @code{foreground} (class @code{Foreground})
183 @item @code{geometry} (class @code{Geometry})
184 Window size and position. Be careful not to specify this resource as
185 @samp{emacs*geometry}, because that may affect individual menus as well
186 as the Emacs frame itself.
188 If this resource specifies a position, that position applies only to the
189 initial Emacs frame (or, in the case of a resource for a specific frame
190 name, only that frame). However, the size, if specified here, applies to
193 @item @code{fullscreen} (class @code{Fullscreen})
194 The desired fullscreen size. The value can be one of @code{fullboth},
195 @code{fullwidth} or @code{fullheight}, which correspond to
196 the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh}
197 (@pxref{Window Size X}).
199 Note that this applies to all frames created, not just the initial
202 @item @code{iconName} (class @code{Title})
203 Name to display in the icon.
205 @item @code{internalBorder} (class @code{BorderWidth})
206 Width in pixels of the internal border.
208 @item @code{lineSpacing} (class @code{LineSpacing})
211 Additional space (@dfn{leading}) between lines, in pixels.
213 @item @code{menuBar} (class @code{MenuBar})
215 Give frames menu bars if @samp{on}; don't have menu bars if
216 @samp{off}. @xref{Lucid Resources}, and @ref{LessTif Resources}, for
217 how to control the appearance of the menu bar if you have one.
219 @item @code{minibuffer} (class @code{Minibuffer})
220 If @samp{none}, don't make a minibuffer in this frame.
221 It will use a separate minibuffer frame instead.
223 @item @code{paneFont} (class @code{Font})
224 @cindex font for menus
225 Font name for menu pane titles, in non-toolkit versions of Emacs.
227 @item @code{pointerColor} (class @code{Foreground})
228 Color of the mouse cursor.
230 @item @code{privateColormap} (class @code{PrivateColormap})
231 If @samp{on}, use a private color map, in the case where the ``default
232 visual'' of class PseudoColor and Emacs is using it.
234 @item @code{reverseVideo} (class @code{ReverseVideo})
235 Switch foreground and background default colors if @samp{on}, use colors as
236 specified if @samp{off}.
238 @item @code{screenGamma} (class @code{ScreenGamma})
239 @cindex gamma correction
240 Gamma correction for colors, equivalent to the frame parameter
243 @item @code{selectionFont} (class @code{SelectionFont})
244 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
245 toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
248 @item @code{selectionTimeout} (class @code{SelectionTimeout})
249 Number of milliseconds to wait for a selection reply.
250 If the selection owner doesn't reply in this time, we give up.
251 A value of 0 means wait as long as necessary.
253 @item @code{synchronous} (class @code{Synchronous})
254 @cindex debugging X problems
255 @cindex synchronous X mode
256 Run Emacs in synchronous mode if @samp{on}. Synchronous mode is
257 useful for debugging X problems.
259 @item @code{title} (class @code{Title})
260 Name to display in the title bar of the initial Emacs frame.
262 @item @code{toolBar} (class @code{ToolBar})
264 Number of lines to reserve for the tool bar. A zero value suppresses
265 the tool bar. If the value is non-zero and
266 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
267 will be changed automatically so that all tool bar items are visible.
269 @item @code{useXIM} (class @code{UseXIM})
271 @cindex X input methods
272 @cindex input methods, X
273 Turn off use of X input methods (XIM) if @samp{false} or @samp{off}.
274 This is only relevant if your Emacs is actually built with XIM
275 support. It is potentially useful to turn off XIM for efficiency,
276 especially slow X client/server links.
278 @item @code{verticalScrollBars} (class @code{ScrollBars})
279 Give frames scroll bars if @samp{on}; don't have scroll bars if
282 @item @code{visualClass} (class @code{VisualClass})
283 Specify the ``visual'' that X should use. This tells X how to handle
286 The value should start with one of @samp{TrueColor},
287 @samp{PseudoColor}, @samp{DirectColor}, @samp{StaticColor},
288 @samp{GrayScale}, and @samp{StaticGray}, followed by
289 @samp{-@var{depth}}, where @var{depth} is the number of color planes.
290 Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo}
291 program outputs information saying which ones.
295 @appendixsec X Resources for Faces
297 You can also use resources to customize the appearance of particular
298 faces (@pxref{Faces}):
301 @item @var{face}.attributeFont
302 Font for face @var{face}.
303 @item @var{face}.attributeForeground
304 Foreground color for face @var{face}.
305 @item @var{face}.attributeBackground
306 Background color for face @var{face}.
307 @item @var{face}.attributeUnderline
308 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
310 @item @var{face}.attributeFamily
311 Font family for face @var{face}.
312 @item @var{face}.attributeWidth
313 Relative proportional width of the font to use for face @var{face}.
314 It should be one of @code{ultra-condensed}, @code{extra-condensed},
315 @code{condensed}, @code{semi-condensed}, @code{normal},
316 @code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or
317 @code{ultra-expanded}.
318 @item @var{face}.attributeHeight
319 Height of the font to use for face @var{face}: either an integer
320 specifying the height in units of 1/10@dmn{pt}, or a floating point
321 number that specifies a scale factor to scale the underlying face's
322 default font, or a function to be called with the default height which
323 will return a new height.
324 @item @var{face}.attributeWeight
325 A weight to use for the face @var{face}. It must be one of
326 @code{ultra-bold}, @code{extra-bold}, @code{bold},
327 @code{semi-bold}, @code{normal}, @code{semi-light}, @code{light},
328 @code{extra-light}, @code{ultra-light}.
329 @item @var{face}.attributeSlant
330 The slant to use for the font of face @var{face}. It must be one of
331 @code{italic}, @code{oblique}, @code{normal},
332 @code{reverse-italic}, or @code{reverse-oblique}.
333 @item @var{face}.attributeStrikeThrough
334 Whether the face @var{face} should be drawn with a line striking
335 through the characters.
336 @item @var{face}.attributeOverline
337 Whether the characters in the face @var{face} should be overlined.
338 @item @var{face}.attributeBox
339 Whether to draw a box around the characters in face @var{face}.
340 @item @var{face}.attributeInverse
341 Whether to display the characters in face @var{face} in inverse
343 @item @var{face}.attributeStipple
344 The name of a pixmap data file to use for the stipple pattern, or
345 @code{false} to not use stipple for the face @var{face}.
346 @item @var{face}.attributeBackgroundPixmap
347 The background pixmap for the face @var{face}. Should be a name of a
348 pixmap file or @code{false}.
349 @item @var{face}.attributeBold
350 Whether to draw the characters in the face @var{face} as bold.
351 @item @var{face}.attributeItalic
352 Whether to draw the characters in the face @var{face} as italic.
355 @node Lucid Resources
356 @appendixsec Lucid Menu X Resources
357 @cindex Menu X Resources (Lucid widgets)
358 @cindex Lucid Widget X Resources
360 If the Emacs installed at your site was built to use the X toolkit
361 with the Lucid menu widgets, then the menu bar is a separate widget and
362 has its own resources. The resource names contain @samp{pane.menubar}
363 (following, as always, the name of the Emacs invocation, or @samp{Emacs},
364 which stands for all Emacs invocations). Specify them like this:
367 Emacs.pane.menubar.@var{resource}: @var{value}
371 For example, to specify the font @samp{8x16} for the menu-bar items,
375 Emacs.pane.menubar.font: 8x16
379 Resources for @emph{non-menubar} toolkit pop-up menus have
380 @samp{menu*}, in like fashion. For example, to specify the font
381 @samp{8x16} for the pop-up menu items, write this:
384 Emacs.menu*.font: 8x16
388 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
391 Emacs.dialog*.font: 8x16
395 Experience shows that on some systems you may need to add
396 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
397 some other systems, you must not add @samp{shell.}.
399 Here is a list of the specific resources for menu bars and pop-up menus:
403 Font for menu item text.
405 Color of the foreground.
407 Color of the background.
408 @item buttonForeground
409 In the menu bar, the color of the foreground for a selected item.
410 @item horizontalSpacing
411 Horizontal spacing in pixels between items. Default is 3.
412 @item verticalSpacing
413 Vertical spacing in pixels between items. Default is 2.
415 Horizontal spacing between the arrow (which indicates a submenu) and
416 the associated text. Default is 10.
417 @item shadowThickness
418 Thickness of shadow line around the widget. Default is 1.
420 Also determines the thickness of shadow lines around other objects,
421 for instance 3D buttons and arrows. If you have the impression that
422 the arrows in the menus do not stand out clearly enough or that the
423 difference between ``in'' and ``out'' buttons is difficult to see, set
424 this to 2. If you have no problems with visibility, the default
425 probably looks better. The background color may also have some effect
428 The margin of the menu bar, in characters. Default is 1.
431 @node LessTif Resources
432 @appendixsec LessTif Menu X Resources
433 @cindex Menu X Resources (LessTif widgets)
434 @cindex LessTif Widget X Resources
436 If the Emacs installed at your site was built to use the X toolkit
437 with the LessTif or Motif widgets, then the menu bar, the dialog
438 boxes, the pop-up menus, and the file-selection box are separate
439 widgets and have their own resources.
441 The resource names for the menu bar contain @samp{pane.menubar}
442 (following, as always, the name of the Emacs invocation, or
443 @samp{Emacs}, which stands for all Emacs invocations). Specify them
447 Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
450 Each individual string in the menu bar is a subwidget; the subwidget's
451 name is the same as the menu item string. For example, the word
452 @samp{File} in the menu bar is part of a subwidget named
453 @samp{emacs.pane.menubar.File}. Most likely, you want to specify the
454 same resources for the whole menu bar. To do this, use @samp{*} instead
455 of a specific subwidget name. For example, to specify the font
456 @samp{8x16} for the menu-bar items, write this:
459 Emacs.pane.menubar.*.fontList: 8x16
463 This also specifies the resource value for submenus.
465 Each item in a submenu in the menu bar also has its own name for X
466 resources; for example, the @samp{File} submenu has an item named
467 @samp{Save (current buffer)}. A resource specification for a submenu
468 item looks like this:
471 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
475 For example, here's how to specify the font for the @samp{Save (current
479 Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
483 For an item in a second-level submenu, such as @samp{Complete Word}
484 under @samp{Spell Checking} under @samp{Tools}, the resource fits this
488 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
495 Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value}
499 (This should be one long line.)
501 It's impossible to specify a resource for all the menu-bar items
502 without also specifying it for the submenus as well. So if you want the
503 submenu items to look different from the menu bar itself, you must ask
504 for that in two steps. First, specify the resource for all of them;
505 then, override the value for submenus alone. Here is an example:
508 Emacs.pane.menubar.*.fontList: 8x16
509 Emacs.pane.menubar.popup_*.fontList: 8x16
513 For LessTif pop-up menus, use @samp{menu*} instead of
514 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
515 the pop-up menu items, write this:
518 Emacs.menu*.fontList: 8x16
522 For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}:
525 Emacs.dialog*.fontList: 8x16
526 Emacs.dialog*.foreground: hotpink
529 To specify resources for the LessTif file-selection box, use
530 @samp{fsb*}, like this:
533 Emacs.fsb*.fontList: 8x16
539 Here is a list of the specific resources for LessTif menu bars and
544 The color to show in an armed button.
553 Amount of space to leave around the item, within the border.
555 The width of the border around the menu item, on all sides.
556 @item shadowThickness
557 The width of the border shadow.
558 @item bottomShadowColor
559 The color for the border shadow, on the bottom and the right.
561 The color for the border shadow, on the top and the left.
566 @appendixsec GTK resources
567 @cindex GTK resources and customization
568 @cindex resource files for GTK
569 @cindex @file{~/.gtkrc-2.0} file
570 @cindex @file{~/.emacs.d/gtkrc} file
572 If Emacs was built to use the GTK widget set, then the menu bar,
573 scroll bar and the dialogs are customized with the standard GTK
574 customization file, @file{~/.gtkrc-2.0}, or with the Emacs specific
575 file @file{~/.emacs.d/gtkrc}. We recommend that you use
576 @file{~/.emacs.d/gtkrc} for customizations, since @file{~/.gtkrc-2.0}
577 seems to be ignored when running GConf with GNOME. These files apply
578 only to GTK widget features. To customize Emacs font, background,
579 faces, etc., use the normal X resources (@pxref{Resources}).
581 Some GTK themes override these mechanisms, which means that using
582 these mechanisms will not work to customize them.
584 In these files you first define a style and say what it means; then
585 you specify to apply the style to various widget types (@pxref{GTK
586 widget names}). Here is an example of how to change the font for
590 # @r{Define the style @samp{metafont}.}
593 font_name = "helvetica bold 14" # This is a Pango font name
596 # @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{metafont}.}
597 widget "*emacs-menuitem*" style "menufont"
600 Here is a more elaborate example, showing how to change the parts of
606 fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
607 bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
608 bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
609 bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
612 widget "*verticalScrollBar*" style "scroll"
615 There are also parameters that affect GTK as a whole. For example, the property
616 @c @code{gtk-font-name} sets the default font for GTK. You must use
617 @c Pango font names (@pxref{GTK styles}). A GTK resources file that
618 @c just sets a default font looks like this:
621 gtk-font-name = "courier 12"
624 The GTK resources file is fully described in the GTK API document.
626 @file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html},
627 where @file{prefix} is the directory in which the GTK libraries were
628 installed (usually @file{/usr} or @file{/usr/local}). You can also
629 find the document online, at
630 @uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
633 * GTK widget names:: How widgets in GTK are named in general.
634 * GTK Names in Emacs:: GTK widget names in Emacs.
635 * GTK styles:: What can be customized in a GTK widget.
638 @node GTK widget names
639 @appendixsubsec GTK widget names
640 @cindex GTK widget names
642 A GTK widget is specified by its @dfn{widget class} and
643 @dfn{widget name}. The widget class is the type of the widget: for
644 example, @code{GtkMenuBar}. The widget name is the name given to a
645 specific widget. A widget always has a class, but need not have a
648 @dfn{Absolute names} are sequences of widget names or widget
649 classes, corresponding to hierarchies of widgets embedded within
650 other widgets. For example, if a @code{GtkWindow} named @code{top}
651 contains a @code{GtkVBox} named @code{box}, which in turn contains
652 a @code{GtkMenuBar} called @code{menubar}, the absolute class name
653 of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and
654 its absolute widget name is @code{top.box.menubar}.
656 When assigning a style to a widget, you can use the absolute class
657 name or the absolute widget name.
659 There are two commands to specify changes for widgets:
662 @item @code{widget_class}
663 specifies a style for widgets based on the absolute class name.
666 specifies a style for widgets based on the absolute class name,
671 You must soecify the class and the style in double-quotes, and put
672 these commands at the top level in a @file{~/.gtkrc-2.0} file, like
678 font_name = "helvetica bold 14"
681 widget "top.box.menubar" style "menufont"
682 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont"
685 Matching of absolute names uses shell wildcard syntax: @samp{*}
686 matches zero or more characters and @samp{?} matches one character.
687 This example assigns @code{base_style} to all widgets:
690 widget "*" style "base_style"
693 Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar}
694 and the corresponding absolute widget name @code{top.box.menubar}, all
695 these examples specify @code{my_style} for the menu bar:
698 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
699 widget_class "GtkWindow.*.GtkMenuBar" style "my_style"
700 widget_class "*GtkMenuBar" style "my_style"
701 widget "top.box.menubar" style "my_style"
702 widget "*box*menubar" style "my_style"
703 widget "*menubar" style "my_style"
704 widget "*menu*" style "my_style"
707 @node GTK Names in Emacs
708 @appendixsubsec GTK Widget Names in Emacs
709 @cindex GTK widget names
710 @cindex GTK widget classes
712 In Emacs, the top level widget for a frame is a @code{GtkWindow}
713 that contains a @code{GtkVBox}. The @code{GtkVBox} contains the
714 @code{GtkMenuBar} and a @code{GtkFixed} widget. The vertical scroll
715 bars, @code{GtkVScrollbar}, are contained in the @code{GtkFixed}
716 widget. The text you write in Emacs is drawn in the @code{GtkFixed}
719 Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a
720 @code{GtkFileSelection} widget.
723 To set a style for the menu bar using the absolute class name, use:
726 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
730 For the scroll bar, the absolute class name is:
734 "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar"
739 The names for the emacs widgets, and their classes, are:
741 @multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
742 @item @code{emacs-filedialog}
743 @tab @code{GtkFileSelection}
744 @item @code{emacs-dialog}
745 @tab @code{GtkDialog}
747 @tab @code{GtkWindow}
752 @item @code{verticalScrollBar}
753 @tab @code{GtkVScrollbar}
754 @item @code{emacs-toolbar}
755 @tab @code{GtkToolbar}
757 @tab @code{GtkMenuBar}
758 @item @code{emacs-menuitem}
759 @tab anything in menus
763 Thus, for Emacs you can write the two examples above as:
766 widget "Emacs.pane.menubar" style "my_style"
767 widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
770 GTK absolute names are quite strange when it comes to menus
771 and dialogs. The names do not start with @samp{Emacs}, as they are
772 free-standing windows and not contained (in the GTK sense) by the
773 Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this:
776 widget "*emacs-dialog*" style "my_dialog_style"
777 widget "*emacs-filedialog* style "my_file_style"
778 widget "*emacs-menuitem* style "my_menu_style"
781 If you specify a customization in @file{~/.emacs.d/gtkrc}, then it
782 automatically applies only to Emacs, since other programs don't read
783 that file. For example, the drop down menu in the file dialog can not
784 be customized by any absolute widget name, only by an absolute class
785 name. This is so because the widgets in the drop down menu do not
786 have names and the menu is not contained in the Emacs GtkWindow. To
787 have all menus in Emacs look the same, use this in
788 @file{~/.emacs.d/gtkrc}:
791 widget_class "*Menu*" style "my_menu_style"
795 @appendixsubsec GTK styles
798 In a GTK style you specify the appearance widgets shall have. You
799 can specify foreground and background color, background pixmap and
800 font. The edit widget (where you edit the text) in Emacs is a GTK
801 widget, but trying to specify a style for the edit widget will have no
802 effect. This is so that Emacs compiled for GTK is compatible with
803 Emacs compiled for other X toolkits. The settings for foreground,
804 background and font for the edit widget is taken from the X resources;
805 @pxref{Resources}. Here is an example of two style declarations,
806 @samp{default} and @samp{ruler}:
809 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
813 font_name = "helvetica 12"
815 bg[NORMAL] = @{ 0.83, 0.80, 0.73 @}
816 bg[SELECTED] = @{ 0.0, 0.55, 0.55 @}
817 bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @}
818 bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @}
819 bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @}
822 fg[SELECTED] = @{ 0.9, 0.9, 0.9 @}
824 fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @}
826 base[INSENSITIVE] = "#777766"
827 text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @}
829 bg_pixmap[NORMAL] = "background.xpm"
830 bg_pixmap[INSENSITIVE] = "background.xpm"
831 bg_pixmap[ACTIVE] = "background.xpm"
832 bg_pixmap[PRELIGHT] = "<none>"
836 style "ruler" = "default"
838 font_name = "helvetica 8"
843 The style @samp{ruler} inherits from @samp{default}. This way you can build
844 on existing styles. The syntax for fonts and colors is described below.
846 As this example shows, it is possible to specify several values for
847 foreground and background depending on the widget's @dfn{state}. The
852 This is the default state for widgets.
854 This is the state for a widget that is ready to do something. It is
855 also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"}
856 sets the scroll bar trough to red. Buttons that have been pressed but
857 not released yet (``armed'') are in this state.
859 This is the state when widgets that can be manipulated have the mouse
860 pointer over them. For example when the mouse is over the thumb in the
861 scroll bar or over a menu item. When the mouse is over a button that
862 is not pressed, the button is in this state.
864 This is the state when some data has been selected by the user. It can
865 be selected text or items selected in a list.
866 There is no place in Emacs where this setting has any effect.
868 This is the state for widgets that are visible, but they can not be
869 manipulated in the usual way---for example, buttons that can't be
870 pressed, and disabled menu items. To display disabled menu items in
871 yellow, use @code{fg[INSENSITIVE] = "yellow"}.
874 Here are the things that can go in a style declaration:
877 @item bg[@var{state}] = @var{color}
878 This specifies the background color for the widget. Note that
879 editable text doesn't use @code{bg}; it uses @code{base} instead.
881 @item base[@var{state}] = @var{color}
882 This specifies the background color for editable text. In Emacs, this
883 color is used for the background of the text fields in the file
886 @item bg_pixmap[@var{state}] = "@var{pixmap}"
887 This specifies an image background (instead of a background color).
888 @var{pixmap} should be the image file name. GTK can use a number of
889 image file formats, including XPM, XBM, GIF, JPEG and PNG. If you
890 want a widget to use the same image as its parent, use
891 @samp{<parent>}. If you don't want any image, use @samp{<none>}.
892 @samp{<none>} is the way to cancel a background image inherited from a
895 You can't specify the file by its absolute file name. GTK looks for
896 the pixmap file in directories specified in @code{pixmap_path}.
897 @code{pixmap_path} is a colon-separated list of directories within
898 double quotes, specified at the top level in a @file{gtkrc} file
899 (i.e. not inside a style definition; see example above):
902 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
905 @item fg[@var{state}] = @var{color}
906 This specifies the foreground color for widgets to use. It is the
907 color of text in menus and buttons, and the color for the arrows in
908 the scroll bar. For editable text, use @code{text}.
910 @item text[@var{state}] = @var{color}
911 This is the color for editable text. In Emacs, this color is used for the
912 text fields in the file dialog.
914 @item font_name = "@var{font}"
915 This specifies the the font for text in the widget. @var{font} is a
916 Pango font name, for example @samp{Sans Italic 10}, @samp{Helvetica
917 Bold 12}, @samp{Courier 14}, @samp{Times 18}. See below for exact
918 syntax. The names are case insensitive.
921 There are three ways to specify a color: by name, in hexadecimal
922 form, and with an RGB triplet.
925 A color name is written within double quotes, for example @code{"red"}.
928 Hexadecimal form is the same as in X:
929 @code{#@var{rrrr}@var{gggg}@var{bbbb}}, where all three color specs
930 must have the same number of hex digits (1, 2, 3 or 4).
933 An RGB triplet looks like @code{@{ @var{r}, @var{g}, @var{b} @}},
934 where @var{r}, @var{g} and @var{b} are either integers in the range
935 0-65535 or floats in the range 0.0-1.0.
937 Pango font names have the form ``@var{family-list} @var{style-options}
939 @cindex Pango font name
941 @var{family-list} is a comma separated list of font families optionally
942 terminated by a comma. This way you can specify several families and the
943 first one found will be used. @var{family} corresponds to the second part in
944 an X font name, for example in
947 -adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1
951 the family name is ``times''.
954 @var{style-options} is a whitespace separated list of words where each word
955 is a style, variant, weight, or stretch. The default value for all of
956 these is @code{normal}.
959 A `style' corresponds to the fourth part of an X font name. In X font
960 names it is the character @samp{r}, @samp{i} or @samp{o}; in Pango
961 font names the corresponding values are @code{normal}, @code{italic},
965 A `variant' is either @code{normal} or @code{small-caps}.
966 Small caps is a font with the lower case characters replaced by
967 smaller variants of the capital characters.
970 Weight describes the ``boldness'' of a font. It corresponds to the third
971 part of an X font name. It is one of @code{ultra-light}, @code{light},
972 @code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}.
975 Stretch gives the width of the font relative to other designs within a
976 family. It corresponds to the fifth part of an X font name. It is one of
977 @code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
978 @code{semi-condensed}, @code{normal}, @code{semi-expanded},
979 @code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
982 @var{size} is a decimal number that describes the font size in points.
985 arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f