/[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.127 by teirllm, Thu Sep 23 04:18:12 2004 UTC revision 1.128 by rms, Sat Sep 25 07:18:08 2004 UTC
# Line 25  that Emacs presents to the user. Line 25  that Emacs presents to the user.
25  * Faces::               A face defines a graphics style for text characters:  * Faces::               A face defines a graphics style for text characters:
26                            font, colors, etc.                            font, colors, etc.
27  * Fringes::             Controlling window fringes.  * Fringes::             Controlling window fringes.
28  * Fringe Bitmaps::      Customizing fringe bitmaps.  * Fringe Bitmaps::      Displaying bitmaps in the window fringes.
29    * Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
30  * Scroll Bars::         Controlling vertical scroll bars.  * Scroll Bars::         Controlling vertical scroll bars.
31  * Pointer Shape::       Controlling the mouse pointer shape.  * Pointer Shape::       Controlling the mouse pointer shape.
32  * Display Property::    Enabling special display features.  * Display Property::    Enabling special display features.
# Line 2599  window is used.  The value has the form Line 2600  window is used.  The value has the form
2600  @end defun  @end defun
2601    
2602  @defvar overflow-newline-into-fringe  @defvar overflow-newline-into-fringe
2603  This variable, if non-@code{nil}, specifies that lines which are  If this is non-@code{nil}, lines exactly as wide as the window (not
2604  exactly as wide as the window (not counting the final newline  counting the final newline character) are not continued.  Instead,
2605  character) shall not be broken into two lines on the display (with  when point is at the end of the line, the cursor appears in the right
2606  just the newline on the second line).  Instead, the newline now  fringe.
 overflows into the right fringe, and the cursor will be displayed in  
 the fringe when positioned on that newline.  
 @end defvar  
   
 @defvar indicate-buffer-boundaries  
 This buffer-local variable controls how the buffer boundaries and  
 window scrolling is indicated in the fringes.  
   
   The buffer boundaries, i.e. first and last line in the buffer, can be  
 marked with angle bitmaps in the left or right fringe.  This can be  
 combined with up and down arrow bitmaps shown at the top and bottom of  
 the left or right fringe if the window can be scrolled in either  
 direction.  
   
   If the value is @code{left} or @code{right}, both angle and arrow  
 bitmaps are displayed in the left or right fringe, respectively.  
 Any other non-@code{nil} value causes the bitmap on the top line to be  
 displayed in the left fringe, and the bitmap on the bottom line in the  
 right fringe.  
   
   If value is a cons @code{(angles . arrows)}, the car specifies the  
 position of the angle bitmaps, and the cdr specifies the position of  
 the arrow bitmaps.  For example, @code{(t .  right)} places the top  
 angle bitmap in left fringe, the bottom angle bitmap in right fringe,  
 and both arrow bitmaps in right fringe.  To show just the angle  
 bitmaps in the left fringe, but no arrow bitmaps, use @code{(left . nil)}.  
 @end defvar  
   
 @defvar default-indicate-buffer-boundaries  
 The value of this variable is the default value for  
 @code{indicate-buffer-boundaries} in buffers that do not override it.  
2607  @end defvar  @end defvar
2608    
2609  @node Fringe Bitmaps  @node Fringe Bitmaps
2610  @section Fringe Bitmaps  @section Fringe Bitmaps
2611  @cindex Fringe Bitmaps  @cindex fringe bitmaps
2612    @cindex bitmaps, fringe
   The @dfn{fringe bitmaps} are tiny icons Emacs displays in the fringe  
 on a window system to indicate truncated or continued lines, buffer  
 boundaries, overlay arrow, etc.  The fringe bitmaps are shared by all  
 frames and windows.  
   
   You can redefine the built-in fringe bitmaps, and you can define new  
 fringe bitmaps.  Emacs can handle a maximum of 255 different fringe  
 bitmaps.  
2613    
2614  A fringe bitmap is identified by an opaque integer, but Lisp code    The @dfn{fringe bitmaps} are tiny icons Emacs displays in the window
2615  should use the following names defined by @code{(require 'fringe)}:  fringe (on a graphic display) to indicate truncated or continued
2616    lines, buffer boundaries, overlay arrow, etc.  The fringe bitmaps are
2617    shared by all frames and windows.  You can redefine the built-in
2618    fringe bitmaps, and you can define new fringe bitmaps.  However, Emacs
2619    can handle only 255 different fringe bitmaps.
2620    
2621      The way to display a bitmap in the left or right fringes for a given
2622    line in a window is by specifying the @code{display} property for one
2623    of the characters that appears in it.  Use a display specification of
2624    the form @code{(left-fringe @var{bitmap} [@var{face}])} or
2625    @code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
2626    Property}).  Here, @var{bitmap} is an integer identifying the bitmap
2627    you want, and @var{face} (which is optional) is the name of the face
2628    whose colors should be used for displaying the bitmap.
2629    @c ??? Shouldn't the symbol name be used?
2630    
2631      These are the symbols identify the standard fringe bitmaps.
2632    Evaluate @code{(require 'fringe)} to define them.  Each symbol's
2633    value is an integer that identifies the corresponding bitmap.
2634    
2635  Truncation and continuation line bitmaps:  @table @asis
2636    @item Truncation and continuation line bitmaps:
2637  @code{left-truncation-fringe-bitmap},  @code{left-truncation-fringe-bitmap},
2638  @code{right-truncation-fringe-bitmap},  @code{right-truncation-fringe-bitmap},
2639  @code{continued-line-fringe-bitmap},  @code{continued-line-fringe-bitmap},
2640  @code{continuation-line-fringe-bitmap}.  @code{continuation-line-fringe-bitmap}.
2641    
2642  Buffer indication bitmaps:  @item Buffer indication bitmaps:
2643  @code{up-arrow-fringe-bitmap},  @code{up-arrow-fringe-bitmap},
2644  @code{down-arrow-fringe-bitmap},  @code{down-arrow-fringe-bitmap},
2645  @code{top-left-angle-fringe-bitmap},  @code{top-left-angle-fringe-bitmap},
# Line 2668  Buffer indication bitmaps: Line 2649  Buffer indication bitmaps:
2649  @code{left-bracket-fringe-bitmap},  @code{left-bracket-fringe-bitmap},
2650  @code{right-bracket-fringe-bitmap}.  @code{right-bracket-fringe-bitmap}.
2651    
2652  Empty line indication bitmap:  @item Empty line indication bitmap:
2653  @code{empty-line-fringe-bitmap}.  @code{empty-line-fringe-bitmap}.
2654    
2655  Overlay arrow bitmap:  @item Overlay arrow bitmap:
2656  @code{overlay-arrow-fringe-bitmap}.  @code{overlay-arrow-fringe-bitmap}.
2657    
2658  Bitmaps for displaying the cursor in right fringe:  @item Bitmaps for displaying the cursor in right fringe:
2659  @code{filled-box-cursor-fringe-bitmap},  @code{filled-box-cursor-fringe-bitmap},
2660  @code{hollow-box-cursor-fringe-bitmap},  @code{hollow-box-cursor-fringe-bitmap},
2661  @code{hollow-square-fringe-bitmap}, @code{bar-cursor-fringe-bitmap},  @code{hollow-square-fringe-bitmap}, @code{bar-cursor-fringe-bitmap},
2662  @code{hbar-cursor-fringe-bitmap}.  @code{hbar-cursor-fringe-bitmap}.
2663    
2664  Fringe bitmap opaque value indicating that no fringe bitmap is present:  @item Value indicating that no fringe bitmap is present:
2665  @code{no-fringe-bitmap}.  @code{no-fringe-bitmap}.
2666    @c ??? I don't understand what that means.
2667    @c ??? Where would you find that value?
2668    
2669  Fringe bitmap opaque value indicating a reference to an undefined bitmap:  @item Value indicating a reference to an undefined bitmap:
2670  @code{undef-fringe-bitmap}.  @code{undef-fringe-bitmap}.
2671    @c ??? I don't understand what that means.
2672    @c ??? Where would you find that value?
2673    @end table
2674    
2675    To display an specific fringe bitmap on a line in an Emacs window,  @defun fringe-bitmaps-at-pos &optional pos window
2676  use it as a @code{left-fringe} or @code{right-fringe} specifier in the  This function returns the fringe bitmaps of the display line
2677  @code{display} property of some text that is displayed on that line  containing position @var{pos} in window @var{window}.  The return
2678  (@pxref{Display Property}).  value has the form @code{(@var{left} . @var{right})}, where @var{left}
2679    is a list of fringe bitmap numbers for left fringe, and @var{right} is
2680    similar for the right fringe.  These bitmap numbers are usually values
2681    of symbols such as the ones listed above.
2682    
2683    @c ??? Why not return a list of symbols that identify the bitmaps?
2684    @c ??? This is Lisp, not C.
2685    
2686    The value is @code{nil} if @var{pos} is not visible in @var{window}.
2687    If @var{window} is @code{nil}, that stands for the selected window.
2688    If @var{pos} is @code{nil}, that stands for the value of point in
2689    @var{window}.
2690    @end defun
2691    
2692  @defun define-fringe-bitmap bits &optional height width align bitmap  @node Customizing Bitmaps
2693  Define a new fringe bitmap, or change an existing bitmap.  @section Customizing Fringe Bitmaps
2694    
2695  The argument @code{bits} is either a string or a vector of integers,  @c ??? Why not pass a symbol as the first argument
2696  where each element (typically) corresponds to one row of the bitmap,  @c ??? and define that symbol.  It would be cleaner.
 and each bit of an integer corresponds to one pixel of the bitmap.  
   
 The optional argument @code{height} specifies the height of the bitmap.  
 If @code{height} is @code{nil}, the length of @code{bits} is used.  
   
 The optional argument @code{width} specifies the width of the bitmap;  
 it must be an integer between 1 and 16, or @code{nil} which defaults  
 to a width of 8 pixels.  
   
 The optional argument @code{align} may be one of @code{top},  
 @code{center}, or @code{bottom}, indicating the positioning of the  
 bitmap relative to the rows where it is used; the default is to center  
 the bitmap.  
   
 The @code{align} argument may also be a list @code{(ALIGN PERIODIC)}  
 where @code{ALIGN} is intepreted as described above, and if  
 @code{PERIODIC} is non-@code{nil} it specifies that the @code{bits} should  
 be repeated until a bitmap of the specified @code{height} is created.  
2697    
2698  The optional argument @code{bitmap} specifies the opaque integer that  @defun define-fringe-bitmap bits &optional height width align bitmap
2699  identifies an existing bitmap to redefine.  This function defines a new fringe bitmap, or replaces an existing
2700    bitmap.
2701    
2702  The return value is a new opaque integer identifying the new bitmap number,  The argument @var{bits} specifies the image to use.  It should be
2703  or @code{nil} of there are no more free bitmap slots.  either a string or a vector of integers, where each element (an
2704    integer) corresponds to one row of the bitmap.  Each bit of an integer
2705    corresponds to one pixel of the bitmap.
2706    @c ??? Is the low bit the leftmost or the rightmost bit?
2707    
2708    The height is normally the length of @var{bits}.  However, you
2709    can specify a different height with non-@code{nil} @var{height}.  The width
2710    is normally 8, but you can specify a different width with non-@code{nil}
2711    @var{width}.  The width must be an integer between 1 and 16.
2712    
2713    The argument @var{align} specifies the positioning of the bitmap
2714    relative to the range of rows where it is used; the default is to
2715    center the bitmap.  The allowed values are @code{top}, @code{center},
2716    or @code{bottom}.
2717    
2718    The @var{align} argument may also be a list @code{(@var{align}
2719    @var{periodic})} where @var{align} is intepreted as described above.
2720    If @var{periodic} is non-@code{nil}, it specifies that the rows in
2721    @code{bits} should be repeated enough times to reach the specified
2722    height.
2723    
2724    The argument @var{bitmap} specifies an existing bitmap to redefine.
2725    You should pass the value of the symbol that identifies the bitmap.
2726    
2727    The return value on success is an integer identifying the new bitmap.
2728    You should save that integer in a variable so it can be used to select
2729    this bitmap.  The value can also be @code{nil} of there are no more
2730    free bitmap slots.
2731    @c ??? Why not signal an error?  That would be cleaner.
2732  @end defun  @end defun
2733    
2734  @defun destroy-fringe-bitmap bitmap  @defun destroy-fringe-bitmap bitmap
2735  Destroy the fringe bitmap identified by the opaque integer  This function destroy the fringe bitmap identified by @var{bitmap}.
2736  @code{bitmap}.  If @code{bitmap} identifies a standard fringe bitmap,  If @var{bitmap} identifies a standard fringe bitmap, it actually
2737  the original built-in bitmap is restored.  restores the standard definition of that bitmap, instead of
2738    eliminating it entirely.
2739  @end defun  @end defun
2740    
2741  @defun set-fringe-bitmap-face bitmap &optional face  @defun set-fringe-bitmap-face bitmap &optional face
2742  Set face for a specific fringe bitmap @code{bitmap} to the face  This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
2743  specified by the argument @code{face}.  If @var{face} is @code{nil}, it selects the @code{fringe} face.  The
2744  If @code{face} is @code{nil}, reset face to default @code{fringe} face.  bitmap's face controls the color to draw it in.
2745    
2746  Normally, the specified face should be a face derived from the  The face you use here should be derived from @code{fringe}, and should
2747  @code{fringe} face, only specifying the foreground color as the  specify only the foreground color.
 desired color of the fringe bitmap.  
2748  @end defun  @end defun
2749    
2750    @defvar indicate-buffer-boundaries
2751    This buffer-local variable controls how the buffer boundaries and
2752    window scrolling are indicated in the window fringes.
2753    
2754    Emacs can indicate the buffer boundaries---that is, the first and last
2755    line in the buffer---with angle icons when they appear on the screen.
2756    In addition, Emacs can display an up-arrow in the fringe to show
2757    that there is text above the screen, and a down-arrow to show
2758    there is text below the screen.
2759    
2760    There are four kinds of basic values:
2761    
2762    @table @asis
2763    @item @code{nil}
2764    Don't display the icons.
2765    @item @code{left}
2766    Display them in the left fringe.
2767    @item @code{right}
2768    Display them in the right fringe.
2769    @item @var{anything-else}
2770    Display the icon at the top of the window top in the left fringe, and other
2771    in the right fringe.
2772    @end table
2773    
2774    If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
2775    controls the angle icons, and @var{arrows} controls the arrows.  Both
2776    @var{angles} and @var{arrows} work according to the table above.
2777    Thus, @code{(t .  right)} places the top angle icon in the left
2778    fringe, the bottom angle icon in the right fringe, and both arrows in
2779    the right fringe.
2780    @end defvar
2781    
2782    @defvar default-indicate-buffer-boundaries
2783    The value of this variable is the default value for
2784    @code{indicate-buffer-boundaries} in buffers that do not override it.
2785    @end defvar
2786    
2787  @node Scroll Bars  @node Scroll Bars
2788  @section Scroll Bars  @section Scroll Bars
2789    
# Line 2751  You can also control this for individual Line 2797  You can also control this for individual
2797  @code{set-window-scroll-bars} to specify what to do for a specific window:  @code{set-window-scroll-bars} to specify what to do for a specific window:
2798    
2799  @defun set-window-scroll-bars window width &optional vertical-type horizontal-type  @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
2800  Set width and type of scroll bars of window @var{window}.  This function sets the width and type of scroll bars for window
2801  If @var{window} is @code{nil}, the selected window is used.  @var{window}.
2802    
2803  @var{width} specifies the scroll bar width in pixels (@code{nil} means  @var{width} specifies the scroll bar width in pixels (@code{nil} means
2804  use whatever is specified for width for the frame).  use the width specified for the frame).  @var{vertical-type} specifies
2805  @var{vertical-type} specifies whether to have a vertical scroll bar  whether to have a vertical scroll bar and, if so, where.  The possible
2806  and, if so, where.  The possible values are @code{left}, @code{right}  values are @code{left}, @code{right} and @code{nil}, just like the
2807  and @code{nil}, just like the values of the  values of the @code{vertical-scroll-bars} frame parameter.
 @code{vertical-scroll-bars} frame parameter.  
2808    
2809  The argument @var{horizontal-type} is meant to specify whether and  The argument @var{horizontal-type} is meant to specify whether and
2810  where to have horizontal scroll bars, but since they are not  where to have horizontal scroll bars, but since they are not
2811  implemented, it has no effect.  implemented, it has no effect.  If @var{window} is @code{nil}, the
2812    selected window is used.
2813  @end defun  @end defun
2814    
2815  @defun window-scroll-bars &optional window  @defun window-scroll-bars &optional window
# Line 2789  specifying the same buffer that is alrea Line 2836  specifying the same buffer that is alrea
2836  @node Pointer Shape  @node Pointer Shape
2837  @section Pointer Shape  @section Pointer Shape
2838    
2839  Normally, the mouse pointer has the @code{text} shape over text and    Normally, the mouse pointer has the @code{text} shape over text and
2840  the @code{arrow} shape over window areas which do not correspond to  the @code{arrow} shape over window areas which do not correspond to
2841  any buffer text.  any buffer text.  You can specify the mouse pointer shape over text or
2842    images via the @code{pointer} text property, and for images with the
2843    @code{:pointer} and @code{:map} image properties.
2844    
2845  The available pointer shapes are: @code{text} (or @code{nil}),    The available pointer shapes are: @code{text} (or @code{nil}),
2846  @code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},  @code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
2847  @code{modeline}, and @code{hourglass}.  @code{modeline}, and @code{hourglass}.
2848    
 The mouse pointer shape over text or images can be changed via the  
 @code{pointer} text property, and for image with the @code{:pointer}  
 and @code{:map} image properties.  
   
2849  @defvar void-text-area-pointer  @defvar void-text-area-pointer
2850  @tindex void-text-area-pointer  @tindex void-text-area-pointer
2851  This variable specifies the mouse pointer shape in void text areas,  This variable specifies the mouse pointer shape in void text areas,
# Line 2828  they mean. Line 2873  they mean.
2873                            up or down on the page; adjusting the width                            up or down on the page; adjusting the width
2874                            of spaces within text.                            of spaces within text.
2875  * 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.
 * Display Fringe Bitmaps::  Displaying a fringe bitmap in a specific line.  
2876  * Conditional Display::  Making any of the above features conditional  * Conditional Display::  Making any of the above features conditional
2877                            depending on some Lisp expression.                            depending on some Lisp expression.
2878  @end menu  @end menu
# Line 2851  can use in @var{props} to specify the we Line 2895  can use in @var{props} to specify the we
2895  @item :width @var{width}  @item :width @var{width}
2896  If @var{width} is an integer or floating point number, it specifies  If @var{width} is an integer or floating point number, it specifies
2897  that the space width should be @var{width} times the normal character  that the space width should be @var{width} times the normal character
2898  width.  The @var{width} may also be a @dfn{pixel width} specification  width.  @var{width} can also be a @dfn{pixel width} specification
2899  (@pxref{Pixel Specification}).  (@pxref{Pixel Specification}).
2900    
2901  @item :relative-width @var{factor}  @item :relative-width @var{factor}
# Line 2862  character, multiplied by @var{factor}. Line 2906  character, multiplied by @var{factor}.
2906    
2907  @item :align-to @var{hpos}  @item :align-to @var{hpos}
2908  Specifies that the space should be wide enough to reach @var{hpos}.  Specifies that the space should be wide enough to reach @var{hpos}.
2909  If the value @var{hpos} is an integer or a floating point number, it  If @var{hpos} is a number, it is measured in units of the normal
2910  is measured in units of the normal character width.  The @var{hpos}  character width.  @var{hpos} can also be a @dfn{pixel width}
2911  may also be a @dfn{pixel width} specification (@pxref{Pixel Specification}).  specification (@pxref{Pixel Specification}).
2912  @end table  @end table
2913    
   The @code{:height} and @code{:align-to} properties are also supported  
 on non-window systems.  
   
2914    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
2915  also specify the height of the space, with other properties:  also specify the height of the space, with these properties:
2916    
2917  @table @code  @table @code
2918  @item :height @var{height}  @item :height @var{height}
# Line 2896  with a @dfn{pixel ascent} specification Line 2937  with a @dfn{pixel ascent} specification
2937    
2938    Don't use both @code{:height} and @code{:relative-height} together.    Don't use both @code{:height} and @code{:relative-height} together.
2939    
2940      The @code{:height} and @code{:align-to} properties are supported on
2941    non-graphic terminals, but the other space properties in this section
2942    are not.
2943    
2944  @node Pixel Specification  @node Pixel Specification
2945  @subsection Pixel Specification for Spaces  @subsection Pixel Specification for Spaces
2946  @cindex spaces, pixel specification  @cindex spaces, pixel specification
2947    
2948    The value of the @code{:width}, @code{:align-to}, @code{:height},    The value of the @code{:width}, @code{:align-to}, @code{:height},
2949  and @code{:ascent} properties can be a (trivial) expression  and @code{:ascent} properties can be a special kind of expression that
2950  which is evaluated during redisplay.  The result of the evaluation is  is evaluated during redisplay.  The result of the evaluation is used
2951  used as an absolute number of pixels.  as an absolute number of pixels.
2952    
2953    The following expressions are supported:    The following expressions are supported:
2954    
2955  @example  @example
2956  @group  @group
2957    EXPR ::= NUM | (NUM) | UNIT | ELEM | POS | IMAGE | FORM    @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | IMAGE | @var{form}
2958    NUM  ::= INTEGER | FLOAT | SYMBOL    @var{num}  ::= @var{integer} | @var{float} | @var{symbol}
2959    UNIT ::= in | mm | cm | width | height    @var{unit} ::= in | mm | cm | width | height
2960    ELEM ::= left-fringe | right-fringe | left-margin | right-margin    @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
2961          |  scroll-bar | text          |  scroll-bar | text
2962    POS  ::= left | center | right    @var{pos}  ::= left | center | right
2963    FORM ::= (NUM . EXPR) | (OP EXPR ...)    @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
2964    OP   ::= + | -    @var{op}   ::= + | -
2965  @end group  @end group
2966  @end example  @end example
2967    
2968    The form @var{NUM} specifies a fractional width or height of the    The form @var{num} specifies a fraction of the default frame font
2969  default frame font size.  The form @code{(@var{NUM})} specifies an  height or width.  The form @code{(@var{num})} specifies an absolute
2970  absolute number of pixels.  If a symbol @var{SYMBOL} is specified, its  number of pixels.  If @var{num} is a symbol, @var{symbol}, its
2971  buffer-local variable binding is used.  buffer-local variable binding is used.
2972    
2973    The @code{in}, @code{mm}, and @code{cm} units specifies the number    The @code{in}, @code{mm}, and @code{cm} units specify the number of
2974  of pixels per inch, milli-meter, and centi-meter, resp.  The  pixels per inch, millimeter, and centimeter, respectively.  The
2975  @code{width} and @code{height} units correspond to the width and  @code{width} and @code{height} units correspond to the default width
2976  height of the current face font.  An image specification @var{IMAGE}  and height of the current face.  An image specification @code{IMAGE}
2977  corresponds to the width or height of the image.  corresponds to the width or height of the image.
2978    
2979    The @code{left-fringe}, @code{right-fringe}, @code{left-margin},    The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
# Line 2939  specify to the width of the correspondin Line 2984  specify to the width of the correspondin
2984  used with @code{:align-to} to specify a position relative to the left  used with @code{:align-to} to specify a position relative to the left
2985  edge, center, or right edge of the text area.  edge, center, or right edge of the text area.
2986    
2987    One of the above window elements (except @code{text}) can also be    Any of the above window elements (except @code{text}) can also be
2988  used with @code{:align-to} to specify that the position is relative to  used with @code{:align-to} to specify that the position is relative to
2989  the left edge of the given area.  Once the base offset for a relative  the left edge of the given area.  Once the base offset for a relative
2990  position has been set (by the first occurrence of one of these  position has been set (by the first occurrence of one of these
# Line 2955  the left-margin, use Line 3000  the left-margin, use
3000  to the left edge of the text area.  For example, @samp{:align-to 0} in a  to the left edge of the text area.  For example, @samp{:align-to 0} in a
3001  header-line aligns with the first text column in the text area.  header-line aligns with the first text column in the text area.
3002    
3003    The value of the form @code{(@var{NUM} . @var{EXPR})} is the value of    A value of the form @code{(@var{num} . @var{expr})} stands
3004  @var{NUM} multiplied by the value of the expression @var{EXPR}.  For  multiplying the values of @var{num} and @var{expr}.  For example,
3005  example, @samp{(2 . in)} specifies a width of 2 inches, while  @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
3006  @samp{(0.5 . IMAGE)} specifies half the width (or height) of the  IMAGE)} specifies half the width (or height) of the specified image.
 specified image.  
3007    
3008    The form @code{(+ @var{EXPR} ...)} adds up the value of the    The form @code{(+ @var{expr} ...)} adds up the value of the
3009  expressions.  The form @code{(- @var{EXPR} ...)} negates or subtracts  expressions.  The form @code{(- @var{expr} ...)} negates or subtracts
3010  the value of the expressions.  the value of the expressions.
3011    
   
3012  @node Other Display Specs  @node Other Display Specs
3013  @subsection Other Display Specifications  @subsection Other Display Specifications
3014    
3015      Here are the other sorts of display specifications that you can use
3016    in the @code{display} text property.
3017    
3018  @table @code  @table @code
3019  @item (image . @var{image-props})  @item (image . @var{image-props})
3020  This is in fact an image descriptor (@pxref{Images}).  When used as a  This is in fact an image descriptor (@pxref{Images}).  When used as a
# Line 2976  display specification, it means to displ Line 3022  display specification, it means to displ
3022  that has the display specification.  that has the display specification.
3023    
3024  @item (slice @var{x} @var{y} @var{width} @var{height})  @item (slice @var{x} @var{y} @var{width} @var{height})
3025  This property is used with an @code{image} property to specify a  This specification together with @code{image} specifies a @dfn{slice}
3026  @dfn{slice} (a partial area) of the image to display.  The top left  (a partial area) of the image to display.  The elements @var{y} and
3027  corner of the slice is specified by @var{y} and @var{x} and the width  @var{x} specify the top left corner of the slice, within the image;
3028  and height of the slice is specified by @var{width} and @var{height}.  @var{width} and @var{height} specify the width and height of the
3029  Integer values are taken as pixel values.  A floating point number in  slice.  Integer values are numbers of pixels.  A floating point number
3030  the range 0.0 - 1.0 is relative to the width or height of the whole  in the range 0.0--1.0 stands for that fraction of the width or height
3031  image.  of the entire image.
3032    
3033  @item ((margin nil) @var{string})  @item ((margin nil) @var{string})
3034  @itemx @var{string}  @itemx @var{string}
# Line 3106  as a cons cell of the form @code{(@var{l Line 3152  as a cons cell of the form @code{(@var{l
3152  If @var{window} is @code{nil}, the selected window is used.  If @var{window} is @code{nil}, the selected window is used.
3153  @end defun  @end defun
3154    
 @node Display Fringe Bitmaps  
 @subsection Displaying Bitmaps in the Fringes  
 @cindex display fringes  
 @cindex margins, fringes  
   
   You can display a bitmap in the left or right fringes for a given  
 line in a window using the @code{display} property.  
   
   To put text in the left or right fringe of the window, use a  
 display specification of the form @code{(left-fringe @var{bitmap} [@var{face}])}  
 or @code{(right-fringe @var{bitmap} [@var{face}])} on one of the  
 characters on the corresponding text line.  
   
   The @var{bitmap} is an opaque integer identifying the bitmap, and the  
 optional @var{face} is the name of the face whose foreground and  
 background color is to be used for displaying the bitmap.  
   
 @defun fringe-bitmaps-at-pos &optional pos window  
 This function returns the fringe bitmaps of the display row containing  
 position @var{pos} in window @var{window}.  The return value is a cons  
 @code{(@var{left} .  @var{right})} where @var{left} and @var{right}  
 are the fringe bitmap numbers for the bitmaps in the left and right  
 fringe, resp.  
   
   Returns @code{nil} if @var{pos} is not visible in window  
 @var{window}.  If @var{window} is @code{nil}, use the selected window.  
 If @var{pos} is @code{nil}, use value of point in that window.  
 @end defun  
   
3155  @node Conditional Display  @node Conditional Display
3156  @subsection Conditional Display Specifications  @subsection Conditional Display Specifications
3157  @cindex conditional display specifications  @cindex conditional display specifications
# Line 3424  it is over the hot-spot. Line 3441  it is over the hot-spot.
3441    
3442  When you click the mouse when the mouse pointer is over a hot-spot, an  When you click the mouse when the mouse pointer is over a hot-spot, an
3443  event is composed by combining the @var{id} of the hot-spot with the  event is composed by combining the @var{id} of the hot-spot with the
3444  mouse event, e.g. @samp{[area4 mouse-1]} if the hot-spot's @var{id} is  mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
3445  @samp{area4}.  @var{id} is @code{area4}.
   
3446  @end table  @end table
3447    
3448  @defun image-mask-p spec &optional frame  @defun image-mask-p spec &optional frame
# Line 3709  buffer's text. Line 3725  buffer's text.
3725    
3726  The argument @var{slice} specifies a slice of the image to insert.  If  The argument @var{slice} specifies a slice of the image to insert.  If
3727  @var{slice} is @code{nil} or omitted the whole image is inserted.  @var{slice} is @code{nil} or omitted the whole image is inserted.
3728  Otherwise, @var{slice} is a list  Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
3729  @code{(@var{x} @var{y} @var{width} @var{height})}  @var{height})} which specifies the @var{x} and @var{y} positions and
 which specifies the @var{x} and @var{y} positions and  
3730  @var{width} and @var{height} of the image area to insert.  Integer  @var{width} and @var{height} of the image area to insert.  Integer
3731  values are taken as pixel values.  A floating point number in the  values are in units of pixels.  A floating point number in the range
3732  range 0.0 - 1.0 is relative to the width or height of the image.  0.0--1.0 stands for that fraction of the width or height of the entire
3733    image.
3734    
3735  Internally, this function inserts @var{string} in the buffer, and gives  Internally, this function inserts @var{string} in the buffer, and gives
3736  it a @code{display} property which specifies @var{image}.  @xref{Display  it a @code{display} property which specifies @var{image}.  @xref{Display
# Line 3722  Property}. Line 3738  Property}.
3738  @end defun  @end defun
3739    
3740  @defun insert-sliced-image image &optional string area rows cols  @defun insert-sliced-image image &optional string area rows cols
3741  This function inserts @var{image} in the current buffer at point like  This function inserts @var{image} in the current buffer at point, like
3742  @code{insert-image}, but the image is automatically split into  @code{insert-image}, but splits the image into @var{rows}x@var{cols}
3743  @var{rows} x @var{cols} equally sized slices.  equally sized slices.
3744  @end defun  @end defun
3745    
3746  @defun put-image image pos &optional string area  @defun put-image image pos &optional string area

Legend:
Removed from v.1.127  
changed lines
  Added in v.1.128

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