/[emacs]/emacs/lispref/display.texi
ViewVC logotype

Diff of /emacs/lispref/display.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.83 by rms, Tue Jun 11 19:27:43 2002 UTC revision 1.83.2.1 by miles, Fri Apr 4 06:20:41 2003 UTC
# Line 1  Line 1 
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
# Line 339  text property (@pxref{Text Properties}) Line 339  text property (@pxref{Text Properties})
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
# Line 387  by a visible newline, it displays an ell Line 389  by a visible newline, it displays an ell
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)
# Line 477  effect is seen only within Emacs. Line 483  effect is seen only within Emacs.
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
# Line 1330  kind of customization item (@pxref{Custo Line 1336  kind of customization item (@pxref{Custo
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
# Line 1382  What kinds of colors the frame supports- Line 1388  What kinds of colors the frame supports-
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
# Line 1467  set width.  This should be one of the sy Line 1473  set width.  This should be one of the sy
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},
# Line 1493  the terminal supports the feature. Line 1499  the terminal supports the feature.
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    
# Line 1643  Thus, Line 1649  Thus,
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    
# Line 1654  to the corresponding values. Line 1660  to the corresponding values.
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}).
# Line 1662  that means the selected frame (@pxref{In Line 1668  that means the selected frame (@pxref{In
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
# Line 1674  For example, Line 1694  For 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
# Line 1738  specify @var{frame}, they refer to the d Line 1773  specify @var{frame}, they refer to the d
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
# Line 1803  With a region that is active.  In Transi Line 1852  With a region that is active.  In Transi
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    
# Line 2236  they mean. Line 2285  they mean.
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
# Line 2272  character, multiplied by @var{factor}. Line 2321  character, multiplied by @var{factor}.
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
# Line 2416  Thus, you can make changes take effect b Line 2465  Thus, you can make changes take effect b
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    
# Line 2867  example: Line 2916  example:
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
# Line 3337  are defined in the library @file{disp-ta Line 3386  are defined in the library @file{disp-ta
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:
# Line 3360  but not under a window system. Line 3428  but not under a window system.
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

Legend:
Removed from v.1.83  
changed lines
  Added in v.1.83.2.1

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26