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