These are commands and functions for locating and operating on buttons in an Emacs buffer.
push-button
is the command that a user uses to actually push
a button, and is bound by default in the button itself to RET
and to mouse-2 using a local keymap in the button’s overlay or
text properties. Commands that are useful outside the buttons itself,
such as forward-button
and backward-button
are
additionally available in the keymap stored in
button-buffer-map
; a mode which uses buttons may want to use
button-buffer-map
as a parent keymap for its keymap.
Alternatively, the button-mode
can be switched on for much the
same effect: It’s a minor mode that does nothing else than install
button-buffer-map
as a minor mode keymap.
If the button has a non-nil
follow-link
property, and
mouse-1-click-follows-link
is set, a quick mouse-1 click
will also activate the push-button
command.
See Defining Clickable Text.
Perform the action specified by a button at location pos.
pos may be either a buffer position or a mouse-event. If
use-mouse-action is non-nil
, or pos is a
mouse-event (see Mouse Events), try to invoke the button’s
mouse-action
property instead of action
; if the button
has no mouse-action
property, use action
as normal.
pos defaults to point, except when push-button
is invoked
interactively as the result of a mouse-event, in which case, the mouse
event’s position is used. If there’s no button at pos, do
nothing and return nil
, otherwise return t
.
Move to the nth next button, or nth previous button if
n is negative. If n is zero, move to the start of any
button at point. If wrap is non-nil
, moving past either
end of the buffer continues from the other end. If
display-message is non-nil
, the button’s help-echo string
is displayed. Any button with a non-nil
skip
property
is skipped over. Returns the button found, and signals an error if no
buttons can be found. If no-error is non-nil
, return nil
instead of signaling the error.
Move to the nth previous button, or nth next button if
n is negative. If n is zero, move to the start of any
button at point. If wrap is non-nil
, moving past either
end of the buffer continues from the other end. If
display-message is non-nil
, the button’s help-echo string
is displayed. Any button with a non-nil
skip
property
is skipped over. Returns the button found, and signals an error if no
buttons can be found. If no-error is non-nil
, return nil
instead of signaling the error.
Return the next button after (for next-button
) or before (for
previous-button
) position pos in the current buffer. If
count-current is non-nil
, count any button at pos
in the search, instead of starting at the next button.