SuperCollider 3.9dev Classes (extension) | GUI | Conductor | External Control > MIDI | External Control > OSC

CVWidgetMSEditor
ExtensionExtension

a GUI for editing widgets and their parameters: specs, MIDI, OSC, actions...

Description

A special editor for CVWidgetMS: As this widget allows connecting to an arbitrary number of control-slots at once this editor is designed to allow the user to make batch-connections as well as it provides the possibility to edit each slot individually. MIDI and OSC tabs within the interface are divided into an area that allows batch editing and an area that comprehends links to CVWidgetEditors for each slot. Each slot can be connected to an external OSC- or MIDI-controller individually.

NOTE:

Class Methods

CVWidgetMSEditor.new(widget, tab)

Open a new editor for widget

Arguments:

widget

the widget-object: must be a CVWidgetMS.

tab

an Integer, specifying which tab of the editor shall be focused upon opening the editor. Each editor contains 4 tabs ( see also TabbedView2): "Spec", "MIDI", "OSC" and "Actions", each addressed by an integer value from 0 to 3

Returns:

a CVWidgetMSEditor

Inherited class methods

Instance Methods

Common GUI properties and methods

The "MIDI"-tab

.midiTabs

Every editor provides the possibility to either batch-edit or edit MIDI-connections individually. For convenience these 2 possibilities are represented within 2 tabs:

  1. a tab for editing batch-connections.
  2. a tab for editing individual MIDI-connections for each slot in the widget's multi-slider.

Returns:

.msMidiIndexStartField

A NumberBox in the batch-editing tab, allowing the user to define at which slider of the widget's multi-slider a batch-connection shall begin (indexing starts at 0)

Returns:

.midiEditGroups

A List of CVMidiEditGroups in the tab representing the individual sliders. Each of the CVMidiEditGroups provides an interface to one of the widget's sliders within the multi-slider.

Returns:

.extMidiCtrlArrayField

A TextField within the batch-editing tab that can be used to enter an Array of (external hardware) sliders.

Returns:

.midiConnectorBut

The Button within the batch-editing tab that creates the MIDI-respopnders and hence finishes a batch-connection.

Returns:

.midiDisconnectorBut

The Button within the batch-editing tab that removes all MIDI-responders connected to the parent widget.

Returns:

Batch-connecting external MIDI hardware

CVWidgetMSEditor allows connecting more than one MIDI-controller in one go:

The numbered fields in the above screenshot provide the following:

  1. MIDI init-button (AbstractCVWidgetEditor: -midiInitBut) - after MIDI has successfully been initialized the originally red button will turn green and the
  2. MIDI-source (AbstractCVWidgetEditor: -midiSourceSelect) - a dropdown-menu that will let the user select among possible MIDI-sources
  3. MIDI-source field (AbstractCVWidgetEditor: -midiSrcField) - when a MIDI-source has been selected its numeric ID will be filled into this field. I.e. any connection made within the batch of connection will listen to this particular device. However, this is optional - if no device has been selected responders will listen to any available device.
  4. MIDI-channel (AbstractCVWidgetEditor: -midiChanField) - another optional field. If no value is set responders will listen on any channel.
  5. multi-slider offset index (-msMidiIndexStartField) - the index of the slider in the multi-slider at which the batch-connection should begin. This affects the multi-slider in the widget only, not the external hardware.
  6. array of external controllers to be connected (-extMidiCtrlArrayField) - within this array the external controller numbers get set. That can be a successive range of values (e.g. (0..8)) or even concetenated arrays (e.g. (0..3)++[5, 6, 8, 9]).

Behind the scenes a batch-connection is accomplished by an algorithm like the following:

<array of ctrl.-nrs.>.do({ |ctrlNum, sl|
    <widget>.midiConnect(<MIDI device ID>, <MIDI channel>, ctrlNum, sl+<multi-slider offset index>)
})

The above code should guarantee that not only controllers get connected to successive sliders but also an offset is possible.

For further reference: CVWidget: -midiConnect

The "OSC"-tab

.oscTabs

Like the MIDI-tab the OSC-tab is organized in 2 tabs:

  1. a tab for editing batch-connections.
  2. a tab containing editable MIDI-connections for each slot in the widget's multi-slider.

Returns:

.extOscCtrlArrayField

A TextField within the batch-editing tab that allows the input of values that shall supplement the placeholders % in the command-name field or message-slot field. (see explanation below in section "Batch-connecting external OSC-controllers")

Returns:

.intStartIndexField

A NumberBox within the batch-editing tab that allows the user to set the index at which batch-connecting the sliders within the widget's multi-slider should start (0 would be the first slider within the multi-slider).

Returns:

.oscDisconnectorBut

A Button in the batch-editing tab that immediatly removes all OSC-responders within the widget.

Returns:

.oscEditBtns

A List of Buttons within the tab for editing individual OSC-connections. Each button displays the current state of the slider it belongs to, and clicking the button opens another editor, allowing to edit all MIDI- and OSC-properties of the parent slider.

Returns:

a List of Buttons

.oscCalibBtns

A List of Buttons within the tab for editing individual OSC-connections. Each button (displayed in red or green in the bottom, right corner of the OSC edit-button) allows to quickly activate or deactivate OSC-calibration for the parent slider. (See also: CVWidget: -oscCalibrate).

Returns:

a List of Buttons

Batch-connecting external OSC-controllers

Like MIDI CVWidgetMSEditor allows to connect more than one OSC-controller in one go:

The numbered fields in the above screenshot provide the following:

  1. IP-address selection (AbstractCVWidgetEditor: -deviceDropDown) - if sclang is receiving OSC the IP-addresses from which the messages are being sent will be listed here. Selecting one of them will restrict the OSC-responder to listen to that address only.
  2. restrict OSC to a specific port (AbstractCVWidgetEditor: -portRestrictor) - if this option is selected an OSC-responder will not listen to the specified IP-address only, it will also restrict listening to the port from which the regarding app/device sends the messages. However, it's probably sufficiant to restrict to an IP-address only.
  3. command-list menu (AbstractCVWidgetEditor: -cmdListMenu) - if an IP-address has been set command-names that have arrived from that IP-address will be listed here. Selecting one of them will insert the command-name in the command-name field (7).
  4. device-list menu (AbstractCVWidgetEditor: -deviceListMenu) - another option to select from a set of predefined commands is selecting a device (can e.g. be an OSC-controller on a mobile phone) which will fill up the command-list menu with commands belonging to that device/app. However, one has to first record commands coming from the app/device - see (5).
  5. record OSC-commands - this button will open the OSC-commands dialog (OSCCommands: -front) and start scanning incoming OSC for command-names. These command-names can then be stored to disk under a unique, user-defined device-name (e.g. "TouchOSC layout 16") that will appear in the device-list menu. For more information see the OSCCommands helpfile.
  6. external OSC-controller numbers (-extOscCtrlArrayField) - an Array of Integers which will be used as supplements for the placeholders used in either the command-name field (7) or the message-slot field (9). Basically OSC-responders for the given numbers will be created sequentially, using one number for one responder. Hence, the size of the array determines how many responders are going to created. See the OSC batch-connection examples below for a better understanding what's happening behind the scenes.
  7. command-name field (AbstractCVWidgetEditor: -nameField)- either enter a command-name manually or select one from the command-list menu (3) which will be inserted automatically. Optionally a placeholder % may be used which is going to be replaced by a number from the external OSC-controller numbers (6): e.g. /my/cmd/name/% used on an array [1, 2, 3] will create 3 OSC-responders for the following command-names: /my/cmd/name/1, /my/cmd/name/2, /my/cmd/name/3. See the OSC batch-connection examples below for a better understanding what's happening behind the scenes.
  8. multi-slider start offset (-intStartIndexField) - the index of the first slider in the widget's multi-slider that's supposed to get connected (numbering of sliders starts with 0). Analog to MIDI batch-connections this field allows an offset in connecting sliders of the multislider.
  9. the message-slot of of the incoming OSC message (AbstractCVWidgetEditor: -indexField) - OSC messages are seen as arrays by sclang: slot 0 will contain the command-name and an arbitrary number of successive slots may contain arbitrary data. E.g. an OSC controller may transmit data from a multi-slider like the following:
    ['/multislider', <value slider 1>, <value slider 2>,..., <value slider n>]

    A multi-dimensional OSC-message like this may be addessed in batch-connections by the placeholder %. Opposite to the possibility of using a number of different OSC command-names - as described in (7) - the command-name here is fixed but successive slots are addresses. Hence, the values in external OSC-controller numbers (6) will represent the slots within the OSC-message (starting at 1). See the OSC batch-connection examples below for a better understanding what's happening behind the scenes.

As already mentioned there are 2 different scenarios in which batch-connecting a CVWidgetMS may makes sense:

  1. a number of OSC commands which differ in one number: '/name/1', '/name/2', '/name/3',..., '/name/n' - these may belong e.g. to a multi-slider on a mobile based controller and there's exactly one value sent in slot 1 of the OSC-message. The underlying connection mechanism would be the following:
    (1..n).do({ arg num, i;
        <widget>.oscConnect(
            ip: <IP-address>,
            port: <port>,
            name: "/name/%".format(num),
            oscMsgIndex: 1,
            slot: i+<slider offset index>
        )
    });

  2. all values of from e.g. a multi-slider in mobile bsed controller are sent within 1 message '/name' within its slots 1 to n:
    (1..n).do({ arg num, i;
        <widget>.oscConnect(
            ip: <IP-address>,
            port: <port>,
            name: "/name",
            oscMsgIndex: "%".format(num),
            slot: i+<slider offset index>
        )
    })

For further reference also have a look at CVWidget: -oscConnect

The "Spec"-tab

This is the place to edit the parent widget's ControlSpec (resp. the ControlSpec of the CV wrapped by the widget). In the textfield (AbstractCVWidgetEditor: -specField) you may either edit the current spec or enter a new one. This can be done by either entering a full ControlSpec-definition (e.g. ControlSpec(10, 100, \exp)) or an Array that will automatically be expanded to a ControlSpec (e.g. #[10, 100, \exp]) or a Symbol symbolising an existing ControlSpec (e.g. \freq).

NOTE: If a one-dimensional ControlSpec gets provided (as argued in the previous sentence) the ControlSpec will automatically expand to the size of the widget's multi-slider (see also: CVWidget: -msSize). I.e. if the multi-slider incorporates 5 sliders a spec like
ControlSpec(10, 100, \exp)

will become

ControlSpec([10, 10, 10, 10, 10], [100, 100, 100, 100, 100], \exp, [0.0, 0.0, 0.0, 0.0, 0.0], [0, 0, 0, 0, 0])

In the drop-down menu below the textfield you may select any of the listed ControlSpecs. If it's a one-dimensional ControlSpec the same mechanism as in the textfield will apply. Also expanded ControlSpecs will be listed under a name that reflects the specs size - e.g. \freq expanded to size 7 will be listed as 'freq_7'

The "Actions"-tab

Even though a CVWidgetMS may have many sliders it has only one CV. As a consequence all actions apply to all sliders (unlike in a CVWidget2D which incorporates 2 CVs). However, a CVWidget2D may still have an arbitrary number of actions assigned to it. Remember that the value of the CV will be an Array of values rather than a single value. E.g. an action setting a control of a running synth will rather user a setn than set:

// example action
{ |cv| mySynth.setn(\freq, cv.value) }

.close

Close the editor.

Returns:

this (a CVWidgetMSEditor)

Inherited instance methods