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}.
50 Programs define named resources with particular meanings. They also
51 define how to group resources into named classes. For instance, in
52 Emacs, the @samp{internalBorder} resource controls the width of the
53 internal border, and the @samp{borderWidth} resource controls the width
54 of the external border. Both of these resources are part of the
55 @samp{BorderWidth} class. Case distinctions are significant in these
58 In @file{~/.Xdefaults}, you can specify a value for a single resource
59 on one line, like this:
66 Or you can use a class name to specify the same value for all resources
67 in that class. Here's an example:
73 If you specify a value for a class, it becomes the default for all
74 resources in that class. You can specify values for individual
75 resources as well; these override the class value, for those particular
76 resources. Thus, this example specifies 2 as the default width for all
77 borders, but overrides this value with 4 for the external border:
84 The order in which the lines appear in the file does not matter.
85 Also, command-line options always override the X resources file.
87 The string @samp{emacs} in the examples above is also a resource
88 name. It actually represents the name of the executable file that you
89 invoke to run Emacs. If Emacs is installed under a different name, it
90 looks for resources under that name instead of @samp{emacs}.
93 @item -name @var{name}
95 @itemx --name=@var{name}
96 @cindex resource name, command-line argument
97 Use @var{name} as the resource name (and the title) for the initial
98 Emacs frame. This option does not affect subsequent frames, but Lisp
99 programs can specify frame names when they create frames.
101 If you don't specify this option, the default is to use the Emacs
102 executable's name as the resource name.
104 @item -xrm @var{resource-values}
106 @itemx --xrm=@var{resource-values}
107 @cindex resource values, command-line argument
108 Specify X resource values for this Emacs job (see below).
111 For consistency, @samp{-name} also specifies the name to use for
112 other resource values that do not belong to any particular frame.
114 The resources that name Emacs invocations also belong to a class; its
115 name is @samp{Emacs}. If you write @samp{Emacs} instead of
116 @samp{emacs}, the resource applies to all frames in all Emacs jobs,
117 regardless of frame titles and regardless of the name of the executable
118 file. Here is an example:
125 You can specify a string of additional resource values for Emacs to
126 use with the command line option @samp{-xrm @var{resources}}. The text
127 @var{resources} should have the same format that you would use inside a file
128 of X resources. To include multiple resource specifications in
129 @var{resources}, put a newline between them, just as you would in a file.
130 You can also use @samp{#include "@var{filename}"} to include a file full
131 of resource specifications. Resource values specified with @samp{-xrm}
132 take precedence over all other resource specifications.
134 One way to experiment with the effect of different resource settings
135 is to use the @code{editres} program. Select @samp{Get Tree} from the
136 @samp{Commands} menu, then click on an Emacs frame. This will display
137 a tree showing the structure of X toolkit widgets used in an Emacs
138 frame. Select one of them, such as @samp{menubar}, then select
139 @samp{Show Resource Box} from the @samp{Commands} menu. This displays
140 a list of all the meaningful X resources and allows you to edit them.
141 Changes take effect immediately if you click on the @samp{Apply} button.
143 @node Table of Resources
144 @appendixsec Table of X Resources for Emacs
146 This table lists the resource names that designate options for
147 Emacs, not counting those for the appearance of the menu bar, each
148 with the class that it belongs to:
151 @item @code{background} (class @code{Background})
152 Background color name.
154 @item @code{bitmapIcon} (class @code{BitmapIcon})
155 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
156 manager choose an icon if @samp{off}.
158 @item @code{borderColor} (class @code{BorderColor})
159 Color name for the external border.
161 @item @code{borderWidth} (class @code{BorderWidth})
162 Width in pixels of the external border.
164 @item @code{cursorColor} (class @code{Foreground})
165 Color name for text cursor (point).
167 @item @code{font} (class @code{Font})
168 Font name for text (or fontset name, @pxref{Fontsets}).
170 @item @code{foreground} (class @code{Foreground})
173 @item @code{geometry} (class @code{Geometry})
174 Window size and position. Be careful not to specify this resource as
175 @samp{emacs*geometry}, because that may affect individual menus as well
176 as the Emacs frame itself.
178 If this resource specifies a position, that position applies only to the
179 initial Emacs frame (or, in the case of a resource for a specific frame
180 name, only that frame). However, the size, if specified here, applies to
183 @item @code{fullscreen} (class @code{Fullscreen})
184 The desired fullscreen size. The value can be one of @code{fullboth},
185 @code{fullwidth} or @code{fullheight}, which correspond to
186 the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh}
187 (@pxref{Window Size X}).
189 Note that this applies to all frames created, not just the initial
192 @item @code{iconName} (class @code{Title})
193 Name to display in the icon.
195 @item @code{internalBorder} (class @code{BorderWidth})
196 Width in pixels of the internal border.
198 @item @code{lineSpacing} (class @code{LineSpacing})
201 Additional space (@dfn{leading}) between lines, in pixels.
203 @item @code{menuBar} (class @code{MenuBar})
204 Give frames menu bars if @samp{on}; don't have menu bars if
205 @samp{off}. @xref{Lucid Resources}, and @ref{LessTif Resources}, for
206 how to control the appearance of the menu bar if you have one.
208 @item @code{minibuffer} (class @code{Minibuffer})
209 If @samp{none}, don't make a minibuffer in this frame.
210 It will use a separate minibuffer frame instead.
212 @item @code{paneFont} (class @code{Font})
213 @cindex font for menus
214 Font name for menu pane titles, in non-toolkit versions of Emacs.
216 @item @code{pointerColor} (class @code{Foreground})
217 Color of the mouse cursor.
219 @item @code{privateColormap} (class @code{PrivateColormap})
220 If @samp{on}, use a private color map, in the case where the ``default
221 visual'' of class PseudoColor and Emacs is using it.
223 @item @code{reverseVideo} (class @code{ReverseVideo})
224 Switch foreground and background default colors if @samp{on}, use colors as
225 specified if @samp{off}.
227 @item @code{screenGamma} (class @code{ScreenGamma})
228 @cindex gamma correction
229 Gamma correction for colors, equivalent to the frame parameter
232 @item @code{selectionFont} (class @code{SelectionFont})
233 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
234 toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
237 @item @code{selectionTimeout} (class @code{SelectionTimeout})
238 Number of milliseconds to wait for a selection reply.
239 If the selection owner doesn't reply in this time, we give up.
240 A value of 0 means wait as long as necessary.
242 @item @code{synchronous} (class @code{Synchronous})
243 @cindex debugging X problems
244 @cindex synchronous X mode
245 Run Emacs in synchronous mode if @samp{on}. Synchronous mode is
246 useful for debugging X problems.
248 @item @code{title} (class @code{Title})
249 Name to display in the title bar of the initial Emacs frame.
251 @item @code{toolBar} (class @code{ToolBar})
252 Number of lines to reserve for the tool bar. A zero value suppresses
253 the tool bar. If the value is non-zero and
254 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
255 will be changed automatically so that all tool bar items are visible.
257 @item @code{verticalScrollBars} (class @code{ScrollBars})
258 Give frames scroll bars if @samp{on}; don't have scroll bars if
263 @appendixsec X Resources for Faces
265 You can also use resources to customize the appearance of particular
266 faces (@pxref{Faces}):
269 @item @var{face}.attributeFont
270 Font for face @var{face}.
271 @item @var{face}.attributeForeground
272 Foreground color for face @var{face}.
273 @item @var{face}.attributeBackground
274 Background color for face @var{face}.
275 @item @var{face}.attributeUnderline
276 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
278 @item @var{face}.attributeFamily
279 Font family for face @var{face}.
280 @item @var{face}.attributeWidth
281 Relative proportional width of the font to use for face @var{face}.
282 It should be one of @code{ultra-condensed}, @code{extra-condensed},
283 @code{condensed}, @code{semi-condensed}, @code{normal},
284 @code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or
285 @code{ultra-expanded}.
286 @item @var{face}.attributeHeight
287 Height of the font to use for face @var{face}: either an integer
288 specifying the height in units of 1/10@dmn{pt}, or a floating point
289 number that specifies a scale factor to scale the underlying face's
290 default font, or a function to be called with the default height which
291 will return a new height.
292 @item @var{face}.attributeWeight
293 A weight to use for the face @var{face}. It must be one of
294 @code{ultra-bold}, @code{extra-bold}, @code{bold},
295 @code{semi-bold}, @code{normal}, @code{semi-light}, @code{light},
296 @code{extra-light}, @code{ultra-light}.
297 @item @var{face}.attributeSlant
298 The slant to use for the font of face @var{face}. It must be one of
299 @code{italic}, @code{oblique}, @code{normal},
300 @code{reverse-italic}, or @code{reverse-oblique}.
301 @item @var{face}.attributeStrikeThrough
302 Whether the face @var{face} should be drawn with a line striking
303 through the characters.
304 @item @var{face}.attributeOverline
305 Whether the characters in the face @var{face} should be overlined.
306 @item @var{face}.attributeBox
307 Whether to draw a box around the characters in face @var{face}.
308 @item @var{face}.attributeInverse
309 Whether to display the characters in face @var{face} in inverse
311 @item @var{face}.attributeStipple
312 The name of a pixmap data file to use for the stipple pattern, or
313 @code{false} to not use stipple for the face @var{face}.
314 @item @var{face}.attributeBackgroundPixmap
315 The background pixmap for the face @var{face}. Should be a name of a
316 pixmap file or @code{false}.
317 @item @var{face}.attributeBold
318 Whether to draw the characters in the face @var{face} as bold.
319 @item @var{face}.attributeItalic
320 Whether to draw the characters in the face @var{face} as italic.
323 @node Lucid Resources
324 @appendixsec Lucid Menu X Resources
325 @cindex Menu X Resources (Lucid widgets)
326 @cindex Lucid Widget X Resources
328 If the Emacs installed at your site was built to use the X toolkit
329 with the Lucid menu widgets, then the menu bar is a separate widget and
330 has its own resources. The resource names contain @samp{pane.menubar}
331 (following, as always, the name of the Emacs invocation, or @samp{Emacs},
332 which stands for all Emacs invocations). Specify them like this:
335 Emacs.pane.menubar.@var{resource}: @var{value}
339 For example, to specify the font @samp{8x16} for the menu-bar items,
343 Emacs.pane.menubar.font: 8x16
347 Resources for @emph{non-menubar} toolkit pop-up menus have
348 @samp{menu*}, in like fashion. For example, to specify the font
349 @samp{8x16} for the pop-up menu items, write this:
352 Emacs.menu*.font: 8x16
356 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
359 Emacs.dialog*.font: 8x16
363 Experience shows that on some systems you may need to add
364 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
365 some other systems, you must not add @samp{shell.}.
367 Here is a list of the specific resources for menu bars and pop-up menus:
371 Font for menu item text.
373 Color of the foreground.
375 Color of the background.
376 @item buttonForeground
377 In the menu bar, the color of the foreground for a selected item.
378 @item horizontalSpacing
379 Horizontal spacing in pixels between items. Default is 3.
380 @item verticalSpacing
381 Vertical spacing in pixels between items. Default is 1.
383 Horizontal spacing between the arrow (which indicates a submenu) and
384 the associated text. Default is 10.
385 @item shadowThickness
386 Thickness of shadow line around the widget.
388 The margin of the menu bar, in characters. The default of 4 makes the
389 menu bar appear like the LessTif/Motif one.
392 @node LessTif Resources
393 @appendixsec LessTif Menu X Resources
394 @cindex Menu X Resources (LessTif widgets)
395 @cindex LessTif Widget X Resources
397 If the Emacs installed at your site was built to use the X toolkit
398 with the LessTif or Motif widgets, then the menu bar, the dialog
399 boxes, the pop-up menus, and the file-selection box are separate
400 widgets and have their own resources.
402 The resource names for the menu bar contain @samp{pane.menubar}
403 (following, as always, the name of the Emacs invocation, or
404 @samp{Emacs}, which stands for all Emacs invocations). Specify them
408 Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
411 Each individual string in the menu bar is a subwidget; the subwidget's
412 name is the same as the menu item string. For example, the word
413 @samp{File} in the menu bar is part of a subwidget named
414 @samp{emacs.pane.menubar.File}. Most likely, you want to specify the
415 same resources for the whole menu bar. To do this, use @samp{*} instead
416 of a specific subwidget name. For example, to specify the font
417 @samp{8x16} for the menu-bar items, write this:
420 Emacs.pane.menubar.*.fontList: 8x16
424 This also specifies the resource value for submenus.
426 Each item in a submenu in the menu bar also has its own name for X
427 resources; for example, the @samp{File} submenu has an item named
428 @samp{Save (current buffer)}. A resource specification for a submenu
429 item looks like this:
432 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
436 For example, here's how to specify the font for the @samp{Save (current
440 Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
444 For an item in a second-level submenu, such as @samp{Complete Word}
445 under @samp{Spell Checking} under @samp{Tools}, the resource fits this
449 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
456 Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value}
460 (This should be one long line.)
462 It's impossible to specify a resource for all the menu-bar items
463 without also specifying it for the submenus as well. So if you want the
464 submenu items to look different from the menu bar itself, you must ask
465 for that in two steps. First, specify the resource for all of them;
466 then, override the value for submenus alone. Here is an example:
469 Emacs.pane.menubar.*.fontList: 8x16
470 Emacs.pane.menubar.popup_*.fontList: 8x16
474 For LessTif pop-up menus, use @samp{menu*} instead of
475 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
476 the pop-up menu items, write this:
479 Emacs.menu*.fontList: 8x16
483 For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}:
486 Emacs.dialog*.fontList: 8x16
487 Emacs.dialog*.foreground: hotpink
490 To specify resources for the LessTif file-selection box, use
491 @samp{fsb*}, like this:
494 Emacs.fsb*.fontList: 8x16
500 Here is a list of the specific resources for LessTif menu bars and
505 The color to show in an armed button.
514 Amount of space to leave around the item, within the border.
516 The width of the border around the menu item, on all sides.
517 @item shadowThickness
518 The width of the border shadow.
519 @item bottomShadowColor
520 The color for the border shadow, on the bottom and the right.
522 The color for the border shadow, on the top and the left.
527 @appendixsec GTK resources
528 @cindex GTK resources and customization
529 @cindex resource files for GTK
530 @cindex @file{~/.gtkrc-2.0} file
531 @cindex @file{~/.emacs.d/gtkrc} file
533 If the Emacs installed at your site was built to use the GTK widget set,
534 then the menu bar, scroll bar and the dialogs can be customized with
535 the standard GTK @file{~/.gtkrc-2.0} file or with the Emacs specific
536 @file{~/.emacs.d/gtkrc} file; note that these files are only for
537 customizing specific GTK widget features. To customize Emacs font,
538 background, faces etc., use the normal X resources, see @ref{Resources}.
540 In these files you first defines a style and then how to apply that style
541 to widgets (@pxref{GTK widget names}). Here is an example of how to
542 change the font for Emacs menus:
548 font_name = "helvetica bold 14" # This is a Pango font name
551 widget "*emacs-menuitem*" style "menufont"
555 There are some things you can set without using any style or widget name,
556 which affect GTK as a whole. Most of these are poorly documented, but can
557 be found in the `Properties' section of the documentation page for
558 @code{GtkSetting}, in the GTK document references below.
560 One property of interest is @code{gtk-font-name} which sets the default
561 font for GTK; you must use Pango font names (@pxref{GTK styles}). A
562 @file{~/.gtkrc-2.0} file that just sets a default font looks like this:
565 gtk-font-name = "courier 12"
569 If GTK at your site is installed under @var{prefix},
570 the resource file syntax is fully described in the GTK API
572 @file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html}.
573 @var{prefix} is usually @file{/usr} or @file{/usr/local}.
574 You can find the same document online at
575 @uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
579 * GTK widget names:: How widgets in GTK are named in general.
580 * GTK names in Emacs:: GTK widget names in Emacs.
581 * GTK styles:: What can be customized in a GTK widget.
585 @node GTK widget names
586 @appendixsubsec GTK widget names
587 @cindex GTK widget names
589 Widgets are specified by widget class or by widget name.
590 The widget class is the type of the widget, for example @code{GtkMenuBar}.
591 The widget name is the name given to a specific widget within a program.
592 A widget always have a class but it is not mandatory to give a name to
593 a widget. Absolute names are sequences of widget names or
594 widget classes, corresponding to hierarchies of widgets embedded within
595 other widgets. For example, if a @code{GtkWindow} contains a @code{GtkVBox}
596 which in turn contains a @code{GtkMenuBar}, the absolute class name
597 is @code{GtkWindow.GtkVBox.GtkMenuBar}.
600 If the widgets are named ``top'', ``box'' and ``menubar'', the absolute
601 widget name is @code{top.box.menubar},
603 When assigning a style to a widget, you can use the absolute class
604 name or the absolute widget name.
605 There are two commands: @code{widget_class} will assign a style to
606 widgets, matching only against the absolute class name.
607 The command @code{widget} will match the absolute widget name,
608 but if there is no name for a widget in the hierarchy, the class is matched.
609 These commands require the absolute name and the style name to be
610 within double quotes. These commands are written at the top level in a
611 @file{~/.gtkrc-2.0} file, like this:
616 font_name = "helvetica bold 14"
619 widget "top.box.menubar" style "menufont"
620 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont"
624 Matching of absolute names is done with shell ``glob'' syntax, that is
625 @samp{*} matches zero or more characters and @samp{?} matches one character.
626 So the following would assign @code{base_style} to all widgets:
629 widget "*" style "base_style"
632 Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar}
633 and the corresponding absolute widget name @code{top.box.menubar},
634 the following all assign @code{my_style} to the menu bar:
637 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
638 widget_class "GtkWindow.*.GtkMenuBar" style "my_style"
639 widget_class "*GtkMenuBar" style "my_style"
640 widget "top.box.menubar" style "my_style"
641 widget "*box*menubar" style "my_style"
642 widget "*menubar" style "my_style"
643 widget "*menu*" style "my_style"
646 @node GTK names in Emacs
647 @appendixsubsec GTK names in Emacs
648 @cindex GTK widget names
649 @cindex GTK widget classes
651 In Emacs the top level widget for a frame is a @code{GtkWindow} that
652 contains a @code{GtkVBox}. The @code{GtkVBox} contains the
653 @code{GtkMenuBar} and a @code{GtkFixed} widget.
654 The vertical scroll bars, @code{GtkVScrollbar},
655 are contained in the @code{GtkFixed} widget.
656 The text you write in Emacs is drawn in the @code{GtkFixed} widget.
658 Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a
659 @code{GtkFileSelection} widget.
662 To set a style for the menu bar using the absolute class name, use:
665 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
669 For the scroll bar, the absolute class name is:
673 "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar"
678 The names for the emacs widgets, and their classes, are:
680 @multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
681 @item @code{emacs-filedialog}
682 @tab @code{GtkFileSelection}
683 @item @code{emacs-dialog}
684 @tab @code{GtkDialog}
686 @tab @code{GtkWindow}
691 @item @code{verticalScrollbar}
692 @tab @code{GtkVScrollbar}
693 @item @code{emacs-toolbar}
694 @tab @code{GtkToolbar}
696 @tab @code{GtkMenuBar}
697 @item @code{emacs-menuitem}
698 @tab anything in menus
702 Thus, for Emacs you can write the two examples above as:
705 widget "Emacs.pane.menubar" style "my_style"
706 widget "Emacs.pane.emacs.verticalScrollbar" style "my_style"
709 GTK absolute names are quite strange when it comes to menus
710 and dialogs. The names do not start with @samp{Emacs}, as they are
711 free-standing windows and not contained (in the GTK sense) by the
712 Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this:
715 widget "*emacs-dialog*" style "my_dialog_style"
716 widget "*emacs-filedialog* style "my_file_style"
717 widget "*emacs-menuitem* style "my_menu_style"
720 An alternative is to put customization into @file{~/.emacs.d/gtkrc}.
721 This file is only read by Emacs, so anything in @file{~/.emacs.d/gtkrc}
722 affects Emacs but leaves other applications unaffected.
723 For example, the drop down menu in the file dialog can not
724 be customized by any absolute widget name, only by an absolute
725 class name. This is so because the widgets in the drop down menu does not
726 have names and the menu is not contained in the Emacs GtkWindow.
727 To have all menus in Emacs look the same, use this in @file{~/.emacs.d/gtkrc}:
730 widget_class "*Menu*" style "my_menu_style"
734 @appendixsubsec GTK styles
737 In a GTK style you specify the appearance widgets shall have. You
738 can specify foreground and background color, background pixmap and font.
739 The edit widget (where you edit the text) in Emacs is a GTK widget,
740 but trying to specify a style for the edit widget will have no effect.
741 This is so that Emacs compiled for GTK is compatible with Emacs compiled
742 for other X toolkits. The settings for foreground, background and font
743 for the edit widget is taken from the X resources; @pxref{Resources}.
744 Here is an example of two style declarations, ``default'' and ``ruler'':
748 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
752 font_name = "helvetica 12"
754 bg[NORMAL] = @{ 0.83, 0.80, 0.73 @}
755 bg[SELECTED] = @{ 0.0, 0.55, 0.55 @}
756 bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @}
757 bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @}
758 bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @}
761 fg[SELECTED] = @{ 0.9, 0.9, 0.9 @}
763 fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @}
765 base[INSENSITIVE] = "#777766"
766 text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @}
768 bg_pixmap[NORMAL] = "background.xpm"
769 bg_pixmap[INSENSITIVE] = "background.xpm"
770 bg_pixmap[ACTIVE] = "background.xpm"
771 bg_pixmap[PRELIGHT] = "<none>"
775 style "ruler" = "default"
777 font_name = "helvetica 8"
782 The style ``ruler'' inherits from ``default''. This way you can build
783 on existing styles. The syntax for fonts and colors is described below.
785 As this example shows, it is possible to specify several values
786 for foreground and background depending on which state the widget has.
787 The possible states are
790 This is the default state for widgets.
792 This is the state for a widget that is ready to do something. It is
793 also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"}
794 sets the scroll bar trough to red. Buttons that have been pressed but
795 not released yet (``armed'') are in this state.
797 This is the state when widgets that can be manipulated have the mouse
798 pointer over them. For example when the mouse is over the thumb in the
799 scroll bar or over a menu item. When the mouse is over a button that
800 is not pressed, the button is in this state.
802 This is the state when some data has been selected by the user. It can
803 be selected text or items selected in a list.
804 There is no place in Emacs where this setting has any effect.
806 This is the state for widgets that are visible, but they can not be
807 manipulated like they normally can. For example, buttons that can't be
808 pressed and menu items that can't be selected.
809 Text for menu items that are not available can be set to yellow with
810 @code{fg[INSENSITIVE] = "yellow"}.
813 Here are the things that can go in a style declaration:
816 @item bg[@var{state}] = @var{color}
817 This is the background color widgets use. This background is not used for
818 editable text, use @code{base} for that.
820 @item base[@var{state}] = @var{color}
821 This is the background color for editable text.
822 In Emacs, this color is used for the background of the text fields in the
825 @item bg_pixmap[@var{state}] = "@var{pixmap}"
826 You can specify a pixmap to be used instead of the background color.
827 @var{pixmap} is a file name. GTK can use a number of file formats,
828 including XPM, XBM, GIF, JPEG and PNG. If you want a widget to use the same
829 pixmap as its parent, use @samp{<parent>}. If you don't want any
830 pixmap use @samp{<none>}. Using @samp{<none>} can be useful
831 if your style inherits a style that does specify a pixmap.
833 GTK looks for the pixmap in directories specified in @code{pixmap_path}.
834 It is not possible to refer to a file by its absolute path name.
835 @code{pixmap_path} is a colon-separated list of directories within double
836 quotes, specified at the top level in a @file{gtkrc} file (i.e. not inside
837 a style definition; see example above):
840 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
843 @item fg[@var{state}] = @var{color}
844 This is the foreground color widgets use. This is the color
845 of text in menus and buttons. It is also the color for the arrows in the
846 scroll bar. For editable text, use @code{text}.
848 @item text[@var{state}] = @var{color}
849 This is the color for editable text. In Emacs, this color is used for the
850 text fields in the file dialog.
852 @item font_name = "@var{font}"
853 This is the font a widget shall use. @var{font} is a Pango font name,
854 for example ``Sans Italic 10'', ``Helvetica Bold 12'', ``Courier 14'',
855 ``Times 18''. See below for exact syntax. The names are case insensitive.
858 Colors are specified in three ways, a name, a hexadecimal form or
862 A color name is written within double quotes, for example @code{"red"}.
865 A hexadecimal form is written within double quotes. There are four forms,
866 @code{#rrrrggggbbbb}, @code{#rrrgggbbb},
867 @code{#rrggbb}, or @code{#rgb}. In each of these r, g and b are hex digits.
870 An RGB triplet looks like @code{@{ r, g, b @}}, where r, g and b are either
871 integers in the range 0-65535 or floats in the range 0.0-1.0.
873 Pango font names have the form ``@var{family-list} @var{style-options}
875 @cindex Pango font name
877 @var{family-list} is a comma separated list of font families optionally
878 terminated by a comma. This way you can specify several families and the
879 first one found will be used. @var{family} corresponds to the second part in
880 an X font name, for example in
883 -adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1
887 the family name is ``times''.
890 @var{style-options} is a whitespace separated list of words where each word
891 is a style, variant, weight, or stretch. The default value for all of
892 these is @code{normal}.
895 A `style' corresponds to the fourth part of an X font name. In X font
896 names it is the character ``r'', ``i'' or ``o''; in Pango font names the
897 corresponding values are @code{normal}, @code{italic}, or @code{oblique}.
900 A `variant' is either @code{normal} or @code{small-caps}.
901 Small caps is a font with the lower case characters replaced by
902 smaller variants of the capital characters.
905 Weight describes the ``boldness'' of a font. It corresponds to the third
906 part of an X font name. It is one of @code{ultra-light}, @code{light},
907 @code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}.
910 Stretch gives the width of the font relative to other designs within a
911 family. It corresponds to the fifth part of an X font name. It is one of
912 @code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
913 @code{semi-condensed}, @code{normal}, @code{semi-expanded},
914 @code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
917 @var{size} is a decimal number that describes the font size in points.