@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, System Interface, Processes, Top
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
+* Abstract Display:: Emacs' Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
* Usual Display:: The usual conventions for displaying nonprinting chars.
* Display Tables:: How to specify other conventions.
redisplay is done, but does not clear them first.
@defun force-window-update &optional object
-This function forces redisplay of some or all windows. If
-@var{object} is a window, it forces redisplay of that window. If
+This function forces some or all windows to be updated on next redisplay.
+If @var{object} is a window, it forces redisplay of that window. If
@var{object} is a buffer or buffer name, it forces redisplay of all
windows displaying that buffer. If @var{object} is @code{nil} (or
omitted), it forces redisplay of all windows.
is exactly what you want. However, you can prevent preemption by
binding @code{redisplay-dont-pause} to a non-@code{nil} value.
-@tindex redisplay-dont-pause
+@defvar redisplay-preemption-period
+This variable specifies how many seconds Emacs waits between checks
+for new input during redisplay. (The default is 0.1 seconds.) If
+input has arrived when Emacs checks, it pre-empts redisplay and
+processes the available input before trying again to redisplay.
+
+If this variable is @code{nil}, Emacs does not check for input during
+redisplay, and redisplay cannot be preempted by input.
+
+This variable is only obeyed on graphical terminals. For
+text terminals, see @ref{Terminal Output}.
+@end defvar
+
@defvar redisplay-dont-pause
If this variable is non-@code{nil}, pending input does not
prevent or halt redisplay; redisplay occurs, and finishes,
regardless of whether input is available.
@end defvar
- You can request a display update, but only if no input is pending,
-with @code{(sit-for 0)}. To force a display update even when input is
-pending, do this:
+@defun redisplay &optional force
+This function performs an immediate redisplay provided there are no
+pending input events. This is equivalent to @code{(sit-for 0)}.
-@example
-(let ((redisplay-dont-pause t))
- (sit-for 0))
-@end example
+If the optional argument @var{force} is non-@code{nil}, it forces an
+immediate and complete redisplay even if input is available.
+
+Returns @code{t} if redisplay was performed, or @code{nil} otherwise.
+@end defun
@node Truncation
@section Truncation
@cindex line wrapping
+@cindex line truncation
@cindex continuation lines
@cindex @samp{$} in display
@cindex @samp{\} in display
- When a line of text extends beyond the right edge of a window, the
-line can either be continued on the next screen line, or truncated to
-one screen line. The additional screen lines used to display a long
-text line are called @dfn{continuation} lines. Normally, a @samp{$} in
-the rightmost column of the window indicates truncation; a @samp{\} on
-the rightmost column indicates a line that ``wraps'' onto the next line,
-which is also called @dfn{continuing} the line. (The display table can
-specify alternative indicators; see @ref{Display Tables}.)
-
- On a graphical display, the @samp{$} and @samp{\} indicators are
-replaced with arrow images displayed in the window fringes
-(@pxref{Fringes}).
-
- Note that continuation is different from filling; continuation happens
-on the screen only, not in the buffer contents, and it breaks a line
-precisely at the right margin, not at a word boundary. @xref{Filling}.
+ When a line of text extends beyond the right edge of a window, Emacs
+can @dfn{continue} the line (make it ``wrap'' to the next screen
+line), or @dfn{truncate} the line (limit it to one screen line). The
+additional screen lines used to display a long text line are called
+@dfn{continuation} lines. Continuation is not the same as filling;
+continuation happens on the screen only, not in the buffer contents,
+and it breaks a line precisely at the right margin, not at a word
+boundary. @xref{Filling}.
+
+ On a graphical display, tiny arrow images in the window fringes
+indicate truncated and continued lines (@pxref{Fringes}). On a text
+terminal, a @samp{$} in the rightmost column of the window indicates
+truncation; a @samp{\} on the rightmost column indicates a line that
+``wraps.'' (The display table can specify alternate characters to use
+for this; @pxref{Display Tables}).
@defopt truncate-lines
This buffer-local variable controls how Emacs displays lines that extend
@node Displaying Messages
@subsection Displaying Messages in the Echo Area
+@cindex display message in echo area
This section describes the functions for explicitly producing echo
area messages. Many other Emacs features display messages there, too.
depending on its size, use @code{display-message-or-buffer} (see below).
@end defun
-@tindex with-temp-message
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
the execution of @var{body}. It displays @var{message}, executes
@end defun
@defun message-box format-string &rest arguments
+@anchor{message-box}
This function displays a message like @code{message}, but uses a dialog
box (or a pop-up menu) whenever that is possible. If it is impossible
to use a dialog box or pop-up menu, because the terminal does not
@end defun
@defun display-message-or-buffer message &optional buffer-name not-this-window frame
-@tindex display-message-or-buffer
This function displays the message @var{message}, which may be either a
string or a buffer. If it is shorter than the maximum height of the
echo area, as defined by @code{max-mini-window-height}, it is displayed
is @var{atom} or if it is a list with @var{atom} as a member.
@item (@var{atom} . t)
-A character is invisible if its @code{invisible} property value
-is @var{atom} or if it is a list with @var{atom} as a member.
-Moreover, if this character is at the end of a line and is followed
-by a visible newline, it displays an ellipsis.
+A character is invisible if its @code{invisible} property value is
+@var{atom} or if it is a list with @var{atom} as a member. Moreover,
+a sequence of such characters displays as an ellipsis.
@end table
@end table
@end defvar
@node Selective Display
@section Selective Display
-@cindex selective display
+@c @cindex selective display Duplicates selective-display
@dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.
@end defvar
@defvar temp-buffer-setup-hook
-@tindex temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
evaluating @var{body}. When the hook runs, the temporary buffer is
current. This hook is normally set up with a function to put the
This is the only valid way to change the endpoints of an overlay. Do
not try modifying the markers in the overlay by hand, as that fails to
update other vital data structures and can cause some overlays to be
-``lost''.
+``lost.''
@end defun
@defun remove-overlays &optional start end name value
@result{} t
@end example
+ Emacs stores the overlays of each buffer in two lists, divided
+around an arbitrary ``center position.'' One list extends backwards
+through the buffer from that center position, and the other extends
+forwards from that center position. The center position can be anywhere
+in the buffer.
+
+@defun overlay-recenter pos
+This function recenters the overlays of the current buffer around
+position @var{pos}. That makes overlay lookup faster for positions
+near @var{pos}, but slower for positions far away from @var{pos}.
+@end defun
+
+ A loop that scans the buffer forwards, creating overlays, can run
+faster if you do @code{(overlay-recenter (point-max))} first.
+
@node Overlay Properties
@subsection Overlay Properties
Attributes}.
@item
-A cons cell of the form @code{(foreground-color . @var{color-name})} or
+A cons cell, either of the form @code{(foreground-color . @var{color-name})} or
@code{(background-color . @var{color-name})}. These elements specify
just the foreground color or just the background color.
@code{inhibit-modification-hooks} to @code{t} around doing so, to
avoid confusing the internal mechanism that calls these hooks.
+Text properties also support the @code{modification-hooks} property,
+but the details are somewhat different (@pxref{Special Properties}).
+
@item insert-in-front-hooks
@kindex insert-in-front-hooks @r{(overlay property)}
This property's value is a list of functions to be called before and
@code{(point-min)}.
@end defun
- Here's a function which uses @code{next-overlay-change} to search
-for the next character which gets a given property @code{prop} from
-either its overlays or its text properties (@pxref{Property Search}):
+ As an example, here's a simplified (and inefficient) version of the
+primitive function @code{next-single-char-property-change}
+(@pxref{Property Search}). It searches forward from position
+@var{pos} for the next position where the value of a given property
+@code{prop}, as obtained from either overlays or text properties,
+changes.
@smallexample
-(defun find-overlay-prop (prop)
+(defun next-single-char-property-change (position prop)
(save-excursion
- (while (and (not (eobp))
- (not (get-char-property (point) prop)))
- (goto-char (min (next-overlay-change (point))
- (next-single-property-change (point) prop))))
+ (goto-char position)
+ (let ((propval (get-char-property (point) prop)))
+ (while (and (not (eobp))
+ (eq (get-char-property (point) prop) propval))
+ (goto-char (min (next-overlay-change (point))
+ (next-single-property-change (point) prop)))))
(point)))
@end smallexample
- Now you can search for a @code{happy} property like this:
-
-@smallexample
-(find-overlay-prop 'happy)
-@end smallexample
-
@node Width
@section Width
@cindex line height
The total height of each display line consists of the height of the
-contents of the line, and additional vertical line spacing below the
-display row.
+contents of the line, plus optional additional vertical line spacing
+above or below the display line.
- The height of the line contents is normally determined from the
-maximum height of any character or image on that display line,
-including the final newline if there is one. (A line that is
-continued doesn't include a final newline.) In the most common case,
-the line height equals the height of the default frame font.
+ The height of the line contents is the maximum height of any
+character or image on that display line, including the final newline
+if there is one. (A display line that is continued doesn't include a
+final newline.) That is the default line height, if you do nothing to
+specify a greater height. (In the most common case, this equals the
+height of the default frame font.)
- There are several ways to explicitly control or change the line
-height, either by specifying an absolute height for the display line,
-or by adding additional vertical space below one or all lines.
+ There are several ways to explicitly specify a larger line height,
+either by specifying an absolute height for the display line, or by
+specifying vertical space. However, no matter what you specify, the
+actual line height can never be less than the default.
@kindex line-height @r{(text property)}
A newline can have a @code{line-height} text or overlay property
that controls the total height of the display line ending in that
newline.
- If the property value is a list @code{(@var{height} @var{total})},
-then @var{height} is used as the actual property value for the
-@code{line-height}, and @var{total} specifies the total displayed
-height of the line, so the line spacing added below the line equals
-the @var{total} height minus the actual line height. In this case,
-the other ways to specify the line spacing are ignored.
+ If the property value is @code{t}, the newline character has no
+effect on the displayed height of the line---the visible contents
+alone determine the height. This is useful for tiling small images
+(or image slices) without adding blank areas between the images.
- If the property value is @code{t}, the displayed height of the
-line is exactly what its contents demand; no line-spacing is added.
-This case is useful for tiling small images or image slices without
-adding blank areas between the images.
+ If the property value is a list of the form @code{(@var{height}
+@var{total})}, that adds extra space @emph{below} the display line.
+First Emacs uses @var{height} as a height spec to control extra space
+@emph{above} the line; then it adds enough space @emph{below} the line
+to bring the total line height up to @var{total}. In this case, the
+other ways to specify the line spacing are ignored.
- If the property value is not @code{t}, it is a height spec. A height
-spec stands for a numeric height value; this height spec specifies the
-actual line height, @var{line-height}. There are several ways to
-write a height spec; here's how each of them translates into a numeric
-height:
+ Any other kind of property value is a height spec, which translates
+into a number---the specified line height. There are several ways to
+write a height spec; here's how each of them translates into a number:
@table @code
@item @var{integer}
is @var{ratio} times the height of the contents of the line.
@end table
- Thus, any valid non-@code{t} property value specifies a height in pixels,
-@var{line-height}, one way or another. If the line contents' height
-is less than @var{line-height}, Emacs adds extra vertical space above
-the line to achieve the total height @var{line-height}. Otherwise,
-@var{line-height} has no effect.
+ Thus, any valid height spec determines the height in pixels, one way
+or another. If the line contents' height is less than that, Emacs
+adds extra vertical space above the line to achieve the specified
+total height.
If you don't specify the @code{line-height} property, the line's
height consists of the contents' height plus the line spacing.
@kindex line-spacing @r{(text property)}
Finally, a newline can have a @code{line-spacing} text or overlay
-property that controls the height of the display line ending with that
-newline. The property value overrides the default frame line spacing
-and the buffer local @code{line-spacing} variable.
+property that overrides the default frame line spacing and the buffer
+local @code{line-spacing} variable, for the display line ending in
+that newline.
One way or another, these mechanisms specify a Lisp value for the
spacing of each line. The value is a height spec, and it translates
@var{spec}, then uses any customizations that were read from the
init file (@pxref{Init File}) to override that specification.
+When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
+Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
+overrides any customizations of the face. This way, the face reflects
+exactly what the @code{defface} says.
+
The purpose of @var{spec} is to specify how the face should appear on
different kinds of terminals. It should be an alist whose elements
have the form @code{(@var{display} @var{atts})}. Each element's
@example
@group
+(defface region
'((((class color) (min-colors 88) (background dark))
:background "blue3")
@end group
The effect of using a face is determined by a fixed set of @dfn{face
attributes}. This table lists all the face attributes, and what they
-mean. Note that in general, more than one face can be specified for a
-given piece of text; when that happens, the attributes of all the faces
-are merged to specify how to display the text. @xref{Displaying Faces}.
+mean. You can specify more than one face for a given piece of text;
+Emacs merges the attributes of all the faces to determine how to
+display the text. @xref{Displaying Faces}.
Any attribute in a face can have the value @code{unspecified}. This
means the face doesn't specify that attribute. In face merging, when
A non-@code{nil} value specifies an italic font.
@end table
- For compatibility, you can still set these ``attributes'', even
+ For compatibility, you can still set these ``attributes,'' even
though they are not real face attributes. Here is what that does:
@table @code
@node Attribute Functions
@subsection Face Attribute Functions
- You can modify the attributes of an existing face with the following
-functions. If you specify @var{frame}, they affect just that frame;
-otherwise, they affect all frames as well as the defaults that apply to
-new frames.
+ This section describes the functions for accessing and modifying the
+attributes of an existing face.
-@tindex set-face-attribute
@defun set-face-attribute face frame &rest arguments
-This function sets one or more attributes of face @var{face}
-for frame @var{frame}. If @var{frame} is @code{nil}, it sets
-the attribute for all frames, and the defaults for new frames.
+This function sets one or more attributes of face @var{face} for frame
+@var{frame}. The attributes you specify this way override whatever
+the @code{defface} says.
The extra arguments @var{arguments} specify the attributes to set, and
the values for them. They should consist of alternating attribute names
@noindent
sets the attributes @code{:width}, @code{:weight} and @code{:underline}
to the corresponding values.
+
+If @var{frame} is @code{t}, this function sets the default attributes
+for new frames. Default attribute values specified this way override
+the @code{defface} for newly created frames.
+
+If @var{frame} is @code{nil}, this function sets the attributes for
+all existing frames, and the default for new frames.
@end defun
-@tindex face-attribute
@defun face-attribute face attribute &optional frame inherit
This returns the value of the @var{attribute} attribute of face
@var{face} on @var{frame}. If @var{frame} is @code{nil},
that means the selected frame (@pxref{Input Focus}).
-If @var{frame} is @code{t}, the value is the default for
-@var{face} for new frames.
+If @var{frame} is @code{t}, this returns whatever new-frames default
+value you previously specified with @code{set-face-attribute} for the
+@var{attribute} attribute of @var{face}. If you have not specified
+one, it returns @code{nil}.
If @var{inherit} is @code{nil}, only attributes directly defined by
@var{face} are considered, so the return value may be
@end example
@end defun
- The functions above did not exist before Emacs 21. For compatibility
-with older Emacs versions, you can use the following functions to set
-and examine the face attributes which existed in those versions.
-
-@tindex face-attribute-relative-p
@defun face-attribute-relative-p attribute value
-This function returns non-@code{nil} if @var{value}, when used as
-the value of the face attribute @var{attribute}, is relative (that is,
-if it modifies an underlying or inherited value of @var{attribute}).
+This function returns non-@code{nil} if @var{value}, when used as the
+value of the face attribute @var{attribute}, is relative. This means
+it would modify, rather than completely override, any value that comes
+from a subsequent face in the face list or that is inherited from
+another face.
+
+@code{unspecified} is a relative value for all attributes.
+For @code{:height}, floating point values are also relative.
+
+For example:
+
+@example
+(face-attribute-relative-p :height 2.0)
+ @result{} t
+@end example
@end defun
-@tindex merge-face-attribute
@defun merge-face-attribute attribute value1 value2
If @var{value1} is a relative value for the face attribute
@var{attribute}, returns it merged with the underlying value
face attribute @var{attribute}, returns @var{value1} unchanged.
@end defun
+ The functions above did not exist before Emacs 21. For compatibility
+with older Emacs versions, you can use the following functions to set
+and examine the face attributes which existed in those versions.
+They use values of @code{t} and @code{nil} for @var{frame}
+just like @code{set-face-attribute} and @code{face-attribute}.
+
@defun set-face-foreground face color &optional frame
@defunx set-face-background face color &optional frame
These functions set the foreground (or background, respectively) color
This actually sets the @code{:slant} attribute.
@end defun
-@defun set-face-underline-p face underline-p &optional frame
+@defun set-face-underline-p face underline &optional frame
This function sets the underline attribute of face @var{face}.
Non-@code{nil} means do underline; @code{nil} means don't.
+If @var{underline} is a string, underline with that color.
@end defun
@defun set-face-inverse-video-p face inverse-video-p &optional frame
@end defun
These functions examine the attributes of a face. If you don't
-specify @var{frame}, they refer to the default data for new frames.
-They return the symbol @code{unspecified} if the face doesn't define any
-value for that attribute.
+specify @var{frame}, they refer to the selected frame; @code{t} refers
+to the default data for new frames. They return the symbol
+@code{unspecified} if the face doesn't define any value for that
+attribute.
@defun face-foreground face &optional frame inherit
@defunx face-background face &optional frame inherit
try.
@defvar face-font-selection-order
-@tindex face-font-selection-order
This variable specifies the order of importance of the face attributes
@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
value should be a list containing those four symbols, in order of
@end defvar
@defvar face-font-family-alternatives
-@tindex face-font-family-alternatives
This variable lets you specify alternative font families to try, if a
given family is specified and doesn't exist. Each element should have
this form:
@end defvar
@defvar face-font-registry-alternatives
-@tindex face-font-registry-alternatives
This variable lets you specify alternative font registries to try, if a
given registry is specified and doesn't exist. Each element should have
this form:
XFree86 servers.
@defvar scalable-fonts-allowed
-@tindex scalable-fonts-allowed
This variable controls which scalable fonts to use. A value of
@code{nil}, the default, means do not use scalable fonts. @code{t}
means to use any scalable font that seems appropriate for the text.
allows the use of scalable fonts with registry @code{muleindian-2}.
@end defvar
-@defun clear-face-cache &optional unload-p
-@tindex clear-face-cache
-This function clears the face cache for all frames.
-If @var{unload-p} is non-@code{nil}, that means to unload
-all unused fonts as well.
-@end defun
-
@defvar face-font-rescale-alist
This variable specifies scaling for certain faces. Its value should
be a list of elements of the form
@cindex automatic face assignment
@cindex faces, automatic choice
-@cindex Font-Lock mode
This hook is used for automatically assigning faces to text in the
-buffer. It is part of the implementation of Font-Lock mode.
+buffer. It is part of the implementation of Jit-Lock mode, used by
+Font-Lock.
-@tindex fontification-functions
@defvar fontification-functions
This variable holds a list of functions that are called by Emacs
redisplay as needed to assign faces automatically to text in the buffer.
@end defun
@defun x-family-fonts &optional family frame
-@tindex x-family-fonts
This function returns a list describing the available fonts for family
@var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
this list applies to all families, and therefore, it contains all
@end defun
@defun x-font-family-list &optional frame
-@tindex x-font-family-list
This function returns a list of the font families available for
@var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
describes the selected frame's display (@pxref{Input Focus}).
@end defun
@defvar font-list-limit
-@tindex font-list-limit
This variable specifies maximum number of fonts to consider in font
matching. The function @code{x-family-fonts} will not return more than
that many fonts, and font selection will consider only that many fonts
@node Fringes
@section Fringes
-@cindex Fringes
+@cindex fringes
The @dfn{fringes} of a window are thin vertical strips down the
sides that are used for displaying bitmaps that indicate truncation,
continued lines, buffer boundaries, overlay arrow, etc.
@defopt indicate-empty-lines
-@tindex indicate-empty-lines
@cindex fringes, and empty line indication
When this is non-@code{nil}, Emacs displays a special glyph in the
fringe of each empty line at the end of the buffer, on graphical
that there is text above the screen, and a down-arrow to show
there is text below the screen.
-There are four kinds of basic values:
+There are three kinds of basic values:
@table @asis
@item @code{nil}
-Don't display the icons.
+Don't display any of these fringe icons.
@item @code{left}
-Display them in the left fringe.
+Display the angle icons and arrows in the left fringe.
@item @code{right}
-Display them in the right fringe.
-@item @var{anything-else}
-Display the icon at the top of the window top in the left fringe, and other
-in the right fringe.
+Display the angle icons and arrows in the right fringe.
+@item any non-alist
+Display the angle icons in the left fringe
+and don't display the arrows.
@end table
-If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
-controls the angle icons, and @var{arrows} controls the arrows. Both
-@var{angles} and @var{arrows} work according to the table above.
-Thus, @code{(t . right)} places the top angle icon in the left
-fringe, the bottom angle icon in the right fringe, and both arrows in
-the right fringe.
+Otherwise the value should be an alist that specifies which fringe
+indicators to display and where. Each element of the alist should
+have the form @code{(@var{indicator} . @var{position})}. Here,
+@var{indicator} is one of @code{top}, @code{bottom}, @code{up},
+@code{down}, and @code{t} (which covers all the icons not yet
+specified), while @var{position} is one of @code{left}, @code{right}
+and @code{nil}.
+
+For example, @code{((top . left) (t . right))} places the top angle
+bitmap in left fringe, and the bottom angle bitmap as well as both
+arrow bitmaps in right fringe. To show the angle bitmaps in the left
+fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}.
@end defvar
@defvar default-indicate-buffer-boundaries
@code{fringe-indicator-alist} in buffers that do not override it.
@end defvar
-@table @asis
-@item Standard fringe bitmaps for indicators:
-@code{left-arrow}, @code{right-arrow}, @code{up-arrow}, @code{down-arrow},
-@code{left-curly-arrow}, @code{right-curly-arrow},
-@code{left-triangle}, @code{right-triangle},
-@code{top-left-angle}, @code{top-right-angle},
-@code{bottom-left-angle}, @code{bottom-right-angle},
-@code{left-bracket}, @code{right-bracket},
-@code{filled-rectangle}, @code{hollow-rectangle},
-@code{filled-square}, @code{hollow-square},
-@code{vertical-bar}, @code{horizontal-bar},
-@code{empty-line},
-@code{question-mark}.
-@end table
+Standard fringe bitmaps for indicators:
+@example
+left-arrow right-arrow up-arrow down-arrow
+left-curly-arrow right-curly-arrow
+left-triangle right-triangle
+top-left-angle top-right-angle
+bottom-left-angle bottom-right-angle
+left-bracket right-bracket
+filled-rectangle hollow-rectangle
+filled-square hollow-square
+vertical-bar horizontal-bar
+empty-line question-mark
+@end example
@node Fringe Cursors
@subsection Fringe Cursors
@defvar fringe-cursor-alist
This variable specifies the mapping from logical cursor type to the
actual fringe bitmaps displayed in the right fringe. The value is an
-alist where each element @code{(@var{cursor}. @var{bitmap})} specifies
+alist where each element @code{(@var{cursor} . @var{bitmap})} specifies
the fringe bitmaps used to display a specific logical cursor type in
the fringe. Here, @var{cursor} specifies the logical cursor type and
@var{bitmap} is a symbol specifying the fringe bitmap to be displayed
@code{fringe-cursor-alist} in buffers that do not override it.
@end defvar
-@table @asis
-@item Standard bitmaps for displaying the cursor in right fringe:
-@code{filled-rectangle}, @code{hollow-rectangle},
-@code{filled-square}, @code{hollow-square},
-@code{vertical-bar}, @code{horizontal-bar}.
-@end table
+Standard bitmaps for displaying the cursor in right fringe:
+@example
+filled-rectangle hollow-rectangle filled-square hollow-square
+vertical-bar horizontal-bar
+@end example
@node Fringe Bitmaps
If @var{periodic} is non-@code{nil}, it specifies that the rows in
@code{bits} should be repeated enough times to reach the specified
height.
-
-The return value on success is an integer identifying the new bitmap.
-You should save that integer in a variable so it can be used to select
-this bitmap.
-
-This function signals an error if there are no more free bitmap slots.
@end defun
@defun destroy-fringe-bitmap bitmap
@node Overlay Arrow
@subsection The Overlay Arrow
-@cindex overlay arrow
+@c @cindex overlay arrow Duplicates variable names
The @dfn{overlay arrow} is useful for directing the user's attention
to a particular line in a buffer. For example, in the modes used for
specify an overlay arrow string (for text-only terminals) or fringe
bitmap (for graphical terminals) to display at the corresponding
overlay arrow position. If either property is not set, the default
-(@code{overlay-arrow-string} or @code{overlay-arrow-fringe-bitmap}) is
-used.
+@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
+is used.
@node Scroll Bars
@section Scroll Bars
+@cindex scroll bars
Normally the frame parameter @code{vertical-scroll-bars} controls
whether the windows in the frame have vertical scroll bars, and
insert images into text, and also control other aspects of how text
displays. The value of the @code{display} property should be a
display specification, or a list or vector containing several display
-specifications.
-
- Some kinds of @code{display} properties specify something to display
-instead of the text that has the property. In this case, ``the text''
-means all the consecutive characters that have the same Lisp object as
-their @code{display} property; these characters are replaced as a
-single unit. By contrast, characters that have similar but distinct
-Lisp objects as their @code{display} properties are handled
-separately. Here's a function that illustrates this point:
+specifications. Display specifications generally apply in parallel to
+the text they cover.
+
+ Some kinds of @code{display} specifications specify something to
+display instead of the text that has the property. If a list of
+display specifications includes more than one of this kind, the first
+is effective and the rest are ignored. You cannot interactively move
+point into the middle of the text that is thus replaced.
+
+ For these specifications, ``the text that has the property'' means
+all the consecutive characters that have the same Lisp object as their
+@code{display} property; these characters are replaced as a single
+unit. By contrast, characters that have similar but distinct Lisp
+objects as their @code{display} properties are handled separately.
+Here's a function that illustrates this point:
@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(let ((string (concat "A")))
- (put-text-property (point) (2+ (point)) 'display string)
+ (put-text-property (point) (+ 2 (point)) 'display string)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 2))))
@end smallexample
@node Specified Space
@subsection Specified Spaces
@cindex spaces, specified height or width
-@cindex specified spaces
@cindex variable-width spaces
To display a space of specified width and/or height, use a display
variables:
@defvar left-margin-width
-@tindex left-margin-width
This variable specifies the width of the left margin.
It is buffer-local in all buffers.
@end defvar
@defvar right-margin-width
-@tindex right-margin-width
This variable specifies the width of the right margin.
It is buffer-local in all buffers.
@end defvar
You can also set the margin widths immediately.
@defun set-window-margins window left &optional right
-@tindex set-window-margins
This function specifies the margin widths for window @var{window}.
The argument @var{left} controls the left margin and
@var{right} controls the right margin (default @code{0}).
@end defun
@defun window-margins &optional window
-@tindex window-margins
This function returns the left and right margins of @var{window}
as a cons cell of the form @code{(@var{left} . @var{right})}.
If @var{window} is @code{nil}, the selected window is used.
descriptor, then use it as a display specifier in the @code{display}
property of text that is displayed (@pxref{Display Property}).
+ Emacs is usually able to display images when it is run on a
+graphical terminal. Images cannot be displayed in a text terminal, on
+certain graphical terminals that lack the support for this, or if
+Emacs is compiled without image support. You can use the function
+@code{display-images-p} to determine if images can in principle be
+displayed (@pxref{Display Feature Testing}).
+
Emacs can display a number of different image formats; some of them
are supported only if particular support libraries are installed on
your machine. In some environments, Emacs can load image
The supported image formats include XBM, XPM (this requires the
libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
-@code{libungif} 4.1.0), Postscript, PBM, JPEG (requiring the
+@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the
@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
v3.4), and PNG (requiring @code{libpng} 1.0.2).
into Emacs.
@end defvar
-@defun image-type-available-p type
-@findex image-type-available-p
-
+@defun image-type-available-p type
This function returns non-@code{nil} if image type @var{type} is
available, i.e., if images of this type can be loaded and displayed in
Emacs. @var{type} should be one of the types contained in
* XBM Images:: Special features for XBM format.
* XPM Images:: Special features for XPM format.
* GIF Images:: Special features for GIF format.
-* Postscript Images:: Special features for Postscript format.
+* PostScript Images:: Special features for PostScript format.
* Other Image Types:: Various other formats are supported.
* Defining Images:: Convenient ways to define an image for later use.
* Showing Images:: Convenient ways to display an image once it is defined.
@end ifnottex
@item disabled
-Specifies transforming the image so that it looks ``disabled''.
+Specifies transforming the image so that it looks ``disabled.''
@end table
@item :mask @var{mask}
@end table
@defun image-mask-p spec &optional frame
-@tindex image-mask-p
This function returns @code{t} if image @var{spec} has a mask bitmap.
@var{frame} is the frame on which the image will be displayed.
@var{frame} @code{nil} or omitted means to use the selected frame
(run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
@end ignore
-@node Postscript Images
-@subsection Postscript Images
-@cindex Postscript images
+@node PostScript Images
+@subsection PostScript Images
+@cindex postscript images
- To use Postscript for an image, specify image type @code{postscript}.
+ To use PostScript for an image, specify image type @code{postscript}.
This works only if you have Ghostscript installed. You must always use
these three properties:
@item :bounding-box @var{box}
The value, @var{box}, must be a list or vector of four integers, which
-specifying the bounding box of the Postscript image, analogous to the
-@samp{BoundingBox} comment found in Postscript files.
+specifying the bounding box of the PostScript image, analogous to the
+@samp{BoundingBox} comment found in PostScript files.
@example
%%BoundingBox: 22 171 567 738
@end example
@end table
- Displaying Postscript images from Lisp data is not currently
+ Displaying PostScript images from Lisp data is not currently
implemented, but it may be implemented by the time you read this.
See the @file{etc/NEWS} file to make sure.
@code{find-image} provide convenient ways to create image descriptors.
@defun create-image file-or-data &optional type data-p &rest props
-@tindex create-image
This function creates and returns an image descriptor which uses the
data in @var{file-or-data}. @var{file-or-data} can be a file name or
a string containing the image data; @var{data-p} should be @code{nil}
@end defun
@defmac defimage symbol specs &optional doc
-@tindex defimage
This macro defines @var{symbol} as an image name. The arguments
@var{specs} is a list which specifies how to display the image.
The third argument, @var{doc}, is an optional documentation string.
@end defmac
@defun find-image specs
-@tindex find-image
This function provides a convenient way to find an image satisfying one
of a list of image specifications @var{specs}.
@end defun
@defvar image-load-path
-@tindex image-load-path
This variable's value is a list of locations in which to search for
image files. If an element is a string or a variable symbol whose
value is a string, the string is taken to be the name of a directory
@end defvar
@defun image-load-path-for-library library image &optional path no-error
-@tindex image-load-path-for-library
This function returns a suitable search path for images used by the
Lisp package @var{library}.
-It searches for @var{image} in @code{image-load-path} (excluding
-@file{@code{data-directory}/images}) and @code{load-path}, followed by
-a path suitable for @var{library}, which includes
-@file{../../etc/images} and @file{../etc/images} relative to the
-library file itself, and then in @file{@code{data-directory}/images}.
+The function searches for @var{image} first using @code{image-load-path},
+excluding @file{@code{data-directory}/images}, and then in
+@code{load-path}, followed by a path suitable for @var{library}, which
+includes @file{../../etc/images} and @file{../etc/images} relative to
+the library file itself, and finally in
+@file{@code{data-directory}/images}.
Then this function returns a list of directories which contains first
the directory in which @var{image} was found, followed by the value of
with versions of Emacs that lack the variable @code{image-load-path}:
@example
-;; Shush compiler.
-(defvar image-load-path)
-
-(let* ((load-path (image-load-path-for-library "mh-e" "mh-logo.xpm"))
+(defvar image-load-path) ; shush compiler
+(let* ((load-path (image-load-path-for-library
+ "mh-e" "mh-logo.xpm"))
(image-load-path (cons (car load-path)
(when (boundp 'image-load-path)
image-load-path))))
@end defun
@defun image-size spec &optional pixels frame
-@tindex image-size
This function returns the size of an image as a pair
@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
specification. @var{pixels} non-@code{nil} means return sizes
@end defun
@defvar max-image-size
-@tindex max-image-size
This variable is used to define the maximum size of image that Emacs
will load. Emacs will refuse to load (and display) any image that is
larger than this limit.
@node Image Cache
@subsection Image Cache
+@cindex image cache
+
+ Emacs stores images in an image cache so that it can display them
+again more efficiently. When Emacs displays an image, it searches the
+image cache for an existing image specification @code{equal} to the
+desired specification. If a match is found, the image is displayed
+from the cache; otherwise, Emacs loads the image normally.
+
+ Occasionally, you may need to tell Emacs to refresh the images
+associated with a given image specification. For example, suppose you
+display an image using a specification that contains a @code{:file}
+property. The image is loaded from the given file and stored in the
+image cache. If you later display the image again, using the same
+image specification, the image is displayed from the image cache.
+Normally, this is not a problem. However, if the image file has
+changed in the meantime, Emacs would be displaying the old version of
+the image. In such a situation, it is necessary to ``refresh'' the
+image using @code{image-refresh}.
+
+@defun image-refresh spec &optional frame
+This function refreshes any images having image specifications
+@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is
+@code{nil}, the selected frame is used. If @var{frame} is @code{t},
+the refresh is applied to all existing frames.
+
+This works by removing all image with image specifications matching
+@var{spec} from the image cache. Thus, the next time the image is
+displayed, Emacs will load the image again.
+@end defun
- Emacs stores images in an image cache when it displays them, so it can
-display them again more efficiently. It removes an image from the cache
-when it hasn't been displayed for a specified period of time.
+@defun clear-image-cache &optional frame
+This function clears the entire image cache. If @var{frame} is
+non-@code{nil}, only the cache for that frame is cleared. Otherwise,
+all frames' caches are cleared.
+@end defun
-When an image is looked up in the cache, its specification is compared
-with cached image specifications using @code{equal}. This means that
-all images with equal specifications share the same image in the cache.
+If an image in the image cache has not been displayed for a specified
+period of time, Emacs removes it from the cache and frees the
+associated memory.
@defvar image-cache-eviction-delay
-@tindex image-cache-eviction-delay
This variable specifies the number of seconds an image can remain in the
cache without being displayed. When an image is not displayed for this
length of time, Emacs removes it from the image cache.
debugging.
@end defvar
-@defun clear-image-cache &optional frame
-@tindex clear-image-cache
-This function clears the image cache. If @var{frame} is non-@code{nil},
-only the cache for that frame is cleared. Otherwise all frames' caches
-are cleared.
-@end defun
-
@node Buttons
@section Buttons
-@cindex buttons
@cindex buttons in buffers
@cindex clickable buttons in buffers
properties or overlays) to a region of text in an Emacs buffer. These
properties are called @dfn{button properties}.
- One of the these properties (@code{action}) is a function, which will
+ One of these properties (@code{action}) is a function, which will
be called when the user invokes it using the keyboard or the mouse.
The invoked function may then examine the button and use its other
properties as desired.
specific tasks.
@defun define-button-type name &rest properties
-@tindex define-button-type
Define a `button type' called @var{name}. The remaining arguments
form a sequence of @var{property value} pairs, specifying default
property values for buttons with this type (a button's type may be set
(@pxref{Overlays}) to hold the button properties:
@defun make-button beg end &rest properties
-@tindex make-button
This makes a button from @var{beg} to @var{end} in the
current buffer, and returns it.
@end defun
@defun insert-button label &rest properties
-@tindex insert-button
This insert a button with the label @var{label} at point,
and returns it.
@end defun
of the new button:
@defun make-text-button beg end &rest properties
-@tindex make-text-button
This makes a button from @var{beg} to @var{end} in the current buffer, using
text properties.
@end defun
@defun insert-text-button label &rest properties
-@tindex insert-text-button
This inserts a button with the label @var{label} at point, using text
properties.
@end defun
invocation function when it is invoked.
@defun button-start button
-@tindex button-start
Return the position at which @var{button} starts.
@end defun
@defun button-end button
-@tindex button-end
Return the position at which @var{button} ends.
@end defun
@defun button-get button prop
-@tindex button-get
Get the property of button @var{button} named @var{prop}.
@end defun
@defun button-put button prop val
-@tindex button-put
Set @var{button}'s @var{prop} property to @var{val}.
@end defun
@defun button-activate button &optional use-mouse-action
-@tindex button-activate
Call @var{button}'s @code{action} property (i.e., invoke it). If
@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
@code{mouse-action} property instead of @code{action}; if the button
@end defun
@defun button-label button
-@tindex button-label
Return @var{button}'s text label.
@end defun
@defun button-type button
-@tindex button-type
Return @var{button}'s button-type.
@end defun
@defun button-has-type-p button type
-@tindex button-has-type-p
Return @code{t} if @var{button} has button-type @var{type}, or one of
@var{type}'s subtypes.
@end defun
@defun button-at pos
-@tindex button-at
Return the button at position @var{pos} in the current buffer, or @code{nil}.
@end defun
@defun button-type-put type prop val
-@tindex button-type-put
Set the button-type @var{type}'s @var{prop} property to @var{val}.
@end defun
@defun button-type-get type prop
-@tindex button-type-get
Get the property of button-type @var{type} named @var{prop}.
@end defun
@defun button-type-subtype-p type supertype
-@tindex button-type-subtype-p
Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
@end defun
@xref{Links and Mouse-1}.
@deffn Command push-button &optional pos use-mouse-action
-@tindex push-button
Perform the action specified by a button at location @var{pos}.
@var{pos} may be either a buffer position or a mouse-event. If
@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
@end deffn
@deffn Command forward-button n &optional wrap display-message
-@tindex forward-button
Move to the @var{n}th next button, or @var{n}th previous button if
@var{n} is negative. If @var{n} is zero, move to the start of any
button at point. If @var{wrap} is non-@code{nil}, moving past either
@end deffn
@deffn Command backward-button n &optional wrap display-message
-@tindex backward-button
Move to the @var{n}th previous button, or @var{n}th next button if
@var{n} is negative. If @var{n} is zero, move to the start of any
button at point. If @var{wrap} is non-@code{nil}, moving past either
@end deffn
@defun next-button pos &optional count-current
-@tindex next-button
-Return the next button after position @var{pos} in the current buffer.
-If @var{count-current} is non-@code{nil}, count any button at
-@var{pos} in the search, instead of starting at the next button.
+@defunx previous-button pos &optional count-current
+Return the next button after (for @code{next-button} or before (for
+@code{previous-button}) position @var{pos} in the current buffer. If
+@var{count-current} is non-@code{nil}, count any button at @var{pos}
+in the search, instead of starting at the next button.
@end defun
-@defun previous-button pos &optional count-current
-@tindex previous-button
-Return the @var{n}th button before position @var{pos} in the current
-buffer. If @var{count-current} is non-@code{nil}, count any button at
-@var{pos} in the search, instead of starting at the next button.
+@node Abstract Display
+@section Abstract Display
+@cindex ewoc
+@cindex display, abstract
+@cindex display, arbitrary objects
+@cindex model/view/controller
+@cindex view part, model/view/controller
+
+ The Ewoc package constructs buffer text that represents a structure
+of Lisp objects, and updates the text to follow changes in that
+structure. This is like the ``view'' component in the
+``model/view/controller'' design paradigm.
+
+ An @dfn{ewoc} is a structure that organizes information required to
+construct buffer text that represents certain Lisp data. The buffer
+text of the ewoc has three parts, in order: first, fixed @dfn{header}
+text; next, textual descriptions of a series of data elements (Lisp
+objects that you specify); and last, fixed @dfn{footer} text.
+Specifically, an ewoc contains information on:
+
+@itemize @bullet
+@item
+The buffer which its text is generated in.
+
+@item
+The text's start position in the buffer.
+
+@item
+The header and footer strings.
+
+@item
+A doubly-linked chain of @dfn{nodes}, each of which contains:
+
+@itemize
+@item
+A @dfn{data element}, a single Lisp object.
+
+@item
+Links to the preceding and following nodes in the chain.
+@end itemize
+
+@item
+A @dfn{pretty-printer} function which is responsible for
+inserting the textual representation of a data
+element value into the current buffer.
+@end itemize
+
+ Typically, you define an ewoc with @code{ewoc-create}, and then pass
+the resulting ewoc structure to other functions in the Ewoc package to
+build nodes within it, and display it in the buffer. Once it is
+displayed in the buffer, other functions determine the correspondance
+between buffer positions and nodes, move point from one node's textual
+representation to another, and so forth. @xref{Abstract Display
+Functions}.
+
+ A node @dfn{encapsulates} a data element much the way a variable
+holds a value. Normally, encapsulation occurs as a part of adding a
+node to the ewoc. You can retrieve the data element value and place a
+new value in its place, like so:
+
+@lisp
+(ewoc-data @var{node})
+@result{} value
+
+(ewoc-set-data @var{node} @var{new-value})
+@result{} @var{new-value}
+@end lisp
+
+@noindent
+You can also use, as the data element value, a Lisp object (list or
+vector) that is a container for the ``real'' value, or an index into
+some other structure. The example (@pxref{Abstract Display Example})
+uses the latter approach.
+
+ When the data changes, you will want to update the text in the
+buffer. You can update all nodes by calling @code{ewoc-refresh}, or
+just specific nodes using @code{ewoc-invalidate}, or all nodes
+satisfying a predicate using @code{ewoc-map}. Alternatively, you can
+delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
+and add new nodes in their place. Deleting a node from an ewoc deletes
+its associated textual description from buffer, as well.
+
+@menu
+* Abstract Display Functions::
+* Abstract Display Example::
+@end menu
+
+@node Abstract Display Functions
+@subsection Abstract Display Functions
+
+ In this subsection, @var{ewoc} and @var{node} stand for the
+structures described above (@pxref{Abstract Display}), while
+@var{data} stands for an arbitrary Lisp object used as a data element.
+
+@defun ewoc-create pretty-printer &optional header footer nosep
+This constructs and returns a new ewoc, with no nodes (and thus no data
+elements). @var{pretty-printer} should be a function that takes one
+argument, a data element of the sort you plan to use in this ewoc, and
+inserts its textual description at point using @code{insert} (and never
+@code{insert-before-markers}, because that would interfere with the
+Ewoc package's internal mechanisms).
+
+Normally, a newline is automatically inserted after the header,
+the footer and every node's textual description. If @var{nosep}
+is non-@code{nil}, no newline is inserted. This may be useful for
+displaying an entire ewoc on a single line, for example, or for
+making nodes ``invisible'' by arranging for @var{pretty-printer}
+to do nothing for those nodes.
+
+An ewoc maintains its text in the buffer that is current when
+you create it, so switch to the intended buffer before calling
+@code{ewoc-create}.
+@end defun
+
+@defun ewoc-buffer ewoc
+This returns the buffer where @var{ewoc} maintains its text.
+@end defun
+
+@defun ewoc-get-hf ewoc
+This returns a cons cell @code{(@var{header} . @var{footer})}
+made from @var{ewoc}'s header and footer.
+@end defun
+
+@defun ewoc-set-hf ewoc header footer
+This sets the header and footer of @var{ewoc} to the strings
+@var{header} and @var{footer}, respectively.
+@end defun
+
+@defun ewoc-enter-first ewoc data
+@defunx ewoc-enter-last ewoc data
+These add a new node encapsulating @var{data}, putting it, respectively,
+at the beginning or end of @var{ewoc}'s chain of nodes.
+@end defun
+
+@defun ewoc-enter-before ewoc node data
+@defunx ewoc-enter-after ewoc node data
+These add a new node encapsulating @var{data}, adding it to
+@var{ewoc} before or after @var{node}, respectively.
+@end defun
+
+@defun ewoc-prev ewoc node
+@defunx ewoc-next ewoc node
+These return, respectively, the previous node and the next node of @var{node}
+in @var{ewoc}.
+@end defun
+
+@defun ewoc-nth ewoc n
+This returns the node in @var{ewoc} found at zero-based index @var{n}.
+A negative @var{n} means count from the end. @code{ewoc-nth} returns
+@code{nil} if @var{n} is out of range.
+@end defun
+
+@defun ewoc-data node
+This extracts the data encapsulated by @var{node} and returns it.
+@end defun
+
+@defun ewoc-set-data node data
+This sets the data encapsulated by @var{node} to @var{data}.
+@end defun
+
+@defun ewoc-locate ewoc &optional pos guess
+This determines the node in @var{ewoc} which contains point (or
+@var{pos} if specified), and returns that node. If @var{ewoc} has no
+nodes, it returns @code{nil}. If @var{pos} is before the first node,
+it returns the first node; if @var{pos} is after the last node, it returns
+the last node. The optional third arg @var{guess}
+should be a node that is likely to be near @var{pos}; this doesn't
+alter the result, but makes the function run faster.
+@end defun
+
+@defun ewoc-location node
+This returns the start position of @var{node}.
+@end defun
+
+@defun ewoc-goto-prev ewoc arg
+@defunx ewoc-goto-next ewoc arg
+These move point to the previous or next, respectively, @var{arg}th node
+in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at
+the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
+moves past the last node, returning @code{nil}. Excepting this special
+case, these functions return the node moved to.
+@end defun
+
+@defun ewoc-goto-node ewoc node
+This moves point to the start of @var{node} in @var{ewoc}.
@end defun
+@defun ewoc-refresh ewoc
+This function regenerates the text of @var{ewoc}. It works by
+deleting the text between the header and the footer, i.e., all the
+data elements' representations, and then calling the pretty-printer
+function for each node, one by one, in order.
+@end defun
+
+@defun ewoc-invalidate ewoc &rest nodes
+This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
+@var{ewoc} are updated instead of the entire set.
+@end defun
+
+@defun ewoc-delete ewoc &rest nodes
+This deletes each node in @var{nodes} from @var{ewoc}.
+@end defun
+
+@defun ewoc-filter ewoc predicate &rest args
+This calls @var{predicate} for each data element in @var{ewoc} and
+deletes those nodes for which @var{predicate} returns @code{nil}.
+Any @var{args} are passed to @var{predicate}.
+@end defun
+
+@defun ewoc-collect ewoc predicate &rest args
+This calls @var{predicate} for each data element in @var{ewoc}
+and returns a list of those elements for which @var{predicate}
+returns non-@code{nil}. The elements in the list are ordered
+as in the buffer. Any @var{args} are passed to @var{predicate}.
+@end defun
+
+@defun ewoc-map map-function ewoc &rest args
+This calls @var{map-function} for each data element in @var{ewoc} and
+updates those nodes for which @var{map-function} returns non-@code{nil}.
+Any @var{args} are passed to @var{map-function}.
+@end defun
+
+@node Abstract Display Example
+@subsection Abstract Display Example
+
+ Here is a simple example using functions of the ewoc package to
+implement a ``color components display,'' an area in a buffer that
+represents a vector of three integers (itself representing a 24-bit RGB
+value) in various ways.
+
+@example
+(setq colorcomp-ewoc nil
+ colorcomp-data nil
+ colorcomp-mode-map nil
+ colorcomp-labels ["Red" "Green" "Blue"])
+
+(defun colorcomp-pp (data)
+ (if data
+ (let ((comp (aref colorcomp-data data)))
+ (insert (aref colorcomp-labels data) "\t: #x"
+ (format "%02X" comp) " "
+ (make-string (ash comp -2) ?#) "\n"))
+ (let ((cstr (format "#%02X%02X%02X"
+ (aref colorcomp-data 0)
+ (aref colorcomp-data 1)
+ (aref colorcomp-data 2)))
+ (samp " (sample text) "))
+ (insert "Color\t: "
+ (propertize samp 'face `(foreground-color . ,cstr))
+ (propertize samp 'face `(background-color . ,cstr))
+ "\n"))))
+
+(defun colorcomp (color)
+ "Allow fiddling with COLOR in a new buffer.
+The buffer is in Color Components mode."
+ (interactive "sColor (name or #RGB or #RRGGBB): ")
+ (when (string= "" color)
+ (setq color "green"))
+ (unless (color-values color)
+ (error "No such color: %S" color))
+ (switch-to-buffer
+ (generate-new-buffer (format "originally: %s" color)))
+ (kill-all-local-variables)
+ (setq major-mode 'colorcomp-mode
+ mode-name "Color Components")
+ (use-local-map colorcomp-mode-map)
+ (erase-buffer)
+ (buffer-disable-undo)
+ (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
+ (color-values color))))
+ (ewoc (ewoc-create 'colorcomp-pp
+ "\nColor Components\n\n"
+ (substitute-command-keys
+ "\n\\@{colorcomp-mode-map@}"))))
+ (set (make-local-variable 'colorcomp-data) data)
+ (set (make-local-variable 'colorcomp-ewoc) ewoc)
+ (ewoc-enter-last ewoc 0)
+ (ewoc-enter-last ewoc 1)
+ (ewoc-enter-last ewoc 2)
+ (ewoc-enter-last ewoc nil)))
+@end example
+
+@cindex controller part, model/view/controller
+ This example can be extended to be a ``color selection widget'' (in
+other words, the controller part of the ``model/view/controller''
+design paradigm) by defining commands to modify @code{colorcomp-data}
+and to ``finish'' the selection process, and a keymap to tie it all
+together conveniently.
+
+@smallexample
+(defun colorcomp-mod (index limit delta)
+ (let ((cur (aref colorcomp-data index)))
+ (unless (= limit cur)
+ (aset colorcomp-data index (+ cur delta)))
+ (ewoc-invalidate
+ colorcomp-ewoc
+ (ewoc-nth colorcomp-ewoc index)
+ (ewoc-nth colorcomp-ewoc -1))))
+
+(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
+(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
+(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
+(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
+(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
+(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
+
+(defun colorcomp-copy-as-kill-and-exit ()
+ "Copy the color components into the kill ring and kill the buffer.
+The string is formatted #RRGGBB (hash followed by six hex digits)."
+ (interactive)
+ (kill-new (format "#%02X%02X%02X"
+ (aref colorcomp-data 0)
+ (aref colorcomp-data 1)
+ (aref colorcomp-data 2)))
+ (kill-buffer nil))
+
+(setq colorcomp-mode-map
+ (let ((m (make-sparse-keymap)))
+ (suppress-keymap m)
+ (define-key m "i" 'colorcomp-R-less)
+ (define-key m "o" 'colorcomp-R-more)
+ (define-key m "k" 'colorcomp-G-less)
+ (define-key m "l" 'colorcomp-G-more)
+ (define-key m "," 'colorcomp-B-less)
+ (define-key m "." 'colorcomp-B-more)
+ (define-key m " " 'colorcomp-copy-as-kill-and-exit)
+ m))
+@end smallexample
+
+Note that we never modify the data in each node, which is fixed when the
+ewoc is created to be either @code{nil} or an index into the vector
+@code{colorcomp-data}, the actual color components.
+
@node Blinking
@section Blinking Parentheses
@cindex parenthesis matching
-@cindex blinking
+@cindex blinking parentheses
@cindex balancing parentheses
-@cindex close parenthesis
This section describes the mechanism by which Emacs shows a matching
open parenthesis when the user inserts a close parenthesis.
The ordinary elements of the display table are indexed by character
codes; the element at index @var{c} says how to display the character
-code @var{c}. The value should be @code{nil} or a vector of glyph
-values (@pxref{Glyphs}). If an element is @code{nil}, it says to
-display that character according to the usual display conventions
+code @var{c}. The value should be @code{nil} or a vector of the
+glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the
+character @var{c} according to the usual display conventions
(@pxref{Usual Display}).
- If you use the display table to change the display of newline
-characters, the whole buffer will be displayed as one long ``line.''
+ @strong{Warning:} if you use the display table to change the display
+of newline characters, the whole buffer will be displayed as one long
+``line.''
The display table also has six ``extra slots'' which serve special
purposes. Here is a table of their meanings; @code{nil} in any slot
@end defun
@defun describe-display-table display-table
-@tindex describe-display-table
This function displays a description of the display table
@var{display-table} in a help buffer.
@end defun
@deffn Command describe-current-display-table
-@tindex describe-current-display-table
This command displays a description of the current display table in a
help buffer.
@end deffn
@cindex glyph
A @dfn{glyph} is a generalization of a character; it stands for an
-image that takes up a single character position on the screen. Glyphs
-are represented in Lisp as integers, just as characters are. Normally
-Emacs finds glyphs in the display table (@pxref{Display Tables}).
-
- A glyph can be @dfn{simple} or it can be defined by the @dfn{glyph
-table}. A simple glyph is just a way of specifying a character and a
-face to output it in. The glyph code for a simple glyph, mod 524288,
-is the character to output, and the glyph code divided by 524288
-specifies the face number (@pxref{Face Functions}) to use while
-outputting it. (524288 is
-@ifnottex
-2**19.)
-@end ifnottex
-@tex
-$2^{19}$.)
-@end tex
-@xref{Faces}.
+image that takes up a single character position on the screen. Normally
+glyphs come from vectors in the display table (@pxref{Display Tables}).
+
+ A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code
+can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A
+simple glyph code is just a way of specifying a character and a face
+to output it in. @xref{Faces}.
+
+ The following functions are used to manipulate simple glyph codes:
+
+@defun make-glyph-code char &optional face
+This function returns a simple glyph code representing char @var{char}
+with face @var{face}.
+@end defun
+
+@defun glyph-char glyph
+This function returns the character of simple glyph code @var{glyph}.
+@end defun
+
+@defun glyph-face glyph
+This function returns face of simple glyph code @var{glyph}, or
+@code{nil} if @var{glyph} has the default face (face-id 0).
+@end defun
On character terminals, you can set up a @dfn{glyph table} to define
-the meaning of glyph codes. The glyph codes is the value of the
-variable @code{glyph-table}.
+the meaning of glyph codes (represented as small integers).
@defvar glyph-table
-The value of this variable is the current glyph table. It should be a
-vector; the @var{g}th element defines glyph code @var{g}.
+The value of this variable is the current glyph table. It should be
+@code{nil} or a vector whose @var{g}th element defines glyph code
+@var{g}.
If a glyph code is greater than or equal to the length of the glyph
-table, that code is automatically simple. If the value of
-@code{glyph-table} is @code{nil} instead of a vector, then all glyphs
-are simple. The glyph table is not used on graphical displays, only
-on character terminals. On graphical displays, all glyphs are simple.
+table, that code is automatically simple. If @code{glyph-table} is
+@code{nil} then all glyph codes are simple.
+
+The glyph table is used only on character terminals. On graphical
+displays, all glyph codes are simple.
@end defvar
- Here are the possible types of elements in the glyph table:
+ Here are the meaningful types of elements in the glyph table:
@table @asis
@item @var{string}
Send the characters in @var{string} to the terminal to output
-this glyph. This alternative is available on character terminals,
-but not on graphical displays.
+this glyph code.
-@item @var{integer}
-Define this glyph code as an alias for glyph code @var{integer}. You
-can use an alias to specify a face code for the glyph and use a small
-number as its code.
+@item @var{code}
+Define this glyph code as an alias for glyph code @var{code} created
+by @code{make-glyph-code}. You can use such an alias to define a
+small-numbered glyph code which specifies a character with a face.
@item @code{nil}
-This glyph is simple.
+This glyph code is simple.
@end table
@defun create-glyph string
-@tindex create-glyph
This function returns a newly-allocated glyph code which is set up to
display by sending @var{string} to the terminal.
@end defun
@node Beeping
@section Beeping
-@cindex beeping
+@c @cindex beeping "beep" is adjacent
@cindex bell
This section describes how to make Emacs ring the bell (or blink the
@section Window Systems
Emacs works with several window systems, most notably the X Window
-System. Both Emacs and X use the term ``window'', but use it
+System. Both Emacs and X use the term ``window,'' but use it
differently. An Emacs frame is a single window as far as X is
concerned; the individual Emacs windows are not known to X at all.
HCoop / bpt / emacs.git / blobdiff