1 |
@c -*-texinfo-*- |
@c -*-texinfo-*- |
2 |
@c This is part of the GNU Emacs Lisp Reference Manual. |
@c This is part of the GNU Emacs Lisp Reference Manual. |
3 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, 2002 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, 2002 |
4 |
@c Free Software Foundation, Inc. |
@c Free Software Foundation, Inc. |
5 |
@c See the file elisp.texi for copying conditions. |
@c See the file elisp.texi for copying conditions. |
6 |
@setfilename ../info/display |
@setfilename ../info/display |
7 |
@node Display, Calendar, Processes, Top |
@node Display, Calendar, Processes, Top |
339 |
In the simplest case, any non-@code{nil} @code{invisible} property makes |
In the simplest case, any non-@code{nil} @code{invisible} property makes |
340 |
a character invisible. This is the default case---if you don't alter |
a character invisible. This is the default case---if you don't alter |
341 |
the default value of @code{buffer-invisibility-spec}, this is how the |
the default value of @code{buffer-invisibility-spec}, this is how the |
342 |
@code{invisible} property works. |
@code{invisible} property works. You should normally use @code{t} |
343 |
|
as the value of the @code{invisible} property if you don't plan |
344 |
|
to set @code{buffer-invisibility-spec} yourself. |
345 |
|
|
346 |
More generally, you can use the variable @code{buffer-invisibility-spec} |
More generally, you can use the variable @code{buffer-invisibility-spec} |
347 |
to control which values of the @code{invisible} property make text |
to control which values of the @code{invisible} property make text |
389 |
@code{buffer-invisibility-spec} and removing elements from it. |
@code{buffer-invisibility-spec} and removing elements from it. |
390 |
|
|
391 |
@defun add-to-invisibility-spec element |
@defun add-to-invisibility-spec element |
392 |
Add the element @var{element} to @code{buffer-invisibility-spec} |
This function adds the element @var{element} to |
393 |
(if it is not already present in that list). |
@code{buffer-invisibility-spec} (if it is not already present in that |
394 |
|
list). If @code{buffer-invisibility-spec} was @code{t}, it changes to |
395 |
|
a list, @code{(t)}, so that text whose @code{invisible} property |
396 |
|
is @code{t} remains invisible. |
397 |
@end defun |
@end defun |
398 |
|
|
399 |
@defun remove-from-invisibility-spec element |
@defun remove-from-invisibility-spec element |
400 |
Remove the element @var{element} from @code{buffer-invisibility-spec}. |
This removeds the element @var{element} from |
401 |
This does nothing if @var{element} is not in the list. |
@code{buffer-invisibility-spec}. This does nothing if @var{element} |
402 |
|
is not in the list. |
403 |
@end defun |
@end defun |
404 |
|
|
405 |
One convention about the use of @code{buffer-invisibility-spec} is |
A convention for use of @code{buffer-invisibility-spec} is that a |
406 |
that a major mode should use the mode's own name as an element of |
major mode should use the mode's own name as an element of |
407 |
@code{buffer-invisibility-spec} and as the value of the @code{invisible} |
@code{buffer-invisibility-spec} and as the value of the |
408 |
property: |
@code{invisible} property: |
409 |
|
|
410 |
@example |
@example |
411 |
;; @r{If you want to display an ellipsis:} |
;; @r{If you want to display an ellipsis:} |
412 |
(add-to-invisibility-spec '(my-symbol . t)) |
(add-to-invisibility-spec '(my-symbol . t)) |
413 |
;; @r{If you don't want ellipsis:} |
;; @r{If you don't want ellipsis:} |
414 |
(add-to-invisibility-spec 'my-symbol) |
(add-to-invisibility-spec 'my-symbol) |
415 |
|
|
416 |
(overlay-put (make-overlay beginning end) |
(overlay-put (make-overlay beginning end) |
417 |
'invisible 'my-symbol) |
'invisible 'my-symbol) |
483 |
|
|
484 |
@defvar selective-display |
@defvar selective-display |
485 |
This buffer-local variable enables selective display. This means that |
This buffer-local variable enables selective display. This means that |
486 |
lines, or portions of lines, may be made invisible. |
lines, or portions of lines, may be made invisible. |
487 |
|
|
488 |
@itemize @bullet |
@itemize @bullet |
489 |
@item |
@item |
1336 |
customize using the Customization buffer (@pxref{Easy Customization,,, |
customize using the Customization buffer (@pxref{Easy Customization,,, |
1337 |
emacs, The GNU Emacs Manual}). |
emacs, The GNU Emacs Manual}). |
1338 |
|
|
1339 |
@defmac defface face spec doc [keyword value]... |
@defmac defface face spec doc [keyword value]... |
1340 |
This declares @var{face} as a customizable face that defaults according |
This declares @var{face} as a customizable face that defaults according |
1341 |
to @var{spec}. You should not quote the symbol @var{face}. The |
to @var{spec}. You should not quote the symbol @var{face}. The |
1342 |
argument @var{doc} specifies the face documentation. The keywords you |
argument @var{doc} specifies the face documentation. The keywords you |
1388 |
The kind of background---either @code{light} or @code{dark}. |
The kind of background---either @code{light} or @code{dark}. |
1389 |
|
|
1390 |
@item supports |
@item supports |
1391 |
Whether or not the frame can display the face attributes (@pxref{Face |
Whether or not the frame can display the face attributes given in |
1392 |
Attributes}) given in @var{value}@dots{}. See the documentation for |
@var{value}@dots{} (@pxref{Face Attributes}). See the documentation |
1393 |
the function @code{display-supports-face-attributes-p} (@pxref{Display |
for the function @code{display-supports-face-attributes-p} for more |
1394 |
Face Attribute Testing}) for more information on exactly how this testing |
information on exactly how this testing is done. @xref{Display Face |
1395 |
is done. |
Attribute Testing}. |
1396 |
@end table |
@end table |
1397 |
|
|
1398 |
If an element of @var{display} specifies more than one @var{value} for a |
If an element of @var{display} specifies more than one @var{value} for a |
1473 |
@code{extra-condensed}, @code{condensed}, @code{semi-condensed}, |
@code{extra-condensed}, @code{condensed}, @code{semi-condensed}, |
1474 |
@code{normal}, @code{semi-expanded}, @code{expanded}, |
@code{normal}, @code{semi-expanded}, @code{expanded}, |
1475 |
@code{extra-expanded}, or @code{ultra-expanded}. |
@code{extra-expanded}, or @code{ultra-expanded}. |
1476 |
|
|
1477 |
@item :height |
@item :height |
1478 |
Either the font height, an integer in units of 1/10 point, a floating |
Either the font height, an integer in units of 1/10 point, a floating |
1479 |
point number specifying the amount by which to scale the height of any |
point number specifying the amount by which to scale the height of any |
1480 |
underlying face, or a function, which is called with the old height |
underlying face, or a function, which is called with the old height |
1481 |
(from the underlying face), and should return the new height. |
(from the underlying face), and should return the new height. |
1482 |
|
|
1483 |
@item :weight |
@item :weight |
1484 |
Font weight---a symbol from this series (from most dense to most faint): |
Font weight---a symbol from this series (from most dense to most faint): |
1485 |
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, |
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, |
1499 |
|
|
1500 |
@item :foreground |
@item :foreground |
1501 |
Foreground color, a string. |
Foreground color, a string. |
1502 |
|
|
1503 |
@item :background |
@item :background |
1504 |
Background color, a string. |
Background color, a string. |
1505 |
|
|
1649 |
|
|
1650 |
@example |
@example |
1651 |
(set-face-attribute 'foo nil |
(set-face-attribute 'foo nil |
1652 |
:width :extended |
:width 'extended |
1653 |
:weight :bold |
:weight 'bold |
1654 |
:underline "red") |
:underline "red") |
1655 |
@end example |
@end example |
1656 |
|
|
1660 |
@end defun |
@end defun |
1661 |
|
|
1662 |
@tindex face-attribute |
@tindex face-attribute |
1663 |
@defun face-attribute face attribute &optional frame |
@defun face-attribute face attribute &optional frame inherit |
1664 |
This returns the value of the @var{attribute} attribute of face |
This returns the value of the @var{attribute} attribute of face |
1665 |
@var{face} on @var{frame}. If @var{frame} is @code{nil}, |
@var{face} on @var{frame}. If @var{frame} is @code{nil}, |
1666 |
that means the selected frame (@pxref{Input Focus}). |
that means the selected frame (@pxref{Input Focus}). |
1668 |
If @var{frame} is @code{t}, the value is the default for |
If @var{frame} is @code{t}, the value is the default for |
1669 |
@var{face} for new frames. |
@var{face} for new frames. |
1670 |
|
|
1671 |
|
If @var{inherit} is nil, only attributes directly defined by |
1672 |
|
@var{face} are considered, so the return value may be |
1673 |
|
@code{unspecified}, or a relative value. If @var{inherit} is non-nil, |
1674 |
|
@var{face}'s definition of @var{attribute} is merged with the faces |
1675 |
|
specified by its @code{:inherit} attribute; however the return value |
1676 |
|
may still be @code{unspecified} or relative. If @var{inherit} is a |
1677 |
|
face or a list of faces, then the result is further merged with that |
1678 |
|
face (or faces), until it becomes specified and absolute. |
1679 |
|
|
1680 |
|
To ensure that the return value is always specified and absolute, use |
1681 |
|
a value of @code{default} for @var{inherit}; this will resolve any |
1682 |
|
unspecified or relative values by merging with the @code{default} face |
1683 |
|
(which is always completely specified). |
1684 |
|
|
1685 |
For example, |
For example, |
1686 |
|
|
1687 |
@example |
@example |
1694 |
with older Emacs versions, you can use the following functions to set |
with older Emacs versions, you can use the following functions to set |
1695 |
and examine the face attributes which existed in those versions. |
and examine the face attributes which existed in those versions. |
1696 |
|
|
1697 |
|
@tindex face-attribute-relative-p |
1698 |
|
@defun face-attribute-relative-p attribute value |
1699 |
|
This function returns non-@code{nil} if @var{value}, when used as a |
1700 |
|
the value of the face attribute @var{attribute}, is relative (that is, |
1701 |
|
if it modifies an underlying or inherited value of @var{attribute}). |
1702 |
|
@end defun |
1703 |
|
|
1704 |
|
@tindex merge-face-attribute |
1705 |
|
@defun merge-face-attribute attribute value1 value2 |
1706 |
|
If @var{value1} is a relative value for the face attribute |
1707 |
|
@var{attribute}, returns it merged with the underlying value |
1708 |
|
@var{value2}; otherwise, if @var{value1} is an absolute value for the |
1709 |
|
face a attribute @var{attribute}, returns @var{value1} unchanged. |
1710 |
|
@end defun |
1711 |
|
|
1712 |
@defun set-face-foreground face color &optional frame |
@defun set-face-foreground face color &optional frame |
1713 |
@defunx set-face-background face color &optional frame |
@defunx set-face-background face color &optional frame |
1714 |
These functions set the foreground (or background, respectively) color |
These functions set the foreground (or background, respectively) color |
1773 |
They return the symbol @code{unspecified} if the face doesn't define any |
They return the symbol @code{unspecified} if the face doesn't define any |
1774 |
value for that attribute. |
value for that attribute. |
1775 |
|
|
1776 |
@defun face-foreground face &optional frame |
@defun face-foreground face &optional frame inherit |
1777 |
@defunx face-background face &optional frame |
@defunx face-background face &optional frame |
1778 |
These functions return the foreground color (or background color, |
These functions return the foreground color (or background color, |
1779 |
respectively) of face @var{face}, as a string. |
respectively) of face @var{face}, as a string. |
1780 |
|
|
1781 |
|
If @var{inherit} is nil, only a color directly defined by the face is |
1782 |
|
returned. If @var{inherit} is non-nil, any faces specified by its |
1783 |
|
@code{:inherit} attribute are considered as well, and if @var{inherit} |
1784 |
|
is a face or a list of faces, then they are also considered, until a |
1785 |
|
specified color is found. To ensure that the return value is always |
1786 |
|
specified, use a value of @code{default} for @var{inherit}. |
1787 |
@end defun |
@end defun |
1788 |
|
|
1789 |
@defun face-stipple face &optional frame |
@defun face-stipple face &optional frame inherit |
1790 |
This function returns the name of the background stipple pattern of face |
This function returns the name of the background stipple pattern of face |
1791 |
@var{face}, or @code{nil} if it doesn't have one. |
@var{face}, or @code{nil} if it doesn't have one. |
1792 |
|
|
1793 |
|
If @var{inherit} is nil, only a stipple directly defined by the face |
1794 |
|
is returned. If @var{inherit} is non-nil, any faces specified by its |
1795 |
|
@code{:inherit} attribute are considered as well, and if @var{inherit} |
1796 |
|
is a face or a list of faces, then they are also considered, until a |
1797 |
|
specified stipple is found. To ensure that the return value is always |
1798 |
|
specified, use a value of @code{default} for @var{inherit}. |
1799 |
@end defun |
@end defun |
1800 |
|
|
1801 |
@defun face-font face &optional frame |
@defun face-font face &optional frame |
1852 |
highlighted with the face @code{region} (@pxref{Standard Faces}). |
highlighted with the face @code{region} (@pxref{Standard Faces}). |
1853 |
|
|
1854 |
@item |
@item |
1855 |
With special glyphs. Each glyph can specify a particular face |
With special glyphs. Each glyph can specify a particular face |
1856 |
number. @xref{Glyphs}. |
number. @xref{Glyphs}. |
1857 |
@end itemize |
@end itemize |
1858 |
|
|
2285 |
@menu |
@menu |
2286 |
* Specified Space:: Displaying one space with a specified width. |
* Specified Space:: Displaying one space with a specified width. |
2287 |
* Other Display Specs:: Displaying an image; magnifying text; moving it |
* Other Display Specs:: Displaying an image; magnifying text; moving it |
2288 |
up or down on the page; adjusting the width |
up or down on the page; adjusting the width |
2289 |
of spaces within text. |
of spaces within text. |
2290 |
* Display Margins:: Displaying text or images to the side of the main text. |
* Display Margins:: Displaying text or images to the side of the main text. |
2291 |
* Conditional Display:: Making any of the above features conditional |
* Conditional Display:: Making any of the above features conditional |
2321 |
@item :align-to @var{hpos} |
@item :align-to @var{hpos} |
2322 |
Specifies that the space should be wide enough to reach @var{hpos}. The |
Specifies that the space should be wide enough to reach @var{hpos}. The |
2323 |
value @var{hpos} is measured in units of the normal character width. It |
value @var{hpos} is measured in units of the normal character width. It |
2324 |
may be an interer or a floating point number. |
may be an integer or a floating point number. |
2325 |
@end table |
@end table |
2326 |
|
|
2327 |
You should use one and only one of the above properties. You can |
You should use one and only one of the above properties. You can |
2465 |
@defun set-window-margins window left &optional right |
@defun set-window-margins window left &optional right |
2466 |
@tindex set-window-margins |
@tindex set-window-margins |
2467 |
This function specifies the margin widths for window @var{window}. |
This function specifies the margin widths for window @var{window}. |
2468 |
The argument @var{left} controls the left margin and |
The argument @var{left} controls the left margin and |
2469 |
@var{right} controls the right margin (default @code{0}). |
@var{right} controls the right margin (default @code{0}). |
2470 |
@end defun |
@end defun |
2471 |
|
|
2916 |
|
|
2917 |
@example |
@example |
2918 |
(defimage test-image |
(defimage test-image |
2919 |
'((:type xpm :file "~/test1.xpm") |
((:type xpm :file "~/test1.xpm") |
2920 |
(:type xbm :file "~/test1.xbm"))) |
(:type xbm :file "~/test1.xbm"))) |
2921 |
@end example |
@end example |
2922 |
|
|
2923 |
@code{defimage} tests each argument, one by one, to see if it is |
@code{defimage} tests each argument, one by one, to see if it is |
3386 |
@cindex glyph |
@cindex glyph |
3387 |
A @dfn{glyph} is a generalization of a character; it stands for an |
A @dfn{glyph} is a generalization of a character; it stands for an |
3388 |
image that takes up a single character position on the screen. Glyphs |
image that takes up a single character position on the screen. Glyphs |
3389 |
are represented in Lisp as integers, just as characters are. |
are represented in Lisp as integers, just as characters are. Normally |
3390 |
|
Emacs finds glyphs in the display table (@pxref{Display Tables}). |
3391 |
|
|
3392 |
@cindex glyph table |
A glyph can be @dfn{simple} or it can be defined by the @dfn{glyph |
3393 |
The meaning of each integer, as a glyph, is defined by the glyph |
table}. A simple glyph is just a way of specifying a character and a |
3394 |
table, which is the value of the variable @code{glyph-table}. |
face to output it in. The glyph code for a simple glyph, mod 524288, |
3395 |
|
is the character to output, and the glyph code divided by 524288 |
3396 |
|
specifies the face number (@pxref{Face Functions}) to use while |
3397 |
|
outputting it. (524288 is |
3398 |
|
@ifnottex |
3399 |
|
2**19.) |
3400 |
|
@end ifnottex |
3401 |
|
@tex |
3402 |
|
$2^{19}$.) |
3403 |
|
@end tex |
3404 |
|
@xref{Faces}. |
3405 |
|
|
3406 |
|
On character terminals, you can set up a @dfn{glyph table} to define |
3407 |
|
the meaning of glyph codes. The glyph codes is the value of the |
3408 |
|
variable @code{glyph-table}. |
3409 |
|
|
3410 |
@defvar glyph-table |
@defvar glyph-table |
3411 |
The value of this variable is the current glyph table. It should be a |
The value of this variable is the current glyph table. It should be a |
3412 |
vector; the @var{g}th element defines glyph code @var{g}. If the value |
vector; the @var{g}th element defines glyph code @var{g}. |
3413 |
is @code{nil} instead of a vector, then all glyphs are simple (see |
|
3414 |
below). The glyph table is not used on windowed displays. |
If a glyph code is greater than or equal to the length of the glyph |
3415 |
|
table, that code is automatically simple. If the value of |
3416 |
|
@code{glyph-table} is @code{nil} instead of a vector, then all glyphs |
3417 |
|
are simple. The glyph table is not used on graphical displays, only |
3418 |
|
on character terminals. On graphical displays, all glyphs are simple. |
3419 |
@end defvar |
@end defvar |
3420 |
|
|
3421 |
Here are the possible types of elements in the glyph table: |
Here are the possible types of elements in the glyph table: |
3428 |
|
|
3429 |
@item @var{integer} |
@item @var{integer} |
3430 |
Define this glyph code as an alias for glyph code @var{integer}. You |
Define this glyph code as an alias for glyph code @var{integer}. You |
3431 |
can use an alias to specify a face code for the glyph; see below. |
can use an alias to specify a face code for the glyph and use a small |
3432 |
|
number as its code. |
3433 |
|
|
3434 |
@item @code{nil} |
@item @code{nil} |
3435 |
This glyph is simple. The glyph code mod 524288 is the character to |
This glyph is simple. |
|
output, and the glyph code divided by 524288 specifies the face number |
|
|
(@pxref{Face Functions}) to use while outputting it. (524288 is |
|
|
@ifnottex |
|
|
2**19.) |
|
|
@end ifnottex |
|
|
@tex |
|
|
$2^{19}$.) |
|
|
@end tex |
|
|
@xref{Faces}. |
|
3436 |
@end table |
@end table |
3437 |
|
|
|
If a glyph code is greater than or equal to the length of the glyph |
|
|
table, that code is automatically simple. |
|
|
|
|
3438 |
@defun create-glyph string |
@defun create-glyph string |
3439 |
@tindex create-glyph |
@tindex create-glyph |
3440 |
This function returns a newly-allocated glyph code which is set up to |
This function returns a newly-allocated glyph code which is set up to |