@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/display
@node Display, System Interface, Processes, Top
* 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
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
* Replacing Specs:: Display specs that replace the text.
* Specified Space:: Displaying one space with a specified width.
* Pixel Specification:: Specifying space width or height in pixels.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
- up or down on the page; adjusting the width
- of spaces within text.
+* Other Display Specs:: Displaying an image; adjusting the height,
+ spacing, and other properties of text.
* Display Margins:: Displaying text or images to the side of the main text.
@end menu
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
but it is done as a special case of marginal display (@pxref{Display
Margins}).
+@item (left-fringe @var{bitmap} @r{[}@var{face}@r{]})
+@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, 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})
This display specification affects all the space characters within the
text that has the specification. It displays all of these spaces
Emacs can display a number of different image formats; some of them
are supported only if particular support libraries are installed on
-your machine. In some environments, Emacs can load image
-libraries on demand; if so, the variable @code{image-library-alist}
-can be used to modify the set of known names for these dynamic
-libraries (though it is not possible to add new image formats).
+your machine. In some environments, Emacs can load support libraries
+on demand; if so, the variable @code{dynamic-library-alist}
+(@pxref{Dynamic Libraries}) can be used to modify the set of known
+names for these dynamic libraries (though it is not possible to add
+new image formats). Note that image types @code{pbm} and @code{xbm}
+do not depend on external libraries and are always available in Emacs.
The supported image formats include XBM, XPM (this requires the
libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
@code{image-type-available-p}.
@end defvar
-@defvar image-library-alist
-This in an alist of image types vs external libraries needed to
-display them.
-
-Each element is a list @code{(@var{image-type} @var{library}...)},
-where the car is a supported image format from @code{image-types}, and
-the rest are strings giving alternate filenames for the corresponding
-external libraries to load.
-
-Emacs tries to load the libraries in the order they appear on the
-list; if none is loaded, the running session of Emacs won't support
-the image type. @code{pbm} and @code{xbm} don't need to be listed;
-they're always supported.
-
-This variable is ignored if the image libraries are statically linked
-into Emacs.
-@end defvar
-
@defun image-type-available-p type
This function returns non-@code{nil} if image type @var{type} is
available, i.e., if images of this type can be loaded and displayed in
@tex
$$\pmatrix{1 & 0 & 0 \cr
0& 0 & 0 \cr
- 9 & 9 & -1 \cr}$$
+ 0 & 0 & -1 \cr}$$
@end tex
@end iftex
@ifnottex
@display
(1 0 0
0 0 0
- 9 9 -1)
+ 0 0 -1)
@end display
@end ifnottex
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
button actually part of the text instead of being a property of the
buffer. Buttons using text properties do not create markers into the
buffer, which is important for speed when you use extremely large
-numbers of buttons. Both functions return the position of the start
-of the new button:
+numbers of buttons. (However, if there is an existing face text
+property at the site of the button, the button face may not be visible.)
+Both functions return the position of the start of the new button:
@defun make-text-button beg end &rest properties
This makes a button from @var{beg} to @var{end} in the current buffer, using
Typically, you define an ewoc with @code{ewoc-create}, and then pass
the resulting ewoc structure to other functions in the Ewoc package to
build nodes within it, and display it in the buffer. Once it is
-displayed in the buffer, other functions determine the correspondance
+displayed in the buffer, other functions determine the correspondence
between buffer positions and nodes, move point from one node's textual
representation to another, and so forth. @xref{Abstract Display
Functions}.
(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)
table can specify a glyph to use instead of @samp{\}.)
@item
-Multibyte character codes above 256 are displayed as themselves, or as a
-question mark or empty box if the terminal cannot display that
-character.
+Multibyte character codes above 256 are displayed as themselves, or as
+a question mark or a hex code or an empty box if the terminal cannot
+display that character.
@end itemize
The usual display conventions apply even when there is a display
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
one documented for the variable @code{window-system} above.
@end defun
+ Do @emph{not} use @code{window-system} and
+@code{initial-window-system} as predicates or boolean flag variables,
+if you want to write code that works differently on text terminals and
+graphic displays. That is because @code{window-system} is not a good
+indicator of Emacs capabilities on a given display type. Instead, use
+@code{display-graphic-p} or any of the other @code{display-*-p}
+predicates described in @ref{Display Feature Testing}.
+
@defvar window-setup-hook
This variable is a normal hook which Emacs runs after handling the
initialization files. Emacs runs this hook after it has completed
interfere with it.
@end defvar
-@ignore
- arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6
-@end ignore
+@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 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
+ 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.
+
+ 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
+ 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}.
+@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.
+@end defun
HCoop / bpt / emacs.git / blobdiff