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