/[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.124 by rms, Sat Jul 17 14:40:22 2004 UTC revision 1.125 by kfstorm, Wed Sep 22 23:06:58 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.
29  * Scroll Bars::         Controlling vertical scroll bars.  * Scroll Bars::         Controlling vertical scroll bars.
30    * Pointer Shapes::      Controlling the mouse pointer shape.
31  * Display Property::    Enabling special display features.  * Display Property::    Enabling special display features.
32  * Images::              Displaying images in Emacs buffers.  * Images::              Displaying images in Emacs buffers.
33  * Buttons::             Adding clickable buttons to Emacs buffers.  * Buttons::             Adding clickable buttons to Emacs buffers.
# Line 1486  font.  (This works only on certain syste Line 1488  font.  (This works only on certain syste
1488    
1489  @item fringe  @item fringe
1490  @kindex fringe @r{(face name)}  @kindex fringe @r{(face name)}
1491  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
1492  either side that are used to display continuation and truncation glyphs.  either side that are used to display continuation and truncation glyphs.
1493    
1494  @item minibuffer-prompt  @item minibuffer-prompt
# Line 2560  non-@code{nil} value. Line 2562  non-@code{nil} value.
2562    
2563  @defvar fringes-outside-margins  @defvar fringes-outside-margins
2564  If the value is non-@code{nil}, the frames appear outside  If the value is non-@code{nil}, the frames appear outside
2565  the display margins.  the display margins.
2566  @end defvar  @end defvar
2567    
2568  @defvar left-fringe-width  @defvar left-fringe-width
# Line 2596  window is used.  The value has the form Line 2598  window is used.  The value has the form
2598  @var{right-width} @var{frames-outside-margins})}.  @var{right-width} @var{frames-outside-margins})}.
2599  @end defun  @end defun
2600    
2601    @defvar overflow-newline-into-fringe
2602    This variable, if non-@code{nil}, specifies that lines which are
2603    exactly as wide as the window (not counting the final newline
2604    character) shall not be broken into two lines on the display (with
2605    just the newline on the second line).  Instead, the newline now
2606    overflows into the right fringe, and the cursor will be displayed in
2607    the fringe when positioned on that newline.
2608    @end defvar
2609    
2610    @defvar indicate-buffer-boundaries
2611    This buffer-local variable controls how the buffer boundaries and
2612    window scrolling is indicated in the fringes.
2613    
2614      The buffer boundaries, i.e. first and last line in the buffer, can be
2615    marked with angle bitmaps in the left or right fringe.  This can be
2616    combined with up and down arrow bitmaps shown at the top and bottom of
2617    the left or right fringe if the window can be scrolled in either
2618    direction.
2619    
2620      If the value is @code{left} or @code{right}, both angle and arrow
2621    bitmaps are displayed in the left or right fringe, respectively.
2622    Any other non-@code{nil} value causes the bitmap on the top line to be
2623    displayed in the left fringe, and the bitmap on the bottom line in the
2624    right fringe.
2625    
2626      If value is a cons @code{(angles . arrows)}, the car specifies the
2627    position of the angle bitmaps, and the cdr specifies the position of
2628    the arrow bitmaps.  For example, @code{(t .  right)} places the top
2629    angle bitmap in left fringe, the bottom angle bitmap in right fringe,
2630    and both arrow bitmaps in right fringe.  To show just the angle
2631    bitmaps in the left fringe, but no arrow bitmaps, use @code{(left . nil)}.
2632    @end defvar
2633    
2634    @defvar default-indicate-buffer-boundaries
2635    The value of this variable is the default value for
2636    @code{indicate-buffer-boundaries} in buffers that do not override it.
2637    @end defvar
2638    
2639    @node Fringe Bitmaps
2640    @section Fringe Bitmaps
2641    @cindex Fringe Bitmaps
2642    
2643      The @dfn{fringe bitmaps} are tiny icons Emacs displays in the fringe
2644    on a window system to indicate truncated or continued lines, buffer
2645    boundaries, overlay arrow, etc.  The fringe bitmaps are shared by all
2646    frames and windows.
2647    
2648      You can redefine the built-in fringe bitmaps, and you can define new
2649    fringe bitmaps.  Emacs can handle a maximum of 255 different fringe
2650    bitmaps.
2651    
2652    A fringe bitmap is identified by an opaque integer, but Lisp code
2653    should use the following names defined by @code{(require 'fringe)}:
2654    
2655    Truncation and continuation line bitmaps:
2656    @code{left-truncation-fringe-bitmap},
2657    @code{right-truncation-fringe-bitmap},
2658    @code{continued-line-fringe-bitmap},
2659    @code{continuation-line-fringe-bitmap}.
2660    
2661    Buffer indication bitmaps:
2662    @code{up-arrow-fringe-bitmap},
2663    @code{down-arrow-fringe-bitmap},
2664    @code{top-left-angle-fringe-bitmap},
2665    @code{top-right-angle-fringe-bitmap},
2666    @code{bottom-left-angle-fringe-bitmap},
2667    @code{bottom-right-angle-fringe-bitmap},
2668    @code{left-bracket-fringe-bitmap},
2669    @code{right-bracket-fringe-bitmap}.
2670    
2671    Empty line indication bitmap:
2672    @code{empty-line-fringe-bitmap}.
2673    
2674    Overlay arrow bitmap:
2675    @code{overlay-arrow-fringe-bitmap}.
2676    
2677    Bitmaps for displaying the cursor in right fringe:
2678    @code{filled-box-cursor-fringe-bitmap},
2679    @code{hollow-box-cursor-fringe-bitmap},
2680    @code{hollow-square-fringe-bitmap}, @code{bar-cursor-fringe-bitmap},
2681    @code{hbar-cursor-fringe-bitmap}.
2682    
2683    Fringe bitmap opaque value indicating that no fringe bitmap is present:
2684    @code{no-fringe-bitmap}.
2685    
2686    Fringe bitmap opaque value indicating a reference to an undefined bitmap:
2687    @code{undef-fringe-bitmap}.
2688    
2689      To display an specific fringe bitmap on a line in an Emacs window,
2690    use it as a @code{left-fringe} or @code{right-fringe} specifier in the
2691    @code{display} property of some text that is displayed on that line
2692    (@pxref{Display Property}).
2693    
2694    @defun define-fringe-bitmap bits &optional height width align bitmap
2695    Define a new fringe bitmap, or change an existing bitmap.
2696    
2697    The argument @code{bits} is either a string or a vector of integers,
2698    where each element (typically) corresponds to one row of the bitmap,
2699    and each bit of an integer corresponds to one pixel of the bitmap.
2700    
2701    The optional argument @code{height} specifies the height of the bitmap.
2702    If @code{height} is @code{nil}, the length of @code{bits} is used.
2703    
2704    The optional argument @code{width} specifies the width of the bitmap;
2705    it must be an integer between 1 and 16, or @code{nil} which defaults
2706    to a width of 8 pixels.
2707    
2708    The optional argument @code{align} may be one of @code{top},
2709    @code{center}, or @code{bottom}, indicating the positioning of the
2710    bitmap relative to the rows where it is used; the default is to center
2711    the bitmap.
2712    
2713    The @code{align} argument may also be a list @code{(ALIGN PERIODIC)}
2714    where @code{ALIGN} is intepreted as described above, and if
2715    @code{PERIODIC} is non-@code{nil} it specifies that the @code{bits} should
2716    be repeated until a bitmap of the specified @code{height} is created.
2717    
2718    The optional argument @code{bitmap} specifies the opaque integer that
2719    identifies an existing bitmap to redefine.
2720    
2721    The return value is a new opaque integer identifying the new bitmap number,
2722    or @code{nil} of there are no more free bitmap slots.
2723    @end defun
2724    
2725    @defun destroy-fringe-bitmap bitmap
2726    Destroy the fringe bitmap identified by the opaque integer
2727    @code{bitmap}.  If @code{bitmap} identifies a standard fringe bitmap,
2728    the original built-in bitmap is restored.
2729    @end defun
2730    
2731    @defun set-fringe-bitmap-face bitmap &optional face
2732    Set face for a specific fringe bitmap @code{bitmap} to the face
2733    specified by the argument @code{face}.
2734    If @code{face} is @code{nil}, reset face to default @code{fringe} face.
2735    
2736    Normally, the specified face should be a face derived from the
2737    @code{fringe} face, only specifying the foreground color as the
2738    desired color of the fringe bitmap.
2739    @end defun
2740    
2741  @node Scroll Bars  @node Scroll Bars
2742  @section Scroll Bars  @section Scroll Bars
2743    
# Line 2609  You can also control this for individual Line 2751  You can also control this for individual
2751  @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:
2752    
2753  @defun set-window-scroll-bars window width &optional vertical-type horizontal-type  @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
2754  Set width and type of scroll bars of window @var{window}.    Set width and type of scroll bars of window @var{window}.
2755  If @var{window} is @code{nil}, the selected window is used.  If @var{window} is @code{nil}, the selected window is used.
2756  @var{width} specifies the scroll bar width in pixels (@code{nil} means  @var{width} specifies the scroll bar width in pixels (@code{nil} means
2757  use whatever is specified for width for the frame).  use whatever is specified for width for the frame).
# Line 2644  in a buffer that is already visible in a Line 2786  in a buffer that is already visible in a
2786  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}
2787  specifying the same buffer that is already displayed.  specifying the same buffer that is already displayed.
2788    
2789    @node Pointer Shapes
2790    @section Pointer Shapes
2791    
2792    Normally, the mouse pointer has the @code{text} shape over text and
2793    the @code{arrow} shape over window areas which do not correspond to
2794    any buffer text.
2795    
2796    The available pointer shapes are: @code{text} (or @code{nil}),
2797    @code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
2798    @code{modeline}, and @code{hourglass}.
2799    
2800    The mouse pointer shape over text or images can be changed via the
2801    @code{pointer} text property, and for image with the @code{:pointer}
2802    and @code{:map} image properties.
2803    
2804    @defvar void-text-area-pointer
2805    @tindex void-text-area-pointer
2806    This variable specifies the mouse pointer shape in void text areas,
2807    i.e. the areas after the end of a line or below the last line in the
2808    buffer.  The default is to use the @code{arrow} (non-text) pointer.
2809    @end defvar
2810    
2811  @node Display Property  @node Display Property
2812  @section The @code{display} Property  @section The @code{display} Property
2813  @cindex display specification  @cindex display specification
# Line 2659  they mean. Line 2823  they mean.
2823    
2824  @menu  @menu
2825  * Specified Space::      Displaying one space with a specified width.  * Specified Space::      Displaying one space with a specified width.
2826    * Pixel Specification::  Specifying space width or height in pixels.
2827  * Other Display Specs::  Displaying an image; magnifying text; moving it  * Other Display Specs::  Displaying an image; magnifying text; moving it
2828                            up or down on the page; adjusting the width                            up or down on the page; adjusting the width
2829                            of spaces within text.                            of spaces within text.
2830  * 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.
2831    * Display Fringe Bitmaps::  Displaying a fringe bitmap in a specific line.
2832  * Conditional Display::  Making any of the above features conditional  * Conditional Display::  Making any of the above features conditional
2833                            depending on some Lisp expression.                            depending on some Lisp expression.
2834  @end menu  @end menu
# Line 2683  can use in @var{props} to specify the we Line 2849  can use in @var{props} to specify the we
2849    
2850  @table @code  @table @code
2851  @item :width @var{width}  @item :width @var{width}
2852  Specifies that the space width should be @var{width} times the normal  If @var{width} is an integer or floating point number, it specifies
2853  character width.  @var{width} can be an integer or floating point  that the space width should be @var{width} times the normal character
2854  number.  width.  The @var{width} may also be a @dfn{pixel width} specification
2855    (@pxref{Pixel Specification}).
2856    
2857  @item :relative-width @var{factor}  @item :relative-width @var{factor}
2858  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 2861  same @code{display} property.  The space
2861  character, multiplied by @var{factor}.  character, multiplied by @var{factor}.
2862    
2863  @item :align-to @var{hpos}  @item :align-to @var{hpos}
2864  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}.
2865  value @var{hpos} is measured in units of the normal character width.  It  If the value @var{hpos} is an integer or a floating point number, it
2866  may be an integer or a floating point number.  is measured in units of the normal character width.  The @var{hpos}
2867    may also be a @dfn{pixel width} specification (@pxref{Pixel Specification}).
2868  @end table  @end table
2869    
2870      The @code{:height} and @code{:align-to} properties are also supported
2871    on non-window systems.
2872    
2873    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
2874  also specify the height of the space, with other properties:  also specify the height of the space, with other properties:
2875    
2876  @table @code  @table @code
2877  @item :height @var{height}  @item :height @var{height}
2878  Specifies the height of the space, as @var{height},  Specifies the height of the space.
2879  measured in terms of the normal line height.  If @var{height} is an integer or floating point number, it specifies
2880    that the space height should be @var{height} times the normal character
2881    height.  The @var{height} may also be a @dfn{pixel height} specification
2882    (@pxref{Pixel Specification}).
2883    
2884  @item :relative-height @var{factor}  @item :relative-height @var{factor}
2885  Specifies the height of the space, multiplying the ordinary height  Specifies the height of the space, multiplying the ordinary height
2886  of the text having this display specification by @var{factor}.  of the text having this display specification by @var{factor}.
2887    
2888  @item :ascent @var{ascent}  @item :ascent @var{ascent}
2889  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
2890  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
2891  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
2892  greater than 100.  above the baseline.  The ascent may also be specified in pixel units
2893    with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
2894    
2895  @end table  @end table
2896    
2897    Don't use both @code{:height} and @code{:relative-height} together.    Don't use both @code{:height} and @code{:relative-height} together.
2898    
2899    @node Pixel Specification
2900    @subsection Pixel Specification for Spaces
2901    @cindex spaces, pixel specification
2902    
2903      The value of the @code{:width}, @code{:align-to}, @code{:height},
2904    and @code{:ascent} properties can be a (trivial) expression
2905    which is evaluated during redisplay.  The result of the evaluation is
2906    used as an absolute number of pixels.
2907    
2908      The following expressions are supported:
2909    
2910    @example
2911    @group
2912      EXPR ::= NUM | (NUM) | UNIT | ELEM | POS | IMAGE | FORM
2913      NUM  ::= INTEGER | FLOAT | SYMBOL
2914      UNIT ::= in | mm | cm | width | height
2915      ELEM ::= left-fringe | right-fringe | left-margin | right-margin
2916            |  scroll-bar | text
2917      POS  ::= left | center | right
2918      FORM ::= (NUM . EXPR) | (OP EXPR ...)
2919      OP   ::= + | -
2920    @end group
2921    @end example
2922    
2923      The form @var{NUM} specifies a fractional width or height of the
2924    default frame font size.  The form @code(@var{NUM})} specifies an
2925    absolute number of pixels.  If a symbol @var{SYMBOL} is specified, its
2926    buffer-local variable binding is used.
2927    
2928      The @code{in}, @code{mm}, and @code{cm} units specifies the number
2929    of pixels per inch, milli-meter, and centi-meter, resp.  The
2930    @code{width} and @code{height} units correspond to the width and
2931    height of the current face font.  An image specification @var{IMAGE}
2932    corresponds to the width or height of the image.
2933    
2934      The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
2935    @code{right-margin}, @code{scroll-bar}, and @code{text} elements
2936    specify to the width of the corresponding area of the window.
2937    
2938      The @code{left}, @code{center}, and @code{right} positions can be
2939    used with @code{:align-to} to specify a position relative to the left
2940    edge, center, or right edge of the text area.
2941    
2942      One of the above window elements (except @code{text}) can also be
2943    used with @code{:align-to} to specify that the position is relative to
2944    the left edge of the given area.  Once the base offset for a relative
2945    position has been set (by the first occurrence of one of these
2946    symbols), further occurences of these symbols are interpreted as the
2947    width of the specified area.  For example, to align to the center of
2948    the left-margin, use
2949    
2950    @example
2951    :align-to (+ left-margin (0.5 . left-margin))
2952    @end example
2953    
2954      If no specific base offset is set for alignment, it is always relative
2955    to the left edge of the text area.  For example, @samp{:align-to 0} in a
2956    header-line aligns with the first text column in the text area.
2957    
2958      The value of the form @code(@var{NUM} . @var{EXPR})} is the value of
2959    @var{NUM} multiplied by the value of the expression @var{EXPR}.  For
2960    example, @samp{(2 . in)} specifies a width of 2 inches, while
2961    @samp{(0.5 . IMAGE)} specifies half the width (or height) of the
2962    specified image.
2963    
2964      The form @code{(+ @var{EXPR} ...)} adds up the value of the
2965    expressions.  The form @code{(- @var{EXPR} ...)} negates or subtracts
2966    the value of the expressions.
2967    
2968    
2969  @node Other Display Specs  @node Other Display Specs
2970  @subsection Other Display Specifications  @subsection Other Display Specifications
2971    
# Line 2729  This is in fact an image descriptor (@px Line 2975  This is in fact an image descriptor (@px
2975  display specification, it means to display the image instead of the text  display specification, it means to display the image instead of the text
2976  that has the display specification.  that has the display specification.
2977    
2978    @item (slice @var{x} @var{y} @var{width} @var{height})
2979    This property is used with an @code{image} property to specify a
2980    @dfn{slice} (a partial area) of the image to display.  The top left
2981    corner of the slice is specified by @var{y} and @var{x} and the width
2982    and height of the slice is specified by @var{width} and @var{height}.
2983    Integer values are taken as pixel values.  A floating point number in
2984    the range 0.0 - 1.0 is relative to the width or height of the whole
2985    image.
2986    
2987  @item ((margin nil) @var{string})  @item ((margin nil) @var{string})
2988  @itemx @var{string}  @itemx @var{string}
2989  A display specification of this form means to display @var{string}  A display specification of this form means to display @var{string}
# Line 2851  as a cons cell of the form @code{(@var{l Line 3106  as a cons cell of the form @code{(@var{l
3106  If @var{window} is @code{nil}, the selected window is used.  If @var{window} is @code{nil}, the selected window is used.
3107  @end defun  @end defun
3108    
3109    @node Display Fringe Bitmaps
3110    @subsection Displaying Bitmaps in the Fringes
3111    @cindex display fringes
3112    @cindex margins, fringes
3113    
3114      You can display a bitmap in the left or right fringes for a given
3115    line in a window using the @code{display} property.
3116    
3117      To put text in the left or right fringe of the window, use a
3118    display specification of the form @code{(left-fringe @var{bitmap} [@var{face}])}
3119    or @code{(right-fringe @var{bitmap} [@var{face}])} on one of the
3120    characters on the corresponding text line.
3121    
3122      The @var{bitmap} is an opaque integer identifying the bitmap, and the
3123    optional @var{face} is the name of the face whose foreground and
3124    background color is to be used for displaying the bitmap.
3125    
3126    @defun fringe-bitmaps-at-pos &optional pos window
3127    This function returns the fringe bitmaps of the display row containing
3128    position @var{pos} in window @var{window}.  The return value is a cons
3129    @code{(@var{left} .  @var{right})} where @var{left} and @var{right}
3130    are the fringe bitmap numbers for the bitmaps in the left and right
3131    fringe, resp.
3132    
3133      Returns @code{nil} if @var{pos} is not visible in window
3134    @var{window}.  If @var{window} is @code{nil}, use the selected window.
3135    If @var{pos} is @code{nil}, use value of point in that window.
3136    @end defun
3137    
3138  @node Conditional Display  @node Conditional Display
3139  @subsection Conditional Display Specifications  @subsection Conditional Display Specifications
3140  @cindex conditional display specifications  @cindex conditional display specifications
# Line 2943  function always returns @code{t}; for ot Line 3227  function always returns @code{t}; for ot
3227  * Other Image Types::   Various other formats are supported.  * Other Image Types::   Various other formats are supported.
3228  * Defining Images::     Convenient ways to define an image for later use.  * Defining Images::     Convenient ways to define an image for later use.
3229  * Showing Images::      Convenient ways to display an image once it is defined.  * Showing Images::      Convenient ways to display an image once it is defined.
3230    * Image Slices::        Displaying image slices.
3231  * Image Cache::         Internal mechanisms of image display.  * Image Cache::         Internal mechanisms of image display.
3232  @end menu  @end menu
3233    
# Line 3105  specifying the color to assume for the b Line 3390  specifying the color to assume for the b
3390  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
3391  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
3392  specifying @code{:mask nil}.  specifying @code{:mask nil}.
3393    
3394    @item :pointer @var{shape}
3395    This specifies the pointer shape when the mouse pointer is over this
3396    image.  @xref{Pointer Shapes}, for available pointer shapes.
3397    
3398    @item :map @var{map}
3399    This associates an image map of @dfn{hot spots} with this image.
3400    
3401    An image map is an alist where each element has the format
3402    @code{(@var{area} @var{id} @var{plist})}.  An @var{area} is specified
3403    as either a rectangle, a circle, or a polygon.
3404    
3405    A rectangle is a cons
3406    @code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
3407    which specifies the pixel coordinates of the upper left and bottom right
3408    corners of the rectangle area.
3409    
3410    A circle is a cons
3411    @code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
3412    which specifies the center and the radius of the circle; @var{r} may
3413    be a float or integer.
3414    
3415    A polygon is a cons
3416    @code(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
3417    where each pair in the vector describes one corner in the polygon.
3418    
3419    When the mouse pointer is above a hot-spot area of an image, the
3420    @var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
3421    property it defines a tool-tip for the hot-spot, and if it contains
3422    a @code{pointer} property, it defines the shape of the mouse cursor when
3423    it is over the hot-spot.
3424    @xref{Pointer Shapes}, for available pointer shapes.
3425    
3426    When you click the mouse when the mouse pointer is over a hot-spot, an
3427    event is composed by combining the @var{id} of the hot-spot with the
3428    mouse event, e.g. @samp{[area4 mouse-1]} if the hot-spot's @var{id} is
3429    @samp{area4}.
3430    
3431  @end table  @end table
3432    
3433  @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 3695  The image is looked for first on @code{l
3695  property yourself, but it is easier to use the functions in this  property yourself, but it is easier to use the functions in this
3696  section.  section.
3697    
3698  @defun insert-image image &optional string area  @defun insert-image image &optional string area slice
3699  This function inserts @var{image} in the current buffer at point.  The  This function inserts @var{image} in the current buffer at point.  The
3700  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
3701  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 3708  If it is @code{left-margin}, the image a
3708  @code{nil} or omitted, the image is displayed at point within the  @code{nil} or omitted, the image is displayed at point within the
3709  buffer's text.  buffer's text.
3710    
3711    The argument @var{slice} specifies a slice of the image to insert.  If
3712    @var{slice} is @code{nil} or omitted the whole image is inserted.
3713    Otherwise, @var{slice} is a list
3714    @code{(@var{x} @var{y} @var{width} @var{height})}
3715    which specifies the @var{x} and @var{y} positions and
3716    @var{width} and @var{height} of the image area to insert.  Integer
3717    values are taken as pixel values.  A floating point number in the
3718    range 0.0 - 1.0 is relative to the width or height of the image.
3719    
3720  Internally, this function inserts @var{string} in the buffer, and gives  Internally, this function inserts @var{string} in the buffer, and gives
3721  it a @code{display} property which specifies @var{image}.  @xref{Display  it a @code{display} property which specifies @var{image}.  @xref{Display
3722  Property}.  Property}.
3723  @end defun  @end defun
3724    
3725    @defun insert-sliced-image image &optional string area rows cols
3726    This function inserts @var{image} in the current buffer at point like
3727    @code{insert-image}, but the image is automatically split into
3728    @var{rows} x @var{cols} equally sized slices.
3729    @end defun
3730    
3731  @defun put-image image pos &optional string area  @defun put-image image pos &optional string area
3732  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
3733  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 3836  entries).
3836  * Making Buttons::         Adding buttons to Emacs buffers.  * Making Buttons::         Adding buttons to Emacs buffers.
3837  * Manipulating Buttons::   Getting and setting properties of buttons.  * Manipulating Buttons::   Getting and setting properties of buttons.
3838  * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.  * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
3839  * Manipulating Button Types::  * Manipulating Button Types::
3840  @end menu  @end menu
3841    
3842  @node Button Properties  @node Button Properties

Legend:
Removed from v.1.124  
changed lines
  Added in v.1.125

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