Callback Functions Introduction

A callback function is a user-defined function that is called during specific events in Arbortext Editor and allows you to customize editing operations. Callback functions provide both a global and a local level of registration or notification to isolate events, while hooks provide only global effect (unless additional user functions are supplied). For example, you might want a particular function called whenever a specific document is saved or a help window has a quit request.

Using Callbacks instead of Hooks

Where possible, use the callback functions instead of hook functions. In some cases, disabling and resetting hooks using sethookname may disrupt the functioning of Arbortext Editor applications.

At the session level, there are two basic callback functions. The session_add_callback function adds a specified function as a callback that's invoked whenever the Arbortext Editor session occurs. The session_remove_callback function removes the function as a callback for session monitoring.

At the window level, there are also two callback functions. The window_add_callback function adds a specified function as a callback to that is invoked whenever the specified action occurs in the specified window or in any window if win is 0. The window_remove_callback function removes the function as a callback.

At the document level, there are two basic callback functions. The doc_add_callback function adds a specified function as a callback that is invoked whenever the specified action occurs in the specified document, or in any document if doc is 0. The doc_remove_callback function removes the function as a callback.

At the dialog item level, there are two basic callback functions. The dlgitem_add_callback function adds a specified function as a callback that is invoked whenever the specified action occurs at the specified dialog item. The dlgitem_remove_callback function removes the function as a callback.

You can also invoke callbacks after a specified amount of time. The timer_add_callback function adds a specified function as a callback that is invoked after a specified interval. The timer_remove_callback function removes the function as a callback.

The basic structure of a callback is (document-level callbacks are used for these examples):

The function specified by funcname is a callback that is invoked whenever the type of action specified by cbtype occurs in document ID doc.

doc is either a valid document ID, or 0. If doc is 0, the callback applies to all documents.

cbtype is a string and must be a callback.

funcname should be a fully-qualified function name with no argument list. As examples of valid and invalid names for funcname:

Callback function specification
Callback function name	Description
'mycallbacks::mycback'	Valid form, where mycallbacks is the package name
'mycback'	Valid, but specify the package name to avoid ambiguity
'xxx::mycback()'	Invalid. The callback function name can't include parentheses.

In the next example, the function mycallback is removed as a callback of type cbtype on the document doc.

An example of a function that is notified whenever a cut is requested on docs 5, 7 or 10:

package mycallbacks
function cut_callback( doc, op )
{
if ( op == 1 )
{
# no reason not to proceed
return 0
}
else if ( op == 2 )
{
# this is where processing occurs
# we want to block the user from
# cutting anywhere inside <para> tags in this doc
if ( inside_tag('para', doc) )
{
response( 'Can\'t cut inside <para> tags.' )
return -1
}
else
{
return 0
}
}
}
...
doc_add_callback( 5, 'cut', 'mycallbacks::cut_callback' )
doc_add_callback( 7, 'cut', 'mycallbacks::cut_callback' )
doc_add_callback( 10, 'cut', 'mycallbacks::cut_callback')

Whether or not a callback function is called with any parameters depends on the particular function. It is an error to assign a callback function when its parameters do not match (although this is not detected until the function is called).

Callback functions that take op as their last argument are called twice in succession. The first call (op=1) checks for approval to act. A return value of 0 means continue execution. A return value of -1 from any callback means stop the operation without calling any more callbacks that may be registered, do not make any op=2 callback calls, and skip basic Arbortext Editor processing. The second call (op=2) performs the action unless the operation has been stopped earlier. A return value of 0 allows basic Arbortext Editor processing after all callbacks have been called. A return code of -1 from any callback prevents basic Arbortext Editor processing.