Revision: miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-12

Add section on button package to lisp reference manual

* lispref/display.texi (Buttons): New section.

2 files changed, 352 insertions, 15 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 7619d6fe2c6..b3b4abf2460 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2004-01-01  Miles Bader  <miles@gnu.org>
+
+        * display.texi (Buttons): New section.
+
 2003-12-31  Andreas Schwab  <schwab@suse.de>
 
         * numbers.texi (Math Functions): sqrt reports a domain-error
diff --git a/lispref/display.texi b/lispref/display.texi
index bd415b69697..25aea971638 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -20,18 +20,19 @@ that Emacs presents to the user.
 * Selective Display::   Hiding part of the buffer text (the old way).
 * Overlay Arrow::       Display of an arrow to indicate position.
 * Temporary Displays::  Displays that go away automatically.
-* Overlays::            Use overlays to highlight parts of the buffer.
+* Overlays::            Use overlays to highlight parts of the buffer.
 * Width::               How wide a character or string is on the screen.
-* Faces::               A face defines a graphics style for text characters:
+* Faces::               A face defines a graphics style for text characters:
                           font, colors, etc.
 * Fringes::             Controlling window fringes.
 * Scroll Bars::         Controlling vertical scroll bars.
 * Display Property::    Enabling special display features.
 * Images::              Displaying images in Emacs buffers.
+* Buttons::             Adding clickable buttons to Emacs buffers.
 * Blinking::            How Emacs shows the matching open parenthesis.
-* Inverse Video::       Specifying how the screen looks.
-* Usual Display::       The usual conventions for displaying nonprinting chars.
-* Display Tables::      How to specify other conventions.
+* Inverse Video::       Specifying how the screen looks.
+* Usual Display::       The usual conventions for displaying nonprinting chars.
+* Display Tables::      How to specify other conventions.
 * Beeping::             Audible signal to the user.
 * Window Systems::      Which window system is being used.
 @end menu
@@ -966,7 +967,7 @@ beginning and end.  It also has properties that you can examine and set;
 these affect the display of the text within the overlay.
 
 @menu
-* Overlay Properties::  How to read and set properties.
+* Overlay Properties::  How to read and set properties.
                         What properties do to the screen display.
 * Managing Overlays::   Creating and moving overlays.
 * Finding Overlays::    Searching for overlays.
@@ -1424,10 +1425,10 @@ face name a special meaning in one frame if you wish.
 * Standard Faces::      The faces Emacs normally comes with.
 * Defining Faces::      How to define a face with @code{defface}.
 * Face Attributes::     What is in a face?
-* Attribute Functions:: Functions to examine and set face attributes.
-* Merging Faces::       How Emacs combines the faces specified for a character.
+* Attribute Functions::  Functions to examine and set face attributes.
+* Merging Faces::       How Emacs combines the faces specified for a character.
 * Font Selection::      Finding the best available font for a face.
-* Face Functions::      How to define and examine faces.
+* Face Functions::      How to define and examine faces.
 * Auto Faces::          Hook for automatic face assignment.
 * Font Lookup::         Looking up the names of available fonts
                           and information about them.
@@ -2639,12 +2640,12 @@ this section describes several kinds of display specifications and what
 they mean.
 
 @menu
-* Specified Space::     Displaying one space with a specified width.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
+* Specified Space::      Displaying one space with a specified width.
+* Other Display Specs::  Displaying an image; magnifying text; moving it
                           up or down on the page; adjusting the width
                           of spaces within text.
 * Display Margins::     Displaying text or images to the side of the main text.
-* Conditional Display:: Making any of the above features conditional
+* Conditional Display::  Making any of the above features conditional
                           depending on some Lisp expression.
 @end menu
 
@@ -3401,6 +3402,338 @@ only the cache for that frame is cleared.  Otherwise all frames' caches
 are cleared.
 @end defun
 
+@node Buttons
+@section Buttons
+@cindex buttons in buffers
+@cindex clickable buttons in buffers
+
+  The @emph{button} package defines functions for inserting and
+manipulating clickable (with the mouse, or via keyboard commands)
+buttons in Emacs buffers, such as might be used for help hyperlinks,
+etc.  Emacs uses buttons for the hyperlinks in help text and the like.
+
+A button is essentially a set of properties attached (via text
+properties or overlays) to a region of text in an emacs buffer, which
+are called its button properties.  @xref{Button Properties}.
+
+One of the 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.
+
+In some ways the emacs button package duplicates functionality offered
+by the widget package (@pxref{Top, , Introduction, widget, The Emacs
+Widget Library}), but the button package has the advantage that it is
+much faster, much smaller, and much simpler to use (for elisp
+programmers---for users, the result is about the same).  The extra
+speed and space savings are useful mainly if you need to create many
+buttons in a buffer (for instance an @code{*Apropos*} buffer uses
+buttons to make entries clickable, and may contain many thousands of
+entries).
+
+@menu
+* Button Properties::      Button properties with special meanings.
+* Button Types::           Defining common properties for classes of buttons.
+* Making buttons::         Adding buttons to emacs buffers.
+* Manipulating Buttons::   Getting and setting properties of buttons.
+* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
+* Manipulating Button Types:: 
+@end menu
+
+@node Button Properties
+@subsection Button Properties
+@cindex button properties
+
+  Buttons have an associated list of properties defining their
+appearance and behavior, and other arbitrary properties may be used
+for application specific purposes.
+
+Some properties that have special meaning to the button package
+include:
+
+@table @code
+
+@item action
+The function to call when the user invokes the button, which is passed
+the single argument @var{button}.  By default this is @code{ignore},
+which does nothing.
+
+@item mouse-action
+This is similar to @code{action}, and when present, will be used
+instead of @code{action} for button invocations resulting from
+mouse-clicks (instead of the user hitting @key{RET}).  If not
+present, mouse-clicks use @code{action} instead.
+
+@item face
+This is an emacs face controlling how buttons of this type are
+displayed; by default this is the @code{button} face.
+
+@item mouse-face
+This is an additional face which controls appearance during
+mouse-overs (merged with the usual button face); by default this is
+the usual emacs @code{highlight} face.
+
+@item keymap
+The button's keymap, defining bindings active within the button
+region.  By default this is the usual button region keymap, stored
+in the variable @code{button-map}, which defines @key{RET} and
+@key{down-mouse-1} to invoke the button.
+
+@item type
+The button-type of the button.  When creating a button, this is
+usually specified using the @code{:type} keyword argument.
+@xref{Button Types}.
+
+@item help-echo
+A string displayed by the emacs tooltip help system; by default,
+@code{"mouse-2, RET: Push this button"}.
+
+@item button
+All buttons have a non-@code{nil} @code{button} property, which may be useful
+in finding regions of text that comprise buttons (which is what the
+standard button functions do).
+@end table
+
+There are other properties defined for the regions of text in a
+button, but these are not generally interesting for typical uses.
+
+@node Button Types
+@subsection Button Types
+@cindex button types
+
+  Every button has a button @emph{type}, which defines default values
+for the button's properties; button types are arranged in a hierarchy,
+with specialized types inheriting from more general types, so that
+it's easy to define special-purpose types of buttons for 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
+by giving it a @code{type} property when creating the button, using
+the @code{:type} keyword argument).
+
+In addition, the keyword argument @code{:supertype} may be used to
+specify a button-type from which @var{name} inherits its default
+property values.  Note that this inheritance happens only when
+@var{name} is defined; subsequent changes to a supertype are not
+reflected in its subtypes.
+@end defun
+
+Using @code{define-button-type} to define default properties for
+buttons is not necessary, but it is is encouraged, since doing so
+usually makes the resulting code clearer and more efficient.
+
+@node Making buttons
+@subsection Making buttons
+@cindex making buttons
+
+  Buttons are associated with a region of text, using an overlay or
+text-properties to hold button-specific information, all of which are
+initialized from the button's type (which defaults to the built-in
+button type @code{button}).  Like all emacs text, the appearance of
+the button is governed by the @code{face} property; by default (via
+the @code{face} property inherited from the @code{button} button-type)
+this is a simple underline, like a typical web-page link.
+
+For convenience, there are two sorts of button-creation functions,
+those that add button properties to an existing region of a buffer,
+called @code{make-...button}, and those also insert the button text,
+called @code{insert-...button}.
+
+The button-creation functions all take the @code{&rest} argument
+@var{properties}, which should be a sequence of @var{property value}
+pairs, specifying properties to add to the button; see @ref{Button
+Properties}.  In addition, the keyword argument @code{:type} may be
+used to specify a button-type from which to inherit other properties;
+see @ref{Button Types}.  Any properties not explicitly specified
+during creation will be inherited from the button's type (if the type
+defines such a property).
+
+The following functions add a button using an overlay
+(@pxref{Overlays}) to hold the button properties:
+
+@defun make-button beg end &rest properties
+@tindex make-button
+Make a button from @var{beg} to @var{end} in the current buffer.
+@end defun
+
+@defun insert-button label &rest properties
+@tindex insert-button
+Insert a button with the label @var{label}.
+@end defun
+
+The following functions are similar, but use emacs text-properties
+(@pxref{Text Properties}) to hold the button properties, making the
+button actually part of the text instead of being a property of the
+buffer (using text-properties is usually faster than using overlays,
+so this may be preferable when creating large numbers of buttons):
+
+@defun make-text-button beg end &rest properties
+@tindex make-text-button
+Make 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
+Insert a button with the label @var{label}, using text-properties.
+@end defun
+
+Buttons using text-properties retain no markers into the buffer are
+retained, which is important for speed in cases where there are
+extremely large numbers of buttons.
+
+@node Manipulating Buttons
+@subsection Manipulating Buttons
+@cindex manipulating buttons
+
+These are functions for getting and setting properties of buttons.
+Often these are used by a button's invocation function to determine
+what to do.
+
+Where a @var{button} parameter is specified, it means an object
+referring to a specific button, either an overlay (for overlay
+buttons), or a buffer-position or marker (for text property buttons).
+Such an object is passed as the first argument to a button's
+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}, but if the
+button has no @code{mouse-action} property, use @code{action} as
+normal.
+@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
+
+@node Button Buffer Commands
+@subsection Button Buffer Commands
+@cindex button buffer commands
+
+These are commands and functions for locating and operating on
+buttons in an emacs buffer.
+
+@code{push-button} is the command that a user uses to actually `push'
+a button, and is bound by default in the button itself to @key{RET}
+and to @key{mouse-down-1} using a region-specific keymap.  Commands
+that are useful outside the buttons itself, such as
+@code{forward-button} and @code{backward-button} are additionally
+available in the keymap stored in @code{button-buffer-map}; a mode
+which uses buttons may want to use @code{button-buffer-map} as a
+parent keymap for its keymap.
+
+@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}, try to invoke the button's
+@code{mouse-action} property instead of @code{action}, but if the
+button has no @code{mouse-action} property, use @code{action} as
+normal.  @var{pos} defaults to point, except when `push-button' is
+invoked interactively as the result of a mouse-event, in which case,
+the mouse event is used.  If there's no button at @var{pos}, do
+nothing and return @code{nil}, otherwise return @code{t}.
+@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 of the buffer continues from the other end.  If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed.  Any button with a non-@code{nil} `skip' property is
+skipped over.  Returns the button found.
+@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 of the buffer continues from the other end.  If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed.  Any button with a non-@code{nil} `skip' property is
+skipped over.  Returns the button found.
+@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.
+@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.
+@end defun
+
+@node Manipulating Button Types
+@subsection Manipulating Button Types
+@cindex manipulating button types
+
+@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
+
 @node Blinking
 @section Blinking Parentheses
 @cindex parenthesis matching
@@ -3595,9 +3928,9 @@ force redisplay of the mode line using a new display table, call
 @code{force-mode-line-update} (@pxref{Mode Line Format}).
 
 @menu
-* Display Table Format::        What a display table consists of.
-* Active Display Table::        How Emacs selects a display table to use.
-* Glyphs::                      How to define a glyph, and what glyphs mean.
+* Display Table Format::  What a display table consists of.
+* Active Display Table::  How Emacs selects a display table to use.
+* Glyphs::              How to define a glyph, and what glyphs mean.
 @end menu
 
 @node Display Table Format