Skip to main content

User Interface Commands

add_menu_item()

add_menu_item(<variable>,<text>,<value>)

Create a menu entry

<variable>

The variable name of the menu UI control

<text>

The text of the menu entry

<value>

The value of the menu entry

Remarks

  • You can create menu entries only in the 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 and then show or hide them dynamically by using set_menu_item_visibility().

  • Using the $CONTROL_PAR_VALUE constant in the get_control_par() command will return the menu index and not the value. If you want to get the menu value, 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

See Also

get_menu_item_str()

get_menu_item_value()

get_menu_item_visibility()

set_menu_item_str()

set_menu_item_visibility()

ui_menu

Specific: $CONTROL_PAR_SELECTED_ITEM_IDX, $CONTROL_PAR_NUM_ITEMS

add_text_line()

add_text_line(<variable>,<text>) 

Add a new text line in the specified label without erasing existing text

<variable>

The variable name of the label UI control

<text>

The text to be displayed

Examples

on init
	declare ui_label $label (1,4)
	set_text($label,"")
	declare $count
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

See Also

set_text()

ui_label

attach_level_meter()

attach_level_meter(<ui-ID>,<group>,<slot>,<channel>,<generic>)

Attach a level meter to a certain position within the instrument to read volume data

<ui-ID>

The ID number of the level meter UI control. You can retrieve the ID number 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 you do not wish to access an FX slot.

<channel>

Select from 0 to 15 to set the channel.

<generic>

Can be one of the following:

  • NI_LEVEL_METER_MAIN: used to access main effects

  • NI_LEVEL_METER_GROUP: used to access the group effects

  • NI_LEVEL_METER_INSERT: used to access the insert effects

  • 0-15: used to access individual buses

Remarks

  • The 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 min and max display values and inverting the display by using $CONTROL_PAR_RANGE_MIN and $CONTROL_PAR_RANGE_MAX.

Examples

on init
    declare $slot_idx := 0
    declare $bus_idx := 0
    declare $group_idx := 0
    declare $channel := 0
    
    declare ui_label $InstOutput (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_label $empty (1,1)
    
    declare ui_level_meter $inst_output_lvl
    attach_level_meter(get_ui_id($inst_output_lvl),-1,-1,$channel,-1)
    
    declare ui_level_meter $bus_output_lvl
    attach_level_meter(get_ui_id($bus_output_lvl),-1,-1,$channel,$bus_idx)
    
    declare ui_level_meter $mainfx_output_lvl
    attach_level_meter(get_ui_id($mainfx_output_lvl),-1,$slot_idx,$channel,-2)
    
    declare ui_level_meter $busfx_output_lvl
    attach_level_meter(get_ui_id($busfx_output_lvl),-1,$slot_idx,$channel,$bus_idx)
    
    declare ui_level_meter $groupfx_output_lvl
    attach_level_meter(get_ui_id($groupfx_output_lvl),$group_idx,$slot_idx,$channel,-1)
    
end on

Various level meters

See Also

ui_level_meter

Specific: $CONTROL_PAR_BG_COLOR, $CONTROL_PAR_OFF_COLOR, $CONTROL_PAR_ON_COLOR, $CONTROL_PAR_OVERLOAD_COLOR, $CONTROL_PAR_PEAK_COLOR, $CONTROL_PAR_VERTICAL, $CONTROL_PAR_RANGE_MIN, $CONTROL_PAR_RANGE_MAX

attach_zone()

attach_zone(<variable>,<zone_id>,<flags>)

Connects the corresponding zone to the waveform so that it shows up within the display

<variable>

The variable name of the waveform display UI control.

<zone_id>

The ID number of the zone that you want to attach to the waveform display

<flags>

You can control different settings of the waveform display UI control via its flags. The following flags are available:

$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 waveform display, also showing the zone’s slices and a table.

See Also

set_ui_wf_property()

get_ui_wf_property()

ui_waveform

Zone and Slice Functions: find_zone()

Specific: Waveform Flag Constants, Waveform Property Constants

fs_get_filename()

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

Return the filename of the last selected file in the file selector UI control.

<ui-ID>

The ID number of the file selector UI control. You can retrieve the the ID number 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 UI callback of ui_file_selector

See Also

fs_navigate()

ui_file_selector

fs_navigate()

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

Jump to the next/previous file in the file selector UI control and trigger its callback.

<ui-ID>

The ID number of the file selector UI control. You can retrieve the ID number 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 a UI callback

  • It will always call the UI callback of the ui_file_selector it is pointed to

See Also

fs_get_filename()

ui_file_selector

get_control_par()

get_control_par(<ui-ID>,<control-parameter>)

Retrieve various parameters of the specified UI control

<ui-ID>

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

<control-parameter>

Parameter of the UI control we wish to retrieve, i.e. $CONTROL_PAR_WIDTH

Remarks

  • get_control_par() comes in three additional flavors:

  • get_control_par_arr() for working with array-based controls (i.e. retrieving values from a particular ui_table index)

  • get_control_par_str() for working with strings (i.e. retrieving text from ui_label or automation name from ui_slider)

  • get_control_par_str_arr() (i.e. retrieving automation name of particular ui_xy cursor)

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

See Also

set_control_par()

General: $CONTROL_PAR_KEY_SHIFT, $CONTROL_PAR_KEY_ALT, $CONTROL_PAR_KEY_CONTROL

get_font_id()

get_font_id(<file-name>)

Returns a font ID from an image file; the font ID can used on any control that has dynamic text elements

<file-name>

Name of the image file, 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 init callback.

  • The 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 needs to contain only one color.

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

See Also

set_control_par()

General: $CONTROL_PAR_FONT_TYPE

get_menu_item_str()

get_menu_item_str(<menu-id>,<index>)

Returns the string value of the menu’s entry

<menu-id>

The ID of the menu UI control. You can retrieve the ID number with get_ui_id().

<index>

The index (not value) of the menu item

Remarks

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

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)
	declare ui_button $button
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

See Also

add_menu_item()

get_menu_item_value()

get_menu_item_visibility()

get_menu_item_str()

set_menu_item_value()

set_menu_item_visibility()

Specific: $CONTROL_PAR_SELECTED_ITEM_IDX, $CONTROL_PAR_NUM_ITEMS

get_menu_item_value()

get_menu_item_value(<menu-id>,<index>)

Returns the value of the menu’s entry

<menu-id>

The ID of the menu UI control. You can retrieve the ID number with get_ui_id().

<index>

The index of the menu item

Remarks

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

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)
	declare ui_button $button
end on

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

Displays the number 5

See Also 

add_menu_item()

get_menu_item_str()

get_menu_item_visibility()

set_menu_item_str()

set_menu_item_value()

set_menu_item_visibility()

Specific: $CONTROL_PAR_SELECTED_ITEM_IDX, $CONTROL_PAR_NUM_ITEMS

get_menu_item_visibility()

get_menu_item_visibility(<menu-id>,<index>)

Returns 1 if the menu entry is visible, otherwise 0

<menu-id>

The ID of the menu UI control. You can retrieve the ID number with get_ui_id().

<index>

The index of the menu entry

Remarks

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

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)

    declare ui_button $visibility
    declare ui_button $value
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.

See Also

add_menu_item()

get_menu_item_str()

get_menu_item_value()

set_menu_item_str()

set_menu_item_value()

set_menu_item_visibility()

Specific: $CONTROL_PAR_SELECTED_ITEM_IDX, $CONTROL_PAR_NUM_ITEMS

get_ui_id()

get_ui_id(<variable>)

Retrieve the ID number of a UI control

Examples

on init
	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 $a
	declare %knob_id[4]
	%knob_id[0] := get_ui_id ($Knob_1)
	%knob_id[1] := get_ui_id ($Knob_2)
	%knob_id[2] := get_ui_id ($Knob_3)
	%knob_id[3] := get_ui_id ($Knob_4)
	
end on

on ui_control ($Set)
	$a := 0
	while ($a < 4)
		set_control_par(%knob_id[$a],$CONTROL_PAR_VALUE,$Set)
		inc($a)
	end while
end on

Store IDs in an array

See Also

set_control_par()

get_control_par()

get_ui_wf_property()

get_ui_wf_property(<variable>,<property>,<index>)

Returns the value of the waveform’s different properties

<variable>

The variable of the waveform UI control

<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,...
		0,$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

See Also

set_ui_wf_property()

ui_waveform

attach_zone()

Zone and Slice Functions: find_zone()

Specific: Waveform Flag Constants, Waveform Property Constants

hide_part()

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

Hide specific parts of user interface controls

<variable>

The variable name of the UI control

<hide-mask>

Bitmask of visibility states for various parts of UI controls, consisting of the following 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)

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.

See Also

Specific: $CONTROL_PAR_HIDE, $HIDE_PART_NOTHING, $HIDE_WHOLE_CONTROL

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, as a string (in quotation marks)

Remarks

  • Only one performance view file can be loaded per script slot

  • This command is only available in the 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 then 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 documentation

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

Remarks

  • make_perfview is only available in the init callback.

  • Cannot be used alongside the load_performance_view() command.

Examples

on init
	make_perfview
	set_script_title("Performance View")
	set_ui_height(6)
	message("")
end on

Many performance view scripts start like this

See Also

set_skin_offset()

set_ui_height()

set_ui_height_px()

set_ui_width_px()

set_ui_color()

move_control()

move_control(<variable>,<x-position>,<y-position>)

Position UI elements in the standard KONTAKT grid

<variable>

The variable name of the UI control

<x-position>

The horizontal position of the control (0 to 6) in grid units

<y-position>

The vertical position of the control (0 to 16) in grid units

Remarks

  • move_control() can be used in the init and other callbacks.

  • Note that the usage of move_control() in other callbacks than the init callback is more CPU intensive, so handle with care.

  • move_control(<variable>,0,0) will hide the UI element.

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,(%CC[1] * (-5) / (127)) + 6 )
	end if
end on

Move a UI element with the modwheel

See Also

move_control_px()

General: $CONTROL_PAR_HIDE

move_control_px()

move_control_px(<variable>,<x-position>,<y-position>)

Position UI elements in pixels

<variable>

The variable name of the UI control

<x-position>

The horizontal position of the control in pixels

<y-position>

The vertical position of the control in pixels

Remarks

  • Once you position a control in pixel, you have to make all other adjustments in pixels too, i.e. you cannot change between "pixel" and "grid" mode for a specific control.

  • move_control_px() can be used in the init and other callbacks.

  • Note that the usage of move_control_px() in other callbacks than the init callback is more CPU intensive, so handle with care.

  • In order to match grid size to pixel position, the following formulas can be used:

  • X position: ((grid_value - 1) * 92) + 66

  • Y position: ((grid_value - 1) * 21) + 2

  • Width (to be used with $CONTROL_PAR_WIDTH): (grid_value * 92) - 5

  • Height (to be used with $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,%CC[1]+66,2)
	end if
end on

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

See Also

move_control()

General: $CONTROL_PAR_POS_X, $CONTROL_PAR_POS_Y

set_control_help()

set_control_help(<variable>,<text>)

Assigns a text string to be displayed when hovering the UI control. The text will appear in KONTAKT's info pane.

<variable>

The variable name of the UI control

<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

See Also

set_script_title()

General:

$CONTROL_PAR_HELP

set_control_par()

set_control_par(<ui-ID>,<control-parameter>,<value>)

Change various parameters of the specified UI control

<ui-ID>

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

<control-parameter>

Parameter of the UI control we wish to retrieve, i.e. $CONTROL_PAR_WIDTH

<value>

The (integer) value

Remarks

  • set_control_par_str() is a variation of the command for usage with text strings.

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 enter "pixel-mode".

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

See Also

get_control_par()

get_ui_id()

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 control, e.g. cursors in the XY pad

<ui-ID>

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

<control-parameter>

Parameter of the UI control we wish to retrieve, e.g. $CONTROL_PAR_AUTOMATION_ID

<value>

The (integer) value

<index>

The element index

Remarks

  • set_control_par_str_arr() is a variation of the command for usage with text strings.

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

See Also

General: $CONTROL_PAR_AUTOMATION_ID, $CONTROL_PAR_AUTOMATION_NAME

Specific: $CONTROL_PAR_CURSOR_PICTURE, $HIDE_PART_CURSOR

set_knob_defval()

set_knob_defval(<variable>,<value>) 

Assign a default value to a knob to which the knob is reset when pressing [Ctrl] (Windows) or [Cmd] (macOS) + clicking the knob.

Remarks

  • In order to assign a default value to a slider, use set_control_par(<ui-ID>,$CONTROL_PAR_DEFAULT_VALUE,<value>)

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 to a knob and slider

See Also

General: $CONTROL_PAR_DEFAULT_VALUE

set_knob_label()

set_knob_label(<variable>,<text>) 

Assign a text string to a 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] := "3/64"
	!rate_names[5] := "1/16"
	!rate_names[6] := "1/8 T"
	!rate_names[7] := "3/32"
	!rate_names[8] := "1/8"
	!rate_names[9] := "1/4 T"
	!rate_names[10] := "3/16"
	!rate_names[11] := "1/4"
	!rate_names[12] := "1/2 T"
	!rate_names[13] := "3/8"
	!rate_names[14] := "1/2"
	!rate_names[15] := "3/4"
	!rate_names[16] := "4/4"
	!rate_names[17] := "Bar"
	
	declare ui_knob $Rate (0,17,1)
	set_knob_label($Rate,!rate_names[$Rate])
	
	read_persistent_var($Rate)
	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

See Also

General: $CONTROL_PAR_LABEL

set_knob_unit()

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

Assign a unit mark to a 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

See Also

General: $CONTROL_PAR_UNIT

set_menu_item_str()

set_menu_item_str(<menu-id>,<index>,<string>)

Sets the value of a menu entry

<menu-id>

The ID of the menu UI control. You can retrieve the ID number 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 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

See Also

add_menu_item()

get_menu_item_str()

get_menu_item_value()

get_menu_item_visibility()

set_menu_item_value()

set_menu_item_visibility()

Specific: $CONTROL_PAR_SELECTED_ITEM_IDX, $CONTROL_PAR_NUM_ITEMS

set_menu_item_value()

set_menu_item_value(<menu-id>,<index>,<value>)

Sets the value of a menu entry

<menu-id>

The ID of the menu UI control. You can retrieve the ID number 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 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

See Also

add_menu_item()

get_menu_item_str()

get_menu_item_value()

get_menu_item_visibility()

set_menu_item_str()

set_menu_item_visibility()

Specific: $CONTROL_PAR_SELECTED_ITEM_IDX, $CONTROL_PAR_NUM_ITEMS

set_menu_item_visibility()

set_menu_item_visibility(<menu-id>,<index>,<visibility>)

Sets the visibility of a menu entry

<menu-id>

The ID of the menu UI control. You can retrieve the ID number 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 init callback; it can’t be changed afterwards. The <value> is set by the third parameter of the add_menu_item() command.

  • Add as many menu entries as you would possibly need within the 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,0)
end on

Hiding the second menu entry

See Also

add_menu_item()

get_menu_item_str()

get_menu_item_value()

get_menu_item_visibility()

set_menu_item_str()

set_menu_item_value()

Specific: $CONTROL_PAR_SELECTED_ITEM_IDX, $CONTROL_PAR_NUM_ITEMS

set_table_steps_shown()

set_table_steps_shown(<variable>,<num-of-steps>)

Changes the number of displayed columns in a UI table

<variable>

The name of the UI table

<num-of-steps>

The number of displayed steps

Examples

on init
	declare ui_table %table[32] (2,2,127)
	
	declare ui_value_edit $Steps (8,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

See Also

ui_table

set_script_title()

set_script_title(<text>)

Set the script title

Remarks

  • This command overrides any manually set script titles.

Examples

on init
	make_perfview
	set_script_title("Performance View")
	set_ui_height(6)
	message("")
end on

Many performance view scripts start like this

See Also

make_perfview

set_skin_offset()

set_skin_offset(<offset-in-pixel>)

Offsets the chosen background picture file by the specified number of pixels

Remarks

If a background PNG graphic file has been selected in the instrument options and it 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

See Also

make_perfview

set_ui_height_px()

set_text()

set_text(<variable>,<text>) 

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

When applied to knobs, buttons, switches and value edits: set the display name of the UI element.

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 UI elements.

See Also

add_text_line()

set_control_par(): set_control_par_str()

General: $CONTROL_PAR_TEXT

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:

9ff0000h {red}

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

The h at the end indicates that it is a hexadecimal value.

Remarks

  • Can be used in all callbacks.

Examples

on init
	make_perfview
	set_ui_color(9000000h)
end on

Creates a black interface

See Also

set_ui_height()

set_ui_height_px()

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 to 8)

Remarks

  • Only possible in the init callback.

Examples

on init
	make_perfview
	set_script_title("Performance View")
	set_ui_height(6)
	message("")
end on

Many performance view scripts start like this

See Also

set_ui_height_px()

set_ui_height_px()

set_ui_height_px(<height>)

Set the height of a script performance view in pixels

<height>

The height of script in pixels (50 to 750)

Remarks

  • Only possible in the init callback.

Examples

on init
	make_perfview
	declare const $SIZE := 1644 {size of tga file}
	declare const $NUM_SLIDES := 4 {amount of slides in tga file}
	
	declare ui_value_edit $Slide (1,$NUM_SLIDES,1)
	
	declare const $HEADER_SIZE := 93
	
	set_ui_height_px(($SIZE/$NUM_SLIDES)-$HEADER_SIZE)
	set_skin_offset (($Slide-1)*($SIZE/$NUM_SLIDES))
	
end on

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

See Also

set_ui_height()

set_ui_height_px()

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 to 1000)

Remarks

  • Only possible in the 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 dimensions

See Also

set_ui_height_px()

set_ui_wf_property()

set_ui_wf_property(<variable>,<property>,<index>,<value>)

Sets different properties for the waveform control

<variable>

The variable of the waveform UI control

<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

<value>

The (integer) value

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

See Also

get_ui_wf_property()

ui_waveform

attach_zone()

Zone and Slice Functions: find_zone()

Specific: Waveform Flag Constants, Waveform Property Constants