diff options
Diffstat (limited to 'doc/emacs/display.texi')
| -rw-r--r-- | doc/emacs/display.texi | 194 |
1 files changed, 170 insertions, 24 deletions
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 6897ef525a2..b7c8825efa2 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -24,6 +24,7 @@ the text is displayed. * Faces:: How to change the display style using faces. * Colors:: Specifying colors for faces. * Standard Faces:: The main predefined faces. +* Icons:: How to change how icons look. * Text Scale:: Increasing or decreasing text size in a buffer. * Font Lock:: Minor mode for syntactic highlighting using faces. * Highlight Interactively:: Tell Emacs what text to highlight. @@ -642,24 +643,41 @@ apply them to specific text when you want the effects they produce. @item default This face is used for ordinary text that doesn't specify any face. Its background color is used as the frame's background color. + @item bold This face uses a bold variant of the default font. + @item italic This face uses an italic variant of the default font. + @item bold-italic This face uses a bold italic variant of the default font. + @item underline This face underlines text. + @item fixed-pitch This face forces use of a fixed-width font. It's reasonable to customize this face to use a different fixed-width font, if you like, but you should not make it a variable-width font. + @item fixed-pitch-serif This face is like @code{fixed-pitch}, except the font has serifs and looks more like traditional typewriting. + @cindex @code{variable-pitch} face @item variable-pitch -This face forces use of a variable-width font. +This face forces use of a variable-width (i.e., proportional) font. +The font size picked for this face matches the font picked for the +default (usually fixed-width) font. + +@item variable-pitch-text +This is like the @code{variable-pitch} face (from which it inherits), +but is slightly larger. A proportional font of the same height as a +monospace font usually appears visually smaller, and can therefore be +harder to read. When displaying longer texts, this face can be a good +choice over the (slightly smaller) @code{variable-pitch} face. + @cindex @code{shadow} face @item shadow This face is used for making the text less noticeable than the surrounding @@ -716,46 +734,62 @@ frame: @table @code @item mode-line @cindex @code{mode-line} face -@cindex faces for mode lines -This face is used for the mode line of the currently selected window, +This is the base face used for the mode lines, as well as header lines and for menu bars when toolkit menus are not used. By default, it's drawn with shadows for a raised effect on graphical displays, and drawn as the inverse of the default face on non-windowed terminals. + +The @code{mode-line-active} and @code{mode-line-inactive} faces (which +are the ones used on the mode lines) inherit from this face. + +@item mode-line-active +@cindex faces for mode lines +Like @code{mode-line}, but used for the mode line of the currently +selected window. This face inherits from @code{mode-line}, so changes +in that face affect mode lines in all windows. + @item mode-line-inactive @cindex @code{mode-line-inactive} face Like @code{mode-line}, but used for mode lines of the windows other than the selected one (if @code{mode-line-in-non-selected-windows} is non-@code{nil}). This face inherits from @code{mode-line}, so changes in that face affect mode lines in all windows. + @item mode-line-highlight @cindex @code{mode-line-highlight} face Like @code{highlight}, but used for mouse-sensitive portions of text on mode lines. Such portions of text typically pop up tooltips (@pxref{Tooltips}) when the mouse pointer hovers above them. + @item mode-line-buffer-id @cindex @code{mode-line-buffer-id} face This face is used for buffer identification parts in the mode line. + @item header-line @cindex @code{header-line} face Similar to @code{mode-line} for a window's header line, which appears at the top of a window just as the mode line appears at the bottom. Most windows do not have a header line---only some special modes, such Info mode, create one. + @item header-line-highlight @cindex @code{header-line-highlight} face Similar to @code{highlight} and @code{mode-line-highlight}, but used for mouse-sensitive portions of text on header lines. This is a separate face because the @code{header-line} face might be customized in a way that does not interact well with @code{highlight}. + @item tab-line @cindex @code{tab-line} face Similar to @code{mode-line} for a window's tab line, which appears at the top of a window with tabs representing window buffers. @xref{Tab Line}. + @item vertical-border @cindex @code{vertical-border} face This face is used for the vertical divider between windows on text terminals. + @item minibuffer-prompt @cindex @code{minibuffer-prompt} face @vindex minibuffer-prompt-properties @@ -765,19 +799,23 @@ By default, Emacs automatically adds this face to the value of properties (@pxref{Text Properties,,, elisp, the Emacs Lisp Reference Manual}) used to display the prompt text. (This variable takes effect when you enter the minibuffer.) + @item fringe @cindex @code{fringe} face The face for the fringes to the left and right of windows on graphic displays. (The fringes are the narrow portions of the Emacs frame between the text area and the window's right and left borders.) @xref{Fringes}. + @item cursor The @code{:background} attribute of this face specifies the color of the text cursor. @xref{Cursor Display}. + @item tooltip This face is used for tooltip text. By default, if Emacs is built with GTK+ support, tooltips are drawn via GTK+ and this face has no effect. @xref{Tooltips}. + @item mouse This face determines the color of the mouse pointer. @end table @@ -814,10 +852,44 @@ This face is used to display on text-mode terminals the menu item that would be selected if you click a mouse or press @key{RET}. @end table +@node Icons +@section Icons +@cindex icons, on clickable buttons + +Emacs sometimes displays clickable buttons (or other informative +icons), and you can customize how these look on display. + +@vindex icon-preference +The main customization point here is the @code{icon-preference} user +option. By using this, you can tell Emacs your overall preferences +for icons. This is a list of icon types, and the first icon type +that's supported will be used. The supported types are: + +@table @code +@item image +Use an image for the icon. + +@item emoji +Use a colorful emoji for the icon. + +@item symbol +Use a monochrome symbol for the icon. + +@item text +Use a simple text for the icon. +@end table + +In addition, each individual icon can be customized with @kbd{M-x +customize-icon}, and themes can further alter the looks of the icons. + +To get a quick description of an icon, use the @kbd{M-x describe-icon} +command. + @node Text Scale @section Text Scale -@cindex adjust buffer face height +@cindex adjust buffer font size +@cindex font size of @code{default} face, increase or decrease @findex text-scale-adjust @kindex C-x C-+ @kindex C-x C-- @@ -825,17 +897,27 @@ would be selected if you click a mouse or press @key{RET}. @kindex C-x C-0 @kindex C-wheel-down @kindex C-wheel-up - To increase the height of the default face in the current buffer, -type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type @kbd{C-x -C--}. To restore the default (global) face height, type @kbd{C-x -C-0}. These keys are all bound to the same command, + To increase the font size of the @code{default} face in the current +buffer, type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type +@kbd{C-x C--}. To restore the default (global) font size, type +@kbd{C-x C-0}. These keys are all bound to the same command, @code{text-scale-adjust}, which looks at the last key typed to -determine which action to take. +determine which action to take and adjusts the font size accordingly +by changing the height of the default face. + + Most faces don't have an explicit setting of the @code{:height} +attribute, and thus inherit the height from the @code{default} face. +Those faces are also scaled by the above commands. + + Faces other than @code{default} that have an explicit setting of the +@code{:height} attribute are not affected by these font size changes. +The @code{header-line} face is an exception: it will be scaled even if +it has an explicit setting of the @code{:height} attribute. Similarly, scrolling the mouse wheel with the @kbd{Ctrl} modifier pressed, when the mouse pointer is above buffer text, will increase or -decrease the height of the default face, depending on the direction of -the scrolling. +decrease the font size of the affected faces, depending on the +direction of the scrolling. The final key of these commands may be repeated without the leading @kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face @@ -845,27 +927,57 @@ of 1.2; to change this factor, customize the variable to the @code{text-scale-adjust} command restores the default height, the same as typing @kbd{C-x C-0}. -@cindex increase buffer face height +@cindex adjust global font size +@findex global-text-scale-adjust +@vindex global-text-scale-adjust-resizes-frames +@kindex C-x C-M-+ +@kindex C-x C-M-= +@kindex C-x C-M-- +@kindex C-x C-M-0 +@kindex C-M-wheel-down +@kindex C-M-wheel-up + Similarly, to change the sizes of the fonts globally, type @kbd{C-x +C-M-+}, @kbd{C-x C-M-=}, @kbd{C-x C-M--} or @kbd{C-x C-M-0}, or scroll +the mouse wheel with both the @kbd{Ctrl} and @kbd{Meta} modifiers +pressed. To enable frame resizing when the font size is changed +globally, customize the variable +@code{global-text-scale-adjust-resizes-frames} (@pxref{Easy +Customization}). + +@cindex increase buffer font size @findex text-scale-increase -@cindex decrease buffer face height +@cindex decrease buffer font size @findex text-scale-decrease The commands @code{text-scale-increase} and -@code{text-scale-decrease} increase or decrease the height of the -default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively. -You may find it convenient to bind to these commands, rather than -@code{text-scale-adjust}. +@code{text-scale-decrease} increase or decrease the size of the font +in the current buffer, just like @kbd{C-x C-+} and @kbd{C-x C--} +respectively. You may find it convenient to bind to these commands, +rather than @code{text-scale-adjust}. -@cindex set buffer face height +@cindex set buffer font size @findex text-scale-set - The command @code{text-scale-set} scales the height of the default -face in the current buffer to an absolute level specified by its -prefix argument. + The command @code{text-scale-set} scales the size of the font in the +current buffer to an absolute level specified by its prefix argument. @findex text-scale-mode The above commands automatically enable the minor mode @code{text-scale-mode} if the current font scaling is other than 1, and disable it otherwise. +@cindex pinch to scale +@findex text-scale-pinch + The command @code{text-scale-pinch} increases or decreases the text +scale based on the distance between fingers on a touchpad when a pinch +gesture is performed by placing two fingers on a touchpad and moving +them towards or apart from each other. This is only available on some +systems with supported hardware. + +@findex mouse-wheel-text-scale + The command @code{mouse-wheel-text-scale} also changes the text +scale. Normally, it is run when you press @key{Ctrl} while moving the +mouse wheel. The text scale is increased when the wheel is moved +downwards, and it is decreased when the wheel is moved upwards. + @node Font Lock @section Font Lock mode @cindex Font Lock mode @@ -960,10 +1072,15 @@ in C comments, use this: @end example @findex font-lock-remove-keywords +@vindex font-lock-ignore @noindent To remove keywords from the font-lock highlighting patterns, use the function @code{font-lock-remove-keywords}. @xref{Search-based Fontification,,, elisp, The Emacs Lisp Reference Manual}. +Alternatively, you can selectively disable highlighting due to some +keywords by customizing the @code{font-lock-ignore} option, +@pxref{Customizing Keywords,,, elisp, The Emacs Lisp Reference +Manual}. @cindex just-in-time (JIT) font-lock @cindex background syntax highlighting @@ -1538,7 +1655,9 @@ charge on the mode-line, by using the command @code{battery-mode-line-format} determines the way the battery charge is displayed; the exact mode-line message depends on the operating system, and it usually shows the current battery charge as a -percentage of the total charge. +percentage of the total charge. The functions in +@code{battery-update-functions} are run after updating the mode line, +and can be used to trigger actions based on the battery status. @cindex mode line, 3D appearance @cindex attributes of mode line, changing @@ -1653,6 +1772,12 @@ characters more prominent on display. @xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs Lisp Reference Manual}, for details. +@findex glyphless-display-mode + The @code{glyphless-display-mode} minor mode can be used to toggle +the display of glyphless characters in the current buffer. The +glyphless characters will be displayed as boxes with acronyms of their +names inside. + @cindex curly quotes, and terminal capabilities @cindex curved quotes, and terminal capabilities @cindex @code{homoglyph} face @@ -1837,12 +1962,22 @@ logical lines, so having a fringe indicator for each wrapped line would be visually distracting. You can change this by customizing the variable @code{visual-line-fringe-indicators}. +@vindex word-wrap-whitespace-mode + By default, Emacs only breaks lines after whitespace characters like +@key{SPC} and @key{TAB}, but does not break after whitespace +characters like @key{EN QUAD}. Emacs provides a minor mode called +@code{word-wrap-whitespace-mode} that switches on word wrapping in the +current mode, and sets up which characters to wrap lines on based on +the @code{word-wrap-whitespace-characters} user option. There's also +a globalized version of that mode called +@code{global-word-wrap-whitespace-mode}. + @vindex word-wrap-by-category @findex modify-category-entry @findex char-category-set @findex category-set-mnemonics - By default, Emacs only breaks lines after whitespace characters. -That produces incorrect results when CJK and Latin text are mixed + Only breaking after whitespace character produces incorrect +results when CJK and Latin text are mixed together (because CJK characters don't use whitespace to separate words). You can customize the option @code{word-wrap-by-category} to allow Emacs to break lines after any character with @samp{|} category @@ -2025,3 +2160,14 @@ argument to suppress the effect of bold-face in this case. byte with a decimal value of 128 is displayed as @code{\200}. To change display to the hexadecimal format of @code{\x80}, set the variable @code{display-raw-bytes-as-hex} to @code{t}. +Care may be needed when interpreting a raw byte when copying +text from a terminal containing an Emacs session, or when a terminal's +@code{escape-glyph} face looks like the default face. For example, by +default Emacs displays the four characters @samp{\}, @samp{2}, +@samp{0}, @samp{0} with the same characters it displays a byte with +decimal value 128. The problem can be worse with hex displays, where +the raw byte 128 followed by the character @samp{7} is displayed as +@code{\x807}, which Emacs Lisp reads as the single character U+0807 +SAMARITAN LETTER IT; this confusion does not occur with the +corresponding octal display @code{\2007} because octal escapes contain +at most three digits. |