* Display Tables:: How to specify other conventions.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
+* Bidirectional Display:: Display of bidirectional scripts, such as
+ Arabic and Farsi.
@end menu
@node Refresh Screen
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.
Attributes}.
@item
-A cons cell, either of the form @code{(foreground-color . @var{color-name})} or
-@code{(background-color . @var{color-name})}. These elements specify
-just the foreground color or just the background color.
+A cons cell, of the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}. These elements
+specify just the foreground color or just the background color.
@code{(foreground-color . @var{color-name})} has the same effect as
@code{(:foreground @var{color-name})}; likewise for the background.
@item mouse-face
@kindex mouse-face @r{(overlay property)}
This property is used instead of @code{face} when the mouse is within
-the range of the overlay.
+the range of the overlay. However, Emacs ignores all face attributes
+from this property that alter the text size (e.g. @code{:height},
+@code{:weight}, and @code{:slant}). Those attributes are always the
+same as in the unhighlighted text.
@item display
@kindex display @r{(overlay property)}
@cindex faces
A @dfn{face} is a collection of graphical attributes for displaying
-text: font family, foreground color, background color, optional
-underlining, and so on. Faces control how buffer text is displayed,
-and how some parts of the frame, such as the mode-line, are displayed.
+text: font, foreground color, background color, optional underlining,
+and so on. Faces control how buffer text is displayed, and how some
+parts of the frame, such as the mode-line, are displayed.
@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of
faces Emacs normally comes with.
@table @code
@item :family
-Font family name or fontset name (a string). If you specify a font
-family name, the wild-card characters @samp{*} and @samp{?} are
-allowed. The function @code{font-family-list}, described below,
-returns a list of available family names. @xref{Fontsets}, for
-information about fontsets.
+Font family or fontset (a string). @xref{Fonts,,, emacs, The GNU
+Emacs Manual}. If you specify a font family name, the wild-card
+characters @samp{*} and @samp{?} are allowed. The function
+@code{font-family-list}, described below, returns a list of available
+family names. @xref{Fontsets}, for information about fontsets.
@item :foundry
-The name of the @dfn{font foundry} in which the font family specified
-by the @code{:family} attribute is located (a string). The wild-card
-characters @samp{*} and @samp{?} are allowed.
+The name of the @dfn{font foundry} for the font family specified by
+the @code{:family} attribute (a string). The wild-card characters
+@samp{*} and @samp{?} are allowed. @xref{Fonts,,, emacs, The GNU
+Emacs Manual}.
@item :width
Relative proportionate character width, also known as the character
@item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
This way you can explicitly specify all aspects of the box. The value
-@var{width} specifies the width of the lines to draw; it defaults to 1.
+@var{width} specifies the width of the lines to draw; it defaults to
+1. A negative width @var{-n} means to draw a line of width @var{n}
+that occupies the space of the underlying text, thus avoiding any
+increase in the character height or width.
The value @var{color} specifies the color to draw with. The default is
the foreground color of the face for simple boxes, and the background
Before Emacs can draw a character on a particular display, it must
select a @dfn{font} for that character@footnote{In this context, the
term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
-Mode}).}. Normally, Emacs automatically chooses a font based on the
-faces assigned to that character---specifically, the face attributes
-@code{:family}, @code{:weight}, @code{:slant}, and @code{:width}
-(@pxref{Face Attributes}). The choice of font also depends on the
-character to be displayed; some fonts can only display a limited set
-of characters. If no available font exactly fits the requirements,
-Emacs looks for the @dfn{closest matching font}. The variables in
-this section control how Emacs makes this selection.
+Mode}).}. @xref{Fonts,,, emacs, The GNU Emacs Manual}. Normally,
+Emacs automatically chooses a font based on the faces assigned to that
+character---specifically, the face attributes @code{:family},
+@code{:weight}, @code{:slant}, and @code{:width} (@pxref{Face
+Attributes}). The choice of font also depends on the character to be
+displayed; some fonts can only display a limited set of characters.
+If no available font exactly fits the requirements, Emacs looks for
+the @dfn{closest matching font}. The variables in this section
+control how Emacs makes this selection.
@defopt face-font-family-alternatives
If a given family is specified but does not exist, this variable
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
and height of the current face. An image specification @code{image}
corresponds to the width or height of the image.
- The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
-@code{right-margin}, @code{scroll-bar}, and @code{text} elements
-specify to the width of the corresponding area of the window.
+ The elements @code{left-fringe}, @code{right-fringe},
+@code{left-margin}, @code{right-margin}, @code{scroll-bar}, and
+@code{text} specify to the width of the corresponding area of the
+window.
The @code{left}, @code{center}, and @code{right} positions can be
used with @code{:align-to} to specify a position relative to the left
@itemx (right-fringe @var{bitmap} @r{[}@var{face}@r{]})
This display specification on any character of a line of text causes
the specified @var{bitmap} be displayed in the left or right fringes
-for that line. The optional @var{face} specifies the colors to be
+for that line, instead of the characters that have the display
+specification. The optional @var{face} specifies the colors to be
used for the bitmap. @xref{Fringe Bitmaps}, for the details.
@item (space-width @var{factor})
found, don't signal an error. Instead, return a list of directories as
before, except that @code{nil} appears in place of the image directory.
-Here is an example that uses a common idiom to provide compatibility
-with versions of Emacs that lack the variable @code{image-load-path}:
+Here is an example of using @code{image-load-path-for-library}:
@example
(defvar image-load-path) ; shush compiler
(let* ((load-path (image-load-path-for-library
- "mh-e" "mh-logo.xpm"))
+ "mh-e" "mh-logo.xpm"))
(image-load-path (cons (car load-path)
- (when (boundp 'image-load-path)
- image-load-path))))
+ image-load-path)))
(mh-tool-bar-folder-buttons-init))
@end example
@end defun
Property}.
@end defun
+@cindex slice, image
+@cindex image slice
@defun insert-sliced-image image &optional string area rows cols
This function inserts @var{image} in the current buffer at point, like
@code{insert-image}, but splits the image into @var{rows}x@var{cols}
equally sized slices.
+
+If an image is inserted ``sliced'', then the Emacs display engine will
+treat each slice as a separate image, and allow more intuitive
+scrolling up/down, instead of jumping up/down the entire image when
+paging through a buffer that displays (large) images.
@end defun
@defun put-image image pos &optional string area
(aref colorcomp-data 2)))
(samp " (sample text) "))
(insert "Color\t: "
- (propertize samp 'face `(foreground-color . ,cstr))
- (propertize samp 'face `(background-color . ,cstr))
+ (propertize samp 'face
+ `(foreground-color . ,cstr))
+ (propertize samp 'face
+ `(background-color . ,cstr))
"\n"))))
(defun colorcomp (color)
concerned; the individual Emacs windows are not known to X at all.
@defvar window-system
-This frame-local variable tells Lisp programs what window system Emacs is using
-for displaying the frame. The possible values are
+This terminal-local variable tells Lisp programs what window system
+Emacs is using for displaying the frame. The possible values are
@table @code
@item x
the window system, and creating the initial window. Users should not
interfere with it.
@end defvar
+
+@node Bidirectional Display
+@section Bidirectional Display
+@cindex bidirectional display
+@cindex right-to-left text
+
+ Emacs can display text written in scripts, such as Arabic, Farsi,
+and Hebrew, whose natural ordering of horizontal text for display is
+from right to left. However, digits and Latin text embedded in these
+scripts are still displayed left to right. It is also not uncommon to
+have small portions of text in Arabic or Hebrew embedded in otherwise
+Latin document, e.g., as comments and strings in a program source
+file. Likewise, small portions of Latin text can be embedded in an
+Arabic or Farsi document. For these reasons, text that uses these
+scripts is actually @dfn{bidirectional}: a mixture of runs of
+left-to-right and right-to-left characters.
+
+ This section describes the facilities and options provided by Emacs
+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
+@dfn{logical} (or @dfn{reading}) order: the buffer or string position
+of the first character you read precedes that of the next character.
+Reordering of bidirectional text into the @dfn{visual} order happens
+at display time. As result, character positions no longer increase
+monotonically with their positions on display. Emacs implements the
+Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}) described in
+the Unicode Standard Annex #9, for reordering of bidirectional text
+for display. Reordering of bidirectional text for display in Emacs is
+a ``Full bidirectionality'' class implementation of the @acronym{UBA}.
+
+@defvar bidi-display-reordering
+ 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
+(@pxref{Header Lines}), is controlled by the default value of
+@code{bidi-display-reordering}.
+@end defvar
+
+@cindex unibyte buffers, and bidi reordering
+ Emacs does not reorder text in unibyte buffers, even if
+@code{bidi-display-reordering} is non-@code{nil} in such a buffer.
+This is because unibyte buffers contain raw bytes, not characters, and
+thus don't have bidirectional properties defined for them which are
+required for correct reordering. Therefore, to test whether text in a
+buffer will be reordered for display, it is not enough to test the
+value of @code{bidi-display-reordering} alone. The correct test is
+this:
+
+@example
+ (if (and enable-multibyte-characters
+ bidi-display-reordering)
+ ;; Buffer is being reordered for display
+ )
+@end example
+
+ In contrast to unibyte buffers, unibyte display and overlay strings
+@emph{are} reordered, if their parent buffer is reordered. This is
+because plain-@sc{ascii} strings are stored by Emacs as unibyte
+strings. If a unibyte display or overlay string includes
+non-@sc{ascii} characters, these characters are assumed to have
+left-to-right direction.
+
+@cindex display properties, and bidi reordering of text
+ Text covered by @code{display} text properties, by overlays with
+@code{display} properties whose value is a string, and by any other
+properties that replace buffer text, is treated as a single unit when
+it is reordered for display. That is, the entire chunk of text
+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
+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
+properties on text whose directionality is identical with text that
+surrounds it.
+
+@cindex base direction of a paragraph
+ Each paragraph of bidirectional text can have its own @dfn{base
+direction}, either right-to-left or left-to-right. Text in
+left-to-right paragraphs is displayed beginning at the left margin of
+the window and is truncated or continued when it reaches the right
+margin. By contrast, display of text in right-to-left paragraphs
+begins at the right margin and is continued or truncated at the left
+margin.
+
+@defvar bidi-paragraph-direction
+ 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
+base direction for its paragraphs. For example, a buffer that visits
+a source code of a program should force all its paragraphs to be
+displayed left to right. The variable
+@code{bidi-paragraph-direction}, if non-@code{nil}, disables the
+dynamic determination of the base direction, and instead forces all
+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
+This function returns the paragraph direction at point in the named
+@var{buffer}. The returned value is a symbol, either
+@code{left-to-right} or @code{right-to-left}. If @var{buffer} is
+omitted or @code{nil}, it defaults to the current buffer. If the
+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. 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.
HCoop / bpt / emacs.git / blobdiff