immediately, but the requested redisplay does happen
eventually---after all the input has been processed.
- Normally, suspending and resuming Emacs also refreshes the screen.
-Some terminal emulators record separate contents for display-oriented
-programs such as Emacs and for ordinary sequential display. If you are
-using such a terminal, you might want to inhibit the redisplay on
-resumption.
+ On text-only terminals, suspending and resuming Emacs normally also
+refreshes the screen. Some terminal emulators record separate
+contents for display-oriented programs such as Emacs and for ordinary
+sequential display. If you are using such a terminal, you might want
+to inhibit the redisplay on resumption.
-@defvar no-redraw-on-reenter
+@defopt no-redraw-on-reenter
@cindex suspend (cf. @code{no-redraw-on-reenter})
@cindex resume (cf. @code{no-redraw-on-reenter})
This variable controls whether Emacs redraws the entire screen after it
has been suspended and resumed. Non-@code{nil} means there is no need
to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
-@end defvar
+@end defopt
@node Forcing Redisplay
@section Forcing Redisplay
@cindex forcing redisplay
Emacs normally tries to redisplay the screen whenever it waits for
-input. With this function you can request an immediate attempt to
-redisplay, in the middle of Lisp code, without actually waiting for
-input.
+input. With the following function, you can request an immediate
+attempt to redisplay, in the middle of Lisp code, without actually
+waiting for input.
@defun redisplay &optional force
This function tries immediately to redisplay, provided there are no
-pending input events. It is equivalent to @code{(sit-for 0)}.
+pending input events.
If the optional argument @var{force} is non-@code{nil}, it does all
pending redisplay work even if input is available, with no
for this; @pxref{Display Tables}).
@defopt truncate-lines
-This buffer-local variable controls how Emacs displays lines that extend
-beyond the right edge of the window. The default is @code{nil}, which
-specifies continuation. If the value is non-@code{nil}, then these
-lines are truncated.
-
-If the variable @code{truncate-partial-width-windows} is non-@code{nil},
-then truncation is always used for side-by-side windows (within one
-frame) regardless of the value of @code{truncate-lines}.
+If this buffer-local variable is non-@code{nil}, lines that extend
+beyond the right edge of the window are truncated; otherwise, they are
+continued. As a special exception, the variable
+@code{truncate-partial-width-windows} takes precedence in
+@dfn{partial-width} windows (i.e., windows that do not occupy the
+entire frame width).
@end defopt
@defopt default-truncate-lines
@end defopt
@defopt truncate-partial-width-windows
-This variable controls display of lines that extend beyond the right
-edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
-If it is non-@code{nil}, these lines are truncated; otherwise,
-@code{truncate-lines} says what to do with them.
+This variable controls line truncation in @dfn{partial-width} windows.
+A partial-width window is one that does not occupy the entire frame
+width (@pxref{Splitting Windows}). If the value is @code{nil}, line
+truncation is determined by the variable @code{truncate-lines} (see
+above). If the value is an integer @var{n}, lines are truncated if
+the partial-width window has fewer than @var{n} columns, regardless of
+the value of @code{truncate-lines}; if the partial-width window has
+@var{n} or more columns, line truncation is determined by
+@code{truncate-lines}. For any other non-@code{nil} value, lines are
+truncated in every partial-width window, regardless of the value of
+@code{truncate-lines}.
@end defopt
When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.
@defvar wrap-prefix
-If this buffer-local variable is non-@code{nil}, the prefix it defines
-will be added at display-time to the beginning of every continuation
-line due to text wrapping (so if lines are truncated, the wrap-prefix
-is never used). It may be a string, an image, or a stretch-glyph such
-as used by the `display' text-property. @xref{Display Property}.
-
-A wrap-prefix may also be specified for regions of text using the
-@code{wrap-prefix} text-property (which takes precedence over the
-value of the @code{wrap-prefix} variable). @xref{Special Properties}.
+If this buffer-local variable is non-@code{nil}, it defines a
+``prefix'' that is prepended to every continuation line at
+display-time. (If lines are truncated, the wrap-prefix is never
+used.) It may be a string, an image, or a stretch-glyph; the value is
+interpreted in the same way as a @code{display} text property.
+@xref{Display Property}.
+
+A wrap-prefix may also be specified for regions of text, using the
+@code{wrap-prefix} text or overlay property. This takes precedence
+over the @code{wrap-prefix} variable. @xref{Special Properties}.
@end defvar
@defvar line-prefix
-If this buffer-local variable is non-@code{nil}, the prefix it defines
-will be added at display-time to the beginning of every
-non-continuation line It may be a string, an image, or a stretch-glyph
-such as used by the `display' text-property. @xref{Display Property}.
+If this buffer-local variable is non-@code{nil}, it defines a
+``prefix'' that is prepended to every non-continuation line at
+display-time. It may be a string, an image, or a stretch-glyph; the
+value is interpreted in the same way as a @code{display} text
+property. @xref{Display Property}.
A line-prefix may also be specified for regions of text using the
-@code{line-prefix} text-property (which takes precedence over the
-value of the @code{line-prefix} variable). @xref{Special Properties}.
+@code{line-prefix} text or overlay property. This takes precedence
+over the @code{line-prefix} variable. @xref{Special Properties}.
@end defvar
If your buffer contains @emph{very} long lines, and you use
-continuation to display them, just thinking about them can make Emacs
-redisplay slow. The column computation and indentation functions also
-become slow. Then you might find it advisable to set
+continuation to display them, computing the continuation lines can
+make Emacs redisplay slow. The column computation and indentation
+functions also become slow. Then you might find it advisable to set
@code{cache-long-line-scans} to @code{t}.
@defvar cache-long-line-scans
@code{(message nil)} or for any other reason.
@end defvar
-@defvar echo-keystrokes
+@defopt echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be an integer or floating point number,
which specifies the
sequence are echoed immediately.)
If the value is zero, then command input is not echoed.
-@end defvar
+@end defopt
@defvar message-truncate-lines
Normally, displaying a long message resizes the echo area to display
(remove-from-invisibility-spec 'my-symbol)
@end example
+ You can check for invisibility using the following function:
+
+@defun invisible-p pos-or-prop
+If @var{pos-or-prop} is a marker or number, this function returns a
+non-@code{nil} value if the text at that position is invisible.
+
+If @var{pos-or-prop} is any other kind of Lisp object, that is taken
+to mean a possible value of the @code{invisible} text or overlay
+property. In that case, this function returns a non-@code{nil} value
+if that value would cause text to become invisible, based on the
+current value of @code{buffer-invisibility-spec}.
+@end defun
+
@vindex line-move-ignore-invisible
Ordinarily, functions that operate on text or move point do not care
whether the text is invisible. The user-level line motion commands
-explicitly ignore invisible newlines if
-@code{line-move-ignore-invisible} is non-@code{nil} (the default), but
-only because they are explicitly programmed to do so.
+ignore invisible newlines if @code{line-move-ignore-invisible} is
+non-@code{nil} (the default), but only because they are explicitly
+programmed to do so.
However, if a command ends with point inside or immediately before
invisible text, the main editing loop moves point further forward or
@end example
@end defvar
-@defvar selective-display-ellipses
+@defopt selective-display-ellipses
If this buffer-local variable is non-@code{nil}, then Emacs displays
@samp{@dots{}} at the end of a line that is followed by hidden text.
This example is a continuation of the previous one.
You can use a display table to substitute other text for the ellipsis
(@samp{@dots{}}). @xref{Display Tables}.
-@end defvar
+@end defopt
@node Temporary Displays
@section Temporary Displays
@end example
@end defspec
-@defvar temp-buffer-show-function
+@defopt temp-buffer-show-function
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
just as @code{with-output-to-temp-buffer} normally would, inside of
@code{save-selected-window} and with the chosen window and buffer
selected.
-@end defvar
+@end defopt
@defvar temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
beginning and end. It also has properties that you can examine and set;
these affect the display of the text within the overlay.
+@cindex scalability of overlays
+The visual effect of an overlay is the same as of the corresponding
+text property (@pxref{Text Properties}). However, due to a different
+implementation, overlays generally don't scale well (many operations
+take a time that is proportional to the number of overlays in the
+buffer). If you need to affect the visual appearance of many portions
+in the buffer, we recommend using text properties.
+
An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text. When you create the overlay,
the overlay. The string does not appear in the buffer in any
sense---only on the screen.
+@item line-prefix
+This property specifies a display spec to prepend to each
+non-continuation line at display-time. @xref{Truncation}.
+
+@itemx wrap-prefix
+This property specifies a display spec to prepend to each continuation
+line at display-time. @xref{Truncation}.
+
@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
parts of Emacs text.
@vindex default-line-spacing
- You can specify the line spacing for all lines in a frame with the
-@code{line-spacing} frame parameter (@pxref{Layout Parameters}).
-However, if the variable @code{default-line-spacing} is
-non-@code{nil}, it overrides the frame's @code{line-spacing}
-parameter. An integer value specifies the number of pixels put below
-lines on graphical displays. A floating point number specifies the
-spacing relative to the frame's default line height.
+ On graphical terminals, you can specify the line spacing for all
+lines in a frame, using the @code{line-spacing} frame parameter
+(@pxref{Layout Parameters}). However, if the variable
+@code{default-line-spacing} is non-@code{nil}, it overrides the
+frame's @code{line-spacing} parameter. An integer value specifies the
+number of pixels put below lines. A floating point number specifies
+the spacing relative to the frame's default line height.
@vindex line-spacing
You can specify the line spacing for all lines in a buffer via the
buffer-local @code{line-spacing} variable. An integer value specifies
-the number of pixels put below lines on graphical displays. A floating
-point number specifies the spacing relative to the default frame line
-height. This overrides line spacings specified for the frame.
+the number of pixels put below lines. A floating point number
+specifies the spacing relative to the default frame line height. This
+overrides line spacings specified for the frame.
@kindex line-spacing @r{(text property)}
Finally, a newline can have a @code{line-spacing} text or overlay
numeric height value specifies the line spacing, rather than the line
height.
+ On text-only terminals, the line spacing cannot be altered.
+
@node Faces
@section Faces
@cindex faces
to be displayed; if it is @code{nil}, the selected frame is used.
@end defun
-@defvar x-bitmap-file-path
+@defopt underline-minimum-offset
+This variable specifies the minimum distance between the baseline and
+the underline, in pixels, when displaying underlined text.
+@end defopt
+
+@defopt x-bitmap-file-path
This variable specifies a list of directories for searching
for bitmap files, for the @code{:stipple} attribute.
-@end defvar
+@end defopt
@defun bitmap-spec-p object
This returns @code{t} if @var{object} is a valid bitmap specification,
@item
If @var{remapping...} recursively references the same face name
@var{face}, either directly remapping entry, or via the
-@code{:inherit} attribute of some other face in
-@var{remapping...}, then that reference uses normal frame-wide
-definition of @var{face} instead of the ``remapped'' definition.
+@code{:inherit} attribute of some other face in @var{remapping...},
+then that reference uses the normal definition of @var{face} in the
+selected frame, instead of the ``remapped'' definition.
For instance, if the @code{mode-line} face is remapped using this
entry in @code{face-remapping-alist}:
(@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
@end example
-Everything except the @var{face} is a ``face spec'', a list of face
-names or face attribute-value pairs. All face specs are merged
-together, with earlier values taking precedence.
+Everything except @var{face} is a ``face spec'': a list of face names
+or face attribute-value pairs. All face specs are merged together,
+with earlier values taking precedence.
The @var{relative_specs_}n values are ``relative specs'', and are
added by @code{face-remap-add-relative} (and removed by
Emacs looks for the @dfn{closest matching font}. The variables in
this section control how Emacs makes this selection.
-@defvar face-font-family-alternatives
+@defopt face-font-family-alternatives
If a given family is specified but does not exist, this variable
specifies alternative font families to try. Each element should have
this form:
If @var{family} is specified but not available, Emacs will try the other
families given in @var{alternate-families}, one by one, until it finds a
family that does exist.
-@end defvar
+@end defopt
-@defvar face-font-selection-order
+@defopt face-font-selection-order
If there is no font that exactly matches all desired face attributes
(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}),
this variable specifies the order in which these attributes should be
default one. But if you put @code{:slant} before @code{:height}, the
@code{italic} face will use an italic font, even if its height is not
quite right.
-@end defvar
+@end defopt
-@defvar face-font-registry-alternatives
+@defopt face-font-registry-alternatives
This variable lets you specify alternative font registries to try, if a
given registry is specified and doesn't exist. Each element should have
this form:
If @var{registry} is specified but not available, Emacs will try the
other registries given in @var{alternate-registries}, one by one,
until it finds a registry that does exist.
-@end defvar
+@end defopt
Emacs can make use of scalable fonts, but by default it does not use
them.
-@defvar scalable-fonts-allowed
+@defopt scalable-fonts-allowed
This variable controls which scalable fonts to use. A value of
@code{nil}, the default, means do not use scalable fonts. @code{t}
means to use any scalable font that seems appropriate for the text.
@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
-@end defvar
+@end defopt
@defvar face-font-rescale-alist
This variable specifies scaling for certain faces. Its value should
@node Font Lookup
@subsection Looking Up Fonts
-@defun x-list-fonts name &optional reference-face frame maximum
+@defun x-list-fonts name &optional reference-face frame maximum width
This function returns a list of available font names that match
@var{name}. @var{name} should be a string containing a font name in
either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font
after the first @var{maximum} matching fonts. Specifying a small
value for @var{maximum} can make this function much faster, in cases
where many fonts match the pattern.
+
+The optional argument @var{width} specifies a desired font width. If
+it is non-@code{nil}, the function only returns those fonts whose
+characters are (on average) @var{width} times as wide as
+@var{reference-face}.
@end defun
@defun x-family-fonts &optional family frame
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
-@defun set-fontset-font name character fontname &optional frame
-This function modifies the existing fontset @var{name} to
-use the font name @var{fontname} for the character @var{character}.
+@defun set-fontset-font name character font-spec &optional frame add
+This function modifies the existing fontset @var{name} to use the font
+matching with @var{font-spec} for the character @var{character}.
-If @var{name} is @code{nil}, this function modifies the default
+If @var{name} is @code{nil}, this function modifies the fontset of the
+selected frame or that of @var{frame} if @var{frame} is not
+@code{nil}.
+
+If @var{name} is @code{t}, this function modifies the default
fontset, whose short name is @samp{fontset-default}.
@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
@var{from} and @var{to} are character codepoints. In that case, use
-@var{fontname} for all characters in the range @var{from} and @var{to}
+@var{font-spec} for all characters in the range @var{from} and @var{to}
(inclusive).
@var{character} may be a charset. In that case, use
-@var{fontname} for all character in the charsets.
+@var{font-spec} for all character in the charsets.
+
+@var{character} may be a script anme. In that case, use
+@var{font-spec} for all character in the charsets.
-@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
+@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
where @var{family} is a family name of a font (possibly including a
foundry name at the head), @var{registry} is a registry name of a font
(possibly including an encoding name at the tail).
+@var{font-spec} may be a font name string.
+
+The optional argument @var{add}, if non-@code{nil}, specifies how to
+add @var{font-spec} to the font specifications previously set. If it
+is @code{prepend}, @var{font-spec} is prepended. If it is
+@code{append}, @var{font-spec} is appended. By default,
+@var{font-spec} overrides the previous settings.
+
For instance, this changes the default fontset to use a font of which
-registry name is @samp{JISX0208.1983} for all characters belonging to
+family name is @samp{Kochi Gothic} for all characters belonging to
the charset @code{japanese-jisx0208}.
@smallexample
-(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
+(set-fontset-font t 'japanese-jisx0208
+ (font-spec :family "Kochi Gothic"))
@end smallexample
@end defun
A font object is a Lisp object that represents a font that Emacs has
@dfn{opened}. Font objects cannot be modified in Lisp, but they can
-be inspected. If you call @code{set-face-attribute} and pass a font
-spec, font entity, or font name string as the value of the
-@code{:font} attribute, Emacs opens the best ``matching'' font that is
-available for display. It then stores the corresponding font object
-as the actual value of the @code{:font} attribute for that face.
+be inspected.
@defun font-at position &optional window string
Return the font object that is being used to display the character at
spec.
@end defun
+ If you call @code{set-face-attribute} and pass a font spec, font
+entity, or font name string as the value of the @code{:font}
+attribute, Emacs opens the best ``matching'' font that is available
+for display. It then stores the corresponding font object as the
+actual value of the @code{:font} attribute for that face.
+
The following functions can be used to obtain information about a
font. For these functions, the @var{font} argument can be a font
object, a font entity, or a font spec.
buffer-local in every buffer.
@end defopt
-@defvar indicate-buffer-boundaries
+@defopt indicate-buffer-boundaries
This buffer-local variable controls how the buffer boundaries and
window scrolling are indicated in the window fringes.
bitmap in left fringe, and the bottom angle bitmap as well as both
arrow bitmaps in right fringe. To show the angle bitmaps in the left
fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}.
-@end defvar
+@end defopt
@defvar default-indicate-buffer-boundaries
The value of this variable is the default value for
normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
display line.
-@defvar overflow-newline-into-fringe
+@defopt overflow-newline-into-fringe
If this is non-@code{nil}, lines exactly as wide as the window (not
counting the final newline character) are not continued. Instead,
when point is at the end of the line, the cursor appears in the right
fringe.
-@end defvar
+@end defopt
@defvar fringe-cursor-alist
This variable specifies the mapping from logical cursor type to the
window take note of the new values by calling @code{set-window-buffer}
specifying the same buffer that is already displayed.
-@defvar scroll-bar-mode
+@defopt scroll-bar-mode
This variable, always local in all buffers, controls whether and where
to put scroll bars in windows displaying the buffer. The possible values
are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
the left, and @code{right} to put a scroll bar on the right.
-@end defvar
+@end defopt
@defun window-current-scroll-bars &optional window
This function reports the scroll bar type for window @var{window}.
but that text does not.
A margin display specification looks like @code{((margin
-right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}.
+right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}.
Here, @var{spec} is another display specification that says what to
display in the margin. Typically it is a string of text to display,
or an image descriptor.
@subsection Image Cache
@cindex image cache
- Emacs stores images in an image cache so that it can display them
-again more efficiently. When Emacs displays an image, it searches the
-image cache for an existing image specification @code{equal} to the
-desired specification. If a match is found, the image is displayed
-from the cache; otherwise, Emacs loads the image normally.
+ Emacs caches images so that it can display them again more
+efficiently. When Emacs displays an image, it searches the image
+cache for an existing image specification @code{equal} to the desired
+specification. If a match is found, the image is displayed from the
+cache; otherwise, Emacs loads the image normally.
Occasionally, you may need to tell Emacs to refresh the images
associated with a given image specification. For example, suppose you
display an image using a specification that contains a @code{:file}
-property. The image is loaded from the given file and stored in the
-image cache. If you later display the image again, using the same
-image specification, the image is displayed from the image cache.
-Normally, this is not a problem. However, if the image file has
-changed in the meantime, Emacs would be displaying the old version of
-the image. In such a situation, it is necessary to ``refresh'' the
-image using @code{image-refresh}.
+property. The image is automatically cached, and subsequent displays
+of that image, with the same image specification, will use the image
+cache. If the image file changes in the meantime, Emacs would be
+displaying the old version of the image. In such a situation, you can
+``refresh'' the image by calling @code{image-refresh}.
+
+ In Emacs' current implementation, each graphical terminal possesses
+an image cache, which is shared by all the frames on that terminal
+(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame
+also refreshes it in all other frames on the same terminal.
@defun image-refresh spec &optional frame
-This function refreshes any images having image specifications
+This function refreshes any images with image specifications
@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is
-@code{nil}, the selected frame is used. If @var{frame} is @code{t},
-the refresh is applied to all existing frames.
-
-This works by removing from the image cache all the images whose image
-specifications match @var{spec}. The next time Emacs needs to display
-such an image, it will reload the image anew.
+@code{nil}, it defaults to the selected frame. If @var{frame} is
+@code{t}, the refresh is applied to all existing frames.
@end defun
@defun clear-image-cache &optional filter
-This function clears the image cache. If @var{filter} is
-a frame, only the cache for that frame is cleared. If omitted or
-@code{nil}, clear the images on the selected frame. If @code{t},
-all frames' caches are cleared. Otherwise, @var{filter} is taken as
-a file name and only images that reference this file will be flushed.
+This function clears an image cache, removing all the images stored in
+it. If @var{filter} is omitted or @code{nil}, it clears the cache for
+the selected frame. If @var{filter} is a frame, it clears the cache
+for that frame. If @var{filter} is @code{t}, all image caches are
+cleared. Otherwise, @var{filter} is taken to be a file name, and all
+images associated with that file name are removed from all image
+caches.
@end defun
If an image in the image cache has not been displayed for a specified
@item follow-link
@kindex follow-link @r{(button property)}
The follow-link property, defining how a @key{Mouse-1} click behaves
-on this button, @xref{Links and Mouse-1}.
+on this button, @xref{Clickable Text}.
@item button
@kindex button @r{(button property)}
If the button has a non-@code{nil} @code{follow-link} property, and
@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
will also activate the @code{push-button} command.
-@xref{Links and Mouse-1}.
+@xref{Clickable Text}.
@deffn Command push-button &optional pos use-mouse-action
Perform the action specified by a button at location @var{pos}.
@defvar initial-window-system
This variable holds the value of @code{window-system} used for the
-first frame created by Emacs during startup.
+first frame created by Emacs during startup. (When Emacs is invoked
+with the @option{--daemon} option, it does not create any initial
+frames, so @code{initial-window-system} is @code{nil}. @xref{Initial
+Options, daemon,, emacs, The GNU Emacs Manual}.)
@end defvar
@defun window-system &optional frame
HCoop / bpt / emacs.git / blobdiff