Mercurial > emacs
diff man/xresources.texi @ 40523:198cafe77e0f
Text broken out from cmdargs.texi.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Tue, 30 Oct 2001 18:38:57 +0000 |
parents | |
children | a8c2103fca6f |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/xresources.texi Tue Oct 30 18:38:57 2001 +0000 @@ -0,0 +1,891 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1987,93,94,95,1997,2001 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. + +@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 +@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}. + + 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}. + + 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. + + In @file{~/.Xdefaults}, you can specify a value for a single resource +on one line, like this: + +@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: + +@example +emacs.BorderWidth: 2 +@end example + + 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: + +@example +emacs.BorderWidth: 2 +emacs.borderWidth: 4 +@end example + + 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}. + +@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. + +If you don't specify this option, the default is to use the Emacs +executable's name as the resource name. + +@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). +@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. + + The following table lists the resource names that designate options +for Emacs, each with the class that it belongs to: + +@table @asis +@item @code{background} (class @code{Background}) +Background color name. + +@item @code{bitmapIcon} (class @code{BitmapIcon}) +Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window +manager choose an icon if @samp{off}. + +@item @code{borderColor} (class @code{BorderColor}) +Color name for the external border. + +@item @code{borderWidth} (class @code{BorderWidth}) +Width in pixels of the external border. + +@item @code{cursorColor} (class @code{Foreground}) +Color name for text cursor (point). + +@item @code{font} (class @code{Font}) +Font name for text (or fontset name, @pxref{Fontsets}). + +@item @code{foreground} (class @code{Foreground}) +Color name for text. + +@item @code{geometry} (class @code{Geometry}) +Window size and position. Be careful not to specify this resource as +@samp{emacs*geometry}, because that may affect individual menus as well +as the Emacs frame itself. + +If this resource specifies a position, that position applies only to the +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{iconName} (class @code{Title}) +Name to display in the icon. + +@item @code{internalBorder} (class @code{BorderWidth}) +Width in pixels of the internal border. + +@item @code{lineSpacing} (class @code{LineSpacing}) +@cindex line spacing +@cindex leading +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. + +@item @code{minibuffer} (class @code{Minibuffer}) +If @samp{none}, don't make a minibuffer in this frame. +It will use a separate minibuffer frame instead. + +@item @code{paneFont} (class @code{Font}) +@cindex font for menus +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 +specified if @samp{off}. + +@item @code{screenGamma} (class @code{ScreenGamma}) +@cindex gamma correction +Gamma correction for colors, equivalent to the frame parameter +@code{screen-gamma}. + +@item @code{selectionFont} (class @code{Font}) +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{synchronous} (class @code{Synchronous}) +@cindex debugging X problems +@cindex synchronous X mode +Run Emacs in synchronous mode if @samp{on}. Synchronous mode is +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{verticalScrollBars} (class @code{ScrollBars}) +Give frames scroll bars if @samp{on}; don't have scroll bars if +@samp{off}. +@end table + + Here are resources for controlling 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 +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}.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}.attributeBold +Whether to draw the characters in the face @var{face} as bold. +@item @var{face}.attributeItalic +Whether to draw the characters in the face @var{face} as italic. +@end table + +@node Lucid Resources +@appendixsec Lucid Menu X Resources +@cindex Menu X Resources (Lucid widgets) +@cindex Lucid Widget X Resources + + If the Emacs installed at your site was built to use the X toolkit +with the Lucid menu widgets, then the menu bar is a separate widget and +has its own resources. The resource names contain @samp{pane.menubar} +(following, as always, the name of the Emacs invocation, or @samp{Emacs}, +which stands for all Emacs invocations). Specify them like this: + +@example +Emacs.pane.menubar.@var{resource}: @var{value} +@end example + +@noindent +For example, to specify the font @samp{8x16} for the menu-bar items, +write this: + +@example +Emacs.pane.menubar.font: 8x16 +@end example + +@noindent +Resources for @emph{non-menubar} toolkit pop-up menus have +@samp{menu*}, in like fashion. 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} instead of @samp{menu}: + +@example +Emacs.dialog*.font: 8x16 +@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 +some other systems, you must not add @samp{shell.}. + + Here is a list of the specific resources for menu bars and pop-up menus: + +@table @code +@item font +Font for menu item text. +@item foreground +Color of the foreground. +@item background +Color of the background. +@item buttonForeground +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. +@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. +@item margin +The margin of the menu bar, in characters. The default of 4 makes the +menu bar appear like the LessTif/Motif one. +@end table + +@node LessTif Resources +@appendixsec LessTif Menu X Resources +@cindex Menu X Resources (LessTif widgets) +@cindex LessTif Widget X Resources + + If the Emacs installed at your site was built to use the X toolkit +with the LessTif or Motif widgets, then the menu bar, the dialog +boxes, the pop-up menus, and the file-selection box are separate +widgets and have their own resources. + + The resource names for the menu bar contain @samp{pane.menubar} +(following, as always, the name of the Emacs invocation, or +@samp{Emacs}, which stands for all Emacs invocations). Specify them +like this: + +@smallexample +Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value} +@end smallexample + + Each individual string in the menu bar is a subwidget; the subwidget's +name is the same as the menu item string. For example, the word +@samp{File} in the menu bar is part of a subwidget named +@samp{emacs.pane.menubar.File}. Most likely, you want to specify the +same resources for the whole menu bar. To do this, use @samp{*} instead +of a specific subwidget name. For example, to specify the font +@samp{8x16} for the menu-bar items, write this: + +@smallexample +Emacs.pane.menubar.*.fontList: 8x16 +@end smallexample + +@noindent +This also specifies the resource value for submenus. + + Each item in a submenu in the menu bar also has its own name for X +resources; for example, the @samp{File} submenu has an item named +@samp{Save (current buffer)}. A resource specification for a submenu +item looks like this: + +@smallexample +Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value} +@end smallexample + +@noindent +For example, here's how to specify the font for the @samp{Save (current +buffer)} item: + +@smallexample +Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16 +@end smallexample + +@noindent +For an item in a second-level submenu, such as @samp{Complete Word} +under @samp{Spell Checking} under @samp{Tools}, the resource fits this +template: + +@smallexample +Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value} +@end smallexample + +@noindent +For example, + +@smallexample +Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value} +@end smallexample + +@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 +for that in two steps. First, specify the resource for all of them; +then, override the value for submenus alone. Here is an example: + +@smallexample +Emacs.pane.menubar.*.fontList: 8x16 +Emacs.pane.menubar.popup_*.fontList: 8x16 +@end smallexample + +@noindent +For LessTif pop-up menus, use @samp{menu*} instead of +@samp{pane.menubar}. For example, to specify the font @samp{8x16} for +the pop-up menu items, write this: + +@smallexample +Emacs.menu*.fontList: 8x16 +@end smallexample + +@noindent +For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}: + +@example +Emacs.dialog*.fontList: 8x16 +Emacs.dialog*.foreground: hotpink +@end example + +To specify resources for the LessTif file-selection box, use +@samp{fsb*}, like this: + +@example +Emacs.fsb*.fontList: 8x16 +@end example + +@iftex +@medbreak +@end iftex + Here is a list of the specific resources for LessTif menu bars and +pop-up menus: + +@table @code +@item armColor +The color to show in an armed button. +@item fontList +The font to use. +@item marginBottom +@itemx marginHeight +@itemx marginLeft +@itemx marginRight +@itemx marginTop +@itemx marginWidth +Amount of space to leave around the item, within the border. +@item borderWidth +The width of the border around the menu item, on all sides. +@item shadowThickness +The width of the border shadow. +@item bottomShadowColor +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