List of Callbacks

GPScript provides the following callbacks:

Rackspace callbacks

Initialization

Initialization()    Autotype

Usage

Initialization
   // Initialization code here
End

Initialization
   // GP4 allows multiple initialization sections
End

Activation

On Activate()    Autotype

Called whenever a rackspace is activated.

Available in

Rackspace scripts and scriptlets

Usage

On Activate
   // Activation code here
End

On Deactivate()    Autotype

Called whenever we deactivate a rackspace

Available in

Rackspace scripts and scriptlets

Usage

On Deactivate
   // Deactivation code here
End

Variations

On Variation(oldVariation, newVariation)    Autotype

Called when you switch to another variation.

Available in

Rackspace scripts and scriptlets

Parameters

• oldVariation (Integer) – The index of the variation from which you came

• newVariation (Integer) – The index of the variation you are in now

Usage

On Variation (oldVariation : Integer, newVariation : Integer)
   // Callback code here
End

MIDI Events

In this chapter, you will learn more about supported MIDI events.

Unconstrained MIDI Events

Important

All these callbacks require a global GPScript variable associated with a MIDI In block. For the examples in the reference, the name of the MIDI In block will be SomeMidiInBlock.

On NoteOnEvent(m)    Autotype From SomeMidiInBlock

Called whenever a NoteOn message is received

Parameters

m (NoteMessage) –

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On NoteOnEvent (m : NoteMessage) From SomeMidiInBlock
   // Callback code here
End

On NoteOffEvent(m)    Autotype From SomeMidiInBlock

Called whenever a NoteOff message is received

Parameters

m (NoteMessage) –

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On NoteOffEvent (m : NoteMessage) From SomeMidiInBlock
   // Callback code here
End

On NoteEvent(m)    Autotype From SomeMidiInBlock

Called whenever a NoteOn or NoteOff message is received

Warning

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

Parameters

m (NoteMessage) –

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On NoteEvent (m : NoteMessage) From SomeMidiInBlock
   // Callback code here
End

On ControlChangeEvent(c)    Autotype From SomeMidiInBlock

Called whenever a Control Change event is received.

Parameters

c (ControlChangeMessage) –

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On ControlChangeEvent (c : ControlChangeMessage) From SomeMidiInBlock
   // Callback code here
End

On PitchBendEvent(p)    Autotype From SomeMidiInBlock

Called whenever a pitch bend event is received.

Parameters

p (PitchBendMessage) –

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On PitchBendEvent (c : PitchBendMessage) From SomeMidiInBlock
   // Callback code here
End

On AftertouchEvent(a)    Autotype From SomeMidiInBlock

Called whenever a channel aftertouch event is received.

Parameters

a (AfterTouchMessage) – Represents the current channel Aftertouch pressure

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On AftertouchEvent (c : AftertouchMessage) From SomeMidiInBlock
   // Callback code here
End

On PolytouchEvent(p)    Autotype From SomeMidiInBlock

Called whenever a note-specific pressure event is received.

Parameters

p (PolyTouchMessage) – Represents note-specific pressure

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On PolytouchEvent (c : PolytouchMessage) From SomeMidiInBlock
   // Callback code here
End

On ProgramChangeEvent(p)    Autotype From SomeMidiInBlock

Called whenever a Program Change event is received.

Parameters

p (ProgramChangeMessage) –

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On ProgramChangeEvent (c : ProgramChangeMessage) From SomeMidiInBlock
   // Callback code here
End

On MidiEvent(p)    Autotype From SomeMidiInBlock

Called when any MIDI event is received.

Warning

This callback does not occur if a more specific MIDI event callback was defined.

Parameters

p (MidiMessage) –

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On MidiEvent (c : MidiMessage) From SomeMidiInBlock
   // Callback code here
End

On SysexEvent(p)    Autotype From SomeSysexInBlock

Called when any system-exclusive MIDI event is received.

Warning

This callback does not occur if a more specific MIDI event callback was defined.

Parameters

p (SysexMessage) –

Requirement

A global GPScript variable associated with a MIDI In block

Usage

On SysexEvent (c : SysexMessage) From SomeMidiInBlock
   // Callback code here
End

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:

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

On ControlChangeEvent (c : ControlChangeMessage) Matching 1,7,14 From SomeMidiInBlock
   // 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.

Using Rig Manager aliases

We saw an example of using a constraint with the ControlChangeEvent callback earlier. However, if you are using the Rig Manager to because you have to use different keyboards or control surfaces then you may have a problem if you switch to a different surface whose knobs, sliders and/buttons transmit CC messages with different numbers. In such a situation a script that uses a hard-coded CC number will fail.

To address this problem, the ControlChangeEvent callback now allows you to use Rig Manager defined control aliases instead of explicit numbers in the Matching clause of the callback. If you have defined the name UpperKnob1 (for example) to represent the first knob of your control surface, then you can write the following:

On ControlChangeEvent (c : ControlChangeMessage) Matching "UpperKnob1" From SomeMidiInBlock
   // This event is called when a CC message arrives from UpperKnob1
End

At compile time, the Rig Manager will be searched to find the correct CC number for the device being used. If you change your gear and consequently update the Rig Manager, scripts will be recompiled automatically so as to reflect the change.

Note that the alias name is specified as a string constant.

Widget Events

On WidgetValueChanged([w, index, ]newValue)    Autotype From SomeWidget, [,SomeWidget]*

Called when the value of one or one of many widgets is changed.

Parameters

• w (Widget) – optional. The widget that triggered the callback.

• index (Integer) – optional. 0-based index into the From list that indicates which widget triggered the callback.

• newValue (Double) – represents the new value of the widget between 0.0 and 1.0

Requirement

A global variable associated with widget

Usage

For a single widget:

On WidgetValueChanged (newValue : Double) from SomeWidget
   // newValue represents a value between 0.0 and 1.0
End

For multiple widgets:

On WidgetValueChanged (w : Widget, index : Integer, newValue : Double)
      from SomeWidget, SomeOtherWidget, EvenOneMoreWidget

   // In this version, you can use a single callback to respond to
   // changes from multiple widgets
   //
   // The first parameter, w, is the widget that triggered the callback
   //
   // The second parameter, index, (0-based) refers to one of the
   // widgets in the 'from' clause. So, if we were triggered by
   // EvenOneMoreWidget, the value of index would be 1.
   //
   // newValue represents a value between 0.0 and 1.0
End

Plugin Events

On ParameterValueChanged(index, value)    Autotype

Parameters

• index (Integer) –

• value (Double) –

Requirement

A global variable associated with a plugin block

Usage

On ParameterValueChanged(index : Integer, value : Double) from SomePlugin
   // The parameter number and new value of the parameter
End

Scriptlet events

On ParameterValueChanged([p, index])    Autotype Matching SomeParameterVariable, [,SomeParameterVariable]*

Called when one or one of many parameter values is changed.

Parameters

• p (Parameter) – optional. Indicates the changed parameter. It needs to be continuous, subrange or discrete and must match the types of the parameter variable list.

• index (Integer) – optional. 0-based index into the Matching list that indicates which widget triggered the callback.

Available in

Scriptlets

Usage

For a single widget:

On ParameterValueChanged Matching SomeParameterVariable
   // Callback code here
End

For multiple widgets:

On ParameterValueChanged(p : Parameter, index : Integer)
      Matching SomeParameterVariable, SomeOtherParameterVariable
   // Callback code here
End

Generator events

On TimePassing(x, y)    Autotype

Parameters

• x (Integer) – linear time based on the length (or frequency) of the generator

• y (Double) – 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

Usage

On TimePassing(x : Integer, y : Double)
   // Callback code here
End

OSC messages

On OSCMessageReceived([index, ]message)    Autotype Matching StringConstant [,OtherStringConstant]*

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.

Parameters

• index (Integer) – optional. If multiple addresses are given in the Matching clause, this will be a 0-based index into the Matching list.

• message (OSCMessage) –

Usage

Basic syntax:

On OSCMessageReceived(message : OSCMessage) Matching "/some/address"
   // Callback code here
End

Extended syntax:

On OSCMessageReceived(index : Integer, message : OSCMessage)
      Matching "/some/address", "/some/other/address"
   // Callback code here
   // Note that the index parameter is still optional.
End

Playhead events

On BeatChanged(barNumber, beatNumber, tick)    Autotype

Called every time that beatNumber increments

Parameters

• barNumber (Integer) – currently unused

• beatNumber (Integer) – number of the current beat

• tick (Integer) – currently unused

Usage

On BeatChanged(barNumber : Integer, BeatNumber : Integer)
   // Callback code here
End

Global state

In this chapter, you will learn more about global state events.

On SystemEvent(newValue)    Autotype Matching PlayheadStateChanged

Called when the playhead has been started or stopped.

Parameters

newValue (Double) – 1.0 when playhead has been started, 0.0 when stopped

Available in

Rackspace and Gig file scripts

Usage

On SystemEvent(newValue : Double) Matching PlayheadStateChanged
   // Callback code here
End

On SystemEvent(newValue)    Autotype Matching GlobalTransposeChanged

Called when the global transpose value has changed.

Parameters

newValue (Integer) – the updated global transpose value

Available in

Rackspace and Gig file scripts

Usage

On SystemEvent(newValue : Double) Matching GlobalTransposeChanged
   // Callback code here
End

On SystemEvent()    Autotype Matching GigLoaded

Called after the Gig file and all rackspace and songs in it were loaded.

Available in

Gig file scripts

Usage

On SystemEvent Matching GigLoaded
   // Callback code here
End

Global events

On Rackspace(oldRackspaceIndex, newRackspaceIndex)    Autotype

Called when you switch to another rackspace.

Parameters

• oldRackspaceIndex (Integer) –

• newRackspaceIndex (Integer) –

Available in

Gig file and global rackspace scripts

Usage

On Rackspace(oldRackspaceIndex : Integer, newRackspaceIndex : Integer)
   // Callback code here
End

On Song(oldSongIndex, newSongIndex)    Autotype

Called when you switch to another song.

Parameters

• oldSongIndex (Integer) –

• newSongIndex (Integer) –

Available in

Gig file scripts

Usage

On Song(oldSongIndex : Integer, newSongIndex : Integer)
   // Callback code here
End

On Songpart(oldSongpartIndex, newSongpartIndex)    Autotype

Called when you switch to another song part.

Parameters

• oldSongpartIndex (Integer) –

• newSongpartIndex (Integer) –

Available in

Gig file and song scripts

Usage

On Songpart(oldSongpartIndex : Integer, newSongpartIndex : Integer)
   // Callback code here
End

On Keystroke()    Autotype Matching KeystrokePattern

Called when the user presses keys matching KeystrokePattern on the computer keyboard.

Available in

Gig file scripts

Usage

For single key presses:

On Keystroke matching "t"
   // Execute if the user types the single letter 't'
End

For key press sequences:

On Keystroke matching "next"
   // Execute if the user (quickly) types the sequence 'n' 'e' 'x' 't'
End

Note

Prefixes must be unique throughout the script. For example, if you write:

On Keystroke matching "ta"

then you can also write:

On Keystroke matching "tb"
On Keystroke matching "txyz"

but you cannot write:

On Keystroke matching "tap"

because the prefix ta has been previously used.

There are some restrictions on what characters are allowed in a key sequence. Also, keystroke events are only recognized when the main Gig Performer window has the focus.