39.19.5 Button Buffer Commands

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.

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 Clickable Text.

command push-button \&optional pos use-mouse-action

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.

command forward-button n \&optional wrap display-message no-error

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.

command backward-button n \&optional wrap display-message no-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.

function next-button pos \&optional count-current

function previous-button pos \&optional count-current

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.