37.18.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

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.

Command: backward-button n &optional wrap display-message

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.

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.