Skip to main content
  • KSP Reference Manual
  • Control Parameters

Control Parameters

General

$CONTROL_PAR_NONE

Nothing will be applied to the widget.

$CONTROL_PAR_CUSTOM_ID

Sets or returns a custom value bound to a specific UI widget. This allows custom tagging of UI widgets, for instance to bind them to a specific parameter in the script.

$CONTROL_PAR_TYPE

Returns the type of the UI widget.

Only works with get_control_par().

Possible return values are:

$NI_CONTROL_TYPE_NONE (UI ID belongs to a normal variable, not a UI widget)

$NI_CONTROL_TYPE_BUTTON

$NI_CONTROL_TYPE_KNOB

$NI_CONTROL_TYPE_MENU

$NI_CONTROL_TYPE_VALUE_EDIT

$NI_CONTROL_TYPE_LABEL

$NI_CONTROL_TYPE_TABLE

$NI_CONTROL_TYPE_WAVEFORM

$NI_CONTROL_TYPE_WAVETABLE

$NI_CONTROL_TYPE_SLIDER

$NI_CONTROL_TYPE_TEXT_EDIT

$NI_CONTROL_TYPE_FILE_SELECTOR

$NI_CONTROL_TYPE_SWITCH

$NI_CONTROL_TYPE_XY

$NI_CONTROL_TYPE_LEVEL_METER

$NI_CONTROL_TYPE_MOUSE_AREA

$NI_CONTROL_TYPE_PANEL

Size, Position and Look

$CONTROL_PAR_POS_X

Sets or returns the horizontal position in pixels.

$CONTROL_PAR_POS_Y

Sets or returns the vertical position in pixels.

$CONTROL_PAR_GRID_X

Sets or returns the horizontal position in grid units.

$CONTROL_PAR_GRID_Y

Sets or returns the vertical position in grid units.

$CONTROL_PAR_WIDTH

Sets or returns the width of the control in pixels.

$CONTROL_PAR_HEIGHT

Sets or returns the height of the control in pixels.

$CONTROL_PAR_GRID_WIDTH

Sets or returns the width of the control in grid units.

$CONTROL_PAR_GRID_HEIGHT

Sets or returns the height of the control in grid units.

$CONTROL_PAR_HIDE

Sets or returns the hide status. Can be used with the following built-in constants:

$HIDE_PART_BG (background of ui_knob, ui_label, ui_value_edit and ui_table)

$HIDE_PART_VALUE (value of ui_knob and ui_table)

$HIDE_PART_TITLE (title of ui_knob)

$HIDE_PART_MOD_LIGHT (mod ring light of ui_knob)

$HIDE_PART_NOTHING (show all elements of the widget)

$HIDE_PART_CURSOR (cursor of ui_xy)

$HIDE_WHOLE_CONTROL

$CONTROL_PAR_PICTURE

Sets or returns the picture name. Full path and extension are not required. If the instrument references a resource container (in this case, Kontakt will look for the specified filename in the pictures subfolder). If the NKI does not reference a resource container, it will first look in the user pictures folder (Documents/Native Instruments/Kontakt 7/pictures), then in the Kontakt factory pictures folder.

$CONTROL_PAR_PICTURE_STATE

Sets or returns the picture state of the control for ui_label, ui_table, ui_value_edit and ui_xy.

$CONTROL_PAR_PARENT_PANEL

Assigns a widget to a particular ui_panel. The value should be the UI ID of the panel. A given widget can only belong to a single parent panel.

$CONTROL_PAR_Z_LAYER

Sets or returns the Z layer position of the widget. Widgets can be placed in one of three layers. Within these layers they are then positioned by widget type, and then by declaration order.

0: Default layer. All widgets are assigned to this layer by default.

-1: Background layer. Widgets in this layer are placed below the default layer.

1: Foreground layer. Widgets in this layer are placed on top of the default and background layers.

Z layer order by widget type (from top to bottom):

  1. Mouse Area

  2. Text Edit

  3. XY Pad

  4. Table

  5. Menu

  6. Value Edit

  7. Button

  8. Switch

  9. Slider

  10. Knob

  11. Label

  12. Level Meter

  13. Wavetable

  14. Waveform

  15. File Selector

Values

$CONTROL_PAR_MIN_VALUE

Returns the minimum declared value of the widget. This control parameter only makes sense for ui_knob, ui_slider and ui_value_edit.

Only works with get_control_par().

$CONTROL_PAR_MAX_VALUE

Returns the minimum declared value of the widget. This control parameter only makes sense for ui_knob, ui_slider and ui_value_edit.

Only works with get_control_par().

$CONTROL_PAR_VALUE

Sets or returns the value of the widget. Note that doing this does NOT execute the UI callback of the widget!

$CONTROL_PAR_DEFAULT_VALUE

Sets or returns the default value of the widget. A widget is set to the default value when clicking it with [Ctrl] (Windows) or [Cmd] (macOS) key held. This is only applicable to ui_knob and ui_slider.

Text

$CONTROL_PAR_TEXT

Sets or returns the widget text, similar to set_text().

$CONTROL_PAR_TEXTLINE

Adds a text line to multiline labels, similar to add_text_line().

$CONTROL_PAR_IDENTIFIER

Returns the name of the UI widget as declared in the script, without the type specifier ($, %, @, ?).

Only works with get_control_par().

$CONTROL_PAR_HELP

Sets or returns the help text, which is displayed in Kontakt's Info pane when hovering above the widget.

$CONTROL_PAR_LABEL

Sets or returns the widget label, similar to set_knob_label(), except this control parameter is not limited to knobs only - it also works with ui_slider, ui_switch and ui_xy.

This is also the string published to the host when using host automation.

$CONTROL_PAR_SHORT_NAME

Sets or returns the short name of the widget.

$CONTROL_PAR_UNIT

Sets or returns the knob unit, similar to set_knob_unit().

$CONTROL_PAR_FONT_TYPE

Sets or returns the font type. Numbers 0 ... 25 are used to select any of the 26 factory fonts, as shown below. Combine with get_font_id() to use custom fonts.

KSP__Font_Type.png

For responsive widgets (ui_button, ui_switch and ui_menu), the font can also be set separately for each of the states via the following control parameters:

$CONTROL_PAR_FONT_TYPE_ON

$CONTROL_PAR_FONT_TYPE_OFF_PRESSED

$CONTROL_PAR_FONT_TYPE_ON_PRESSED

$CONTROL_PAR_FONT_TYPE_OFF_HOVER

$CONTROL_PAR_FONT_TYPE_ON_HOVER

Not using any of the five additional state fonts will result in the default ($CONTROL_PAR_FONT_TYPE) being used instead.

$CONTROL_PAR_DISABLE_TEXT_SHIFTING

Deactivates text position shifting when clicking on ui_button or ui_switch.

$CONTROL_PAR_TEXTPOS_Y

Shifts the vertical position in pixels of text in ui_button, ui_switch, ui_label. ui_menu, and parameter name in ui_value_edit.

$CONTROL_PAR_TEXT_ALIGNMENT

The text alignment in ui_button, ui_switch, ui_label, ui_menu and ui_text_edit:

0: Left

1: Centered

2: Right

$CONTROL_PAR_VALUEPOS_Y

Shifts the vertical position in pixels of the parameter value in ui_value_edit.

Automation

$CONTROL_PAR_ALLOW_AUTOMATION

Sets or returns if a UI widget can be automated (1) or not (0). By default, automation is allowed for all automatable widgets (ui_knob, ui_slider, ui_switch, ui_xy cursors).

This control parameter can only be used in the on init callback.

When allowing automation for ui_xy cursors, use set_control_par_arr() command instead of set_control_par().

$CONTROL_PAR_AUTOMATION_NAME

Sets or returns an automation name to a UI widget when used with set_control_par_str().

$CONTROL_PAR_LABEL can be used to set the automation value string.

When assigning automation names to ui_xy cursors, use set_control_par_str_arr() command instead of set_control_par_str().

$CONTROL_PAR_AUTOMATION_ID

Sets or returns an automation ID to a UI widget, in range 0 ... 2047. Can only be used in the init callback.

Automation IDs can only be assigned to automatable widgets (ui_knob, ui_slider, ui_switch, ui_xy cursors).

When assigning automation IDs to ui_xy cursors, use set_control_par_arr() command instead of set_control_par().

Key Modifiers

$CONTROL_PAR_KEY_SHIFT

Returns 1 when the shift key was pressed (0 otherwise) while clicking the UI widget.

ui_menu and ui_value_edit are not supported.

The basic [Shift] modifier functionality on ui_slider and ui_knob is preserved.

$CONTROL_PAR_KEY_ALT

Returns 1 if the [Alt] (Windows) or [Opt] (macOS) key was pressed (0 otherwise) while clicking the UI widget.

ui_menu and ui_value_edit are not supported.

$CONTROL_PAR_KEY_CONTROL

Returns 1 if the [Ctrl] (Windows) or [Cmd] (macOS) key was pressed (0 otherwise) while clicking the UI widget.

ui_menu and ui_value_edit are not supported.

The basic [Ctrl]/[Cmd] modifier functionality on ui_slider and ui_knob is preserved.

Specific

Tables

$NI_CONTROL_PAR_IDX 

Returns the index of the ui_table column that triggered the on ui_control callback.

Tables and Waveforms

$CONTROL_PAR_BAR_COLOR 

Sets or returns the color of the step bar in ui_table and ui_value_edit.

Colors are set using a hex value in the following format:

0ff0000h { red } 

The 0 at the start is just to let Kontakt know the value is a number. The h or H at the end is to indicate that it is a hexadecimal value.

$CONTROL_PAR_ZERO_LINE_COLOR 

Sets or returns the color of the middle line in ui_table.

Menus

$CONTROL_PAR_NUM_ITEMS 

Returns the number of menu entries in a specific ui_menu.

Only works with get_control_par().

$CONTROL_PAR_SELECTED_ITEM_IDX 

Returns the index of the currently selected menu entry.

Only works with get_control_par().

Mouse Area

$CONTROL_PAR_DND_ACCEPT_AUDIO 

$CONTROL_PAR_DND_ACCEPT_MIDI 

$CONTROL_PAR_DND_ACCEPT_ARRAY 

Enables ui_mouse_area to accept audio, MIDI or NKA array files.

These can be set to one of the following values:

$NI_DND_ACCEPT_NONE 

$NI_DND_ACCEPT_ONE 

$NI_DND_ACCEPT_MULTIPLE 

$CONTROL_PAR_RECEIVE_DRAG_EVENTS 

Configures whether on ui_control callback of ui_mouse_area gets triggered just for the drop event (when set to 0) or also for drag events (when set to 1).

The UI callback has two built-in variables:

$NI_MOUSE_EVENT_TYPE 

Specifies the event type that triggered the callback and can have one of the following values:

$NI_MOUSE_EVENT_TYPE_DND_DROP 

$NI_MOUSE_EVENT_TYPE_DND_DRAG 

$NI_MOUSE_OVER_CONTROL 

1: The mouse has entered ui_mouse_area on a drag event

0: The mouse has left ui_mouse_area on a drag event

Example

on ui_control ($aMouseArea)   
    if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP)     
        message(num_elements(!NI_DND_ITEMS_AUDIO))      
    end if      

    if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DRAG)    
        message(num_elements(!NI_DND_ITEMS_AUDIO))    
        message($MOUSE_OVER_CONTROL)     
    end if
end on

Labels

$CONTROL_PAR_DND_BEHAVIOUR 

Sets or returns the drag and drop behavior for ui_label. Using a value of 1 sets the label as a drag and drop area, allowing the user to export the MIDI object currently held in memory by a simple drag and drop action. For more information on MIDI handling in KSP, refer to MIDI Object Commands. 

$CONTROL_PAR_MIDI_EXPORT_AREA_IDX 

Assigns one of 512 available MIDI object export areas to be drag and drop exported via a particular ui_label. For more information on MIDI handling in KSP, refer to MIDI Object Commands. 

Value Edit

$CONTROL_PAR_SHOW_ARROWS 

Hides the arrows of ui_value_edit.

0: Arrows are hidden

1: Arrows are shown

Level Meters

$CONTROL_PAR_BG_COLOR 

Sets or returns the background color of ui_level_meter.

$CONTROL_PAR_OFF_COLOR 

Sets the second background color of ui_level_meter.

$CONTROL_PAR_ON_COLOR 

Sets the main level meter color of ui_level_meter.

$CONTROL_PAR_OVERLOAD_COLOR 

Sets the color of ui_level_meter overload section.

$CONTROL_PAR_PEAK_COLOR 

Sets the color of the little bar showing the current peak level.

$CONTROL_PAR_VERTICAL 

Aligns ui_level_meter vertically (1) or horizontally (0, default).

$CONTROL_PAR_RANGE_MIN 

$CONTROL_PAR_RANGE_MAX 

Sets the minimum and maximum display range of ui_level_meter, with default range 0 ... 1000000.

If the minimum values is smaller than the maximum value, the display is inverted.

File Selector

$CONTROL_PAR_BASEPATH 

Sets or returns the basepath of ui_file_selector. This control parameter can be used in any callback.

Be careful with the number of subfolders in the basepath, as it might take too long to scan the filesystem.

$CONTROL_PAR_COLUMN_WIDTH 

Sets or returns the width of ui_file_selector columns. This control par can only be used in on init callback.

$CONTROL_PAR_FILEPATH 

Sets or returns the actual path (full path of the file) currently selected in ui_file_selector. The file path must be a subpath of the instrument’s basepath. This control parameter is useful for recalling the prior state of the file selector upon loading the instrument. Can only be used in on init callback.

$CONTROL_PAR_FILE_TYPE 

Sets or returns the file type for ui_file_selector. Can only be used in on init callback.

The following file types are available:

$NI_FILE_TYPE_MIDI 

$NI_FILE_TYPE_AUDIO 

$NI_FILE_TYPE_ARRAY 

Instrument Icon and Wallpaper

$INST_ICON_ID 

The ID of the instrument icon.

It's possible to hide the instrument icon:

set_control_par($INST_ICON_ID, $CONTROL_PAR_HIDE, $HIDE_WHOLE_CONTROL) 

It's also possible to load a different picture file for the instrument icon:

set_control_par_str($INST_ICON_ID, $CONTROL_PAR_PICTURE, <file-name>) 

$INST_WALLPAPER_ID 

The ID of the instrument wallpaper. It is used in a similar way as $INST_ICON_ID:

set_control_par_str($INST_WALLPAPER_ID, $CONTROL_PAR_PICTURE, <file_name>) 

This command can only be used in on init callback. Note that a wallpaper set via the script replaces the one set in Instrument Options dialog, and it will not be checked in the Content Missing dialog when loading the wallpaper from the resource container.

This command only supports wallpapers that are located within the resource container.

If you use it in different script slots, then the last script slot in which wallpaper was set will be the one that is loaded.

Waveform

Waveform Flag Constants 

To be used with attach_zone(). You can combine flag constants using the bitwise .or..

$UI_WAVEFORM_USE_SLICES 

Display the zone’s slice markers.

$UI_WAVEFORM_USE_TABLE 

Display a per-slice table.

Note: this only works if the slice markers are also active.

$UI_WAVEFORM_TABLE_IS_BIPOLAR 

Make the table bipolar.

$UI_WAVEFORM_USE_MIDI_DRAG 

Display a MIDI drag and drop icon.

Note: this only works if the slice markers are also active.

Waveform Property Constants 

To be used with get_ui_wf_property() and set_ui_wf_property().

$UI_WF_PROP_PLAY_CURSOR 

Sets or returns the play cursor position, in microseconds.

$UI_WF_PROP_FLAGS 

Used to set new flag constants after the attach_zone() command is used.

$UI_WF_PROP_TABLE_VAL 

Sets or returns the value of the indexed slice’s table.

$UI_WF_PROP_TABLE_IDX_HIGHLIGHT 

Highlights the indexed slice within the ui_waveform widget.

$UI_WF_PROP_MIDI_DRAG_START_NOTE 

Defines the start note for the MIDI drag and drop function.

$CONTROL_PAR_WF_VIS_MODE 

Changes the way the waveform is drawn. Valid values:

$NI_WF_VIS_MODE_1 (Default)

$NI_WF_VIS_MODE_2 (X-ray)

$NI_WF_VIS_MODE_3 (X-ray filled)

$CONTROL_PAR_BG_COLOR 

Sets or returns the background color of ui_waveform.

$CONTROL_PAR_WAVE_COLOR 

Sets or returns the color of the waveform drawn in ui_waveform.

$CONTROL_PAR_WAVE_CURSOR_COLOR 

Sets or returns the color of the playback cursor in ui_waveform.

$CONTROL_PAR_SLICEMARKERS_COLOR 

Sets or returns the color of the slice markers in ui_waveform.

$CONTROL_PAR_BG_ALPHA 

Sets or returns the alpha channel (opacity) of the background of ui_waveform.

Range: 0 (fully transparent) to 255 (fully opaque).

Wavetable

$CONTROL_PAR_WT_ZONE 

Attaches a zone to ui_wavetable, taking the zone ID as the argument.

$CONTROL_PAR_WT_VIS_MODE 

Sets or returns the visualization mode of ui_wavetable. Can be set to the following values:

$NI_WT_VIS_2D (2D, oscilloscope-style visualization, only showing the current wavetable position)

$NI_WT_VIS_3D (3D visualization displaying the whole wavetable as well as the the current position)

$CONTROL_PAR_PARALLAX_X 

Sets or returns the X-axis parallax of ui_wavetable (only applicable to 3D mode).

Range: -1000000 ... 1000000

$CONTROL_PAR_PARALLAX_Y 

Sets or returns the Y-axis parallax of ui_wavetable (only applicable to 3D mode).

Range: -1000000 ... 1000000

$CONTROL_PAR_WAVE_COLOR 

Sets or returns the color of the waveform drawn in 2D visualization mode, or the current waveform drawn in 3D visualization mode of ui_wavetable.

$CONTROL_PAR_WAVE_ALPHA 

Sets or returns the alpha channel (opacity) of the waveform drawn in 2D visualization mode, or the current waveform drawn in 3D visualization mode of ui_wavetable.

Range: 0 (fully transparent) to 255 (fully opaque).

$CONTROL_PAR_WAVETABLE_COLOR 

Sets or returns the color of the background waveforms in 3D visualization mode of ui_wavetable.

$CONTROL_PAR_WAVETABLE_ALPHA 

Sets or returns the alpha channel (opacity) of the background waveforms in 3D visualization mode of ui_wavetable.

Range: 0 (fully transparent) to 255 (fully opaque).

$CONTROL_PAR_BG_COLOR 

Sets or returns the background color of ui_wavetable.

$CONTROL_PAR_BG_ALPHA 

Sets or returns the alpha channel (opacity) of ui_wavetable.

Range: 0 (fully transparent) to 255 (fully opaque).

Additional Color and Alpha Parameters 

To be paired with the above control parameters in order to create gradient effects. If not explicitly set, they inherit the value of their match from above, resulting in no gradient.

$CONTROL_PAR_WAVE_END_COLOR 

Sets or returns the color for the end of the gradient applied to the waveform (2D) or current waveform (3D).

$CONTROL_PAR_WAVE_END_ALPHA 

Sets or returns the alpha channel (opacity) for the end of the gradient applied to the waveform (2D) or current waveform (3D).

$CONTROL_PAR_WAVETABLE_END_COLOR 

Sets or returns the color for the end of the gradient applied to the background waveforms (3D).

$CONTROL_PAR_WAVETABLE_END_ALPHA 

Sets or returns the alpha channel (opacity) for the end of the gradient applied to the background waveforms (3D).

Slider

$CONTROL_PAR_MOUSE_BEHAVIOUR 

A value from -5000 to 5000, setting the move direction of ui_slider and its sensitivity.

Settings are relative to the size of the slider picture.

Negative values give a vertical slider behavior, positive values give a horizontal behavior.

XY Pad

$CONTROL_PAR_MOUSE_BEHAVIOUR_X 

Mouse behavior, i.e. the drag scale, of the X axis of all ui_xy cursors.

$CONTROL_PAR_MOUSE_BEHAVIOUR_Y 

Mouse behavior, i.e. the drag scale, of the Y axis of all ui_xy cursors.

$CONTROL_PAR_MOUSE_MODE 

Sets the way ui_xy responds to mouse clicks and drags.

0: Clicks anywhere other than on a cursor are ignored. Clicking on a cursor and dragging, sets new values respecting the usual $CONTROL_PAR_MOUSE_BEHAVIOUR settings.

1: Clicks anywhere on the XY pad are registered but don't change the values. Clicking anywhere and dragging, sets new values; the cursor moves parallel to the mouse cursor with distances scaled based on the $CONTROL_PAR_MOUSE_BEHAVIOUR settings.

2: Clicks anywhere on the XY pad are registered and immediately change the values, with the cursor immediately matching the mouse cursor. Clicking anywhere and dragging has a similar effect; the $CONTROL_PAR_MOUSE_BEHAVIOUR settings are ignored; cursor always follows mouse cursor one-to-one.

$CONTROL_PAR_ACTIVE_INDEX 

Sets and gets the index of the active ui_xy cursor. Only relevant in multi-cursor setups. The $CONTROL_PAR_MOUSE_MODE setting will influence how this parameter behaves:

0 and 1: The active cursor can only be changed manually by setting this control parameter. Inactive cursors don't receive any clicks.

2: Active cursor is set automatically based on the last clicked cursor. Setting it manually within on ui_control callback of ui_xy can result in unexpected results, but using it in other callbacks is fully encouraged and makes sense in many scenarios. The returned value is -1 when not clicking on any cursor.

The index can only ever be an even number (with the exception of the -1 value) that matches the index of the X axis of the cursor in the main array representing the XY control, e.g. the first cursor has an index of 0, the second one has an index of 2, etc.

$CONTROL_PAR_CURSOR_PICTURE 

Sets the cursor image. Each cursor can have its own image set using the set_control_par_str_arr() command.

Using $CONTROL_PAR_PICTURE on ui_xy UI ID itself will set the background image of the control.

The cursor images can have up to 6 frames, corresponding to the following states. Frame selection is automatic, exactly like with ui_button and ui_switch.

1: Inactive

2: Active

3: Inactive pressed

4: Active pressed

5: Inactive mouse over

6: Active mouse over

$HIDE_PART_CURSOR 

When used with set_control_par_arr(), this can be used to hide specific ui_xy cursors. Below is a simple example:

if ($hide = 1)
    set_control_par_arr($id, $CONTROL_PAR_HIDE, $HIDE_PART_CURSOR, $index)
else
    set_control_par_arr($id, $CONTROL_PAR_HIDE, $HIDE_PART_NOTHING, $index)
end if

The index should be an even number that matches the index of the X axis of the cursor in the main array representing the XY control, so the first cursor has an index of 0, the second has an index of 2, and so on.

$NI_CONTROL_PAR_IDX 

Returns the index of the cursor that triggered the on ui_control callback of a ui_xy widget. Note that indices are always even numbers starting from 0, so the first cursor has an index of 0, the second has an index of 2, and so on.

$NI_MOUSE_EVENT_TYPE 

Returns the type of mouse event that triggered the on ui_controlcallback of a ui_xy widget. Can only be used within the on ui_control callback.

The following mouse event types are available:

$NI_MOUSE_EVENT_TYPE_LEFT_BUTTON_DOWN 

$NI_MOUSE_EVENT_TYPE_LEFT_BUTTON_UP 

$NI_MOUSE_EVENT_TYPE_DRAG