X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/06415cad5da16edd6f1515a618e7b111745d5c39..fbc284f6f71ec837ca5d6b518235fc70413361dd:/man/xresources.texi diff --git a/man/xresources.texi b/man/xresources.texi index a854730055..ce6709ad76 100644 --- a/man/xresources.texi +++ b/man/xresources.texi @@ -1,471 +1,61 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1987,93,94,95,1997,2001 Free Software Foundation, Inc. +@c Copyright (C) 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, +@c 2004, 2005, 2006 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. -@node X Resources, Antinews, Command Arguments, Top -@appendix X Resources - - Some aspects of Emacs behavior can be customized using X resources, -as is usual for programs that use X. X resources are the only way to -customize tool-bar menus, pop-up menus and tooltip windows, since they -are implemented by general-purpose libraries that always handle -customization this way. This appendix describes the X resources -that Emacs recognizes and what they mean. - - One way to experiment with the effect of different resource settings -is to use the @code{editres} program. Select @samp{Get Tree} from the -@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 and allows you to edit them. -Changes take effect immediately if you click on the @samp{Apply} button. +@node X Resources, Antinews, Emacs Invocation, Top +@appendix X Options and Resources + + 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, the Mac Carbon port emulates X +resources using the Preferences system. @xref{Mac Environment Variables}. + + When Emacs is built using an `X toolkit', such as Lucid or LessTif, +you need to use X resources to customize the appearance of the +widgets, including the menu-bar, scroll-bar, and dialog boxes. This +is because the libraries that implement these don't provide for +customization through Emacs. GTK+ widgets use a separate system of +`GTK resources', which we will also describe. @menu -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors X:: Choosing colors, under X. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Resources X:: Advanced use of classes and resources, under X. +* Resources:: Using X resources with Emacs (in general). +* Table of Resources:: Table of specific X resources that affect Emacs. +* Face Resources:: X resources for customizing faces. * Lucid Resources:: X resources for Lucid menus. * LessTif Resources:: X resources for LessTif and Motif menus. +* GTK resources:: Resources for GTK widgets. @end menu -@node Display X -@appendixsec Specifying the Display Name -@cindex display name (X Window System) -@cindex @env{DISPLAY} environment variable - - The environment variable @env{DISPLAY} tells all X clients, including -Emacs, where to display their windows. Its value is set by default -in ordinary circumstances, when you start an X server and run jobs -locally. Occasionally you may need to specify the display yourself; for -example, if you do a remote login and want to run a client program -remotely, displaying on your local screen. - - With Emacs, the main reason people change the default display is to -let them log into another system, run Emacs on that system, but have the -window displayed at their local terminal. You might need to log in -to another system because the files you want to edit are there, or -because the Emacs executable file you want to run is there. - - The syntax of the @env{DISPLAY} environment variable is -@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the -host name of the X Window System server machine, @var{display} is an -arbitrarily-assigned number that distinguishes your server (X terminal) -from other servers on the same machine, and @var{screen} is a -rarely-used field that allows an X server to control multiple terminal -screens. The period and the @var{screen} field are optional. If -included, @var{screen} is usually zero. - - For example, if your host is named @samp{glasperle} and your server is -the first (or perhaps the only) server listed in the configuration, your -@env{DISPLAY} is @samp{glasperle:0.0}. - - You can specify the display name explicitly when you run Emacs, either -by changing the @env{DISPLAY} variable, or with the option @samp{-d -@var{display}} or @samp{--display=@var{display}}. Here is an example: - -@smallexample -emacs --display=glasperle:0 & -@end smallexample - - You can inhibit the direct use of the window system and GUI with the -@samp{-nw} option. It tells Emacs to display using ordinary ASCII on -its controlling terminal. This is also an initial option. - - Sometimes, security arrangements prevent a program on a remote system -from displaying on your local system. In this case, trying to run Emacs -produces messages like this: - -@smallexample -Xlib: connection to "glasperle:0.0" refused by server -@end smallexample - -@noindent -You might be able to overcome this problem by using the @code{xhost} -command on the local system to give permission for access from your -remote machine. - -@node Font X -@appendixsec Font Specification Options -@cindex font name (X Window System) - - By default, Emacs displays text in the font named @samp{9x15}, which -makes each character nine pixels wide and fifteen pixels high. You can -specify a different font on your command line through the option -@samp{-fn @var{name}} (or @samp{--font}, which is an alias for -@samp{-fn}). - -@table @samp -@item -fn @var{name} -@opindex -fn -@itemx --font=@var{name} -@opindex --font -@cindex specify default font from the command line -Use font @var{name} as the default font. -@end table - - Under X, each font has a long name which consists of eleven words or -numbers, separated by dashes. Some fonts also have shorter -nicknames---@samp{9x15} is such a nickname. You can use either kind of -name. You can use wildcard patterns for the font name; then Emacs lets -X choose one of the fonts that match the pattern. Here is an example, -which happens to specify the font whose nickname is @samp{6x13}: - -@smallexample -emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" & -@end smallexample - -@noindent -You can also specify the font in your @file{.Xdefaults} file: - -@smallexample -emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 -@end smallexample - - A long font name has the following form: - -@smallexample --@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} -@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset} -@end smallexample - -@table @var -@item maker -This is the name of the font manufacturer. -@item family -This is the name of the font family---for example, @samp{courier}. -@item weight -This is normally @samp{bold}, @samp{medium} or @samp{light}. Other -words may appear here in some font names. -@item slant -This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique), -@samp{ri} (reverse italic), or @samp{ot} (other). -@item widthtype -This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed} -or @samp{normal}. Other words may appear here in some font names. -@item style -This is an optional additional style name. Usually it is empty---most -long font names have two hyphens in a row at this point. -@item pixels -This is the font height, in pixels. -@item height -This is the font height on the screen, measured in tenths of a printer's -point---approximately 1/720 of an inch. In other words, it is the point -size of the font, times ten. For a given vertical resolution, -@var{height} and @var{pixels} are proportional; therefore, it is common -to specify just one of them and use @samp{*} for the other. -@item horiz -This is the horizontal resolution, in pixels per inch, of the screen for -which the font is intended. -@item vert -This is the vertical resolution, in pixels per inch, of the screen for -which the font is intended. Normally the resolution of the fonts on -your system is the right value for your screen; therefore, you normally -specify @samp{*} for this and @var{horiz}. -@item spacing -This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} -(character cell). -@item width -This is the average character width, in pixels, multiplied by ten. -@item charset -This is the character set that the font depicts. -Normally you should use @samp{iso8859-1}. -@end table - -@cindex listing system fonts - You will probably want to use a fixed-width default font---that is, -a font in which all characters have the same width. Any font with -@samp{m} or @samp{c} in the @var{spacing} field of the long name is a -fixed-width font. Here's how to use the @code{xlsfonts} program to -list all the fixed-width fonts available on your system: - -@example -xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' -@end example - -@noindent -To see what a particular font looks like, use the @code{xfd} command. -For example: - -@example -xfd -fn 6x13 -@end example - -@noindent -displays the entire font @samp{6x13}. - - While running Emacs, you can set the font of the current frame -(@pxref{Frame Parameters}) or for a specific kind of text -(@pxref{Faces}). - -@node Colors X -@appendixsec Window Color Options -@cindex color of window -@cindex text colors, from command line - -@findex list-colors-display -@cindex available colors - On a color display, you can specify which color to use for various -parts of the Emacs display. To find out what colors are available on -your system, type @kbd{M-x list-colors-display}, or press -@kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu. -If you do not specify colors, on windowed displays the default for the -background is white and the default for all other colors is black. On a -monochrome display, the foreground is black, the background is white, -and the border is gray if the display supports that. On terminals, the -background is usually black and the foreground is white. - - Here is a list of the command-line options for specifying colors: - -@table @samp -@item -fg @var{color} -@opindex -fg -@itemx --foreground-color=@var{color} -@opindex --foreground-color -@cindex foreground color, command-line argument -Specify the foreground color. @var{color} should be a standard color -name, or a numeric specification of the color's red, green, and blue -components as in @samp{#4682B4} or @samp{RGB:46/82/B4}. -@item -bg @var{color} -@opindex -bg -@itemx --background-color=@var{color} -@opindex --background-color -@cindex background color, command-line argument -Specify the background color. -@item -bd @var{color} -@opindex -bd -@itemx --border-color=@var{color} -@opindex --border-color -@cindex border color, command-line argument -Specify the color of the border of the X window. -@item -cr @var{color} -@opindex -cr -@itemx --cursor-color=@var{color} -@opindex --cursor-color -@cindex cursor color, command-line argument -Specify the color of the Emacs cursor which indicates where point is. -@item -ms @var{color} -@opindex -ms -@itemx --mouse-color=@var{color} -@opindex --mouse-color -@cindex mouse pointer color, command-line argument -Specify the color for the mouse cursor when the mouse is in the Emacs window. -@item -r -@opindex -r -@itemx -rv -@opindex -rv -@itemx --reverse-video -@opindex --reverse-video -@cindex reverse video, command-line argument -Reverse video---swap the foreground and background colors. -@end table - - For example, to use a coral mouse cursor and a slate blue text cursor, -enter: - -@example -emacs -ms coral -cr 'slate blue' & -@end example - - You can reverse the foreground and background colors through the -@samp{-rv} option or with the X resource @samp{reverseVideo}. - - The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on -text-only terminals as well as on window systems. - -@node Window Size X -@appendixsec Options for Window Geometry -@cindex geometry of Emacs window -@cindex position and size of Emacs frame -@cindex width and height of Emacs frame - - The @samp{--geometry} option controls the size and position of the -initial Emacs frame. Here is the format for specifying the window -geometry: - -@table @samp -@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex -g -Specify window size @var{width} and @var{height} (measured in character -columns and lines), and positions @var{xoffset} and @var{yoffset} -(measured in pixels). - -@item --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex --geometry -This is another way of writing the same thing. -@end table - -@noindent -@code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus -sign before @var{xoffset} means it is the distance from the left side of -the screen; a minus sign means it counts from the right side. A plus -sign before @var{yoffset} means it is the distance from the top of the -screen, and a minus sign there indicates the distance from the bottom. -The values @var{xoffset} and @var{yoffset} may themselves be positive or -negative, but that doesn't change their meaning, only their direction. - - Emacs uses the same units as @code{xterm} does to interpret the geometry. -The @var{width} and @var{height} are measured in characters, so a large font -creates a larger frame than a small font. (If you specify a proportional -font, Emacs uses its maximum bounds width as the width unit.) The -@var{xoffset} and @var{yoffset} are measured in pixels. - - Since the mode line and the echo area occupy the last 2 lines of the -frame, the height of the initial text window is 2 less than the height -specified in your geometry. In non-X-toolkit versions of Emacs, the -menu bar also takes one line of the specified number. But in the X -toolkit version, the menu bar is additional and does not count against -the specified height. The tool bar, if present, is also additional. - - You do not have to specify all of the fields in the geometry -specification. - - If you omit both @var{xoffset} and @var{yoffset}, the window manager -decides where to put the Emacs frame, possibly by letting you place -it with the mouse. For example, @samp{164x55} specifies a window 164 -columns wide, enough for two ordinary width windows side by side, and 55 -lines tall. - - The default width for Emacs is 80 characters and the default height is -40 lines. You can omit either the width or the height or both. If -you start the geometry with an integer, Emacs interprets it as the -width. If you start with an @samp{x} followed by an integer, Emacs -interprets it as the height. Thus, @samp{81} specifies just the width; -@samp{x45} specifies just the height. - - If you start with @samp{+} or @samp{-}, that introduces an offset, -which means both sizes are omitted. Thus, @samp{-3} specifies the -@var{xoffset} only. (If you give just one offset, it is always -@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the -@var{yoffset}, placing the frame near the bottom left of the screen. - - You can specify a default for any or all of the fields in -@file{.Xdefaults} file, and then override selected fields with a -@samp{--geometry} option. - -@node Borders X -@appendixsec Internal and External Borders -@cindex borders (X Window System) - - An Emacs frame has an internal border and an external border. The -internal border is an extra strip of the background color around the -text portion of the frame. Emacs itself draws the internal border. -The external border is added by the window manager outside the frame; -depending on the window manager you use, it may contain various boxes -you can click on to move or iconify the window. - -@table @samp -@item -ib @var{width} -@opindex -ib -@itemx --internal-border=@var{width} -@opindex --internal-border -@cindex border width, command-line argument -Specify @var{width} as the width of the internal border, in pixels. - -@item -bw @var{width} -@opindex -bw -@itemx --border-width=@var{width} -@opindex --border-width -Specify @var{width} as the width of the main border, in pixels. -@end table - - When you specify the size of the frame, that does not count the -borders. The frame's position is measured from the outside edge of the -external border. - - Use the @samp{-ib @var{n}} option to specify an internal border -@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to -specify the width of the external border (though the window manager may -not pay attention to what you specify). The default width of the -external border is 2. - -@node Title X -@appendixsec Frame Titles - - An Emacs frame may or may not have a specified title. The frame -title, if specified, appears in window decorations and icons as the -name of the frame. If an Emacs frame has no specified title, the -default title has the form @samp{@var{invocation-name}@@@var{machine}} -(if there is only one frame) or the selected window's buffer name (if -there is more than one frame). - - You can specify a title for the initial Emacs frame with a command -line option: - -@table @samp -@item -title @var{title} -@opindex --title -@itemx --title=@var{title} -@itemx -T @var{title} -@opindex -T -@cindex frame title, command-line argument -Specify @var{title} as the title for the initial Emacs frame. -@end table - - The @samp{--name} option (@pxref{Resources X}) also specifies the title -for the initial Emacs frame. - -@node Icons X -@appendixsec Icons -@cindex icons (X Window System) - - Most window managers allow the user to ``iconify'' a frame, removing -it from sight, and leaving a small, distinctive ``icon'' window in its -place. Clicking on the icon window makes the frame itself appear again. -If you have many clients running at once, you can avoid cluttering up -the screen by iconifying most of the clients. - -@table @samp -@item -i -@opindex -i -@itemx --icon-type -@opindex --icon-type -@cindex Emacs icon, a gnu -Use a picture of a gnu as the Emacs icon. - -@item -iconic -@opindex --iconic -@itemx --iconic -@cindex start iconified, command-line argument -Start Emacs in iconified state. -@end table - - The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon -window containing a picture of the GNU gnu. If omitted, Emacs lets the -window manager choose what sort of icon to use---usually just a small -rectangle containing the frame's title. - - The @samp{-iconic} option tells Emacs to begin running as an icon, -rather than showing a frame right away. In this situation, the icon -is the only indication that Emacs has started; the text frame doesn't -appear until you deiconify it. - -@node Resources X +@node Resources @appendixsec X Resources @cindex resources - -@cindex X resources, @file{~/.Xdefaults} file - 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}. +@cindex X resources +@cindex @file{~/.Xdefaults} file +@cindex @file{~/.Xresources} file + + 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). @cindex Registry (MS-Windows) -@cindex @file{.Xdefaults} file, and MS-Windows MS-Windows systems don't support @file{~/.Xdefaults} files, but Emacs compiled for Windows looks for X resources in the Windows -Registry, under the keys @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} -and @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}. +Registry, 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 scrollbars 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.) Programs define named resources with particular meanings. They also define how to group resources into named classes. For instance, in @@ -475,6 +65,11 @@ 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: @@ -503,11 +98,8 @@ emacs.borderWidth: 4 The order in which the lines appear in the file does not matter. Also, command-line options always override the X resources file. - - The string @samp{emacs} in the examples above is also a resource -name. It actually represents the name of the executable file that you -invoke to run Emacs. If Emacs is installed under a different name, it -looks for resources under that name instead of @samp{emacs}. +Here is a list of X command-line options and their corresponding +resource names. @table @samp @item -name @var{name} @@ -551,8 +143,22 @@ 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. - The following table lists the resource names that designate options -for Emacs, each with the class that it belongs to: + One way to experiment with the effect of different resource settings +is to use the @code{editres} program. Select @samp{Get Tree} from the +@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 and allows you to edit them. +Changes take effect immediately if 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 + + This table lists the resource names that designate options for +Emacs, not counting those for the appearance of the menu bar, each +with the class that it belongs to: @table @asis @item @code{background} (class @code{Background}) @@ -571,6 +177,10 @@ Width in pixels of the external border. @item @code{cursorColor} (class @code{Foreground}) Color name for text cursor (point). +@item @code{cursorBlink} (class @code{CursorBlink}) +Specifies whether to make the cursor blink. The default is @samp{on}. Use +@samp{off} or @samp{false} to turn cursor blinking off. + @item @code{font} (class @code{Font}) Font name for text (or fontset name, @pxref{Fontsets}). @@ -587,6 +197,15 @@ initial Emacs frame (or, in the case of a resource for a specific frame name, only that frame). However, the size, if specified here, applies to all frames. +@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} +(@pxref{Window Size X}). + +Note that this applies to all frames created, not just the initial +one. + @item @code{iconName} (class @code{Title}) Name to display in the icon. @@ -599,13 +218,10 @@ Width in pixels of the internal border. Additional space (@dfn{leading}) between lines, in pixels. @item @code{menuBar} (class @code{MenuBar}) -Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}. - -@item @code{toolBar} (class @code{ToolBar}) -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. +@cindex menu bar +Give frames menu bars if @samp{on}; don't have menu bars if +@samp{off}. @xref{Lucid Resources}, and @ref{LessTif Resources}, for +how to control the appearance of the menu bar if you have one. @item @code{minibuffer} (class @code{Minibuffer}) If @samp{none}, don't make a minibuffer in this frame. @@ -618,11 +234,9 @@ Font name for menu pane titles, in non-toolkit versions of Emacs. @item @code{pointerColor} (class @code{Foreground}) Color of the mouse cursor. -@ignore @item @code{privateColormap} (class @code{PrivateColormap}) If @samp{on}, use a private color map, in the case where the ``default visual'' of class PseudoColor and Emacs is using it. -@end ignore @item @code{reverseVideo} (class @code{ReverseVideo}) Switch foreground and background default colors if @samp{on}, use colors as @@ -633,11 +247,16 @@ specified if @samp{off}. Gamma correction for colors, equivalent to the frame parameter @code{screen-gamma}. -@item @code{selectionFont} (class @code{Font}) +@item @code{selectionFont} (class @code{SelectionFont}) Font name for pop-up menu items, in non-toolkit versions of Emacs. (For toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif Resources}.) +@item @code{selectionTimeout} (class @code{SelectionTimeout}) +Number of milliseconds to wait for a selection reply. +If the selection owner doesn't reply in this time, we give up. +A value of 0 means wait as long as necessary. + @item @code{synchronous} (class @code{Synchronous}) @cindex debugging X problems @cindex synchronous X mode @@ -647,17 +266,45 @@ useful for debugging X problems. @item @code{title} (class @code{Title}) 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. + +@item @code{useXIM} (class @code{UseXIM}) +@cindex XIM +@cindex X input methods +@cindex input methods, X +Turn off use of X input methods (XIM) if @samp{false} or @samp{off}. +This is only relevant if your Emacs is actually built with XIM +support. It is potentially useful to turn off XIM for efficiency, +especially slow X client/server links. + @item @code{verticalScrollBars} (class @code{ScrollBars}) Give frames scroll bars if @samp{on}; don't have scroll bars if @samp{off}. + +@item @code{visualClass} (class @code{VisualClass}) +Specify the ``visual'' that X should use. This tells X how to handle +colors. + +The value should start with one of @samp{TrueColor}, +@samp{PseudoColor}, @samp{DirectColor}, @samp{StaticColor}, +@samp{GrayScale}, and @samp{StaticGray}, followed by +@samp{-@var{depth}}, where @var{depth} is the number of color planes. +Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo} +program outputs information saying which ones. @end table - Here are resources for controlling the appearance of particular faces -(@pxref{Faces}): +@node Face Resources +@appendixsec X Resources for Faces + + You can use resources to customize the appearance of particular +faces (@pxref{Faces}): @table @code -@item @var{face}.attributeFont -Font for face @var{face}. @item @var{face}.attributeForeground Foreground color for face @var{face}. @item @var{face}.attributeBackground @@ -665,49 +312,45 @@ Background color for face @var{face}. @item @var{face}.attributeUnderline Underline flag for face @var{face}. Use @samp{on} or @samp{true} for yes. +@item @var{face}.attributeStrikeThrough +@itemx @var{face}.attributeOverline +@itemx @var{face}.attributeBox +@itemx @var{face}.attributeInverse +Likewise, for other boolean font attributes. +@item @var{face}.attributeStipple +The name of a pixmap data file to use for the stipple pattern, or +@code{false} to not use stipple for the face @var{face}. +@item @var{face}.attributeBackgroundPixmap +The background pixmap for the face @var{face}. Should be a name of a +pixmap file or @code{false}. +@item @var{face}.attributeFont +Font name (full XFD name or valid X abbreviation) for face @var{face}. +Instead of this, you can specify the font through separate attributes. +@end table + + Instead of using @code{attributeFont} to specify a font name, you can +select a font through these separate attributes: + +@table @code @item @var{face}.attributeFamily Font family for face @var{face}. -@item @var{face}.attributeWidth -Relative proportional width of the font to use for face @var{face}. -It should be one of @code{ultra-condensed}, @code{extra-condensed}, -@code{condensed}, @code{semi-condensed}, @code{normal}, -@code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or -@code{ultra-expanded}. @item @var{face}.attributeHeight Height of the font to use for face @var{face}: either an integer specifying the height in units of 1/10@dmn{pt}, or a floating point number that specifies a scale factor to scale the underlying face's default font, or a function to be called with the default height which will return a new height. -@item @var{face}.attributeWeight -A weight to use for the face @var{face}. It must be one of -@code{ultra-bold}, @code{extra-bold}, @code{bold}, -@code{semi-bold}, @code{normal}, @code{semi-light}, @code{light}, -@code{extra-light}, @code{ultra-light}. -@item @var{face}.attributeSlant -The slant to use for the font of face @var{face}. It must be one of -@code{italic}, @code{oblique}, @code{normal}, -@code{reverse-italic}, or @code{reverse-oblique}. -@item @var{face}.attributeStrikeThrough -Whether the face @var{face} should be drawn with a line striking -through the characters. -@item @var{face}.attributeOverline -Whether the characters in the face @var{face} should be overlined. -@item @var{face}.attributeBox -Whether to draw a box around the characters in face @var{face}. -@item @var{face}.attributeInverse -Whether to display the characters in face @var{face} in inverse -video. -@item @var{face}.attributeStipple -The name of a pixmap data file to use for the stipple pattern, or -@code{false} to not use stipple for the face @var{face}. -@item @var{face}.attributeBackgroundPixmap -The background pixmap for the face @var{face}. Should be a name of a -pixmap file or @code{false}. +@item @var{face}.attributeWidth +@itemx @var{face}.attributeWeight +@itemx @var{face}.attributeSlant +Each of these resources corresponds to a like-named font attribute, +and you write the resource value the same as the symbol you would use +for the font attribute value. @item @var{face}.attributeBold -Whether to draw the characters in the face @var{face} as bold. +Bold flag for face @var{face}---instead of @code{attributeWeight}. Use @samp{on} or @samp{true} for +yes. @item @var{face}.attributeItalic -Whether to draw the characters in the face @var{face} as italic. +Italic flag for face @var{face}---instead of @code{attributeSlant}. @end table @node Lucid Resources @@ -749,6 +392,19 @@ For dialog boxes, use @samp{dialog} instead of @samp{menu}: Emacs.dialog*.font: 8x16 @end example +@noindent +The Lucid menus can display multilingual text in your locale. For more +information about fontsets see the man page for XCreateFontSet. To enable +multilingual menu text you specify a fontSet resource instead of the font +resource. If both font and fontSet resources are specified, the fontSet +resource is used. To specify +@samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*} for both the popup and +menu bar menus, write this: + +@example +Emacs*fontSet: -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,* +@end example + @noindent Experience shows that on some systems you may need to add @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On @@ -759,6 +415,8 @@ some other systems, you must not add @samp{shell.}. @table @code @item font Font for menu item text. +@item fontSet +Fontset for menu item text. @item foreground Color of the foreground. @item background @@ -768,15 +426,22 @@ In the menu bar, the color of the foreground for a selected item. @item horizontalSpacing Horizontal spacing in pixels between items. Default is 3. @item verticalSpacing -Vertical spacing in pixels between items. Default is 1. +Vertical spacing in pixels between items. Default is 2. @item arrowSpacing Horizontal spacing between the arrow (which indicates a submenu) and the associated text. Default is 10. @item shadowThickness -Thickness of shadow line around the widget. +Thickness of shadow line around the widget. Default is 1. + +Also determines the thickness of shadow lines around other objects, +for instance 3D buttons and arrows. If you have the impression that +the arrows in the menus do not stand out clearly enough or that the +difference between ``in'' and ``out'' buttons is difficult to see, set +this to 2. If you have no problems with visibility, the default +probably looks better. The background color may also have some effect +on the contrast. @item margin -The margin of the menu bar, in characters. The default of 4 makes the -menu bar appear like the LessTif/Motif one. +The margin of the menu bar, in characters. Default is 1. @end table @node LessTif Resources @@ -848,7 +513,7 @@ Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value} @noindent (This should be one long line.) - + It's impossible to specify a resource for all the menu-bar items without also specifying it for the submenus as well. So if you want the submenu items to look different from the menu bar itself, you must ask @@ -911,3 +576,427 @@ The color for the border shadow, on the bottom and the right. @item topShadowColor The color for the border shadow, on the top and the left. @end table + + +@node GTK resources +@appendixsec GTK resources +@cindex GTK resources and customization +@cindex resource files for GTK +@cindex @file{~/.gtkrc-2.0} file +@cindex @file{~/.emacs.d/gtkrc} file + + If Emacs was built to use the GTK widget set, then the menu bar, +scroll bar and the dialogs are customized with the standard GTK +customization file, @file{~/.gtkrc-2.0}, or with the Emacs specific +file @file{~/.emacs.d/gtkrc}. We recommend that you use +@file{~/.emacs.d/gtkrc} for customizations, since @file{~/.gtkrc-2.0} +seems to be ignored when running GConf with GNOME. These files apply +only to GTK widget features. To customize Emacs font, background, +faces, etc., use the normal X resources (@pxref{Resources}). + + Some GTK themes override these mechanisms, which means that using +these mechanisms will not work to customize them. + + In these files you first define a style and say what it means; then +you specify to apply the style to various widget types (@pxref{GTK +widget names}). Here is an example of how to change the font for +Emacs menus: + +@smallexample +# @r{Define the style @samp{metafont}.} +style "menufont" +@{ + font_name = "helvetica bold 14" # This is a Pango font name +@} + +# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{metafont}.} +widget "*emacs-menuitem*" style "menufont" +@end smallexample + + Here is a more elaborate example, showing how to change the parts of +the scroll bar: + +@smallexample +style "scroll" +@{ + fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.} + bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.} + bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.} + bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.} +@} + +widget "*verticalScrollBar*" style "scroll" +@end smallexample + + There are also parameters that affect GTK as a whole. For example, +the property @code{gtk-font-name} sets the default font for GTK. You +must use Pango font names (@pxref{GTK styles}). A GTK resources file +that just sets a default font looks like this: + +@smallexample +gtk-font-name = "courier 12" +@end smallexample + + The GTK resources file is fully described in the GTK API document. +This can be found in +@file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html}, +where @file{prefix} is the directory in which the GTK libraries were +installed (usually @file{/usr} or @file{/usr/local}). You can also +find the document online, at +@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}. + +@menu +* GTK widget names:: How widgets in GTK are named in general. +* GTK Names in Emacs:: GTK widget names in Emacs. +* GTK styles:: What can be customized in a GTK widget. +@end menu + +@node GTK widget names +@appendixsubsec GTK widget names +@cindex GTK widget names + + A GTK widget is specified by its @dfn{widget class} and +@dfn{widget name}. The widget class is the type of the widget: for +example, @code{GtkMenuBar}. The widget name is the name given to a +specific widget. A widget always has a class, but need not have a +name. + + @dfn{Absolute names} are sequences of widget names or widget +classes, corresponding to hierarchies of widgets embedded within +other widgets. For example, if a @code{GtkWindow} named @code{top} +contains a @code{GtkVBox} named @code{box}, which in turn contains +a @code{GtkMenuBar} called @code{menubar}, the absolute class name +of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and +its absolute widget name is @code{top.box.menubar}. + + When assigning a style to a widget, you can use the absolute class +name or the absolute widget name. + + There are two commands to specify changes for widgets: + +@table @asis +@item @code{widget_class} +specifies a style for widgets based on the absolute class name. + +@item @code{widget} +specifies a style for widgets based on the absolute class name, +or just the class. +@end table + +@noindent +You must specify the class and the style in double-quotes, and put +these commands at the top level in the GTK customization file, like +this: + +@smallexample +style "menufont" +@{ + font_name = "helvetica bold 14" +@} + +widget "top.box.menubar" style "menufont" +widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont" +@end smallexample + + Matching of absolute names uses shell wildcard syntax: @samp{*} +matches zero or more characters and @samp{?} matches one character. +This example assigns @code{base_style} to all widgets: + +@smallexample +widget "*" style "base_style" +@end smallexample + + Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar} +and the corresponding absolute widget name @code{top.box.menubar}, all +these examples specify @code{my_style} for the menu bar: + +@smallexample +widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style" +widget_class "GtkWindow.*.GtkMenuBar" style "my_style" +widget_class "*GtkMenuBar" style "my_style" +widget "top.box.menubar" style "my_style" +widget "*box*menubar" style "my_style" +widget "*menubar" style "my_style" +widget "*menu*" style "my_style" +@end smallexample + +@node GTK Names in Emacs +@appendixsubsec GTK Widget Names in Emacs +@cindex GTK widget names +@cindex GTK widget classes + + In Emacs, the top level widget for a frame is a @code{GtkWindow} +that contains a @code{GtkVBox}. The @code{GtkVBox} contains the +@code{GtkMenuBar} and a @code{GtkFixed} widget. The vertical scroll +bars, @code{GtkVScrollbar}, are contained in the @code{GtkFixed} +widget. The text you write in Emacs is drawn in the @code{GtkFixed} +widget. + + Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a +@code{GtkFileSelection} widget. + +@noindent +To set a style for the menu bar using the absolute class name, use: + +@smallexample +widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style" +@end smallexample + +@noindent +For the scroll bar, the absolute class name is: + +@smallexample +widget_class + "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" + style "my_style" +@end smallexample + +@noindent +The names for the emacs widgets, and their classes, are: + +@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some} +@item @code{emacs-filedialog} +@tab @code{GtkFileSelection} +@item @code{emacs-dialog} +@tab @code{GtkDialog} +@item @code{Emacs} +@tab @code{GtkWindow} +@item @code{pane} +@tab @code{GtkVHbox} +@item @code{emacs} +@tab @code{GtkFixed} +@item @code{verticalScrollBar} +@tab @code{GtkVScrollbar} +@item @code{emacs-toolbar} +@tab @code{GtkToolbar} +@item @code{menubar} +@tab @code{GtkMenuBar} +@item @code{emacs-menuitem} +@tab anything in menus +@end multitable + +@noindent +Thus, for Emacs you can write the two examples above as: + +@smallexample +widget "Emacs.pane.menubar" style "my_style" +widget "Emacs.pane.emacs.verticalScrollBar" style "my_style" +@end smallexample + + GTK absolute names are quite strange when it comes to menus +and dialogs. The names do not start with @samp{Emacs}, as they are +free-standing windows and not contained (in the GTK sense) by the +Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this: + +@smallexample +widget "*emacs-dialog*" style "my_dialog_style" +widget "*emacs-filedialog* style "my_file_style" +widget "*emacs-menuitem* style "my_menu_style" +@end smallexample + + If you specify a customization in @file{~/.emacs.d/gtkrc}, then it +automatically applies only to Emacs, since other programs don't read +that file. For example, the drop down menu in the file dialog can not +be customized by any absolute widget name, only by an absolute class +name. This is because the widgets in the drop down menu do not +have names and the menu is not contained in the Emacs GtkWindow. To +have all menus in Emacs look the same, use this in +@file{~/.emacs.d/gtkrc}: + +@smallexample +widget_class "*Menu*" style "my_menu_style" +@end smallexample + +@node GTK styles +@appendixsubsec GTK styles +@cindex GTK styles + + In a GTK style you specify the appearance widgets shall have. You +can specify foreground and background color, background pixmap and +font. The edit widget (where you edit the text) in Emacs is a GTK +widget, but trying to specify a style for the edit widget will have no +effect. This is so that Emacs compiled for GTK is compatible with +Emacs compiled for other X toolkits. The settings for foreground, +background and font for the edit widget is taken from the X resources; +@pxref{Resources}. Here is an example of two style declarations, +@samp{default} and @samp{ruler}: + +@smallexample +pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" + +style "default" +@{ + font_name = "helvetica 12" + + bg[NORMAL] = @{ 0.83, 0.80, 0.73 @} + bg[SELECTED] = @{ 0.0, 0.55, 0.55 @} + bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @} + bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @} + bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @} + + fg[NORMAL] = "black" + fg[SELECTED] = @{ 0.9, 0.9, 0.9 @} + fg[ACTIVE] = "black" + fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @} + + base[INSENSITIVE] = "#777766" + text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @} + + bg_pixmap[NORMAL] = "background.xpm" + bg_pixmap[INSENSITIVE] = "background.xpm" + bg_pixmap[ACTIVE] = "background.xpm" + bg_pixmap[PRELIGHT] = "" + +@} + +style "ruler" = "default" +@{ + font_name = "helvetica 8" +@} + +@end smallexample + + The style @samp{ruler} inherits from @samp{default}. This way you can build +on existing styles. The syntax for fonts and colors is described below. + + As this example shows, it is possible to specify several values for +foreground and background depending on the widget's @dfn{state}. The +possible states are: + +@table @code +@item NORMAL +This is the default state for widgets. +@item ACTIVE +This is the state for a widget that is ready to do something. It is +also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"} +sets the scroll bar trough to red. Buttons that have been pressed but +not released yet (``armed'') are in this state. +@item PRELIGHT +This is the state for a widget that can be manipulated, when the mouse +pointer is over it---for example when the mouse is over the thumb in +the scroll bar or over a menu item. When the mouse is over a button +that is not pressed, the button is in this state. +@item SELECTED +This is the state for data that has been selected by the user. It can +be selected text or items selected in a list. This state is not used +in Emacs. +@item INSENSITIVE +This is the state for widgets that are visible, but they can not be +manipulated in the usual way---for example, buttons that can't be +pressed, and disabled menu items. To display disabled menu items in +yellow, use @code{fg[INSENSITIVE] = "yellow"}. +@end table + + Here are the things that can go in a style declaration: + +@table @code +@item bg[@var{state}] = @var{color} +This specifies the background color for the widget. Note that +editable text doesn't use @code{bg}; it uses @code{base} instead. + +@item base[@var{state}] = @var{color} +This specifies the background color for editable text. In Emacs, this +color is used for the background of the text fields in the file +dialog. + +@item bg_pixmap[@var{state}] = "@var{pixmap}" +This specifies an image background (instead of a background color). +@var{pixmap} should be the image file name. GTK can use a number of +image file formats, including XPM, XBM, GIF, JPEG and PNG. If you +want a widget to use the same image as its parent, use +@samp{}. If you don't want any image, use @samp{}. +@samp{} is the way to cancel a background image inherited from a +parent style. + +You can't specify the file by its absolute file name. GTK looks for +the pixmap file in directories specified in @code{pixmap_path}. +@code{pixmap_path} is a colon-separated list of directories within +double quotes, specified at the top level in a @file{gtkrc} file +(i.e. not inside a style definition; see example above): + +@smallexample +pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" +@end smallexample + +@item fg[@var{state}] = @var{color} +This specifies the foreground color for widgets to use. It is the +color of text in menus and buttons, and the color for the arrows in +the scroll bar. For editable text, use @code{text}. + +@item text[@var{state}] = @var{color} +This is the color for editable text. In Emacs, this color is used for the +text fields in the file dialog. + +@item font_name = "@var{font}" +This specifies the font for text in the widget. @var{font} is a +Pango font name, for example @samp{Sans Italic 10}, @samp{Helvetica +Bold 12}, @samp{Courier 14}, @samp{Times 18}. See below for exact +syntax. The names are case insensitive. +@end table + + There are three ways to specify a color: by name, in hexadecimal +form, and with an RGB triplet. + +@noindent +A color name is written within double quotes, for example @code{"red"}. + +@noindent +Hexadecimal form is the same as in X: +@code{#@var{rrrr}@var{gggg}@var{bbbb}}, where all three color specs +must have the same number of hex digits (1, 2, 3 or 4). + +@noindent +An RGB triplet looks like @code{@{ @var{r}, @var{g}, @var{b} @}}, +where @var{r}, @var{g} and @var{b} are either integers in the range +0-65535 or floats in the range 0.0-1.0. + + Pango font names have the form ``@var{family-list} @var{style-options} +@var{size}''. +@cindex Pango font name +@noindent +@var{family-list} is a comma separated list of font families optionally +terminated by a comma. This way you can specify several families and the +first one found will be used. @var{family} corresponds to the second part in +an X font name, for example in + +@smallexample +-adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1 +@end smallexample + +@noindent +the family name is ``times''. + +@noindent +@var{style-options} is a whitespace separated list of words where each word +is a style, variant, weight, or stretch. The default value for all of +these is @code{normal}. + +@noindent +A `style' corresponds to the fourth part of an X font name. In X font +names it is the character @samp{r}, @samp{i} or @samp{o}; in Pango +font names the corresponding values are @code{normal}, @code{italic}, +or @code{oblique}. + +@noindent +A `variant' is either @code{normal} or @code{small-caps}. +Small caps is a font with the lower case characters replaced by +smaller variants of the capital characters. + +@noindent +Weight describes the ``boldness'' of a font. It corresponds to the third +part of an X font name. It is one of @code{ultra-light}, @code{light}, +@code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}. + +@noindent +Stretch gives the width of the font relative to other designs within a +family. It corresponds to the fifth part of an X font name. It is one of +@code{ultra-condensed}, @code{extra-condensed}, @code{condensed}, +@code{semi-condensed}, @code{normal}, @code{semi-expanded}, +@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}. + +@noindent +@var{size} is a decimal number that describes the font size in points. + +@ignore + arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f +@end ignore