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.
146 @node Table of Resources
147 @appendixsec Table of X Resources for Emacs
149 This table lists the resource names that designate options for
150 Emacs, not counting those for the appearance of the menu bar, each
151 with the class that it belongs to:
154 @item @code{background} (class @code{Background})
155 Background color name.
157 @item @code{bitmapIcon} (class @code{BitmapIcon})
158 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
159 manager choose an icon if @samp{off}.
161 @item @code{borderColor} (class @code{BorderColor})
162 Color name for the external border.
164 @item @code{borderWidth} (class @code{BorderWidth})
165 Width in pixels of the external border.
167 @item @code{cursorColor} (class @code{Foreground})
168 Color name for text cursor (point).
170 @item @code{font} (class @code{Font})
171 Font name for text (or fontset name, @pxref{Fontsets}).
173 @item @code{foreground} (class @code{Foreground})
176 @item @code{geometry} (class @code{Geometry})
177 Window size and position. Be careful not to specify this resource as
178 @samp{emacs*geometry}, because that may affect individual menus as well
179 as the Emacs frame itself.
181 If this resource specifies a position, that position applies only to the
182 initial Emacs frame (or, in the case of a resource for a specific frame
183 name, only that frame). However, the size, if specified here, applies to
186 @item @code{fullscreen} (class @code{Fullscreen})
187 The desired fullscreen size. The value can be one of @code{fullboth},
188 @code{fullwidth} or @code{fullheight}, which correspond to
189 the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh}
190 (@pxref{Window Size X}).
192 Note that this applies to all frames created, not just the initial
195 @item @code{iconName} (class @code{Title})
196 Name to display in the icon.
198 @item @code{internalBorder} (class @code{BorderWidth})
199 Width in pixels of the internal border.
201 @item @code{lineSpacing} (class @code{LineSpacing})
204 Additional space (@dfn{leading}) between lines, in pixels.
206 @item @code{menuBar} (class @code{MenuBar})
208 Give frames menu bars if @samp{on}; don't have menu bars if
209 @samp{off}. @xref{Lucid Resources}, and @ref{LessTif Resources}, for
210 how to control the appearance of the menu bar if you have one.
212 @item @code{minibuffer} (class @code{Minibuffer})
213 If @samp{none}, don't make a minibuffer in this frame.
214 It will use a separate minibuffer frame instead.
216 @item @code{paneFont} (class @code{Font})
217 @cindex font for menus
218 Font name for menu pane titles, in non-toolkit versions of Emacs.
220 @item @code{pointerColor} (class @code{Foreground})
221 Color of the mouse cursor.
223 @item @code{privateColormap} (class @code{PrivateColormap})
224 If @samp{on}, use a private color map, in the case where the ``default
225 visual'' of class PseudoColor and Emacs is using it.
227 @item @code{reverseVideo} (class @code{ReverseVideo})
228 Switch foreground and background default colors if @samp{on}, use colors as
229 specified if @samp{off}.
231 @item @code{screenGamma} (class @code{ScreenGamma})
232 @cindex gamma correction
233 Gamma correction for colors, equivalent to the frame parameter
236 @item @code{selectionFont} (class @code{SelectionFont})
237 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
238 toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
241 @item @code{selectionTimeout} (class @code{SelectionTimeout})
242 Number of milliseconds to wait for a selection reply.
243 If the selection owner doesn't reply in this time, we give up.
244 A value of 0 means wait as long as necessary.
246 @item @code{synchronous} (class @code{Synchronous})
247 @cindex debugging X problems
248 @cindex synchronous X mode
249 Run Emacs in synchronous mode if @samp{on}. Synchronous mode is
250 useful for debugging X problems.
252 @item @code{title} (class @code{Title})
253 Name to display in the title bar of the initial Emacs frame.
255 @item @code{toolBar} (class @code{ToolBar})
257 Number of lines to reserve for the tool bar. A zero value suppresses
258 the tool bar. If the value is non-zero and
259 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
260 will be changed automatically so that all tool bar items are visible.
262 @item @code{useXIM} (class @code{UseXIM})
264 @cindex X input methods
265 @cindex input methods, X
266 Turn off use of X input methods (XIM) if @samp{false} or @samp{off}.
267 This is only relevant if your Emacs is actually built with XIM
268 support. It is potentially useful to turn off XIM for efficiency,
269 especially slow X client/server links.
271 @item @code{verticalScrollBars} (class @code{ScrollBars})
272 Give frames scroll bars if @samp{on}; don't have scroll bars if
277 @appendixsec X Resources for Faces
279 You can also use resources to customize the appearance of particular
280 faces (@pxref{Faces}):
283 @item @var{face}.attributeFont
284 Font for face @var{face}.
285 @item @var{face}.attributeForeground
286 Foreground color for face @var{face}.
287 @item @var{face}.attributeBackground
288 Background color for face @var{face}.
289 @item @var{face}.attributeUnderline
290 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
292 @item @var{face}.attributeFamily
293 Font family for face @var{face}.
294 @item @var{face}.attributeWidth
295 Relative proportional width of the font to use for face @var{face}.
296 It should be one of @code{ultra-condensed}, @code{extra-condensed},
297 @code{condensed}, @code{semi-condensed}, @code{normal},
298 @code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or
299 @code{ultra-expanded}.
300 @item @var{face}.attributeHeight
301 Height of the font to use for face @var{face}: either an integer
302 specifying the height in units of 1/10@dmn{pt}, or a floating point
303 number that specifies a scale factor to scale the underlying face's
304 default font, or a function to be called with the default height which
305 will return a new height.
306 @item @var{face}.attributeWeight
307 A weight to use for the face @var{face}. It must be one of
308 @code{ultra-bold}, @code{extra-bold}, @code{bold},
309 @code{semi-bold}, @code{normal}, @code{semi-light}, @code{light},
310 @code{extra-light}, @code{ultra-light}.
311 @item @var{face}.attributeSlant
312 The slant to use for the font of face @var{face}. It must be one of
313 @code{italic}, @code{oblique}, @code{normal},
314 @code{reverse-italic}, or @code{reverse-oblique}.
315 @item @var{face}.attributeStrikeThrough
316 Whether the face @var{face} should be drawn with a line striking
317 through the characters.
318 @item @var{face}.attributeOverline
319 Whether the characters in the face @var{face} should be overlined.
320 @item @var{face}.attributeBox
321 Whether to draw a box around the characters in face @var{face}.
322 @item @var{face}.attributeInverse
323 Whether to display the characters in face @var{face} in inverse
325 @item @var{face}.attributeStipple
326 The name of a pixmap data file to use for the stipple pattern, or
327 @code{false} to not use stipple for the face @var{face}.
328 @item @var{face}.attributeBackgroundPixmap
329 The background pixmap for the face @var{face}. Should be a name of a
330 pixmap file or @code{false}.
331 @item @var{face}.attributeBold
332 Whether to draw the characters in the face @var{face} as bold.
333 @item @var{face}.attributeItalic
334 Whether to draw the characters in the face @var{face} as italic.
337 @node Lucid Resources
338 @appendixsec Lucid Menu X Resources
339 @cindex Menu X Resources (Lucid widgets)
340 @cindex Lucid Widget X Resources
342 If the Emacs installed at your site was built to use the X toolkit
343 with the Lucid menu widgets, then the menu bar is a separate widget and
344 has its own resources. The resource names contain @samp{pane.menubar}
345 (following, as always, the name of the Emacs invocation, or @samp{Emacs},
346 which stands for all Emacs invocations). Specify them like this:
349 Emacs.pane.menubar.@var{resource}: @var{value}
353 For example, to specify the font @samp{8x16} for the menu-bar items,
357 Emacs.pane.menubar.font: 8x16
361 Resources for @emph{non-menubar} toolkit pop-up menus have
362 @samp{menu*}, in like fashion. For example, to specify the font
363 @samp{8x16} for the pop-up menu items, write this:
366 Emacs.menu*.font: 8x16
370 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
373 Emacs.dialog*.font: 8x16
377 Experience shows that on some systems you may need to add
378 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
379 some other systems, you must not add @samp{shell.}.
381 Here is a list of the specific resources for menu bars and pop-up menus:
385 Font for menu item text.
387 Color of the foreground.
389 Color of the background.
390 @item buttonForeground
391 In the menu bar, the color of the foreground for a selected item.
392 @item horizontalSpacing
393 Horizontal spacing in pixels between items. Default is 3.
394 @item verticalSpacing
395 Vertical spacing in pixels between items. Default is 1.
397 Horizontal spacing between the arrow (which indicates a submenu) and
398 the associated text. Default is 10.
399 @item shadowThickness
400 Thickness of shadow line around the widget.
402 The margin of the menu bar, in characters. The default of 4 makes the
403 menu bar appear like the LessTif/Motif one.
406 @node LessTif Resources
407 @appendixsec LessTif Menu X Resources
408 @cindex Menu X Resources (LessTif widgets)
409 @cindex LessTif Widget X Resources
411 If the Emacs installed at your site was built to use the X toolkit
412 with the LessTif or Motif widgets, then the menu bar, the dialog
413 boxes, the pop-up menus, and the file-selection box are separate
414 widgets and have their own resources.
416 The resource names for the menu bar contain @samp{pane.menubar}
417 (following, as always, the name of the Emacs invocation, or
418 @samp{Emacs}, which stands for all Emacs invocations). Specify them
422 Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
425 Each individual string in the menu bar is a subwidget; the subwidget's
426 name is the same as the menu item string. For example, the word
427 @samp{File} in the menu bar is part of a subwidget named
428 @samp{emacs.pane.menubar.File}. Most likely, you want to specify the
429 same resources for the whole menu bar. To do this, use @samp{*} instead
430 of a specific subwidget name. For example, to specify the font
431 @samp{8x16} for the menu-bar items, write this:
434 Emacs.pane.menubar.*.fontList: 8x16
438 This also specifies the resource value for submenus.
440 Each item in a submenu in the menu bar also has its own name for X
441 resources; for example, the @samp{File} submenu has an item named
442 @samp{Save (current buffer)}. A resource specification for a submenu
443 item looks like this:
446 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
450 For example, here's how to specify the font for the @samp{Save (current
454 Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
458 For an item in a second-level submenu, such as @samp{Complete Word}
459 under @samp{Spell Checking} under @samp{Tools}, the resource fits this
463 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
470 Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value}
474 (This should be one long line.)
476 It's impossible to specify a resource for all the menu-bar items
477 without also specifying it for the submenus as well. So if you want the
478 submenu items to look different from the menu bar itself, you must ask
479 for that in two steps. First, specify the resource for all of them;
480 then, override the value for submenus alone. Here is an example:
483 Emacs.pane.menubar.*.fontList: 8x16
484 Emacs.pane.menubar.popup_*.fontList: 8x16
488 For LessTif pop-up menus, use @samp{menu*} instead of
489 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
490 the pop-up menu items, write this:
493 Emacs.menu*.fontList: 8x16
497 For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}:
500 Emacs.dialog*.fontList: 8x16
501 Emacs.dialog*.foreground: hotpink
504 To specify resources for the LessTif file-selection box, use
505 @samp{fsb*}, like this:
508 Emacs.fsb*.fontList: 8x16
514 Here is a list of the specific resources for LessTif menu bars and
519 The color to show in an armed button.
528 Amount of space to leave around the item, within the border.
530 The width of the border around the menu item, on all sides.
531 @item shadowThickness
532 The width of the border shadow.
533 @item bottomShadowColor
534 The color for the border shadow, on the bottom and the right.
536 The color for the border shadow, on the top and the left.
541 @appendixsec GTK resources
542 @cindex GTK resources and customization
543 @cindex resource files for GTK
544 @cindex @file{~/.gtkrc-2.0} file
545 @cindex @file{~/.emacs.d/gtkrc} file
547 If the Emacs installed at your site was built to use the GTK widget set,
548 then the menu bar, scroll bar and the dialogs can be customized with
549 the standard GTK @file{~/.gtkrc-2.0} file or with the Emacs specific
550 @file{~/.emacs.d/gtkrc} file; note that these files are only for
551 customizing specific GTK widget features. To customize Emacs font,
552 background, faces etc., use the normal X resources, see @ref{Resources}.
554 In these files you first defines a style and then how to apply that style
555 to widgets (@pxref{GTK widget names}). Here is an example of how to
556 change the font for Emacs menus:
562 font_name = "helvetica bold 14" # This is a Pango font name
565 widget "*emacs-menuitem*" style "menufont"
569 There are some things you can set without using any style or widget name,
570 which affect GTK as a whole. Most of these are poorly documented, but can
571 be found in the `Properties' section of the documentation page for
572 @code{GtkSetting}, in the GTK document references below.
574 One property of interest is @code{gtk-font-name} which sets the default
575 font for GTK; you must use Pango font names (@pxref{GTK styles}). A
576 @file{~/.gtkrc-2.0} file that just sets a default font looks like this:
579 gtk-font-name = "courier 12"
583 If GTK at your site is installed under @var{prefix},
584 the resource file syntax is fully described in the GTK API
586 @file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html}.
587 @var{prefix} is usually @file{/usr} or @file{/usr/local}.
588 You can find the same document online at
589 @uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
593 * GTK widget names:: How widgets in GTK are named in general.
594 * GTK names in Emacs:: GTK widget names in Emacs.
595 * GTK styles:: What can be customized in a GTK widget.
599 @node GTK widget names
600 @appendixsubsec GTK widget names
601 @cindex GTK widget names
603 Widgets are specified by widget class or by widget name.
604 The widget class is the type of the widget, for example @code{GtkMenuBar}.
605 The widget name is the name given to a specific widget within a program.
606 A widget always have a class but it is not mandatory to give a name to
607 a widget. Absolute names are sequences of widget names or
608 widget classes, corresponding to hierarchies of widgets embedded within
609 other widgets. For example, if a @code{GtkWindow} contains a @code{GtkVBox}
610 which in turn contains a @code{GtkMenuBar}, the absolute class name
611 is @code{GtkWindow.GtkVBox.GtkMenuBar}.
614 If the widgets are named ``top'', ``box'' and ``menubar'', the absolute
615 widget name is @code{top.box.menubar},
617 When assigning a style to a widget, you can use the absolute class
618 name or the absolute widget name.
619 There are two commands: @code{widget_class} will assign a style to
620 widgets, matching only against the absolute class name.
621 The command @code{widget} will match the absolute widget name,
622 but if there is no name for a widget in the hierarchy, the class is matched.
623 These commands require the absolute name and the style name to be
624 within double quotes. These commands are written at the top level in a
625 @file{~/.gtkrc-2.0} file, like this:
630 font_name = "helvetica bold 14"
633 widget "top.box.menubar" style "menufont"
634 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont"
638 Matching of absolute names is done with shell ``glob'' syntax, that is
639 @samp{*} matches zero or more characters and @samp{?} matches one character.
640 So the following would assign @code{base_style} to all widgets:
643 widget "*" style "base_style"
646 Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar}
647 and the corresponding absolute widget name @code{top.box.menubar},
648 the following all assign @code{my_style} to the menu bar:
651 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
652 widget_class "GtkWindow.*.GtkMenuBar" style "my_style"
653 widget_class "*GtkMenuBar" style "my_style"
654 widget "top.box.menubar" style "my_style"
655 widget "*box*menubar" style "my_style"
656 widget "*menubar" style "my_style"
657 widget "*menu*" style "my_style"
660 @node GTK names in Emacs
661 @appendixsubsec GTK names in Emacs
662 @cindex GTK widget names
663 @cindex GTK widget classes
665 In Emacs the top level widget for a frame is a @code{GtkWindow} that
666 contains a @code{GtkVBox}. The @code{GtkVBox} contains the
667 @code{GtkMenuBar} and a @code{GtkFixed} widget.
668 The vertical scroll bars, @code{GtkVScrollbar},
669 are contained in the @code{GtkFixed} widget.
670 The text you write in Emacs is drawn in the @code{GtkFixed} widget.
672 Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a
673 @code{GtkFileSelection} widget.
676 To set a style for the menu bar using the absolute class name, use:
679 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
683 For the scroll bar, the absolute class name is:
687 "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar"
692 The names for the emacs widgets, and their classes, are:
694 @multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
695 @item @code{emacs-filedialog}
696 @tab @code{GtkFileSelection}
697 @item @code{emacs-dialog}
698 @tab @code{GtkDialog}
700 @tab @code{GtkWindow}
705 @item @code{verticalScrollbar}
706 @tab @code{GtkVScrollbar}
707 @item @code{emacs-toolbar}
708 @tab @code{GtkToolbar}
710 @tab @code{GtkMenuBar}
711 @item @code{emacs-menuitem}
712 @tab anything in menus
716 Thus, for Emacs you can write the two examples above as:
719 widget "Emacs.pane.menubar" style "my_style"
720 widget "Emacs.pane.emacs.verticalScrollbar" style "my_style"
723 GTK absolute names are quite strange when it comes to menus
724 and dialogs. The names do not start with @samp{Emacs}, as they are
725 free-standing windows and not contained (in the GTK sense) by the
726 Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this:
729 widget "*emacs-dialog*" style "my_dialog_style"
730 widget "*emacs-filedialog* style "my_file_style"
731 widget "*emacs-menuitem* style "my_menu_style"
734 An alternative is to put customization into @file{~/.emacs.d/gtkrc}.
735 This file is only read by Emacs, so anything in @file{~/.emacs.d/gtkrc}
736 affects Emacs but leaves other applications unaffected.
737 For example, the drop down menu in the file dialog can not
738 be customized by any absolute widget name, only by an absolute
739 class name. This is so because the widgets in the drop down menu does not
740 have names and the menu is not contained in the Emacs GtkWindow.
741 To have all menus in Emacs look the same, use this in @file{~/.emacs.d/gtkrc}:
744 widget_class "*Menu*" style "my_menu_style"
748 @appendixsubsec GTK styles
751 In a GTK style you specify the appearance widgets shall have. You
752 can specify foreground and background color, background pixmap and font.
753 The edit widget (where you edit the text) in Emacs is a GTK widget,
754 but trying to specify a style for the edit widget will have no effect.
755 This is so that Emacs compiled for GTK is compatible with Emacs compiled
756 for other X toolkits. The settings for foreground, background and font
757 for the edit widget is taken from the X resources; @pxref{Resources}.
758 Here is an example of two style declarations, ``default'' and ``ruler'':
762 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
766 font_name = "helvetica 12"
768 bg[NORMAL] = @{ 0.83, 0.80, 0.73 @}
769 bg[SELECTED] = @{ 0.0, 0.55, 0.55 @}
770 bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @}
771 bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @}
772 bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @}
775 fg[SELECTED] = @{ 0.9, 0.9, 0.9 @}
777 fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @}
779 base[INSENSITIVE] = "#777766"
780 text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @}
782 bg_pixmap[NORMAL] = "background.xpm"
783 bg_pixmap[INSENSITIVE] = "background.xpm"
784 bg_pixmap[ACTIVE] = "background.xpm"
785 bg_pixmap[PRELIGHT] = "<none>"
789 style "ruler" = "default"
791 font_name = "helvetica 8"
796 The style ``ruler'' inherits from ``default''. This way you can build
797 on existing styles. The syntax for fonts and colors is described below.
799 As this example shows, it is possible to specify several values
800 for foreground and background depending on which state the widget has.
801 The possible states are
804 This is the default state for widgets.
806 This is the state for a widget that is ready to do something. It is
807 also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"}
808 sets the scroll bar trough to red. Buttons that have been pressed but
809 not released yet (``armed'') are in this state.
811 This is the state when widgets that can be manipulated have the mouse
812 pointer over them. For example when the mouse is over the thumb in the
813 scroll bar or over a menu item. When the mouse is over a button that
814 is not pressed, the button is in this state.
816 This is the state when some data has been selected by the user. It can
817 be selected text or items selected in a list.
818 There is no place in Emacs where this setting has any effect.
820 This is the state for widgets that are visible, but they can not be
821 manipulated like they normally can. For example, buttons that can't be
822 pressed and menu items that can't be selected.
823 Text for menu items that are not available can be set to yellow with
824 @code{fg[INSENSITIVE] = "yellow"}.
827 Here are the things that can go in a style declaration:
830 @item bg[@var{state}] = @var{color}
831 This is the background color widgets use. This background is not used for
832 editable text, use @code{base} for that.
834 @item base[@var{state}] = @var{color}
835 This is the background color for editable text.
836 In Emacs, this color is used for the background of the text fields in the
839 @item bg_pixmap[@var{state}] = "@var{pixmap}"
840 You can specify a pixmap to be used instead of the background color.
841 @var{pixmap} is a file name. GTK can use a number of file formats,
842 including XPM, XBM, GIF, JPEG and PNG. If you want a widget to use the same
843 pixmap as its parent, use @samp{<parent>}. If you don't want any
844 pixmap use @samp{<none>}. Using @samp{<none>} can be useful
845 if your style inherits a style that does specify a pixmap.
847 GTK looks for the pixmap in directories specified in @code{pixmap_path}.
848 It is not possible to refer to a file by its absolute path name.
849 @code{pixmap_path} is a colon-separated list of directories within double
850 quotes, specified at the top level in a @file{gtkrc} file (i.e. not inside
851 a style definition; see example above):
854 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
857 @item fg[@var{state}] = @var{color}
858 This is the foreground color widgets use. This is the color
859 of text in menus and buttons. It is also the color for the arrows in the
860 scroll bar. For editable text, use @code{text}.
862 @item text[@var{state}] = @var{color}
863 This is the color for editable text. In Emacs, this color is used for the
864 text fields in the file dialog.
866 @item font_name = "@var{font}"
867 This is the font a widget shall use. @var{font} is a Pango font name,
868 for example ``Sans Italic 10'', ``Helvetica Bold 12'', ``Courier 14'',
869 ``Times 18''. See below for exact syntax. The names are case insensitive.
872 Colors are specified in three ways, a name, a hexadecimal form or
876 A color name is written within double quotes, for example @code{"red"}.
879 A hexadecimal form is written within double quotes. There are four forms,
880 @code{#rrrrggggbbbb}, @code{#rrrgggbbb},
881 @code{#rrggbb}, or @code{#rgb}. In each of these r, g and b are hex digits.
884 An RGB triplet looks like @code{@{ r, g, b @}}, where r, g and b are either
885 integers in the range 0-65535 or floats in the range 0.0-1.0.
887 Pango font names have the form ``@var{family-list} @var{style-options}
889 @cindex Pango font name
891 @var{family-list} is a comma separated list of font families optionally
892 terminated by a comma. This way you can specify several families and the
893 first one found will be used. @var{family} corresponds to the second part in
894 an X font name, for example in
897 -adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1
901 the family name is ``times''.
904 @var{style-options} is a whitespace separated list of words where each word
905 is a style, variant, weight, or stretch. The default value for all of
906 these is @code{normal}.
909 A `style' corresponds to the fourth part of an X font name. In X font
910 names it is the character ``r'', ``i'' or ``o''; in Pango font names the
911 corresponding values are @code{normal}, @code{italic}, or @code{oblique}.
914 A `variant' is either @code{normal} or @code{small-caps}.
915 Small caps is a font with the lower case characters replaced by
916 smaller variants of the capital characters.
919 Weight describes the ``boldness'' of a font. It corresponds to the third
920 part of an X font name. It is one of @code{ultra-light}, @code{light},
921 @code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}.
924 Stretch gives the width of the font relative to other designs within a
925 family. It corresponds to the fifth part of an X font name. It is one of
926 @code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
927 @code{semi-condensed}, @code{normal}, @code{semi-expanded},
928 @code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
931 @var{size} is a decimal number that describes the font size in points.