Hook Functions Introduction
A hook is a user-defined function that is called at strategic places by Arbortext Editor so you can customize editing operations. Setting a hook has global effect unless you build in additional user functions to specify a local level.
|
|
Callback functions provide an easier interface than direct hooks. For instance, direct hooks only provide global monitoring, whereas callbacks can be global or specific to a document or a window. Therefore, callbacks are the preferred method for custom processing functions when both a hook and a callback are available.
|
The built-in functions add_hook and remove_hook are convenience routines that enable and disable hook functions. The add_hook function has the form:
add_hook(hookname, funcname[, prepend])
where hookname is the name of the hook set option, funcname is a string specifying the name of the user-defined function to call, and prepend is an optional flag which if non-zero specifies the function should be added to the head of the hook function list. add_hook will not add funcname if it is already present in the list. The remove_hook function has the form:
remove_hook(hookname, funcname)
where the parameters hookname and funcname are the same as for add_hook.
Whether or not a hook function is called with any parameters depends on the particular hook. It is an error to assign a hook function with mismatched parameters (although this is not detected until the hook function is called). Some hook functions must return a result. For hooks that do return a result, -1 is generally a special return value. This value means the edit operation was completed by the callback, no additional callbacks are needed, and Arbortext Editor need not continue processing the command.
A hook function may change the associated set option (by using add_hook or remove_hook), although the change will not take effect until all functions on the current hook list have been called. However, any hook may still return a value of -1 to abort the processing of the remaining hooks.
When a hook function is called, the hook is suspended so that the function will not be reentered if it executes a command or function that would result in the hook function being called again.
