www.delorie.com/gnu/docs/hyperbole/hyperbole_64.html

search

	Buy GNU books!

Hyperbole User Manual

10.2.2 Implicit Button Types

An implicit button type is created or loaded via the (defib) function (which is an alias for (ibtype:create)). The calling signature for this function is given in its documentation; it is the same as that of (defun), but with a number of constraints. The parameter list should always be empty since no parameters will be used. A documentation string is required. The type's body follows this.

The body of an implicit button type is a predicate which determines whether or not point is within an implicit button of the type. If not, the predicate returns nil. If so, it may optionally setup to flash the button and then perform one or more actions. A call of the form: (ibut:label-set label start-pos end-pos) is used to setup the button flashing, if desired. This is then typically immediately followed by an action invocation of the form: (hact 'actype &rest actype-arguments). It is imperative that all actions (non-predicate code) be invoked through the (hact) function rather than directly or your ibtypes will not work properly. (Hyperbole first tests to see if any ibtype matches the current context before activating any type, so it ensures that (hact) calls are disabled during this testing.) Any action types used may be created before or after the implicit button type definition but obviously should be defined before any implicit buttons of the given type are activated; an error will result, otherwise.

If an implicit button type create is successful, the symbol that Hyperbole uses internally to reference the type is returned. Nil is returned on failure so that you may test whether or not the operation succeeds. Implicit button type names and action type names may be the same without any conflict. In fact, such naming is encouraged when an implicit button type is the exclusive user of an action type.

Call (ibtype:delete) to remove an implicit button type from a Hyperbole environment. It takes a single parameter which should be the same type symbol used in the type definition call (not the Hyperbole symbol returned by the call). This will not delete the action type used by the implicit button; that must be done separately.

By default, a request for help on an implicit button will display the button's attributes in the same manner as is done for explicit buttons. For some implicit button types, other forms of help will be more appropriate. If an Emacs Lisp function is defined whose name is formed from the concatenation of the type name followed by :help, e.g. my-ibtype:help, it is used to respond to requests for help on buttons of that type. Any such function should take a single argument of an implicit button construct. (This is what (ibut:at-p) returns when point is within an implicit button context.) The button may be queried for its attributes using functions from the hbut and hattr classes. See the `hib-kbd.el' file for an example of a custom help function.