Programmatic Button Creation

A common need when developing with Hyperbole is to create or to modify explicit buttons without user interaction. For example, an application might require the addition of an explicit summary button to a file for each new mail message a user reads that contains a set of keywords. The user could then check the summary file and jump to desired messages quickly.

The Hyperbole class ‘ebut’ supports programmatic access to explicit buttons. Examine it within the hbut.el file for full details.

The simplest way to create explicit buttons programmatically is to call ebut:program. This generates an explicit button at point from LABEL, ACTYPE (action type) and any optional ACTYPE ARGS. It inserts the LABEL text at point surrounded by <( )> delimiters, adding any necessary instance number of the button after the LABEL. ACTYPE may be a Hyperbole action type name (from defact) or an Emacs Lisp function, followed by a list of arguments for the actype, aside from the button LABEL which is automatically provided as the first argument.

For interactive explicit creation, use hui:ebut-create instead.

The documentation for (ebut:create) explains the set of attributes necessary to create an explicit button. For operations over the whole set of buttons within the visible (non-narrowed) portion of a buffer, use the (ebut:map) function.

Similarly, gbut:ebut-program programmatically adds global explicit buttons at the end of the personal button file.