* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
+* Glyphless Chars:: How glyphless characters are drawn.
@end menu
@node Refresh Screen
to put more work on the queue to be done by redisplay whenever there
is a chance.
- Emacs redisplay normally stops if input arrives, and does not happen
-at all if input is available before it starts. Most of the time, this
-is exactly what you want. However, you can prevent preemption by
-binding @code{redisplay-dont-pause} to a non-@code{nil} value.
-
@defvar redisplay-dont-pause
-If this variable is non-@code{nil}, pending input does not
-prevent or halt redisplay; redisplay occurs, and finishes,
-regardless of whether input is available.
+If this variable is non-@code{nil}, pending input does not prevent or
+halt redisplay; redisplay occurs, and finishes, regardless of whether
+input is available. If it is @code{nil}, Emacs redisplay stops if
+input arrives, and does not happen at all if input is available before
+it starts. The default is @code{t}.
@end defvar
@defvar redisplay-preemption-period
When an operation can take a while to finish, you should inform the
user about the progress it makes. This way the user can estimate
remaining time and clearly see that Emacs is busy working, not hung.
+A convenient way to do this is to use a @dfn{progress reporter}.
- Functions listed in this section provide simple and efficient way of
-reporting operation progress. Here is a working example that does
-nothing useful:
+ Here is a working example that does nothing useful:
@smallexample
(let ((progress-reporter
(progress-reporter-done progress-reporter))
@end smallexample
-@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
-This function creates and returns a @dfn{progress reporter}---an
-object you will use as an argument for all other functions listed
-here. The idea is to precompute as much data as possible to make
-progress reporting very fast.
+@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time
+This function creates and returns a progress reporter object, which
+you will use as an argument for the other functions listed below. The
+idea is to precompute as much data as possible to make progress
+reporting very fast.
When this progress reporter is subsequently used, it will display
@var{message} in the echo area, followed by progress percentage.
on a filename, for instance, use @code{format} before calling this
function.
-@var{min-value} and @var{max-value} arguments stand for starting and
-final states of your operation. For instance, if you scan a buffer,
-they should be the results of @code{point-min} and @code{point-max}
-correspondingly. It is required that @var{max-value} is greater than
-@var{min-value}. If you create progress reporter when some part of
-the operation has already been completed, then specify
-@var{current-value} argument. But normally you should omit it or set
-it to @code{nil}---it will default to @var{min-value} then.
-
-Remaining arguments control the rate of echo area updates. Progress
-reporter will wait for at least @var{min-change} more percents of the
-operation to be completed before printing next message.
-@var{min-time} specifies the minimum time in seconds to pass between
-successive prints. It can be fractional. Depending on Emacs and
-system capabilities, progress reporter may or may not respect this
-last argument or do it with varying precision. Default value for
-@var{min-change} is 1 (one percent), for @var{min-time}---0.2
-(seconds.)
+The arguments @var{min-value} and @var{max-value} should be numbers
+standing for the starting and final states of the operation. For
+instance, an operation that ``scans'' a buffer should set these to the
+results of @code{point-min} and @code{point-max} correspondingly.
+@var{max-value} should be greater than @var{min-value}.
+
+Alternatively, you can set @var{min-value} and @var{max-value} to
+@code{nil}. In that case, the progress reporter does not report
+process percentages; it instead displays a ``spinner'' that rotates a
+notch each time you update the progress reporter.
+
+If @var{min-value} and @var{max-value} are numbers, you can give the
+argument @var{current-value} a numerical value specifying the initial
+progress; if omitted, this defaults to @var{min-value}.
+
+The remaining arguments control the rate of echo area updates. The
+progress reporter will wait for at least @var{min-change} more
+percents of the operation to be completed before printing next
+message; the default is one percent. @var{min-time} specifies the
+minimum time in seconds to pass between successive prints; the default
+is 0.2 seconds. (On some operating systems, the progress reporter may
+handle fractions of seconds with varying precision).
This function calls @code{progress-reporter-update}, so the first
message is printed immediately.
* Face Attributes:: What is in a face?
* Attribute Functions:: Functions to examine and set face attributes.
* Displaying Faces:: How Emacs combines the faces specified for a character.
-* Face Remapping:: Remapping faces to alternative definitions.
+* Face Remapping:: Remapping faces to alternative definitions.
* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
+* Basic Faces:: Faces that are defined by default.
* Font Selection:: Finding the best available font for a face.
* Font Lookup:: Looking up the names of available fonts
and information about them.
entity, or a string. Emacs converts such values to an appropriate
font object, and stores that font object as the actual attribute
value. If you specify a string, the contents of the string should be
-a font name (@pxref{Font X,, Font Specification Options, emacs, The
-GNU Emacs Manual}); if the font name is an XLFD containing wildcards,
-Emacs chooses the first font matching those wildcards. Specifying
-this attribute also changes the values of the @code{:family},
-@code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and
-@code{:slant} attributes.
+a font name (@pxref{Fonts,,, emacs, The GNU Emacs Manual}); if the
+font name is an XLFD containing wildcards, Emacs chooses the first
+font matching those wildcards. Specifying this attribute also changes
+the values of the @code{:family}, @code{:foundry}, @code{:width},
+@code{:height}, @code{:weight}, and @code{:slant} attributes.
@item :inherit
The name of a face from which to inherit attributes, or a list of face
@end defun
@defun face-list
-This function returns a list of all defined face names.
+This function returns a list of all defined faces.
@end defun
@defun copy-face old-face new-name &optional frame new-frame
usually assign faces to around 400 to 600 characters at each call.
@end defvar
+@node Basic Faces
+@subsection Basic Faces
+
+If your Emacs Lisp program needs to assign some faces to text, it is
+often a good idea to use certain existing faces or inherit from them,
+rather than defining entirely new faces. This way, if other users
+have customized the basic faces to give Emacs a certain look, your
+program will ``fit in'' without additional customization.
+
+ Some of the basic faces defined in Emacs are listed below. In
+addition to these, you might want to make use of the Font Lock faces
+for syntactic highlighting, if highlighting is not already handled by
+Font Lock mode, or if some Font Lock faces are not in use.
+@xref{Faces for Font Lock}.
+
+@table @code
+@item default
+The default face, whose attributes are all specified. All other faces
+implicitly inherit from it: any unspecified attribute defaults to the
+attribute on this face (@pxref{Face Attributes}).
+
+@item bold
+@itemx italic
+@itemx bold-italic
+@itemx underline
+@itemx fixed-pitch
+@itemx variable-pitch
+These have the attributes indicated by their names (e.g. @code{bold}
+has a bold @code{:weight} attribute), with all other attributes
+unspecified (and so given by @code{default}).
+
+@item shadow
+For ``dimmed out'' text. For example, it is used for the ignored
+part of a filename in the minibuffer (@pxref{Minibuffer File,,
+Minibuffers for File Names, emacs, The GNU Emacs Manual}).
+
+@item link
+@itemx link-visited
+For clickable text buttons that send the user to a different
+buffer or ``location''.
+
+@item highlight
+For stretches of text that should temporarily stand out. For example,
+it is commonly assigned to the @code{mouse-face} property for cursor
+highlighting (@pxref{Special Properties}).
+
+@item match
+For text matching a search command.
+
+@item error
+@itemx warning
+@itemx success
+For text concerning errors, warnings, or successes. For example,
+these are used for messages in @samp{*Compilation*} buffers.
+@end table
+
@node Font Selection
@subsection Font Selection
@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
-Specification Options, emacs, The GNU Emacs Manual}). Within an XLFD
-string, wildcard characters may be used: the @samp{*} character
-matches any substring, and the @samp{?} character matches any single
-character. Case is ignored when matching font names.
+either the Fontconfig, GTK, or XLFD format (@pxref{Fonts,,, emacs, The
+GNU Emacs Manual}). Within an XLFD string, wildcard characters may be
+used: the @samp{*} character matches any substring, and the @samp{?}
+character matches any single character. Case is ignored when matching
+font names.
If the optional arguments @var{reference-face} and @var{frame} are
specified, the returned list includes only fonts that are the same
@table @code
@item :name
The font name (a string), in either XLFD, Fontconfig, or GTK format.
-@xref{Font X,, Font Specification Options, emacs, The GNU Emacs
-Manual}.
+@xref{Fonts,,, emacs, The GNU Emacs Manual}.
@item :family
@itemx :foundry
@defun font-xlfd-name font &optional fold-wildcards
This function returns the XLFD (X Logical Font Descriptor), a string,
-matching @var{font}. @xref{Font X,, Font Specification Options,
-emacs, The GNU Emacs Manual}, for information about XLFDs. If the
-name is too long for an XLFD (which can contain at most 255
-characters), the function returns @code{nil}.
+matching @var{font}. @xref{Fonts,,, emacs, The GNU Emacs Manual}, for
+information about XLFDs. If the name is too long for an XLFD (which
+can contain at most 255 characters), the function returns @code{nil}.
If the optional argument @var{fold-wildcards} is non-@code{nil},
consecutive wildcards in the XLFD are folded into one.
non-graphic terminals, but the other space properties in this section
are not.
+ Note that space properties are treated as paragraph separators for
+the purposes of reordering bidirectional text for display.
+@xref{Bidirectional Display}, for the details.
+
@node Pixel Specification
@subsection Pixel Specification for Spaces
@cindex spaces, pixel specification
for editing and displaying bidirectional text.
@cindex logical order
+@cindex reading order
@cindex visual order
@cindex unicode bidirectional algorithm
Emacs stores right-to-left and bidirectional text in the so-called
a ``Full bidirectionality'' class implementation of the @acronym{UBA}.
@defvar bidi-display-reordering
- The buffer-local variable @code{bidi-display-reordering} controls
-whether text in the buffer is reordered for display. If its value is
-non-@code{nil}, Emacs reorders characters that have right-to-left
-directionality when they are displayed. The default value is
-@code{t}. Text in overlay strings (@pxref{Overlay
-Properties,,before-string}), display strings (@pxref{Overlay
-Properties,,display}), and @code{display} text properties
-(@pxref{Display Property}) is also reordered if the buffer whose text
-includes these strings is reordered for display. Turning off
-@code{bidi-display-reordering} for a buffer turns off reordering of
-all the overlay and display strings in that buffer.
+ This buffer-local variable controls whether text in the buffer is
+reordered for display. If its value is non-@code{nil}, Emacs reorders
+characters that have right-to-left directionality when they are
+displayed. The default value is @code{t}. Text in overlay strings
+(@pxref{Overlay Properties,,before-string}), display strings
+(@pxref{Overlay Properties,,display}), and @code{display} text
+properties (@pxref{Display Property}) is also reordered for display if
+the buffer whose text includes these strings is reordered. Turning
+off @code{bidi-display-reordering} for a buffer turns off reordering
+of all the overlay and display strings in that buffer.
Reordering of strings that are unrelated to any buffer, such as text
displayed on the mode line (@pxref{Mode Line Format}) or header line
covered by these properties is reordered together. Moreover, the
bidirectional properties of the characters in this chunk of text are
ignored, and Emacs reorders them as if they were replaced with a
-single character @code{u+FFFC}, known as the @dfn{Object Replacement
+single character @code{U+FFFC}, known as the @dfn{Object Replacement
Character}. This means that placing a display property over a portion
of text may change the way that the surrounding text is reordered for
display. To prevent this unexpected effect, always place such
margin.
@defvar bidi-paragraph-direction
- Emacs determines the base direction of each paragraph dynamically,
-based on the text at the beginning of the paragraph. The precise
-method of determining the base direction is specified by the
+ By default, Emacs determines the base direction of each paragraph
+dynamically, based on the text at the beginning of the paragraph. The
+precise method of determining the base direction is specified by the
@acronym{UBA}; in a nutshell, the first character in a paragraph that
has an explicit directionality determines the base direction of the
paragraph. However, sometimes a buffer may need to force a certain
paragraphs in the buffer to have the direction specified by its
buffer-local value. The value can be either @code{right-to-left} or
@code{left-to-right}. Any other value is interpreted as @code{nil}.
+The default is @code{nil}.
+
+@cindex @code{prog-mode}, and @code{bidi-paragraph-direction}
+Modes that are meant to display program source code should force a
+@code{left-to-right} paragraph direction. The easiest way of doing so
+is to derive the mode from Prog Mode, which already sets
+@code{bidi-paragraph-direction} to that value.
@end defvar
@defun current-bidi-paragraph-direction &optional buffer
buffer-local value of the variable @code{bidi-paragraph-direction} is
non-@code{nil}, the returned value will be identical to that value;
otherwise, the returned value reflects the paragraph direction
-determined dynamically by Emacs.
-@end defun
+determined dynamically by Emacs. For buffers whose value of
+@code{bidi-display-reordering} is @code{nil} as well as unibyte
+buffers, this function always returns @code{left-to-right}.
+@end defun
+
+@cindex layout on display, and bidirectional text
+@cindex jumbled display of bidirectional text
+@cindex concatenating bidirectional strings
+ Reordering of bidirectional text for display can have surprising and
+unpleasant effects when two strings with bidirectional content are
+juxtaposed in a buffer, or otherwise programmatically concatenated
+into a string of text. A typical example is a buffer whose lines are
+actually sequences of items, or fields, separated by whitespace or
+punctuation characters. This is used in specialized modes such as
+Buffer-menu Mode or various email summary modes, like Rmail Summary
+Mode. Because these separator characters are @dfn{weak}, i.e.@: have
+no strong directionality, they take on the directionality of
+surrounding text. As result, a numeric field that follows a field
+with bidirectional content can be displayed @emph{to the left} of the
+preceding field, producing a jumbled display and messing up the
+expected layout.
+
+ To countermand this, we recommend that you use one of the following
+techniques for forcing correct order of fields on display:
+
+@itemize @minus
+@item
+Append the special character @code{U+200E}, LEFT-TO-RIGHT MARK, or
+@acronym{LRM}, to the end of each field that may have bidirectional
+content, or prepend it to the beginning of the following field. The
+function @code{bidi-string-mark-left-to-right}, described below, comes
+in handy for this purpose. (In a right-to-left paragraph, use
+@code{U+200F}, RIGHT-TO-LEFT MARK, or @acronym{RLM}, instead.) This
+is one of the solutions recommended by
+@uref{http://www.unicode.org/reports/tr9/#Separators, the
+@acronym{UBA}}.
+
+@item
+Include the tab character in the field separator. The tab character
+plays the role of @dfn{segment separator} in the @acronym{UBA}
+reordering, whose effect is to make each field a separate segment, and
+thus reorder them separately.
+
+@cindex @code{space} display spec, and bidirectional text
+@item
+Separate fields with a @code{display} property or overlay with the
+property value of the form @code{(space . PROPS)} (@pxref{Specified
+Space}). This display specification is treated by Emacs as a
+@dfn{paragraph separator}; the text before and after the separator is
+reordered separately, which avoids the influence of any field on its
+neighboring fields.
+@end itemize
+
+@defun bidi-string-mark-left-to-right string
+This subroutine returns its argument @var{string}, possibly modified,
+such that the result can be safely concatenated with another string,
+or juxtaposed with another string in a buffer, without disrupting the
+relative layout of this string and the next one on display. If the
+string returned by this function is displayed as part of a
+left-to-right paragraph, it will always appear on display to the left
+of the text that follows it. The function works by examining the
+characters of its argument, and if any of those characters could cause
+reordering on display, the function appends the @acronym{LRM}
+character to the string. The appended @acronym{LRM} character is made
+@emph{invisible} (@pxref{Invisible Text}), to hide it on display.
+@end defun
+
+ The reordering algorithm uses the bidirectional properties of the
+characters stored as their @code{bidi-class} property
+(@pxref{Character Properties}). Lisp programs can change these
+properties by calling the @code{put-char-code-property} function.
+However, doing this requires a thorough understanding of the
+@acronym{UBA}, and is therefore not recommended. Any changes to the
+bidirectional properties of a character have global effect: they
+affect all Emacs frames and windows.
+
+ Similarly, the @code{mirroring} property is used to display the
+appropriate mirrored character in the reordered text. Lisp programs
+can affect the mirrored display by changing this property. Again, any
+such changes affect all of Emacs display.
+
+@node Glyphless Chars
+@section Glyphless Character Display
+@cindex glyphless characters
+
+ @dfn{Glyphless characters} are not displayed in the usual way when
+they appear in a buffer, but in some special way (e.g. as a box
+containing a hexadecimal code). These include characters that cannot
+be displayed with any available font (on a graphical display), or that
+cannot be encoded by the terminal's coding system (on a text-only
+terminal). Specific characters can also be defined to be glyphless.
+
+@defvar glyphless-char-display
+The value of this variable is a char-table that defines glyphless
+characters and how they are displayed. If an entry is @code{nil}, the
+corresponding character is displayed in its usual way. Otherwise, an
+entry should be one of the following display methods:
+
+@table @asis
+@item @code{zero-width}
+Don't display the character.
+
+@item @code{thin-space}
+Display a thin space, 1-pixel wide on graphical displays, or
+1-character wide on text-only terminals.
+
+@item @code{empty-box}
+Display an empty box.
+
+@item @code{hex-code}
+Display a box containing the Unicode codepoint of the character, in
+hexadecimal notation.
+
+@item an @acronym{ASCII} string
+Display a box containing that string.
+@end table
+
+@noindent
+Except for @code{zero-width}, these methods display using the
+@code{glyphless-char} face.
+
+An entry can also be a cons cell @code{(@var{graphical}
+. @var{text})}, where @var{graphical} and @var{text} are the display
+methods on graphical displays and text-only terminals respectively.
+
+The char-table has one extra slot, which determines how to display any
+character that cannot be displayed with any available font, or cannot
+be encoded by the terminal's coding system. Its value should be one
+of the above display methods, except @code{zero-width} or a cons cell.
+@end defvar
+
+@defopt glyphless-char-display-control
+This user option provides a convenient way to set
+@code{glyphless-char-display} for groups of similar characters. It
+takes effect via a custom @code{:set} function (@pxref{Variable
+Definitions}), which update @code{glyphless-char-display}.
+
+Its value should be an alist of elements @code{(@var{group}
+. @var{method})}, where @var{group} is a symbol specifying a group of
+characters, and @var{method} is a symbol specifying how to display
+them.
+
+@var{group} should be one of the following:
+
+@table @code
+@item c0-control
+@acronym{ASCII} control characters @code{U+0000} to @code{U+001F},
+excluding the newline and tab characters (normally displayed as escape
+sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed,
+emacs, The GNU Emacs Manual}).
+
+@item c1-control
+Non-@acronym{ASCII}, non-printing characters @code{U+0080} to
+@code{U+009F} (normally displayed as octal escape sequences like
+@samp{\230}).
+
+@item format-control
+Characters of Unicode General Category `Cf', such as @samp{U+200E}
+(Left-to-Right Mark), but excluding characters that have graphic
+images, such as @samp{U+00AD} (Soft Hyphen).
+
+@item no-font
+Characters for there is no suitable font, or which cannot be encoded
+by the terminal's coding system.
+@end table
+
+@c FIXME: this can also be `acronym', but that's not currently
+@c completely implemented; it applies only to the format-control
+@c group, and only works if the acronym is in `char-acronym-table'.
+The @var{method} symbol should be one of @code{zero-width},
+@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have
+the same meanings as in @code{glyphless-char-display}, above.
+@end defopt
HCoop / bpt / emacs.git / blobdiff