Control Parameters

Nothing will be applied to the control

Sets or returns the help text which is displayed in the info pane when hovering the control

Places a control to a panel. The value should be the UI ID of the panel

Sets or returns the horizontal position in pixels

Sets or returns the vertical position in pixels

Sets or returns the horizontal position in grid units

Sets or returns the vertical position in grid units

Sets or returns the width of the control in pixels

Sets or returns the height of the control in pixels

Sets or returns the width of the control in grid units

Sets or returns the height of the control in grid units

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

$HIDE_PART_BG (background of knobs, labels, value edits and tables)

$HIDE_PART_VALUE (value of knobs and tables)

$HIDE_PART_TITLE (title of knobs)

$HIDE_PART_MOD_LIGHT (mod ring light of knobs)

$HIDE_PART_NOTHING (show all)

$HIDE_WHOLE_CONTROL

Sets or returns the picture name. An extension is not required for the picture name, neither is the full path. If the NKI references a resource container, KONTAKT will look for the file in the pictures subfolder. If the NKI does not reference a resource container, it will first look in the user pictures folder (located in user/documents/Native Instruments/Kontakt/pictures), then in the KONTAKT pictures folder.

The picture state of the control for tables, value edits and labels

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

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

-1: Back layer. Controls in this layer are placed below the default layer

1: Front layer. Controls in this layer are placed on top of the default and back layers.

Z layer order by control type (from lowest level to highest):

File Selector

Waveform

Wavetable

Level Meter

Label

Knob

Slider

Switch

Button

Value Edit

Menu

Table

XY Pad

Text Edit

Mouse Area

Sets or returns the value

Sets or returns the default value

Sets or returns the control text, similar to set_text()

Adds a text line, similar to add_text_line()

Sets or returns the knob label, similar to set_knob_label().

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

This also works for switches.

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

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

For responsive controls (buttons, switches and menus) the font can also be set separately for each of the control’s 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 for those states.

Deactivates text position shifting when clicking on buttons and switches

Shifts the vertical position in pixels of text in buttons, menus, switches and labels

The text alignment in buttons, menus, switches and labels:

0: left

1: centered

2: right

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

$CONTROL_PAR_LABEL can be used to set the automation value string

When assigning automation names to XY pad cursors, use the set_control_par_str_arr() command with this parameter.

Sets or returns if a UI control can be automated (1) or not (0). By default, automation is activated for all automatable controls. Can only be used in the init callback. Automation IDs can also be assigned to XY pad cursors using the set_control_par_arr() command.

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

Automation IDs can only be assigned to automatable controls (sliders, switches, and knobs).

When assigning automation IDs to XY pad cursors, use the set_control_par_arr() command with this parameter.

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

Menus and value edits are not supported.

The basic shift modifier functionality on sliders and knobs is preserved.

Returns 1 if the [Alt] (Windows) or [Opt] (macOS) key was pressed (0 otherwise) while clicking the UI control. Menus and value edits are not supported.

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

Menus and value edits are not supported.

Returns the index of the table column that triggered the on ui_control() callback

Sets or returns the color of the step bar in UI tables and UI waveforms.

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

9ff0000h {red}

The 9 at the start is just to let KONTAKT know the value is a number. The h at the end is to indicate that it is a hexadecimal value.

Sets or returns the color of the middle line in UI tables.

Returns the number of menu entries of a specific dropdown menu.

Only works with get_control_par().

Returns the index of the currently selected menu entry.

Only works with get_control_par().

Enables the mouse area to accept audio files.

Enables the mouse area to accept MIDI files.

Enables the mouse area to accept arrays.

$NI_DND_ACCEPT_NONE

$NI_DND_ACCEPT_ONE

$NI_DND_ACCEPT_MULTIPLE

Configures whether the mouse area's ui_control callback gets triggered just for the drop event (variable = 0) or also for drag events (variable = 1).

The ui_control callback has 2 built-in variables:

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

Equals 1 if the mouse entered the mouse_area on a drag event

Equals 0 if the mouse left the 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

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

Hides the arrows of value edits:

0: arrows are hidden

1: arrows are shown

Sets or returns the background color of the UI level meter.

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

9ff0000h {red}

The 9 at the start is just to let KONTAKT know the value is a number. The h at the end is to indicate that it is a hexadecimal value.

Sets the second background color of the UI level meter

Sets the main level meter color of the UI level meter

Sets the color of the level meter’s overload section

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

Aligns a UI level meter vertically (1) or horizontally (0, default)

Sets the minimum and maximum display range of the level meters, with default ranges from 0 to 1000000.

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

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

Be careful with the number of subfolders of the basepath as it might take too long to scan the sub file system.

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

Sets or returns the actual path (full path of the file) of the UI file selector. The file path must be a subpath of the instrument’s basepath. This control par is useful for recalling the last status of the browser upon loading the instrument. Can only be used in the init callback.

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

The following file types are available:

$NI_FILE_TYPE_MIDI

$NI_FILE_TYPE_AUDIO

$NI_FILE_TYPE_ARRAY

The (fixed) 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>)

The (fixed) 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 the init callback. Note that a wallpaper set via script replaces the one set in the instrument options and it will not be checked in the samples missing dialog when loading the wallpaper from a 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 wallpaper set will be the one that is loaded.

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

Display the zone’s slice markers

Display a per slice table

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

Make the table bipolar

Display a MIDI drag and drop icon

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

To be used with get/set_ui_wf_property()

Sets or returns the play head position

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

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

Highlights the indexed slice within the UI waveform

Defines the start note for the MIDI drag and drop function

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)

Sets the background color of the waveform display

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

9ff0000h {red}

The 9 at the start is just to let KONTAKT know the value is a number. The h at the end is to indicate that it is a hexadecimal value.

Sets or returns the color of the waveform

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

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

Sets or returns the color of the playback cursor

Sets or returns the color of the slice markers

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

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

Attaches a zone to a wavetable taking the zone idx as argument.

Sets the mode of the wavetable widget. 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)

Sets the x-axis parallax of the wavetable control (only applicable to 3D mode)

Range: -1000000 to 1000000

Sets the y-axis parallax of the wavetable control (only applicable to 3D mode)

Range: -1000000 to 1000000

Sets or returns the color of the whole wavetable

Sets or returns the alpha channel (opacity) of the whole wavetable

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

Sets or returns the background color of the wavetable widget.

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

9ff0000h {red}

The 9 at the start is just to let KONTAKT know the value is a number. The h at the end is to indicate that it is a hexadecimal value.

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

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

To be paired with the ones above to create gradient effects; if not explicitly set, they inherit the value of their match from above, resulting in no gradient.

Sets or returns the color for the end of the gradient applied to the waveform

Sets or returns the alpha channel (opacity) for the end of the gradient applied to the waveform

Sets or returns the color for the end of the gradient applied to the wavetable

Sets or returns the alpha channel (opacity) for the end of the gradient applied to the wavetable

A value from -5000 to 5000, setting the move direction of a slider and its drag-scale.

Settings are relative to the size of the slider picture.

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

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

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

Sets the way the XY pad 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_BEHAVIOR 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_BEHAVIOR 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_BEHAVIOR settings are ignored; cursor always follows mouse cursor one-to-one.

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

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

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

The index can only 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

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

Using $CONTROL_PAR_PICTURE with the XY pad 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 as with buttons/switches.

1: Inactive

2: Active

3: Inactive pressed

4: Active pressed

5: Inactive mouse over

6: Active mouse over

When used with set_control_par_arr(), this can be used to hide specific cursors in the XY pad. Below is a simple syntax 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.

Returns the index of the cursor that triggered the on ui_control() callback for the XY pad. 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.

Returns the type of mouse event that triggered the on ui_control() callback for the XY pad. Can only be used within a on ui_control()callback.

The following file types are available:

$NI_MOUSE_EVENT_TYPE_LEFT_BUTTON_DOWN (click)

$NI_MOUSE_EVENT_TYPE_LEFT_BUTTON_UP (release)

$NI_MOUSE_EVENT_TYPE_DRAG (drag)