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, Command Arguments, 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}. X resources are the only way to customize
11 tooltip windows and LessTif menus, since the libraries that implement
12 them don't provide for customization through Emacs. This appendix
13 describes the X resources that Emacs recognizes and how to use them.
16 * Resources:: Using X resources with Emacs (in general).
17 * Table of Resources:: Table of specific X resources that affect Emacs.
18 * Face Resources:: X resources for customizing faces.
19 * Lucid Resources:: X resources for Lucid menus.
20 * LessTif Resources:: X resources for LessTif and Motif menus.
21 * GTK resources:: Resources for GTK widgets.
25 @appendixsec X Resources
28 @cindex @file{~/.Xdefaults} file
29 @cindex @file{~/.Xresources} file
31 Programs running under the X Window System organize their user
32 options under a hierarchy of classes and resources. You can specify
33 default values for these options in your X resources file, usually
34 named @file{~/.Xdefaults} or @file{~/.Xresources}.
35 If changes in @file{~/.Xdefaults} do not
36 take effect, it is because your X server stores its own list of
37 resources; to update them, use the shell command @command{xrdb}---for
38 instance, @samp{xrdb ~/.Xdefaults}.
40 Each line in the file specifies a value for one option or for a
41 collection of related options, for one program or for several programs
42 (optionally even for all programs).
44 @cindex Registry (MS-Windows)
45 MS-Windows systems don't support @file{~/.Xdefaults} files, but
46 Emacs compiled for Windows looks for X resources in the Windows
47 Registry, under the key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs}
48 and then under the key @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}.
49 The menu and scrollbars are native widgets on MS-Windows, so they are
50 only customizable via the system-wide settings in the Display Control
53 Programs define named resources with particular meanings. They also
54 define how to group resources into named classes. For instance, in
55 Emacs, the @samp{internalBorder} resource controls the width of the
56 internal border, and the @samp{borderWidth} resource controls the width
57 of the external border. Both of these resources are part of the
58 @samp{BorderWidth} class. Case distinctions are significant in these
61 In @file{~/.Xdefaults}, you can specify a value for a single resource
62 on one line, like this:
69 Or you can use a class name to specify the same value for all resources
70 in that class. Here's an example:
76 If you specify a value for a class, it becomes the default for all
77 resources in that class. You can specify values for individual
78 resources as well; these override the class value, for those particular
79 resources. Thus, this example specifies 2 as the default width for all
80 borders, but overrides this value with 4 for the external border:
87 The order in which the lines appear in the file does not matter.
88 Also, command-line options always override the X resources file.
90 The string @samp{emacs} in the examples above is also a resource
91 name. It actually represents the name of the executable file that you
92 invoke to run Emacs. If Emacs is installed under a different name, it
93 looks for resources under that name instead of @samp{emacs}.
96 @item -name @var{name}
98 @itemx --name=@var{name}
99 @cindex resource name, command-line argument
100 Use @var{name} as the resource name (and the title) for the initial
101 Emacs frame. This option does not affect subsequent frames, but Lisp
102 programs can specify frame names when they create frames.
104 If you don't specify this option, the default is to use the Emacs
105 executable's name as the resource name.
107 @item -xrm @var{resource-values}
109 @itemx --xrm=@var{resource-values}
110 @cindex resource values, command-line argument
111 Specify X resource values for this Emacs job (see below).
114 For consistency, @samp{-name} also specifies the name to use for
115 other resource values that do not belong to any particular frame.
117 The resources that name Emacs invocations also belong to a class; its
118 name is @samp{Emacs}. If you write @samp{Emacs} instead of
119 @samp{emacs}, the resource applies to all frames in all Emacs jobs,
120 regardless of frame titles and regardless of the name of the executable
121 file. Here is an example:
128 You can specify a string of additional resource values for Emacs to
129 use with the command line option @samp{-xrm @var{resources}}. The text
130 @var{resources} should have the same format that you would use inside a file
131 of X resources. To include multiple resource specifications in
132 @var{resources}, put a newline between them, just as you would in a file.
133 You can also use @samp{#include "@var{filename}"} to include a file full
134 of resource specifications. Resource values specified with @samp{-xrm}
135 take precedence over all other resource specifications.
137 One way to experiment with the effect of different resource settings
138 is to use the @code{editres} program. Select @samp{Get Tree} from the
139 @samp{Commands} menu, then click on an Emacs frame. This will display
140 a tree showing the structure of X toolkit widgets used in an Emacs
141 frame. Select one of them, such as @samp{menubar}, then select
142 @samp{Show Resource Box} from the @samp{Commands} menu. This displays
143 a list of all the meaningful X resources and allows you to edit them.
144 Changes take effect immediately if you click on the @samp{Apply} button.
145 (See the @code{editres} man page for more details.)
147 @node Table of Resources
148 @appendixsec Table of X Resources for Emacs
150 This table lists the resource names that designate options for
151 Emacs, not counting those for the appearance of the menu bar, each
152 with the class that it belongs to:
155 @item @code{background} (class @code{Background})
156 Background color name.
158 @item @code{bitmapIcon} (class @code{BitmapIcon})
159 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
160 manager choose an icon if @samp{off}.
162 @item @code{borderColor} (class @code{BorderColor})
163 Color name for the external border.
165 @item @code{borderWidth} (class @code{BorderWidth})
166 Width in pixels of the external border.
168 @item @code{cursorColor} (class @code{Foreground})
169 Color name for text cursor (point).
171 @item @code{font} (class @code{Font})
172 Font name for text (or fontset name, @pxref{Fontsets}).
174 @item @code{foreground} (class @code{Foreground})
177 @item @code{geometry} (class @code{Geometry})
178 Window size and position. Be careful not to specify this resource as
179 @samp{emacs*geometry}, because that may affect individual menus as well
180 as the Emacs frame itself.
182 If this resource specifies a position, that position applies only to the
183 initial Emacs frame (or, in the case of a resource for a specific frame
184 name, only that frame). However, the size, if specified here, applies to
187 @item @code{fullscreen} (class @code{Fullscreen})
188 The desired fullscreen size. The value can be one of @code{fullboth},
189 @code{fullwidth} or @code{fullheight}, which correspond to
190 the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh}
191 (@pxref{Window Size X}).
193 Note that this applies to all frames created, not just the initial
196 @item @code{iconName} (class @code{Title})
197 Name to display in the icon.
199 @item @code{internalBorder} (class @code{BorderWidth})
200 Width in pixels of the internal border.
202 @item @code{lineSpacing} (class @code{LineSpacing})
205 Additional space (@dfn{leading}) between lines, in pixels.
207 @item @code{menuBar} (class @code{MenuBar})
209 Give frames menu bars if @samp{on}; don't have menu bars if
210 @samp{off}. @xref{Lucid Resources}, and @ref{LessTif Resources}, for
211 how to control the appearance of the menu bar if you have one.
213 @item @code{minibuffer} (class @code{Minibuffer})
214 If @samp{none}, don't make a minibuffer in this frame.
215 It will use a separate minibuffer frame instead.
217 @item @code{paneFont} (class @code{Font})
218 @cindex font for menus
219 Font name for menu pane titles, in non-toolkit versions of Emacs.
221 @item @code{pointerColor} (class @code{Foreground})
222 Color of the mouse cursor.
224 @item @code{privateColormap} (class @code{PrivateColormap})
225 If @samp{on}, use a private color map, in the case where the ``default
226 visual'' of class PseudoColor and Emacs is using it.
228 @item @code{reverseVideo} (class @code{ReverseVideo})
229 Switch foreground and background default colors if @samp{on}, use colors as
230 specified if @samp{off}.
232 @item @code{screenGamma} (class @code{ScreenGamma})
233 @cindex gamma correction
234 Gamma correction for colors, equivalent to the frame parameter
237 @item @code{selectionFont} (class @code{SelectionFont})
238 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
239 toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
242 @item @code{selectionTimeout} (class @code{SelectionTimeout})
243 Number of milliseconds to wait for a selection reply.
244 If the selection owner doesn't reply in this time, we give up.
245 A value of 0 means wait as long as necessary.
247 @item @code{synchronous} (class @code{Synchronous})
248 @cindex debugging X problems
249 @cindex synchronous X mode
250 Run Emacs in synchronous mode if @samp{on}. Synchronous mode is
251 useful for debugging X problems.
253 @item @code{title} (class @code{Title})
254 Name to display in the title bar of the initial Emacs frame.
256 @item @code{toolBar} (class @code{ToolBar})
258 Number of lines to reserve for the tool bar. A zero value suppresses
259 the tool bar. If the value is non-zero and
260 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
261 will be changed automatically so that all tool bar items are visible.
263 @item @code{useXIM} (class @code{UseXIM})
265 @cindex X input methods
266 @cindex input methods, X
267 Turn off use of X input methods (XIM) if @samp{false} or @samp{off}.
268 This is only relevant if your Emacs is actually built with XIM
269 support. It is potentially useful to turn off XIM for efficiency,
270 especially slow X client/server links.
272 @item @code{verticalScrollBars} (class @code{ScrollBars})
273 Give frames scroll bars if @samp{on}; don't have scroll bars if
278 @appendixsec X Resources for Faces
280 You can also use resources to customize the appearance of particular
281 faces (@pxref{Faces}):
284 @item @var{face}.attributeFont
285 Font for face @var{face}.
286 @item @var{face}.attributeForeground
287 Foreground color for face @var{face}.
288 @item @var{face}.attributeBackground
289 Background color for face @var{face}.
290 @item @var{face}.attributeUnderline
291 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
293 @item @var{face}.attributeFamily
294 Font family for face @var{face}.
295 @item @var{face}.attributeWidth
296 Relative proportional width of the font to use for face @var{face}.
297 It should be one of @code{ultra-condensed}, @code{extra-condensed},
298 @code{condensed}, @code{semi-condensed}, @code{normal},
299 @code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or
300 @code{ultra-expanded}.
301 @item @var{face}.attributeHeight
302 Height of the font to use for face @var{face}: either an integer
303 specifying the height in units of 1/10@dmn{pt}, or a floating point
304 number that specifies a scale factor to scale the underlying face's
305 default font, or a function to be called with the default height which
306 will return a new height.
307 @item @var{face}.attributeWeight
308 A weight to use for the face @var{face}. It must be one of
309 @code{ultra-bold}, @code{extra-bold}, @code{bold},
310 @code{semi-bold}, @code{normal}, @code{semi-light}, @code{light},
311 @code{extra-light}, @code{ultra-light}.
312 @item @var{face}.attributeSlant
313 The slant to use for the font of face @var{face}. It must be one of
314 @code{italic}, @code{oblique}, @code{normal},
315 @code{reverse-italic}, or @code{reverse-oblique}.
316 @item @var{face}.attributeStrikeThrough
317 Whether the face @var{face} should be drawn with a line striking
318 through the characters.
319 @item @var{face}.attributeOverline
320 Whether the characters in the face @var{face} should be overlined.
321 @item @var{face}.attributeBox
322 Whether to draw a box around the characters in face @var{face}.
323 @item @var{face}.attributeInverse
324 Whether to display the characters in face @var{face} in inverse
326 @item @var{face}.attributeStipple
327 The name of a pixmap data file to use for the stipple pattern, or
328 @code{false} to not use stipple for the face @var{face}.
329 @item @var{face}.attributeBackgroundPixmap
330 The background pixmap for the face @var{face}. Should be a name of a
331 pixmap file or @code{false}.
332 @item @var{face}.attributeBold
333 Whether to draw the characters in the face @var{face} as bold.
334 @item @var{face}.attributeItalic
335 Whether to draw the characters in the face @var{face} as italic.
338 @node Lucid Resources
339 @appendixsec Lucid Menu X Resources
340 @cindex Menu X Resources (Lucid widgets)
341 @cindex Lucid Widget X Resources
343 If the Emacs installed at your site was built to use the X toolkit
344 with the Lucid menu widgets, then the menu bar is a separate widget and
345 has its own resources. The resource names contain @samp{pane.menubar}
346 (following, as always, the name of the Emacs invocation, or @samp{Emacs},
347 which stands for all Emacs invocations). Specify them like this:
350 Emacs.pane.menubar.@var{resource}: @var{value}
354 For example, to specify the font @samp{8x16} for the menu-bar items,
358 Emacs.pane.menubar.font: 8x16
362 Resources for @emph{non-menubar} toolkit pop-up menus have
363 @samp{menu*}, in like fashion. For example, to specify the font
364 @samp{8x16} for the pop-up menu items, write this:
367 Emacs.menu*.font: 8x16
371 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
374 Emacs.dialog*.font: 8x16
378 Experience shows that on some systems you may need to add
379 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
380 some other systems, you must not add @samp{shell.}.
382 Here is a list of the specific resources for menu bars and pop-up menus:
386 Font for menu item text.
388 Color of the foreground.
390 Color of the background.
391 @item buttonForeground
392 In the menu bar, the color of the foreground for a selected item.
393 @item horizontalSpacing
394 Horizontal spacing in pixels between items. Default is 3.
395 @item verticalSpacing
396 Vertical spacing in pixels between items. Default is 2.
398 Horizontal spacing between the arrow (which indicates a submenu) and
399 the associated text. Default is 10.
400 @item shadowThickness
401 Thickness of shadow line around the widget. Default is 1.
403 Also determines the thickness of shadow lines around other objects,
404 for instance 3D buttons and arrows. If you have the impression that
405 the arrows in the menus do not stand out clearly enough or that the
406 difference between ``in'' and ``out'' buttons is difficult to see, set
407 this to 2. If you have no problems with visibility, the default
408 probably looks better. The background color may also have some effect
411 The margin of the menu bar, in characters. Default is 1.
414 @node LessTif Resources
415 @appendixsec LessTif Menu X Resources
416 @cindex Menu X Resources (LessTif widgets)
417 @cindex LessTif Widget X Resources
419 If the Emacs installed at your site was built to use the X toolkit
420 with the LessTif or Motif widgets, then the menu bar, the dialog
421 boxes, the pop-up menus, and the file-selection box are separate
422 widgets and have their own resources.
424 The resource names for the menu bar contain @samp{pane.menubar}
425 (following, as always, the name of the Emacs invocation, or
426 @samp{Emacs}, which stands for all Emacs invocations). Specify them
430 Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
433 Each individual string in the menu bar is a subwidget; the subwidget's
434 name is the same as the menu item string. For example, the word
435 @samp{File} in the menu bar is part of a subwidget named
436 @samp{emacs.pane.menubar.File}. Most likely, you want to specify the
437 same resources for the whole menu bar. To do this, use @samp{*} instead
438 of a specific subwidget name. For example, to specify the font
439 @samp{8x16} for the menu-bar items, write this:
442 Emacs.pane.menubar.*.fontList: 8x16
446 This also specifies the resource value for submenus.
448 Each item in a submenu in the menu bar also has its own name for X
449 resources; for example, the @samp{File} submenu has an item named
450 @samp{Save (current buffer)}. A resource specification for a submenu
451 item looks like this:
454 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
458 For example, here's how to specify the font for the @samp{Save (current
462 Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
466 For an item in a second-level submenu, such as @samp{Complete Word}
467 under @samp{Spell Checking} under @samp{Tools}, the resource fits this
471 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
478 Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value}
482 (This should be one long line.)
484 It's impossible to specify a resource for all the menu-bar items
485 without also specifying it for the submenus as well. So if you want the
486 submenu items to look different from the menu bar itself, you must ask
487 for that in two steps. First, specify the resource for all of them;
488 then, override the value for submenus alone. Here is an example:
491 Emacs.pane.menubar.*.fontList: 8x16
492 Emacs.pane.menubar.popup_*.fontList: 8x16
496 For LessTif pop-up menus, use @samp{menu*} instead of
497 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
498 the pop-up menu items, write this:
501 Emacs.menu*.fontList: 8x16
505 For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}:
508 Emacs.dialog*.fontList: 8x16
509 Emacs.dialog*.foreground: hotpink
512 To specify resources for the LessTif file-selection box, use
513 @samp{fsb*}, like this:
516 Emacs.fsb*.fontList: 8x16
522 Here is a list of the specific resources for LessTif menu bars and
527 The color to show in an armed button.
536 Amount of space to leave around the item, within the border.
538 The width of the border around the menu item, on all sides.
539 @item shadowThickness
540 The width of the border shadow.
541 @item bottomShadowColor
542 The color for the border shadow, on the bottom and the right.
544 The color for the border shadow, on the top and the left.
549 @appendixsec GTK resources
550 @cindex GTK resources and customization
551 @cindex resource files for GTK
552 @cindex @file{~/.gtkrc-2.0} file
553 @cindex @file{~/.emacs.d/gtkrc} file
555 If the Emacs installed at your site was built to use the GTK widget set,
556 then the menu bar, scroll bar and the dialogs can be customized with
557 the standard GTK @file{~/.gtkrc-2.0} file or with the Emacs specific
558 @file{~/.emacs.d/gtkrc} file; note that these files are only for
559 customizing specific GTK widget features. To customize Emacs font,
560 background, faces etc., use the normal X resources, see @ref{Resources}.
562 In these files you first defines a style and then how to apply that style
563 to widgets (@pxref{GTK widget names}). Here is an example of how to
564 change the font for Emacs menus:
570 font_name = "helvetica bold 14" # This is a Pango font name
573 widget "*emacs-menuitem*" style "menufont"
577 There are some things you can set without using any style or widget name,
578 which affect GTK as a whole. Most of these are poorly documented, but can
579 be found in the `Properties' section of the documentation page for
580 @code{GtkSetting}, in the GTK document references below.
582 One property of interest is @code{gtk-font-name} which sets the default
583 font for GTK; you must use Pango font names (@pxref{GTK styles}). A
584 @file{~/.gtkrc-2.0} file that just sets a default font looks like this:
587 gtk-font-name = "courier 12"
591 If GTK at your site is installed under @var{prefix},
592 the resource file syntax is fully described in the GTK API
594 @file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html}.
595 @var{prefix} is usually @file{/usr} or @file{/usr/local}.
596 You can find the same document online at
597 @uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
601 * GTK widget names:: How widgets in GTK are named in general.
602 * GTK names in Emacs:: GTK widget names in Emacs.
603 * GTK styles:: What can be customized in a GTK widget.
607 @node GTK widget names
608 @appendixsubsec GTK widget names
609 @cindex GTK widget names
611 Widgets are specified by widget class or by widget name.
612 The widget class is the type of the widget, for example @code{GtkMenuBar}.
613 The widget name is the name given to a specific widget within a program.
614 A widget always have a class but it is not mandatory to give a name to
615 a widget. Absolute names are sequences of widget names or
616 widget classes, corresponding to hierarchies of widgets embedded within
617 other widgets. For example, if a @code{GtkWindow} contains a @code{GtkVBox}
618 which in turn contains a @code{GtkMenuBar}, the absolute class name
619 is @code{GtkWindow.GtkVBox.GtkMenuBar}.
622 If the widgets are named ``top'', ``box'' and ``menubar'', the absolute
623 widget name is @code{top.box.menubar},
625 When assigning a style to a widget, you can use the absolute class
626 name or the absolute widget name.
627 There are two commands: @code{widget_class} will assign a style to
628 widgets, matching only against the absolute class name.
629 The command @code{widget} will match the absolute widget name,
630 but if there is no name for a widget in the hierarchy, the class is matched.
631 These commands require the absolute name and the style name to be
632 within double quotes. These commands are written at the top level in a
633 @file{~/.gtkrc-2.0} file, like this:
638 font_name = "helvetica bold 14"
641 widget "top.box.menubar" style "menufont"
642 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont"
646 Matching of absolute names is done with shell ``glob'' syntax, that is
647 @samp{*} matches zero or more characters and @samp{?} matches one character.
648 So the following would assign @code{base_style} to all widgets:
651 widget "*" style "base_style"
654 Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar}
655 and the corresponding absolute widget name @code{top.box.menubar},
656 the following all assign @code{my_style} to the menu bar:
659 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
660 widget_class "GtkWindow.*.GtkMenuBar" style "my_style"
661 widget_class "*GtkMenuBar" style "my_style"
662 widget "top.box.menubar" style "my_style"
663 widget "*box*menubar" style "my_style"
664 widget "*menubar" style "my_style"
665 widget "*menu*" style "my_style"
668 @node GTK names in Emacs
669 @appendixsubsec GTK names in Emacs
670 @cindex GTK widget names
671 @cindex GTK widget classes
673 In Emacs the top level widget for a frame is a @code{GtkWindow} that
674 contains a @code{GtkVBox}. The @code{GtkVBox} contains the
675 @code{GtkMenuBar} and a @code{GtkFixed} widget.
676 The vertical scroll bars, @code{GtkVScrollbar},
677 are contained in the @code{GtkFixed} widget.
678 The text you write in Emacs is drawn in the @code{GtkFixed} widget.
680 Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a
681 @code{GtkFileSelection} widget.
684 To set a style for the menu bar using the absolute class name, use:
687 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
691 For the scroll bar, the absolute class name is:
695 "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar"
700 The names for the emacs widgets, and their classes, are:
702 @multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
703 @item @code{emacs-filedialog}
704 @tab @code{GtkFileSelection}
705 @item @code{emacs-dialog}
706 @tab @code{GtkDialog}
708 @tab @code{GtkWindow}
713 @item @code{verticalScrollBar}
714 @tab @code{GtkVScrollbar}
715 @item @code{emacs-toolbar}
716 @tab @code{GtkToolbar}
718 @tab @code{GtkMenuBar}
719 @item @code{emacs-menuitem}
720 @tab anything in menus
724 Thus, for Emacs you can write the two examples above as:
727 widget "Emacs.pane.menubar" style "my_style"
728 widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
731 GTK absolute names are quite strange when it comes to menus
732 and dialogs. The names do not start with @samp{Emacs}, as they are
733 free-standing windows and not contained (in the GTK sense) by the
734 Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this:
737 widget "*emacs-dialog*" style "my_dialog_style"
738 widget "*emacs-filedialog* style "my_file_style"
739 widget "*emacs-menuitem* style "my_menu_style"
742 An alternative is to put customization into @file{~/.emacs.d/gtkrc}.
743 This file is only read by Emacs, so anything in @file{~/.emacs.d/gtkrc}
744 affects Emacs but leaves other applications unaffected.
745 For example, the drop down menu in the file dialog can not
746 be customized by any absolute widget name, only by an absolute
747 class name. This is so because the widgets in the drop down menu does not
748 have names and the menu is not contained in the Emacs GtkWindow.
749 To have all menus in Emacs look the same, use this in @file{~/.emacs.d/gtkrc}:
752 widget_class "*Menu*" style "my_menu_style"
756 @appendixsubsec GTK styles
759 In a GTK style you specify the appearance widgets shall have. You
760 can specify foreground and background color, background pixmap and font.
761 The edit widget (where you edit the text) in Emacs is a GTK widget,
762 but trying to specify a style for the edit widget will have no effect.
763 This is so that Emacs compiled for GTK is compatible with Emacs compiled
764 for other X toolkits. The settings for foreground, background and font
765 for the edit widget is taken from the X resources; @pxref{Resources}.
766 Here is an example of two style declarations, ``default'' and ``ruler'':
770 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
774 font_name = "helvetica 12"
776 bg[NORMAL] = @{ 0.83, 0.80, 0.73 @}
777 bg[SELECTED] = @{ 0.0, 0.55, 0.55 @}
778 bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @}
779 bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @}
780 bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @}
783 fg[SELECTED] = @{ 0.9, 0.9, 0.9 @}
785 fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @}
787 base[INSENSITIVE] = "#777766"
788 text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @}
790 bg_pixmap[NORMAL] = "background.xpm"
791 bg_pixmap[INSENSITIVE] = "background.xpm"
792 bg_pixmap[ACTIVE] = "background.xpm"
793 bg_pixmap[PRELIGHT] = "<none>"
797 style "ruler" = "default"
799 font_name = "helvetica 8"
804 The style ``ruler'' inherits from ``default''. This way you can build
805 on existing styles. The syntax for fonts and colors is described below.
807 As this example shows, it is possible to specify several values
808 for foreground and background depending on which state the widget has.
809 The possible states are
812 This is the default state for widgets.
814 This is the state for a widget that is ready to do something. It is
815 also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"}
816 sets the scroll bar trough to red. Buttons that have been pressed but
817 not released yet (``armed'') are in this state.
819 This is the state when widgets that can be manipulated have the mouse
820 pointer over them. For example when the mouse is over the thumb in the
821 scroll bar or over a menu item. When the mouse is over a button that
822 is not pressed, the button is in this state.
824 This is the state when some data has been selected by the user. It can
825 be selected text or items selected in a list.
826 There is no place in Emacs where this setting has any effect.
828 This is the state for widgets that are visible, but they can not be
829 manipulated like they normally can. For example, buttons that can't be
830 pressed and menu items that can't be selected.
831 Text for menu items that are not available can be set to yellow with
832 @code{fg[INSENSITIVE] = "yellow"}.
835 Here are the things that can go in a style declaration:
838 @item bg[@var{state}] = @var{color}
839 This is the background color widgets use. This background is not used for
840 editable text, use @code{base} for that.
842 @item base[@var{state}] = @var{color}
843 This is the background color for editable text.
844 In Emacs, this color is used for the background of the text fields in the
847 @item bg_pixmap[@var{state}] = "@var{pixmap}"
848 You can specify a pixmap to be used instead of the background color.
849 @var{pixmap} is a file name. GTK can use a number of file formats,
850 including XPM, XBM, GIF, JPEG and PNG. If you want a widget to use the same
851 pixmap as its parent, use @samp{<parent>}. If you don't want any
852 pixmap use @samp{<none>}. Using @samp{<none>} can be useful
853 if your style inherits a style that does specify a pixmap.
855 GTK looks for the pixmap in directories specified in @code{pixmap_path}.
856 It is not possible to refer to a file by its absolute path name.
857 @code{pixmap_path} is a colon-separated list of directories within double
858 quotes, specified at the top level in a @file{gtkrc} file (i.e. not inside
859 a style definition; see example above):
862 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
865 @item fg[@var{state}] = @var{color}
866 This is the foreground color widgets use. This is the color
867 of text in menus and buttons. It is also the color for the arrows in the
868 scroll bar. For editable text, use @code{text}.
870 @item text[@var{state}] = @var{color}
871 This is the color for editable text. In Emacs, this color is used for the
872 text fields in the file dialog.
874 @item font_name = "@var{font}"
875 This is the font a widget shall use. @var{font} is a Pango font name,
876 for example ``Sans Italic 10'', ``Helvetica Bold 12'', ``Courier 14'',
877 ``Times 18''. See below for exact syntax. The names are case insensitive.
880 Colors are specified in three ways, a name, a hexadecimal form or
884 A color name is written within double quotes, for example @code{"red"}.
887 A hexadecimal form is written within double quotes. There are four forms,
888 @code{#rrrrggggbbbb}, @code{#rrrgggbbb},
889 @code{#rrggbb}, or @code{#rgb}. In each of these r, g and b are hex digits.
892 An RGB triplet looks like @code{@{ r, g, b @}}, where r, g and b are either
893 integers in the range 0-65535 or floats in the range 0.0-1.0.
895 Pango font names have the form ``@var{family-list} @var{style-options}
897 @cindex Pango font name
899 @var{family-list} is a comma separated list of font families optionally
900 terminated by a comma. This way you can specify several families and the
901 first one found will be used. @var{family} corresponds to the second part in
902 an X font name, for example in
905 -adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1
909 the family name is ``times''.
912 @var{style-options} is a whitespace separated list of words where each word
913 is a style, variant, weight, or stretch. The default value for all of
914 these is @code{normal}.
917 A `style' corresponds to the fourth part of an X font name. In X font
918 names it is the character ``r'', ``i'' or ``o''; in Pango font names the
919 corresponding values are @code{normal}, @code{italic}, or @code{oblique}.
922 A `variant' is either @code{normal} or @code{small-caps}.
923 Small caps is a font with the lower case characters replaced by
924 smaller variants of the capital characters.
927 Weight describes the ``boldness'' of a font. It corresponds to the third
928 part of an X font name. It is one of @code{ultra-light}, @code{light},
929 @code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}.
932 Stretch gives the width of the font relative to other designs within a
933 family. It corresponds to the fifth part of an X font name. It is one of
934 @code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
935 @code{semi-condensed}, @code{normal}, @code{semi-expanded},
936 @code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
939 @var{size} is a decimal number that describes the font size in points.
942 arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f