User Interface Commands

add_menu_item()

`add_menu_item(<variable>, <text>, <value>)`
Create an entry in a `ui_menu` widget.
`<variable>`	The variable name of the `ui_menu` widget.
`<text>`	The text of the menu entry.
`<value>`	The value of the menu entry.

Remarks

You can create menu entries only in the on init callback, but you can change their text and value afterwards by using set_menu_item_str() and set_menu_item_value(). You can add as many menu entries as you want, then show or hide them dynamically by using set_menu_item_visibility().
Using the $CONTROL_PAR_VALUE control parameter with the get_control_par() command will return the currently selected menu index, not the currently selected value. If you want to get the menu value instead, use the get_menu_item_value() command.

Examples

on init
    declare ui_menu $menu
    add_menu_item($menu, "First Entry", 0)
    add_menu_item($menu, "Second Entry", 1)
    add_menu_item($menu, "Third Entry", 2)
end on

A simple menu.

add_text_line()

`add_text_line(<variable>, <text>)`
Add a new text line in the specified `ui_label`, without erasing existing text.
`<variable>`	The variable name of the `ui_label` widget.
`<text>`	The text to be displayed.

Examples

on init
    declare $count
    declare ui_label $label (1, 4)

    set_text($label, "")
end on

on note
    inc($count)

    select ($count)
        case 1
            set_text($label, $count & ": " & $EVENT_NOTE)
        case 2 to 4
            add_text_line($label, $count & ": " & $EVENT_NOTE)
    end select

    if ($count = 4)
        $count := 0
    end if
end on

Monitoring the last four played notes.

attach_level_meter()

`attach_level_meter(<ui-id>, <group>, <slot>, <channel>, <generic>)`
Attach a `ui_level_meter` to a certain location within the instrument to read volume data.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<group>`	The index of the group you want to access. Should be set to -1 if not using the group level.
`<slot>`	The index of the FX slot you wish to access. Should be set to -1 if not accessing an FX slot.
`<channel>`	Select from 0 to 15 to set the audio channel the level meter will be displaying.
`<generic>`	Can be one of the following: `NI_LEVEL_METER_MAIN`: used to access Main FX chain `NI_LEVEL_METER_GROUP`: used to access the Group FX chain `NI_LEVEL_METER_INSERT`: used to access the Insert FX chain `0 ... 15`: used to access individual instrument buses

Remarks

Level meters can be attached to the output of an instrument bus and the instrument main output. They can also be attached to compressor and limiter effects to display gain reduction data, with the ability to set minimum and maximum display values and inverting the display by using $CONTROL_PAR_RANGE_MIN and $CONTROL_PAR_RANGE_MAX control parameters.

Examples

on init
    declare const $GROUP_IDX := 0
    declare const $BUS_IDX := 0
    declare const $SLOT_IDX := 0
    declare const $CHANNEL_L := 0
    declare const $CHANNEL_R := 1

    declare ui_label $InstOutputL (1, 1)
    declare ui_label $InstOutputR (1, 1)
    declare ui_label $BusOutput (1, 1)
    declare ui_label $MainFX (1, 1)
    declare ui_label $BusFX (1, 1)
    declare ui_label $GroupFX (1, 1)

    declare ui_level_meter $inst_output_l_lvl
    declare ui_level_meter $inst_output_r_lvl
    declare ui_level_meter $bus_output_lvl
    declare ui_level_meter $mainfx_output_lvl
    declare ui_level_meter $busfx_output_lvl
    declare ui_level_meter $groupfx_output_lvl

    attach_level_meter(get_ui_id($inst_output_l_lvl), -1, -1, $CHANNEL_L, -1)
    attach_level_meter(get_ui_id($inst_output_r_lvl), -1, -1, $CHANNEL_R, -1)
    attach_level_meter(get_ui_id($bus_output_lvl), -1, -1, $CHANNEL_L, $BUS_IDX)
    attach_level_meter(get_ui_id($mainfx_output_lvl), -1, $SLOT_IDX, $CHANNEL_L, -2)
    attach_level_meter(get_ui_id($busfx_output_lvl), -1, $SLOT_IDX, $CHANNEL_L, $BUS_IDX)
    attach_level_meter(get_ui_id($groupfx_output_lvl), $GROUP_IDX, $SLOT_IDX, $CHANNEL_L, -1)
end on

Various level meters.

attach_zone()

`attach_zone(<variable>, <zone-id>, <flags>)`
Connects the corresponding zone to the waveform so that it shows up on the `ui_waveform` widget.
`<variable>`	The variable name of the `ui_waveform` widget.
`<zone-id>`	The ID number of the zone that you want to attach.
`<flags>`	You can control different settings of the widget via the following flags: `$UI_WAVEFORM_USE_SLICES` `$UI_WAVEFORM_USE_TABLE` `$UI_WAVEFORM_TABLE_IS_BIPOLAR` `$UI_WAVEFORM_USE_MIDI_DRAG`

Remarks

Use the bitwise .or. operator to combine flags.
The $UI_WAVEFORM_USE_TABLE and $UI_WAVEFORM_USE_MIDI_DRAG flags will only work if $UI_WAVEFORM_USE_SLICES is already set.

Examples

on init
    declare ui_waveform $Waveform (6, 6)
    attach_zone ($Waveform,find_zone(”Test”), $UI_WAVEFORM_USE_SLICES .or. $UI_WAVEFORM_USE_TABLE)
end on

Attaches a zone named “Test” to the ui_waveform widget, also showing the zone’s slices and a table.

fs_get_filename()

`fs_get_filename(<ui-id>, <return-parameter>)`
Return the filename of the last selected file in a `ui_file_selector` widget.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<return-parameter>`	0: Returns the filename without extension. 1: Returns the filename with extension. 2: Returns the whole path.

fs_get_filename(<ui-id>, <return-parameter>)

Return the filename of the last selected file in a ui_file_selector widget.

<ui-id>

The ID number of the UI widget. You can retrieve it with get_ui_id().

<return-parameter>

0: Returns the filename without extension.

1: Returns the filename with extension.

2: Returns the whole path.

Remarks

This command is only available in the on ui_control callbacks of ui_file_selectors.

fs_navigate()

`fs_navigate(<ui-id>, <direction>)`
Jump to the previous or next file in a ui_file_selector widget and trigger its callback.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<direction>`	0: The previous file (in relation to the currently selected one) is selected 1: The next file (in relation to the currently selected one) is selected

fs_navigate(<ui-id>, <direction>)

Jump to the previous or next file in a ui_file_selector widget and trigger its callback.

<ui-id>

The ID number of the UI widget. You can retrieve it with get_ui_id().

<direction>

0: The previous file (in relation to the currently selected one) is selected

1: The next file (in relation to the currently selected one) is selected

Remarks

This command is only available in the on ui_control callbacks of ui_file_selectors.
It will always call the UI callback of the ui_file_selector it is pointed to.

get_control_par()

`get_control_par(<ui-id>, <control-parameter>)`
Retrieve various parameters of the specified UI widget.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<control-parameter>`	Parameter of the UI widget we want to retrieve, i.e. `$CONTROL_PAR_WIDTH`.

Remarks

get_control_par_str() is an additional flavor of the command for use with strings (i.e. retrieving text from ui_label or automation name from ui_slider).

Examples

on init
    declare ui_value_edit $Test (0, 100, 1)
    message(get_control_par(get_ui_id($Test), $CONTROL_PAR_WIDTH))
end on

Retrieving the width of a value edit in pixels.

get_control_par_arr()

`get_control_par_arr(<ui-id>, <control-parameter>, <index>)`
Retrieve various parameters of the specified UI widget
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<control-parameter>`	Parameter of the UI widget we want to retrieve, i.e. `$CONTROL_PAR_WIDTH`.
`<index>`	Array index of the UI widget we want to retrieve.

Remarks

get_control_par_arr() comes in two additional flavors:
- get_control_par_str_arr() (i.e. retrieving automation name of a particular ui_xy cursor)
- get_control_par_real_arr() (i.e. retrieving values of ui_xy cursor X and Y axes)

Examples

on init
    declare ui_xy ?XY1[2]
    declare ui_xy ?XY2[2]
    declare ui_xy ?XY3[2]
    declare ui_xy ?XY4[2]
    declare ui_button $Random

    declare $i
    declare ~val
end on

on ui_control ($Random)
    $i := 0
    while ($i < 8)
        { randomize X axis value }
        ~val := int_to_real(random(0, 1000000)) / 1000000.0
        set_control_par_real_arr(get_ui_id(?XY1) + $i / 2, $CONTROL_PAR_VALUE, ~val, $i mod 2)

        { randomize Y axis value }
        ~val := int_to_real(random(0, 1000000)) / 1000000.0
        set_control_par_real_arr(get_ui_id(?XY1) + $i / 2, $CONTROL_PAR_VALUE, ~val, ($i mod 2) + 1)

        inc($i)
    end while

    $Random := 0
end on

Randomize the values of the first cursor for 4 different XY pads in one loop.

get_font_id()

`get_font_id(<file-name>)`
Returns a font ID generated for a custom font based on an image file. This font ID can be used on any control that has dynamic text elements.
`<file-name>`	Name of the image, without extension. The image has to be in PNG format and reside in the "pictures" subfolder of the resource container.

Remarks

This command is only available in the on init callback.
Custom font images need to be formatted in a special way to be interpreted correctly as custom fonts. All characters need to be placed side-by-side, following the Windows-1252 character set, with a fully red (#FF0000) pixel at the top left of every character frame. Also, alpha layer of this image needs to be solid (contain only one color). We recommend using the SuperPNG addon for Adobe Photoshop (use the "Clean Transparent" option during export), or KSP Font Generator plugin for Figma.

Examples

on init
    declare ui_text_edit @textEdit
    set_control_par(get_ui_id(@textEdit), $CONTROL_PAR_FONT_TYPE, get_font_id("Font1"))
end on

Using a custom font on a ui_text_edit control.

get_menu_item_str()

`get_menu_item_str(<ui-id>, <index>)`
Returns the string value of a particular `ui_menu` entry.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<index>`	The index (not the value!) of the menu item.

Remarks

The <index> is defined by the order in which the menu items are added within the on init callback; it cannot be changed afterwards.

Examples

on init
    declare ui_button $button
    declare ui_menu $menu

    add_menu_item($menu, "First Entry", 0)
    add_menu_item($menu, "Second Entry", 5)
    add_menu_item($menu, "Third Entry", 10)
end on

on ui_control ($button)
    message(get_menu_item_str(get_ui_id($menu), 1))
end on

Displays the message “Second Entry” when clicking on the button, since we are reading the text of menu item index 1.

get_menu_item_value()

`get_menu_item_value(<ui-id>, <index>)`
Returns the value of a particular `ui_menu` entry.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<index>`	The index (not the value!) of the menu item.

Remarks

The <index> is defined by the order in which the menu items are added within the on init callback; it cannot be changed afterwards.

Examples

on init
    declare ui_button $button
    declare ui_menu $menu

    add_menu_item($menu, "First Entry", 0)
    add_menu_item($menu, "Second Entry", 5)
    add_menu_item($menu, "Third Entry", 10)
end on

on ui_control ($button)
    message(get_menu_item_value(get_ui_id($menu), 1))
end on

Displays the number 5, since we're reading the value of menu item index 1.

get_menu_item_visibility()

`get_menu_item_visibility(<ui-id>, <index>)`
Returns 1 if a particular `ui_menu` entry is visible, otherwise 0.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<index>`	The index (not the value!) of the menu entry.

Remarks

The <index> is defined by the order in which the menu items are added within the on init callback; it cannot be changed afterwards.

Examples

on init
    declare ui_button $visibility
    declare ui_button $value
    declare ui_menu $menu

    add_menu_item($menu, "First Entry", 0)
    add_menu_item($menu, "Second Entry", 5)
    add_menu_item($menu, "Third Entry", 10)
end on

on ui_control ($visibility)
    set_menu_item_visibility(get_ui_id($menu), $visibility))
end on

on ui_control ($value)
    message(get_menu_item_visibility(get_ui_id($menu), 1))
end on

Clicking on Visibility button shows or hides the second menu entry, while clicking on Value button shows the visibility state of that same menu entry.

get_ui_id()

`get_ui_id(<variable>)`
Retrieves the UI ID number of a UI widget.

Remarks

UI IDs are assigned sequentially from the very first variable or constant declared in the script, which starts at 32768.
Even regular variables and constants (those that are not UI widgets) get a UI ID assigned, however this ID cannot be used with various get_control_par()/set_control_par() commands!

Examples

on init
    declare const $NUM_KNOBS := 4

    declare ui_knob $Knob_1 (0, 100, 1)
    declare ui_knob $Knob_2 (0, 100, 1)
    declare ui_knob $Knob_3 (0, 100, 1)
    declare ui_knob $Knob_4 (0, 100, 1)

    declare ui_value_edit $Set (0, 100, 1)

    declare $i
    declare %ID[$NUM_KNOBS]

    while ($i < $NUM_KNOBS)
        %ID[$i] := get_ui_id($Knob_1) + $i

        inc($i)
    end while
end on

on ui_control ($Set)
    $i := 0
    while ($i < $NUM_KNOBS)
        set_control_par(%ID[$i], $CONTROL_PAR_VALUE, $Set)
        inc($i)
    end while
end on

Store IDs in an array and use those IDs to set multiple knobs to the same value.

get_ui_wf_property()

`get_ui_wf_property(<variable>, <property>, <index>)`
Returns the values of different properties pertaining to the `ui_waveform` widget.
`<variable>`	Variable name of the `ui_waveform` widget.
`<property>`	The following properties are available: `$UI_WF_PROP_PLAY_CURSOR` `$UI_WF_PROP_FLAGS` `$UI_WF_PROP_TABLE_VAL` `$UI_WF_PROP_TABLE_IDX_HIGHLIGHT` `$UI_WF_PROP_MIDI_DRAG_START_NOTE`
`<index>`	The index of the slice.

Examples

on init
    declare $play_pos

    declare ui_waveform $Waveform (6, 6)

    attach_zone($Waveform, find_zone("Test"), 0)
end on

on note
    while ($NOTE_HELD = 1)
        $play_pos := get_event_par($EVENT_ID, $EVENT_PAR_PLAY_POS)

        set_ui_wf_property($Waveform, $UI_WF_PROP_PLAY_CURSOR, $play_pos)
        message(get_ui_wf_property($Waveform, $UI_WF_PROP_PLAY_CURSOR, 0))

        wait(10000)
    end while
end on

Displays the current play position value.

hide_part()

`hide_part(<variable>, <hide-mask>)`
Hide specific parts of various widgets.
`<variable>`	The variable name of the widget.
`<hide-mask>`	Bitmask of visibility states for various parts of UI controls, consisting of the following 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_CURSOR` (hide a particular `ui_xy` cursor)

hide_part(<variable>, <hide-mask>)

Hide specific parts of various widgets.

<variable>

The variable name of the widget.

<hide-mask>

Bitmask of visibility states for various parts of UI controls, consisting of the following 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_CURSOR (hide a particular ui_xy cursor)

Examples

on init
    declare ui_knob $Knob (0, 100, 1)

    hide_part($Knob, $HIDE_PART_BG .or. $HIDE_PART_MOD_LIGHT .or. $HIDE_PART_TITLE .or. $HIDE_PART_VALUE)
end on

A naked knob.

on init
    declare ui_label $label_1 (1, 1)
    set_text($label_1, "Small Label")
    hide_part($label_1, $HIDE_PART_BG)
end on

Hide the background of a label. This is also possible with other UI elements.

load_performance_view()

`load_performance_view(<filename>)`
Loads a performance view file (.nckp) that was created in the Creator Tools GUI Designer.
`<filename>`	The filename of the .nckp file without extension, entered as a string.

Remarks

Only one performance view file can be loaded per script slot.
This command is only available in the on init callback.
This command cannot be used alongside make_perfview.
The performance view file should be in the performance_view subfolder of the resource container.
All contained controls are accessible as if they were declared and set up in KSP; variable names can be identified in Creator Tools.
More information in the Creator Tools manual.

Examples

on init
    load_performance_view(“performanceView”)
end on

on ui_control ($testButton)
    if ($testButton = 0)
        set_control_par(get_ui_id($testSlider), $CONTROL_PAR_HIDE, $HIDE_PART_WHOLE_CONTROL)
    else
        set_control_par(get_ui_id($testSlider), $CONTROL_PAR_HIDE, $HIDE_PART_NOTHING)
    end if
end on

Loads a performance view file and then defines some basic behavior involving two of the contained controls.

make_perfview

`make_perfview`
Activates the performance view for the respective script slot.

Remarks

This command can only be used in the on init callback.
Cannot be used alongside the load_performance_view() command.

Examples

on init
    message("")

    make_perfview
    set_script_title("My Cool Instrument")
    set_ui_height(6)
end on

Many KSP scripts will start something like this.

move_control()

`move_control(<variable>, <x-position>, <y-position>)`
Position UI widgets in the standard KONTAKT grid.
`<variable>`	The variable name of the UI widget.
`<x-position>`	The horizontal position of the widget in grid units (0 ... 6).
`<y-position>`	The vertical position of the widget in grid units (0 ... 16).

Remarks

move_control() can be used in all callbacks.
Note that using move_control() outside of the on init callback is more CPU intensive, so handle with care.
move_control(<variable>, 0, 0) will hide the UI widget.
Pixel-based control parameters cannot be mixed with grid-based ones, so if you want to set $CONTROL_PAR_WIDTH for a ui_label that is positioned to grid coordinates (2, 1), this will not work - you would have to use $CONTROL_PAR_GRID_WIDTH instead.

Examples

on init
    set_ui_height(3)

    declare ui_label $label (1, 1)
    set_text($label, "Move the wheel!")
    move_control($label, 3, 6)
end on

on controller
    if ($CC_NUM = 1)
        move_control($label, 3,  6 - ((%CC[1] * 5) / 127))
    end if
end on

Move a UI element with the modwheel.

move_control_px()

`move_control_px(<variable>, <x-position>, <y-position>)`
Position UI widgets in pixels.
`<variable>`	The variable name of the UI widget.
`<x-position>`	The horizontal position of the widget in pixels (0 ... 1000).
`<y-position>`	The vertical position of the widget in pixels (0 ... 750).

Remarks

Pixel-based control parameters cannot be mixed with grid-based ones, so if you want to set $CONTROL_PAR_WIDTH for a ui_label that is positioned to grid coordinates (2, 1), this will not work - you would have to use $CONTROL_PAR_GRID_WIDTH instead.
move_control_px() can be used in all callbacks.
Note that using move_control_px() outside of the on init callback is more CPU intensive, so handle with care.
In order to match KONTAKT standard grid sizes to pixel position, the following formulae can be used:
- X position: ((grid_value - 1) * 92) + 66
- Y position: ((grid_value - 1) * 21) + 2
- Width ($CONTROL_PAR_WIDTH): (grid_value * 92) - 5
- Height ($CONTROL_PAR_HEIGHT): (grid_value * 21) - 3

Examples

on init
    declare ui_label $label (1, 1)
    set_text($label, "Move the wheel!")
    move_control_px($label, 66, 2)
end on

on controller
    if ($CC_NUM = 1)
        move_control_px($label, 66 + %CC[1], 2)
    end if
end on

Transform CC values into pixel position. This might be useful for reference.

set_control_help()

`set_control_help(<variable>, <text>)`
Assigns a text string to be displayed when hovering over a UI widget. The text will appear in KONTAKT's info pane.
`<variable>`	The variable name of the UI widget.
`<text>`	The info text to be displayed.

Remarks

The text string used can contain a maximum of 320 characters.

Examples

on init
    declare ui_knob $Knob (0, 100, 1)
    set_control_help($Knob, "I'm the only knob, folks!")
end on

set_control_help() in action.

set_control_par()

`set_control_par(<ui-id>, <control-parameter>, <value>)`
Change various parameters of the specified UI widget.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<control-parameter>`	Parameter of the UI control we wish to set, i.e. `$CONTROL_PAR_WIDTH`.
`<value>`	The value of the control parameter we wish to set.

Remarks

set_control_par_str() is an additional flavor of the command for use with strings (i.e. setting the text of a ui_label, or automation name of a ui_slider).

Examples

on init
    declare ui_value_edit $test (0, 100, $VALUE_EDIT_MODE_NOTE_NAMES)
    set_text($test,"")
    set_control_par(get_ui_id($test), $CONTROL_PAR_WIDTH, 45)
    move_control_px($test, 100, 10)
end on

Changing the width of a value edit to 45 pixels. Note that you also have to specify its position in pixels once you use pixel-based control parameters.

on init
    declare ui_label $test (1, 1)
    set_control_par_str(get_ui_id($test), $CONTROL_PAR_TEXT, "This is Text")
    set_control_par(get_ui_id($test), $CONTROL_PAR_TEXT_ALIGNMENT, 1)
end on

Set and center text in labels.

set_control_par_arr()

`set_control_par_arr(<ui-id>, <control-parameter>, <value>, <index>)`
Change various parameters of an element within an array-based UI widget, e.g. `ui_xy` cursors.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<control-parameter>`	Parameter of the UI widgetwe wish to set, e.g. `$CONTROL_PAR_AUTOMATION_ID`.
`<value>`	The value of the control parameter we wish to set.
`<index>`	The array index of the UI control we wish to set.

Remarks

set_control_par_arr() comes in two additional flavors:
- set_control_par_str_arr() (i.e. setting automation names of individual ui_xy cursors)
- set_control_par_real_arr() (i.e. values of individual ui_xy cursor X and Y axes)

Examples

on init
    make_perfview
    set_ui_height_px(350)

    declare ui_xy ?myXY[4]
    declare $xyID
    $xyID := get_ui_id(?myXY)

    set_control_par_arr($xyID, $CONTROL_PAR_AUTOMATION_ID, 0, 0)
    set_control_par_arr($xyID, $CONTROL_PAR_AUTOMATION_ID, 1, 1)
    set_control_par_arr($xyID, $CONTROL_PAR_AUTOMATION_ID, 2, 2)
    set_control_par_arr($xyID, $CONTROL_PAR_AUTOMATION_ID, 3, 3)

    set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, "Cutoff", 0)
    set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, "Resonance", 1)
    set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, "Delay Pan", 2)
    set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, "Delay Feedback", 3)
end on

Setting automation IDs and names of an XY pad with two cursors.

set_knob_defval()

`set_knob_defval(<variable>, <value>)`
Assign a default value to a `ui_knob` to which it will be reset when pressing `[Ctrl]` (on Windows) or `[Cmd]` (on macOS) and clicking the knob.

Remarks

In order to assign a default value to a ui_slider, use set_control_par() with $CONTROL_PAR_DEFAULT_VALUE control parameter.

Examples

on init
    declare ui_knob $Knob (-100, 100, 0)
    set_knob_defval($Knob, 0)
    $Knob := 0

    declare ui_slider $Slider (-100, 100)
    set_control_par(get_ui_id($Slider), $CONTROL_PAR_DEFAULT_VALUE, 0)
    $Slider := 0
end on

Assigning default values for a knob and a slider.

set_knob_label()

`set_knob_label(<variable>, <text>)`
Assign a text string to a `ui_knob`.

Examples

on init
    declare !rate_names[18]
    !rate_names[ 0] := "1/128"
    !rate_names[ 1] := "1/64"
    !rate_names[ 2] := "1/32"
    !rate_names[ 3] := "1/16 T"
    !rate_names[ 4] := "1/32 D"
    !rate_names[ 5] := "1/16"
    !rate_names[ 6] := "1/8 T"
    !rate_names[ 7] := "1/16 D"
    !rate_names[ 8] := "1/8"
    !rate_names[ 9] := "1/4 T"
    !rate_names[10] := "1/8 D"
    !rate_names[11] := "1/4"
    !rate_names[12] := "1/2 T"
    !rate_names[13] := "1/4 D"
    !rate_names[14] := "1/2"
    !rate_names[15] := "1/1 T"
    !rate_names[16] := "1/2 D"
    !rate_names[17] := "1/1"

    declare ui_knob $Rate (0, 17, 1)
    set_knob_label($Rate, !rate_names[$Rate])
end on

on persistence_changed
    set_knob_label($Rate, !rate_names[$Rate])
end on

on ui_control ($Rate)
    set_knob_label($Rate, !rate_names[$Rate])
end on

Useful for displaying rhythmical values.

set_knob_unit()

`set_knob_unit(<variable>, <knob-unit-constant>)`
Assign a unit mark to a `ui_knob`. The following constants are available: `$KNOB_UNIT_NONE` `$KNOB_UNIT_DB` `$KNOB_UNIT_HZ` `$KNOB_UNIT_PERCENT` `$KNOB_UNIT_MS` `$KNOB_UNIT_OCT` `$KNOB_UNIT_ST`

set_knob_unit(<variable>, <knob-unit-constant>)

Assign a unit mark to a ui_knob. The following constants are available:

$KNOB_UNIT_NONE

$KNOB_UNIT_DB

$KNOB_UNIT_HZ

$KNOB_UNIT_PERCENT

$KNOB_UNIT_MS

$KNOB_UNIT_OCT

$KNOB_UNIT_ST

Examples

on init
    declare ui_knob $Time (0, 1000, 10)
    set_knob_unit($Time, $KNOB_UNIT_MS)

    declare ui_knob $Octave (1, 6, 1)
    set_knob_unit($Octave, $KNOB_UNIT_OCT)

    declare ui_knob $Volume (-600, 600, 100)
    set_knob_unit($Volume, $KNOB_UNIT_DB)

    declare ui_knob $Scale (0, 100, 1)
    set_knob_unit($Scale, $KNOB_UNIT_PERCENT)

    declare ui_knob $Tune (4300, 4500, 10)
    set_knob_unit($Tune, $KNOB_UNIT_HZ)
end on

Various knob unit marks.

set_menu_item_str()

`set_menu_item_str(<ui-id>, <index>, <string>)`
Sets the value of a `ui_menu` entry.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<index>`	The index of the menu item.
`<string>`	The text you wish to set for the selected menu item.

Remarks

The <index> is defined by the order in which the menu items are added within the on init callback; it can’t be changed afterwards.

Examples

on init
    declare ui_menu $menu
    declare ui_button $button
    add_menu_item ($menu, "First Entry", 0)
    add_menu_item ($menu, "Second Entry", 5)
    add_menu_item ($menu, "Third Entry", 10)
end on

on ui_control ($button)
    set_menu_item_str(get_ui_id($menu), 1, "Renamed")
end on

Renaming the second menu entry.

set_menu_item_value()

`set_menu_item_value(<ui-id>, <index>, <value>)`
Sets the value of a `ui_menu` entry.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<index>`	The index of the menu item.
`<value>`	The value you want to give the menu item.

Remarks

The <index> is defined by the order in which the menu items are added within the on init callback; it can’t be changed afterwards.
The <value> is set by the third parameter of the add_menu_item() command.

Examples

on init
    declare ui_menu $menu
    add_menu_item ($menu, "First Entry", 0)
    add_menu_item ($menu, "Second Entry", 5)
    add_menu_item ($menu, "Third Entry", 10)

    set_menu_item_value(get_ui_id($menu), 1, 20)
end on

Changing the value of the second menu entry to 20.

set_menu_item_visibility()

`set_menu_item_visibility(<ui-id>, <index>, <visibility>)`
Sets the visibility of a `ui_menu` entry.
`<ui-id>`	The ID number of the UI widget. You can retrieve it with `get_ui_id()`.
`<index>`	The index of the menu item.
`<visibility>`	Set to either 0 (invisible) or 1 (visible).

Remarks

The <index> is defined by the order in which the menu items are added within the on init callback; it can’t be changed afterwards.
Add as many menu entries as you would possibly need within the on init callback, then show or hide them dynamically by using set_menu_item_visibility().
If you set the currently selected menu item to invisible, the item will remain visible until it is no longer selected.

Examples

on init
    declare ui_menu $menu
    declare ui_button $button
    add_menu_item ($menu, "First Entry", 0)
    add_menu_item ($menu, "Second Entry", 5)
    add_menu_item ($menu, "Third Entry", 10)
end on

on ui_control ($button)
    set_menu_item_visibility(get_ui_id($menu), 1, $button)
end on

Hiding the second menu entry with a button.

set_table_steps_shown()

`set_table_steps_shown(<variable>, <num-of-steps>)`
Changes the number of displayed columns in a `ui_table` widget.
`<variable>`	The variable name of the `ui_table` widget.
`<num-of-steps>`	The number of displayed steps.

Examples

on init
    declare ui_table %table[32] (5, 4, 127)
    declare ui_value_edit $Steps (2, 32, 1)

    $Steps := 16
    set_table_steps_shown(%table, $Steps)
end on

on ui_control($Steps)
    set_table_steps_shown(%table, $Steps)
end on

Changing the number of shown steps.

set_script_title()

`set_script_title(<text>)`
Set the script title.

Remarks

This command overrides any manually set script titles.

Examples

on init
    message("")

    make_perfview
    set_script_title("My Cool Instrument")
    set_ui_height(6)
end on

Many performance view scripts start like this.

set_skin_offset()

`set_skin_offset(<offset-in-px>)`
Offsets the chosen background picture file by the specified number of pixels.

Remarks

If a PNG file used for the background has been set and is larger than the maximum height of the performance view, you can use this command to offset the background graphic, thus creating separate backgrounds for each of the script slots while only using one picture file.

Examples

on init
    make_perfview
    set_ui_height(1)
end on

on controller
    if ($CC_NUM = 1)
        set_skin_offset(%CC[1])
    end if
end on

set_text()

`set_text(<variable>, <text>)`
When applied to a `ui_label`: replace the text currently visible in the specified label and add new text. When applied to `ui_knob`, `ui_button`, `ui_switch` and `ui_value_edit`: set the display name of the widget.

set_text(<variable>, <text>)

When applied to a ui_label: replace the text currently visible in the specified label and add new text.

When applied to ui_knob, ui_button, ui_switch and ui_value_edit: set the display name of the widget.

Examples

on init
    declare ui_label $label_1 (1, 1)
    set_text($label_1, "Small Label")

    declare ui_label $label_2 (3, 6)
    set_text($label_2, "Big Label")
    add_text_line($label_2, "...with a second text line")
end on

Two labels with different sizes.

on init
    declare ui_label $label_1 (1, 1)
    set_text ($label_1, "Small Label")
    hide_part ($label_1, $HIDE_PART_BG)
end on

Hide the background of a label. This is also possible with other widgets.

set_ui_color()

`set_ui_color(<hex-value>)`
Set the main background color of the performance view.
`<hex value>`	The hexadecimal color value in the following format: `0ff0000h {red}` The 0 at the start lets KONTAKT know the value is a number. The h at the end indicates that it is a hexadecimal value. You can also use uppercase H.

set_ui_color(<hex-value>)

Set the main background color of the performance view.

<hex value>

The hexadecimal color value in the following format:

0ff0000h {red}

The 0 at the start lets KONTAKT know the value is a number.

The h at the end indicates that it is a hexadecimal value. You can also use uppercase H.

Remarks

This command can be used in all callbacks.

Examples

on init
    make_perfview
    set_ui_color(0000000H)
end on

Paint it black.

set_ui_height()

`set_ui_height(<height>)`
Set the height of a script performance view in grid units.
`<height>`	The height of script in grid units (1 ... 8).

Remarks

This command can only be used in the on init callback.

Examples

on init
    message("")

    make_perfview
    set_script_title("My Cool Instrument")
    set_ui_height(6)
end on

Many performance view scripts start like this.

`set_ui_height_px(<height>)`
Set the height of a script performance view in pixels.
`<height>`	The height of script in pixels (50 ... 750).

Remarks

This command can only be used in the on init callback.

Examples

on init
    make_perfview

    declare const $SIZE := 1644    { picture height }
    declare const $NUM_FRAMES := 4
    declare const $HEADER_SIZE := 68

    declare ui_value_edit $Slide (1, $NUM_SLIDES, 1)

    set_ui_height_px(($SIZE / $NUM_FRAMES) - $HEADER_SIZE)
    set_skin_offset(($Slide - 1) * ($SIZE / $NUM_FRAMES))
end on

on ui_control ($Slide)
    set_skin_offset(($Slide - 1) * ($SIZE / $NUM_FRAMES))
end on

set_ui_width_px()

`set_ui_width_px(<width>)`
Set the width of a script performance view in pixels.
`<width>`	The width of the script in pixels (633 ... 1000).

Remarks

This command can only be used in the on init callback.

Examples

on init
    make_perfview
    set_ui_height_px(750) 
    set_ui_width_px(1000)
end on

Making a performance view with the largest possible size.

set_ui_wf_property()

`set_ui_wf_property(<variable>, <property>, <index>, <value>)`
Sets different properties for the `ui_waveform` widget.
`<variable>`	Variable name of the `ui_waveform` widget.
`<property>`	The following properties are available: `$UI_WF_PROP_PLAY_CURSOR` `$UI_WF_PROP_FLAGS` `$UI_WF_PROP_TABLE_VAL` `$UI_WF_PROP_TABLE_IDX_HIGHLIGHT` `$UI_WF_PROP_MIDI_DRAG_START_NOTE`
`<index>`	The index of the slice to which the selected property applies. Only valid for `$UI_WF_PROP_TABLE_IDX_HIGHLIGHT` and `$UI_WF_PROP_TABLE_VAL`
`<value>`	The value of the selected property.

Examples

on init
    declare $play_pos
    declare ui_waveform $Waveform (6, 6)

    attach_zone($Waveform, find_zone("Test"), 0)
end on

on note
    while ($NOTE_HELD = 1)
        $play_pos := get_event_par($EVENT_ID, $EVENT_PAR_PLAY_POS)
        set_ui_wf_property($Waveform, $UI_WF_PROP_PLAY_CURSOR, 0, $play_pos)
        wait(10000)
    end while
end on

Attaches a zone named “Test” to the waveform display and shows a play cursor within the waveform as long as you play a note.

User Interface Commands

add_menu_item()

Remarks

Examples

See Also

add_text_line()

Examples

See Also

attach_level_meter()

Remarks

Examples

See Also

attach_zone()

Remarks

Examples

See Also

fs_get_filename()

Remarks

See Also

fs_navigate()

Remarks

See Also

get_control_par()

Remarks

Examples

See Also

get_control_par_arr()

Remarks

Examples

See Also

get_font_id()

Remarks

Examples

See Also

get_menu_item_str()

Remarks

Examples

See Also

get_menu_item_value()

Remarks

Examples

See Also

get_menu_item_visibility()

Remarks

Examples

See Also

get_ui_id()

Remarks

Examples

See Also

get_ui_wf_property()

Examples

See Also

hide_part()

Examples

See Also

load_performance_view()

Remarks

Examples

make_perfview

Remarks

Examples

See Also

move_control()

Remarks

Examples

See Also

move_control_px()

Remarks

Examples

See Also

set_control_help()

Remarks

Examples

See Also

set_control_par()

Remarks

Examples

See Also

set_control_par_arr()