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