Creating Action Types
New forms of explicit buttons may be created by adding new action types to a Hyperbole environment. The file, hactypes.el, contains 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 or global button definitions. Implicit buttons never use an action type’s interactive form; however, 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 to prompt for type-specific button attributes whenever an explicit button is created. The rest of its body is used when a button with this 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 that uses 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 or see Code Characters for ’interactive’ in the GNU Emacs Lisp Reference Manual. 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 different standard interactive meanings.
The present Hyperbole extension characters are:
+I
Prompts with completion for an existing Info (filename)nodename.
+K
Prompts for an existing kcell identifier, either a full outline level identifier or a permanent idstamp.
+L
Prompts for a klink specification. See the documentation for the function (kcell-view:reference) for details of the format of a klink.
+M
Prompts for a mail message date and the filename in which it resides. The mail parameters prompted for by this character code may change in the future.
+V
Prompts for a Koutliner view specification string, with the current view spec, if any, as a default.
+X
Prompts with completion for an existing Info index (filename)itemname.
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. On failure, ‘nil’ is returned 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 other 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).