Internal Event Callbacks¶
Event Callbacks are a way to call a function or a process each time some internal event occurs. These internal event cannot be handled by a predicate so the usual whenever mechanism cannot be used to react to these events.
The internal events handled are the following:
-
The begining or the end of a logical instant: a logical instant corresponds to some activity triggered somewhere. A logical instant gather all computations that must be done simultaneously. The reception of an OSC message, the recognition of a musical event, the expiration of a delay, the reception of a Max or PD message, etc., give rise to a new logical instant. It is possible to trigger a function or a process at the very begining of a logical instant, or at its end.
-
The entry or the exit of the fastforward mode.
-
The occurence of the next event (this event can be signaled by the listening machine or result of a
antescofo::nextevent
command). -
The occurence of a musical event (for all musical events).
-
The occurence of a
antescofo::stop
command).
The handler triggered by such internal events is installed using a call to the following system functions:
- @callback_start_logical_instant
- @callback_stop_logical_instant
- @callback_start_fastforward
- @callback_stop_fastforward
- @callback_next_event
- @callback_all_event
- @callback_stop
The handler is any applicable value that takes two parameters. When
called, the handler is called with two arguments: the relative time
(i.e., the value of $RNOW
at the time of call), and the
abslute time (i.e., the value of $NOW
at the time of
call).
The previous functions install a new handler to be triggered when an internal event occurs. They all have the same signature
@callback_xxx(handler, persistence)
where handler
is an applicable value and persistence
is a boolean value that specifies if the handler is
triggered only one time (nd then the handler is no longer active) or if
the handler is used for all occurences of the xxx
internal event.
Notice the installation of a persistent handler for the next event, implements the same behavior as a persistent handler for all events. Similarly, a non persistent handler for all events achieve the same effect of a non persistent handler for the next event.
The installation functions return a non-zero integer rank
that can be used later to remove an handler, using the following
signature:
@callback_xxx(<undef>, rank)
Several handlers can be installed for the same internal event. They are triggered following their installation sequence (the rank returned by the installation functions is related to the sequence of handlers for a given internal event).
See additional information at @callback_xxx