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

search

	Buy GNU books!

Hyperbole User Manual

10.2.1 Action Type Creation

New forms of explicit buttons may be created by adding new action types to a Hyperbole environment. The file, `hactypes.el', provides many examples of working action types.

An action type is created, i.e. loaded into the Hyperbole environment, with the (defact) function (which is an alias for (actype:create)). The calling signature for this function is given in its documentation; it is the same as that of (defun) except that a documentation string is required. (An interactive calling form is also required if the action type has formal parameters and is to be used in explicit button definitions. Implicit buttons never use an action type's interactive form. It is good practice to include an interactive form since the type creator cannot know how users may choose to apply the type.)

An action type's parameters are used differently than those of a function being called. Its interactive calling form is used when an explicit button is created to prompt for type-specific button attributes. The rest of its body is used when a button with that action type is activated. Then the button attributes together with the action type body are used to form an action that is executed in response to the button activation. The action's result is returned to the action caller unless it returns nil, in which case t is returned to the caller to ensure that it registers the performance of the action.

An action type body may perform any computation using Emacs Lisp and Hyperbole functions.

The interactive calling form for an action type is of the same form as that of a regular Emacs Lisp function definition (see the documentation for the Emacs Lisp (interactive) form). It may additionally use Hyperbole command character extensions when the form is given as a string. Each such extension character must be preceded by a plus sign, +, in order to be recognized since such characters may also have standard interactive form meanings.

The present Hyperbole extension characters are:

+I

Prompts for an existing Info node name and file.

+K

Prompts for an existing kcell identifier, either a full outline level identifier or a permanent idstamp.

+M

Prompts for a mail message date and the file name it resides in. The mail parameters prompted for by this character code are likely to change in the future.

+V

Prompts for a Hyperbole view specification. Not yet available for use.

Arguments are read by the functions in Hyperbole's hargs class, rather than the standard Lisp read functions, in order to allow direct selection of arguments via the Action Key.

If an action 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.

Once you have defined an action type within your present Hyperbole environment, you can create new explicit buttons which use it. There is no explicit button type beyond its action type, so no further work is necessary.

Call (actype:delete) to remove an action 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).