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. |
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 |
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 |
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 |
|
|
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 |
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 |
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. |
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 |
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} |
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 |
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 |
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 |
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 |