/[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.2.16 by miles, Fri Jul 23 04:42:21 2004 UTC revision 1.83.2.17 by miles, Wed Oct 6 05:21:50 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::      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.
32  * Display Property::    Enabling special display features.  * Display Property::    Enabling special display features.
33  * Images::              Displaying images in Emacs buffers.  * Images::              Displaying images in Emacs buffers.
34  * Buttons::             Adding clickable buttons to Emacs buffers.  * Buttons::             Adding clickable buttons to Emacs buffers.
# Line 1486  font.  (This works only on certain syste Line 1489  font.  (This works only on certain syste
1489    
1490  @item fringe  @item fringe
1491  @kindex fringe @r{(face name)}  @kindex fringe @r{(face name)}
1492  This face controls the colors of window fringes, the thin areas on  This face controls the default colors of window fringes, the thin areas on
1493  either side that are used to display continuation and truncation glyphs.  either side that are used to display continuation and truncation glyphs.
1494    
1495  @item minibuffer-prompt  @item minibuffer-prompt
# Line 2560  non-@code{nil} value. Line 2563  non-@code{nil} value.
2563    
2564  @defvar fringes-outside-margins  @defvar fringes-outside-margins
2565  If the value is non-@code{nil}, the frames appear outside  If the value is non-@code{nil}, the frames appear outside
2566  the display margins.  the display margins.
2567  @end defvar  @end defvar
2568    
2569  @defvar left-fringe-width  @defvar left-fringe-width
# Line 2596  window is used.  The value has the form Line 2599  window is used.  The value has the form
2599  @var{right-width} @var{frames-outside-margins})}.  @var{right-width} @var{frames-outside-margins})}.
2600  @end defun  @end defun
2601    
2602    @defvar overflow-newline-into-fringe
2603    If this is non-@code{nil}, lines exactly as wide as the window (not
2604    counting the final newline character) are not continued.  Instead,
2605    when point is at the end of the line, the cursor appears in the right
2606    fringe.
2607    @end defvar
2608    
2609    @node Fringe Bitmaps
2610    @section Fringe Bitmaps
2611    @cindex fringe bitmaps
2612    @cindex bitmaps, fringe
2613    
2614      The @dfn{fringe bitmaps} are tiny icons Emacs displays in the window
2615    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    @table @asis
2636    @item Truncation and continuation line bitmaps:
2637    @code{left-truncation-fringe-bitmap},
2638    @code{right-truncation-fringe-bitmap},
2639    @code{continued-line-fringe-bitmap},
2640    @code{continuation-line-fringe-bitmap}.
2641    
2642    @item Buffer indication bitmaps:
2643    @code{up-arrow-fringe-bitmap},
2644    @code{down-arrow-fringe-bitmap},
2645    @code{top-left-angle-fringe-bitmap},
2646    @code{top-right-angle-fringe-bitmap},
2647    @code{bottom-left-angle-fringe-bitmap},
2648    @code{bottom-right-angle-fringe-bitmap},
2649    @code{left-bracket-fringe-bitmap},
2650    @code{right-bracket-fringe-bitmap}.
2651    
2652    @item Empty line indication bitmap:
2653    @code{empty-line-fringe-bitmap}.
2654    
2655    @item Overlay arrow bitmap:
2656    @code{overlay-arrow-fringe-bitmap}.
2657    
2658    @item Bitmaps for displaying the cursor in right fringe:
2659    @code{filled-box-cursor-fringe-bitmap},
2660    @code{hollow-box-cursor-fringe-bitmap},
2661    @code{hollow-square-fringe-bitmap}, @code{bar-cursor-fringe-bitmap},
2662    @code{hbar-cursor-fringe-bitmap}.
2663    
2664    @item Value indicating that no fringe bitmap is present:
2665    @code{no-fringe-bitmap}.
2666    @c ??? I don't understand what that means.
2667    @c ??? Where would you find that value?
2668    
2669    @item Value indicating a reference to an undefined bitmap:
2670    @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    @defun fringe-bitmaps-at-pos &optional pos window
2676    This function returns the fringe bitmaps of the display line
2677    containing position @var{pos} in window @var{window}.  The return
2678    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    @node Customizing Bitmaps
2693    @section Customizing Fringe Bitmaps
2694    
2695    @c ??? Why not pass a symbol as the first argument
2696    @c ??? and define that symbol.  It would be cleaner.
2697    
2698    @defun define-fringe-bitmap bits &optional height width align bitmap
2699    This function defines a new fringe bitmap, or replaces an existing
2700    bitmap.
2701    
2702    The argument @var{bits} specifies the image to use.  It should be
2703    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
2733    
2734    @defun destroy-fringe-bitmap bitmap
2735    This function destroy the fringe bitmap identified by @var{bitmap}.
2736    If @var{bitmap} identifies a standard fringe bitmap, it actually
2737    restores the standard definition of that bitmap, instead of
2738    eliminating it entirely.
2739    @end defun
2740    
2741    @defun set-fringe-bitmap-face bitmap &optional face
2742    This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
2743    If @var{face} is @code{nil}, it selects the @code{fringe} face.  The
2744    bitmap's face controls the color to draw it in.
2745    
2746    The face you use here should be derived from @code{fringe}, and should
2747    specify only the foreground color.
2748    @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 2609  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 2644  in a buffer that is already visible in a Line 2833  in a buffer that is already visible in a
2833  window take note of the new values by calling @code{set-window-buffer}  window take note of the new values by calling @code{set-window-buffer}
2834  specifying the same buffer that is already displayed.  specifying the same buffer that is already displayed.
2835    
2836    @node Pointer Shape
2837    @section Pointer Shape
2838    
2839      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
2841    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}),
2846    @code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
2847    @code{modeline}, and @code{hourglass}.
2848    
2849    @defvar void-text-area-pointer
2850    @tindex void-text-area-pointer
2851    This variable specifies the mouse pointer shape in void text areas,
2852    i.e. the areas after the end of a line or below the last line in the
2853    buffer.  The default is to use the @code{arrow} (non-text) pointer.
2854    @end defvar
2855    
2856  @node Display Property  @node Display Property
2857  @section The @code{display} Property  @section The @code{display} Property
2858  @cindex display specification  @cindex display specification
# Line 2659  they mean. Line 2868  they mean.
2868    
2869  @menu  @menu
2870  * Specified Space::      Displaying one space with a specified width.  * Specified Space::      Displaying one space with a specified width.
2871    * Pixel Specification::  Specifying space width or height in pixels.
2872  * Other Display Specs::  Displaying an image; magnifying text; moving it  * Other Display Specs::  Displaying an image; magnifying text; moving it
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.
# Line 2683  can use in @var{props} to specify the we Line 2893  can use in @var{props} to specify the we
2893    
2894  @table @code  @table @code
2895  @item :width @var{width}  @item :width @var{width}
2896  Specifies that the space width should be @var{width} times the normal  If @var{width} is an integer or floating point number, it specifies
2897  character width.  @var{width} can be an integer or floating point  that the space width should be @var{width} times the normal character
2898  number.  width.  @var{width} can also be a @dfn{pixel width} specification
2899    (@pxref{Pixel Specification}).
2900    
2901  @item :relative-width @var{factor}  @item :relative-width @var{factor}
2902  Specifies that the width of the stretch should be computed from the  Specifies that the width of the stretch should be computed from the
# Line 2694  same @code{display} property.  The space Line 2905  same @code{display} property.  The space
2905  character, multiplied by @var{factor}.  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}.  The  Specifies that the space should be wide enough to reach @var{hpos}.
2909  value @var{hpos} is measured in units of the normal character width.  It  If @var{hpos} is a number, it is measured in units of the normal
2910  may be an integer or a floating point number.  character width.  @var{hpos} can also be a @dfn{pixel width}
2911    specification (@pxref{Pixel Specification}).
2912  @end table  @end table
2913    
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}
2919  Specifies the height of the space, as @var{height},  Specifies the height of the space.
2920  measured in terms of the normal line height.  If @var{height} is an integer or floating point number, it specifies
2921    that the space height should be @var{height} times the normal character
2922    height.  The @var{height} may also be a @dfn{pixel height} specification
2923    (@pxref{Pixel Specification}).
2924    
2925  @item :relative-height @var{factor}  @item :relative-height @var{factor}
2926  Specifies the height of the space, multiplying the ordinary height  Specifies the height of the space, multiplying the ordinary height
2927  of the text having this display specification by @var{factor}.  of the text having this display specification by @var{factor}.
2928    
2929  @item :ascent @var{ascent}  @item :ascent @var{ascent}
2930  Specifies that @var{ascent} percent of the height of the space should be  If the value of @var{ascent} is a non-negative number no greater than
2931  considered as the ascent of the space---that is, the part above the  100, it specifies that @var{ascent} percent of the height of the space
2932  baseline.  The value of @var{ascent} must be a non-negative number no  should be considered as the ascent of the space---that is, the part
2933  greater than 100.  above the baseline.  The ascent may also be specified in pixel units
2934    with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
2935    
2936  @end table  @end table
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
2945    @subsection Pixel Specification for Spaces
2946    @cindex spaces, pixel specification
2947    
2948      The value of the @code{:width}, @code{:align-to}, @code{:height},
2949    and @code{:ascent} properties can be a special kind of expression that
2950    is evaluated during redisplay.  The result of the evaluation is used
2951    as an absolute number of pixels.
2952    
2953      The following expressions are supported:
2954    
2955    @example
2956    @group
2957      @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | IMAGE | @var{form}
2958      @var{num}  ::= @var{integer} | @var{float} | @var{symbol}
2959      @var{unit} ::= in | mm | cm | width | height
2960      @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
2961            |  scroll-bar | text
2962      @var{pos}  ::= left | center | right
2963      @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
2964      @var{op}   ::= + | -
2965    @end group
2966    @end example
2967    
2968      The form @var{num} specifies a fraction of the default frame font
2969    height or width.  The form @code{(@var{num})} specifies an absolute
2970    number of pixels.  If @var{num} is a symbol, @var{symbol}, its
2971    buffer-local variable binding is used.
2972    
2973      The @code{in}, @code{mm}, and @code{cm} units specify the number of
2974    pixels per inch, millimeter, and centimeter, respectively.  The
2975    @code{width} and @code{height} units correspond to the default width
2976    and height of the current face.  An image specification @code{IMAGE}
2977    corresponds to the width or height of the image.
2978    
2979      The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
2980    @code{right-margin}, @code{scroll-bar}, and @code{text} elements
2981    specify to the width of the corresponding area of the window.
2982    
2983      The @code{left}, @code{center}, and @code{right} positions can be
2984    used with @code{:align-to} to specify a position relative to the left
2985    edge, center, or right edge of the text area.
2986    
2987      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
2989    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
2991    symbols), further occurences of these symbols are interpreted as the
2992    width of the specified area.  For example, to align to the center of
2993    the left-margin, use
2994    
2995    @example
2996    :align-to (+ left-margin (0.5 . left-margin))
2997    @end example
2998    
2999      If no specific base offset is set for alignment, it is always relative
3000    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.
3002    
3003      A value of the form @code{(@var{num} . @var{expr})} stands
3004    multiplying the values of @var{num} and @var{expr}.  For example,
3005    @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
3006    IMAGE)} specifies half the width (or height) of the specified image.
3007    
3008      The form @code{(+ @var{expr} ...)} adds up the value of the
3009    expressions.  The form @code{(- @var{expr} ...)} negates or subtracts
3010    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
3021  display specification, it means to display the image instead of the text  display specification, it means to display the image instead of the text
3022  that has the display specification.  that has the display specification.
3023    
3024    @item (slice @var{x} @var{y} @var{width} @var{height})
3025    This specification together with @code{image} specifies a @dfn{slice}
3026    (a partial area) of the image to display.  The elements @var{y} and
3027    @var{x} specify the top left corner of the slice, within the image;
3028    @var{width} and @var{height} specify the width and height of the
3029    slice.  Integer values are numbers of pixels.  A floating point number
3030    in the range 0.0--1.0 stands for that fraction of the width or height
3031    of the entire image.
3032    
3033  @item ((margin nil) @var{string})  @item ((margin nil) @var{string})
3034  @itemx @var{string}  @itemx @var{string}
3035  A display specification of this form means to display @var{string}  A display specification of this form means to display @var{string}
# Line 3105  specifying the color to assume for the b Line 3406  specifying the color to assume for the b
3406  If @var{mask} is @code{nil}, remove a mask from the image, if it has  If @var{mask} is @code{nil}, remove a mask from the image, if it has
3407  one.  Images in some formats include a mask which can be removed by  one.  Images in some formats include a mask which can be removed by
3408  specifying @code{:mask nil}.  specifying @code{:mask nil}.
3409    
3410    @item :pointer @var{shape}
3411    This specifies the pointer shape when the mouse pointer is over this
3412    image.  @xref{Pointer Shapes}, for available pointer shapes.
3413    
3414    @item :map @var{map}
3415    This associates an image map of @dfn{hot spots} with this image.
3416    
3417    An image map is an alist where each element has the format
3418    @code{(@var{area} @var{id} @var{plist})}.  An @var{area} is specified
3419    as either a rectangle, a circle, or a polygon.
3420    
3421    A rectangle is a cons
3422    @code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
3423    which specifies the pixel coordinates of the upper left and bottom right
3424    corners of the rectangle area.
3425    
3426    A circle is a cons
3427    @code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
3428    which specifies the center and the radius of the circle; @var{r} may
3429    be a float or integer.
3430    
3431    A polygon is a cons
3432    @code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
3433    where each pair in the vector describes one corner in the polygon.
3434    
3435    When the mouse pointer is above a hot-spot area of an image, the
3436    @var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
3437    property it defines a tool-tip for the hot-spot, and if it contains
3438    a @code{pointer} property, it defines the shape of the mouse cursor when
3439    it is over the hot-spot.
3440    @xref{Pointer Shapes}, for available pointer shapes.
3441    
3442    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
3444    mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
3445    @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 3372  The image is looked for first on @code{l Line 3710  The image is looked for first on @code{l
3710  property yourself, but it is easier to use the functions in this  property yourself, but it is easier to use the functions in this
3711  section.  section.
3712    
3713  @defun insert-image image &optional string area  @defun insert-image image &optional string area slice
3714  This function inserts @var{image} in the current buffer at point.  The  This function inserts @var{image} in the current buffer at point.  The
3715  value @var{image} should be an image descriptor; it could be a value  value @var{image} should be an image descriptor; it could be a value
3716  returned by @code{create-image}, or the value of a symbol defined with  returned by @code{create-image}, or the value of a symbol defined with
# Line 3385  If it is @code{left-margin}, the image a Line 3723  If it is @code{left-margin}, the image a
3723  @code{nil} or omitted, the image is displayed at point within the  @code{nil} or omitted, the image is displayed at point within the
3724  buffer's text.  buffer's text.
3725    
3726    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.
3728    Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
3729    @var{height})} which specifies the @var{x} and @var{y} positions and
3730    @var{width} and @var{height} of the image area to insert.  Integer
3731    values are in units of pixels.  A floating point number in the range
3732    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
3737  Property}.  Property}.
3738  @end defun  @end defun
3739    
3740    @defun insert-sliced-image image &optional string area rows cols
3741    This function inserts @var{image} in the current buffer at point, like
3742    @code{insert-image}, but splits the image into @var{rows}x@var{cols}
3743    equally sized slices.
3744    @end defun
3745    
3746  @defun put-image image pos &optional string area  @defun put-image image pos &optional string area
3747  This function puts image @var{image} in front of @var{pos} in the  This function puts image @var{image} in front of @var{pos} in the
3748  current buffer.  The argument @var{pos} should be an integer or a  current buffer.  The argument @var{pos} should be an integer or a
# Line 3498  entries). Line 3851  entries).
3851  * Making Buttons::         Adding buttons to Emacs buffers.  * Making Buttons::         Adding buttons to Emacs buffers.
3852  * Manipulating Buttons::   Getting and setting properties of buttons.  * Manipulating Buttons::   Getting and setting properties of buttons.
3853  * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.  * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
3854  * Manipulating Button Types::  * Manipulating Button Types::
3855  @end menu  @end menu
3856    
3857  @node Button Properties  @node Button Properties

Legend:
Removed from v.1.83.2.16  
changed lines
  Added in v.1.83.2.17

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