X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/5bc6ddff00c50acf546530ef0e08a27140614d27..14beddf4711854b01d400f36166dc71eb39435bb:/doc/emacs/xresources.texi diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi index 9173de21a5..1482bbd046 100644 --- a/doc/emacs/xresources.texi +++ b/doc/emacs/xresources.texi @@ -1,6 +1,6 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +@c Copyright (C) 1987, 1993-1995, 1997, 2001-2011 +@c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node X Resources, Antinews, Emacs Invocation, Top @appendix X Options and Resources @@ -8,8 +8,7 @@ You can customize some X-related aspects of Emacs behavior using X resources, as is usual for programs that use X. On MS-Windows, you can customize some of the same aspects using the system registry. -@xref{MS-Windows Registry}. Likewise, Emacs on MacOS Carbon emulates X -resources using the Preferences system. @xref{Mac Environment Variables}. +@xref{MS-Windows Registry}. When Emacs is built using an ``X toolkit'', such as Lucid or LessTif, you need to use X resources to customize the appearance of @@ -46,63 +45,49 @@ manual. Programs running under the X Window System organize their user options under a hierarchy of classes and resources. You can specify -default values for these options in your X resources file, usually -named @file{~/.Xdefaults} or @file{~/.Xresources}. -If changes in @file{~/.Xdefaults} do not -take effect, it is because your X server stores its own list of -resources; to update them, use the shell command @command{xrdb}---for -instance, @samp{xrdb ~/.Xdefaults}. - - Each line in the file specifies a value for one option or for a -collection of related options, for one program or for several programs -(optionally even for all programs). +default values for these options in your @dfn{X resource file}, +usually named @file{~/.Xdefaults} or @file{~/.Xresources}. Changes in +this file do not take effect immediately, because the X server stores +its own list of resources; to update it, use the command +@command{xrdb}---for instance, @samp{xrdb ~/.Xdefaults}. @cindex Registry (MS-Windows) - MS-Windows systems do not support @file{~/.Xdefaults} files, so -instead Emacs compiled for Windows looks for X resources in the -Windows Registry, first under the key -@samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} and then under the key + (MS-Windows systems do not support X resource files; on Windows, +Emacs looks for X resources in the Windows Registry, first under the +key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} and then under the key @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}. The menu and scroll bars are native widgets on MS-Windows, so they are only customizable via the system-wide settings in the Display Control Panel. You can -also set resources using the @samp{-xrm} command line option (see -below.) +also set resources using the @samp{-xrm} command line option, as +explained below.) -@iftex - Applications such as Emacs look for resources with specific names -and their particular meanings. Case distinctions are significant in -these names. Each resource specification in @file{~/.Xdefaults} -states the name of the program and the name of the resource. For -Emacs, the program name is @samp{Emacs}. It looks like this: - -@example -Emacs.borderWidth: 2 -@end example -@end iftex -@ifnottex - Programs define named resources with particular meanings. They also -define how to group resources into named classes. For instance, in -Emacs, the @samp{internalBorder} resource controls the width of the -internal border, and the @samp{borderWidth} resource controls the width -of the external border. Both of these resources are part of the -@samp{BorderWidth} class. Case distinctions are significant in these -names. - - Every resource definition is associated with a specific program -name---the name of the executable file that you ran. For Emacs, that -is normally @samp{emacs}. To specify a definition for all instances -of Emacs, regardless of their names, use @samp{Emacs}. - - In @file{~/.Xdefaults}, you can specify a value for a single resource -on one line, like this: + Each line in the X resource file specifies a value for one option or +for a collection of related options. Each resource specification +consists of a @dfn{program name} and a @dfn{resource name}. Case +distinctions are significant in each of these names. Here is an +example: @example emacs.borderWidth: 2 @end example -@noindent -Or you can use a class name to specify the same value for all resources -in that class. Here's an example: +@ifnottex + The program name is the name of the executable file to which the +resource applies. For Emacs, this is normally @samp{emacs}. To +specify a definition that applies to all instances of Emacs, +regardless of the name of the Emacs executable, use @samp{Emacs}. + + The resource name is the name of a program setting. For instance, +Emacs recognizes a @samp{borderWidth} resource that controls the width +of the external border for graphical frames. + + Resources are grouped into named classes. For instance, the +@samp{BorderWidth} class contains both the @samp{borderWidth} resource +(which we just described), as well as the @samp{internalBorder} +resource, which controls the width of the internal border for +graphical frames. Instead of using a resource name, you can use a +class name to specify the same value for all resources in that class. +Here's an example: @example emacs.BorderWidth: 2 @@ -110,9 +95,10 @@ emacs.BorderWidth: 2 If you specify a value for a class, it becomes the default for all resources in that class. You can specify values for individual -resources as well; these override the class value, for those particular -resources. Thus, this example specifies 2 as the default width for all -borders, but overrides this value with 4 for the external border: +resources as well; these override the class value, for those +particular resources. The following example specifies 2 as the +default width for all borders, but overrides this value with 4 for the +external border: @example emacs.BorderWidth: 2 @@ -121,69 +107,56 @@ emacs.borderWidth: 4 @end ifnottex The order in which the lines appear in the file does not matter. -Also, command-line options always override the X resources file. +One way to experiment with the effect of different resource settings +is to use the @code{editres} program. See the @code{editres} man page +for more details. + + Emacs does not process X resources at all if you set the variable +@code{inhibit-x-resources} to a non-@code{nil} value, or if you +specify the @samp{-Q} (or @samp{--quick}) command-line argument +(@pxref{Initial Options}). (The @samp{-Q} argument automatically sets +@code{inhibit-x-resources} to @code{t}.) @ifnottex -Here is a list of X command-line options and their corresponding -resource names. + In addition, you can use the following command-line options to +override the X resources file: @table @samp @item -name @var{name} @opindex --name @itemx --name=@var{name} @cindex resource name, command-line argument -Use @var{name} as the resource name (and the title) for the initial -Emacs frame. This option does not affect subsequent frames, but Lisp -programs can specify frame names when they create frames. +This option sets the program name of the initial Emacs frame to +@var{name}. It also sets the title of the initial frame to +@var{name}. This option does not affect subsequent frames. If you don't specify this option, the default is to use the Emacs -executable's name as the resource name. +executable's name as the program name. + +For consistency, @samp{-name} also specifies the name to use for other +resource values that do not belong to any particular frame. + +The resources that name Emacs invocations also belong to a class, +named @samp{Emacs}. If you write @samp{Emacs} instead of +@samp{emacs}, the resource applies to all frames in all Emacs jobs, +regardless of frame titles and regardless of the name of the +executable file. @item -xrm @var{resource-values} @opindex --xrm @itemx --xrm=@var{resource-values} @cindex resource values, command-line argument -Specify X resource values for this Emacs job (see below). +This option specifies X resource values for the present Emacs job. + +@var{resource-values} should have the same format that you would use +inside a file of X resources. To include multiple resource +specifications in @var{resource-values}, put a newline between them, +just as you would in a file. You can also use @samp{#include +"@var{filename}"} to include a file full of resource specifications. +Resource values specified with @samp{-xrm} take precedence over all +other resource specifications. @end table - - For consistency, @samp{-name} also specifies the name to use for -other resource values that do not belong to any particular frame. - - The resources that name Emacs invocations also belong to a class; its -name is @samp{Emacs}. If you write @samp{Emacs} instead of -@samp{emacs}, the resource applies to all frames in all Emacs jobs, -regardless of frame titles and regardless of the name of the executable -file. Here is an example: - -@example -Emacs.BorderWidth: 2 -Emacs.borderWidth: 4 -@end example - - You can specify a string of additional resource values for Emacs to -use with the command line option @samp{-xrm @var{resources}}. The text -@var{resources} should have the same format that you would use inside a file -of X resources. To include multiple resource specifications in -@var{resources}, put a newline between them, just as you would in a file. -You can also use @samp{#include "@var{filename}"} to include a file full -of resource specifications. Resource values specified with @samp{-xrm} -take precedence over all other resource specifications. - - One way to experiment with the effect of different resource settings -is to use the @code{editres} program. Select @samp{Get Tree} from the @end ifnottex -@iftex - You can experiment with the effect of different resource settings -with the @code{editres} program. Select @samp{Get Tree} from the -@end iftex -@samp{Commands} menu, then click on an Emacs frame. This will display -a tree showing the structure of X toolkit widgets used in an Emacs -frame. Select one of them, such as @samp{menubar}, then select -@samp{Show Resource Box} from the @samp{Commands} menu. This displays -a list of all the meaningful X resources for that widget, and allows -you to edit them. Changes take effect when you click on the -@samp{Apply} button. (See the @code{editres} man page for more -details.) @node Table of Resources @appendixsec Table of X Resources for Emacs @@ -220,7 +193,17 @@ Specifies whether to make the cursor blink. The default is @samp{on}. Use @end ifnottex @item @code{font} (class @code{Font}) -Font name (or fontset name, @pxref{Fontsets}) for @code{default} font. +Font name for the @code{default} font. @xref{Fonts}. You can also +specify a fontset name (@pxref{Fontsets}). + +@item @code{fontBackend} (class @code{FontBackend}) +The backend(s) to use for drawing fonts; if multiple backends are +specified, they must be comma-delimited and given in order of +precedence. On X, for instance, the value @samp{x,xft} tells Emacs to +draw fonts using the X core font driver, falling back on the Xft font +driver if that fails. Normally, you can leave this resource unset, in +which case Emacs tries using all font backends available on your +graphical device. @item @code{foreground} (class @code{Foreground}) Color name for text. @@ -238,8 +221,8 @@ all frames. @ifnottex @item @code{fullscreen} (class @code{Fullscreen}) The desired fullscreen size. The value can be one of @code{fullboth}, -@code{fullwidth} or @code{fullheight}, which correspond to -the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh} +@code{maximized}, @code{fullwidth} or @code{fullheight}, which correspond to +the command-line options @samp{-fs}, @samp{-mm}, @samp{-fw}, and @samp{-fh} (@pxref{Window Size X}). Note that this applies to the initial frame only. @@ -324,12 +307,14 @@ Name to display in the title bar of the initial Emacs frame. @item @code{toolBar} (class @code{ToolBar}) @cindex tool bar Number of lines to reserve for the tool bar. A zero value suppresses -the tool bar. If the value is non-zero and -@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size -will be changed automatically so that all tool bar items are visible. +the tool bar. For the Emacs tool bar (i.e. not Gtk+), if the value is +non-zero and @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's +size will be changed automatically so that all tool bar items are visible. If the value of @code{auto-resize-tool-bars} is @code{grow-only}, the tool bar expands automatically, but does not contract automatically. To contract the tool bar, you must redraw the frame by entering @kbd{C-l}. +For the Gtk+ tool bar, any non-zero value means on and +@code{auto-resize-tool-bars} has no effect. @item @code{useXIM} (class @code{UseXIM}) @cindex XIM @@ -414,8 +399,9 @@ Italic flag for face @var{face}---instead of @code{attributeSlant}. @end table @node Lucid Resources -@appendixsec Lucid Menu X Resources +@appendixsec Lucid Menu And Dialog X Resources @cindex Menu X Resources (Lucid widgets) +@cindex Dialog X Resources (Lucid widgets) @cindex Lucid Widget X Resources @ifnottex @@ -430,7 +416,7 @@ Emacs.pane.menubar.@var{resource}: @var{value} @end example @noindent -For example, to specify the font @samp{8x16} for the menu-bar items, +For example, to specify the font @samp{Courier-12} for the menu-bar items, write this: @end ifnottex @iftex @@ -438,32 +424,37 @@ write this: with the Lucid menu widgets, then the menu bar is a separate widget and has its own resources. The resource specifications start with @samp{Emacs.pane.menubar}---for instance, to specify the font -@samp{8x16} for the menu-bar items, write this: +@samp{Courier-12} for the menu-bar items, write this: @end iftex @example -Emacs.pane.menubar.font: 8x16 +Emacs.pane.menubar.faceName: Courier-12 @end example @noindent -Resources for @emph{non-menubar} toolkit pop-up menus have -@samp{menu*} instead of @samp{pane.menubar}. For example, to specify -the font @samp{8x16} for the pop-up menu items, write this: +To specify a font, use fontconfig font names as values to the @code{faceName} +resource. + +If Emacs is not built with the Xft library, Lucid menus and dialogs +can only display old style fonts. If Emacs is built with Xft and you +prefer the old fonts, you have to specify @samp{none} to +@code{faceName}: @example -Emacs.menu*.font: 8x16 +Emacs.pane.menubar.faceName: none +Emacs.pane.dialog.faceName: none @end example @noindent -For dialog boxes, use @samp{dialog*}: +To specify a non-Xft font, use @code{font}. For example: @example -Emacs.dialog*.font: 8x16 +Emacs.pane.menubar.font: lucidasanstypewriter-10 @end example @noindent -The Lucid menus can display multilingual text in your locale. For -more information about fontsets see the man page for +The Lucid menus can display multilingual text in your locale with old style +fonts. For more information about fontsets see the man page for @code{XCreateFontSet}. To enable multilingual menu text you specify a @code{fontSet} resource instead of the font resource. If both @code{font} and @code{fontSet} resources are specified, the @@ -476,6 +467,22 @@ for both the popup and menu bar menus, write this: Emacs*menu*fontSet: -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,* @end example +@noindent +Resources for @emph{non-menubar} toolkit pop-up menus have +@samp{menu*} instead of @samp{pane.menubar}. For example, to specify +the font @samp{8x16} for the pop-up menu items, write this: + +@example +Emacs.menu*.font: 8x16 +@end example + +@noindent +For dialog boxes, use @samp{dialog*}: + +@example +Emacs.dialog*.faceName: Sans-12 +@end example + @noindent The @samp{*menu*} as a wildcard matches @samp{pane.menubar} and @samp{menu@dots{}}. @@ -488,6 +495,8 @@ approach should work on both kinds of systems. Here is a list of the specific resources for menu bars and pop-up menus: @table @code +@item faceName +Xft font for menu item text. @item font Font for menu item text. @item fontSet @@ -1210,7 +1219,3 @@ family. It corresponds to the fifth part of an X font name. It is one of @noindent @var{size} is a decimal number that describes the font size in points. @end ifnottex - -@ignore - arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f -@end ignore