List of callbacks
-----------------

GP Script provides the following callbacks:

Initialization
^^^^^^^^^^^^^^

.. callback:: Initialization
   :omitprefix:

   Initialization code here.
   There can only be one of these.

Rackspace activation
^^^^^^^^^^^^^^^^^^^^

.. callback:: Activate

   Called whenever rackspace is activated


.. callback:: Deactivate

   Called whenever we deactivate a rackspace


Variations
^^^^^^^^^^

.. callback:: Variation(oldVariation, newVariation)

   Called when you switch to another variation

   :param Integer oldVariation: The index of the variation from which you came
   :param Integer newVariation: The index of the variation you are in now


MIDI Events
^^^^^^^^^^^

.. important::

   All these callbacks require a global GP Script variable associated with a *MIDI In* block.
   For the examples in the reference, the name of the MIDI In block will be ``A800``.


.. callback:: NoteOnEvent(m) From A800

   Called whenever a NoteOn message is received

   :param NoteMessage m:

   :requirement: |requires-global-midiin-variable|


.. callback:: NoteOffEvent(m) From A800

   Called whenever a NoteOff message is received

   :param NoteMessage m:

   :requirement: |requires-global-midiin-variable|


.. callback:: NoteEvent(m) From A800

   Called whenever a NoteOn or NoteOff message is received

   :param NoteMessage m:
   
   :requirement: |requires-global-midiin-variable|

   .. warning::

      This callback will not be invoked for NoteOn events or for NoteOff events if you have defined `NoteOnEvent` or `NoteOffEvent` respectively callbacks.


.. callback:: ControlChangeEvent(c) From A800

   :param ControlChangeMessage c: 

   :requirement: |requires-global-midiin-variable|


.. callback:: PitchBendEvent(p) From A800

   :param PitchBendMessage p:

   :requirement: |requires-global-midiin-variable|


.. callback:: AftertouchEvent(a) From A800

   :param AfterTouchMessage a: Represents the current channel Aftertouch pressure

   :requirement: |requires-global-midiin-variable|

   .. todo:: How can the data in ``a`` be accessed?


.. callback:: PolytouchEvent(p) From A800

   :param PolyTouchMessage p: Represents note-specific pressure

   :requirement: |requires-global-midiin-variable|


.. callback:: ProgramChangeEvent(p) From A800

   :param ProgramChangeMessage p:

   :requirement: |requires-global-midiin-variable|


Constrained MIDI events
"""""""""""""""""""""""

The Note events (`NoteEvent`, `NoteOnEvent`, `NoteOffEvent`) and the `ControlChangeEvent` callbacks can optionally include a constraint that specifies either a range or an explicit sequence of numbers for which the callback is triggered.
For example:

.. code-block::

   On NoteEvent (m : NoteMessage) Matching [C3..C4] From A800
      // This event is only called if you play a note with
      // a MIDI note number that is in the range 60 to 72
   End

.. code-block::

   On ControlChangeEvent (c : ControlChangeMessage) Matching 1,7,14 From A800
      // This event is only called for controller numbers
      // 1, 7 or 14
   End


When you used constrained events, you can have multiple events of the same kind as long as their ranges have no overlaps.
The main purpose of this mechanism is to allow you to specify callbacks for specific purposes without having to handle all events in your script.
For example, you might create a callback to handle key switches where the bottom octave of your keyboard is used for controlling some effects while notes in other octaves are handled normally.
If you create a callback with no constraints, then any subsequent callbacks with constraints will cause a compilation error because your non-constrained callback is handling all possible values.
On the other hand, if you create some callbacks with constraints and add a non-constrained callback afterwards, then that last callback will apply just to values that have not been specified in previously defined constrained callbacks.


Widget Events
^^^^^^^^^^^^^

.. callback:: WidgetValueChanged(newValue) From SomeWidget
   
   :param Double newValue: represents a value between 0.0 and 1.0

   :requirement: A global variable associated with widget


Plugin Events
^^^^^^^^^^^^^
.. callback:: ParameterValueChanged(index, value)

   :param Integer index:
   :param Double value:

   :requirement: A global variable associated with a plugin block


Generator events
^^^^^^^^^^^^^^^^

.. callback:: TimePassing(x, y)
   
   :param Integer x: linear time based on the length (or frequency) of the generator
   :param Double y: an amplitude with a value ranging between 0.0 and 1.0. The actual value for y at some position x depends on the kind of generator and the settings being used.

   :requirement: A global variable associated with a generator

OSC messages
^^^^^^^^^^^^

.. callback:: OSCMessageReceived(message) Matching StringConstant
    
    ``StringConstant`` will be an explicit OSC Address to which this callback will respond.
    Use the OSC functions in the system library to access the arguments of the received message.
   
   :param OSCMessage message: 


Playhead events
^^^^^^^^^^^^^^^

.. callback:: BeatChanged(barNumber, beatNumber, tick)

   Called every time that ``beatNumber`` increments

   :param Integer barNumber: currently unused
   :param Integer beatNumber: number of the current beat
   :param Integer tick: currently unused

   .. warning:: |experimental|


System events
^^^^^^^^^^^^^

.. callback:: SystemEvent(newValue) Matching PlayheadStateChanged

   :param Double newValue: 1.0 when playhead has been started, 0.0 when stopped

   .. warning:: |experimental|


.. |requires-global-midiin-variable| replace:: A global GP Script variable associated with a *MIDI In* block
.. |experimental| replace:: This is experimental!