User Interface Commands
add_text_line()
| |
---|---|
Add a new text line in the specified label, without erasing existing text | |
| The variable name of the ui_label widget |
| 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
See Also
attach_level_meter()
| |
---|---|
Attach a level meter to a certain position within the instrument to read volume data | |
| The ID number of the ui_level_meter widget. You can retrieve it with |
| The index of the group you want to access. Should be set to -1 if not using the group level. |
| The index of the FX slot you wish to access. Should be set to -1 if not accessing an FX slot. |
| Select from 0 to 15 to set the audio channel the level meter will be displaying. |
| Can be one of the following:
|
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 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
See Also
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()
| |
---|---|
Connects the corresponding zone to the waveform so that it shows up on the ui_waveform widget | |
| The variable name of the ui_waveform widget |
| The ID number of the zone that you want to attach to the ui_waveform display |
| You can control different settings of the ui_waveform widget via the following flags:
|
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.
See Also
Zone and Slice Functions: find_zone()
Specific: Waveform Flag Constants, Waveform Property Constants
fs_get_filename()
| |
---|---|
Return the filename of the last selected file in a ui_file_selector widget. | |
| The ID number of the ui_file_selector widget. You can retrieve this ID number with |
| 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
get_control_par()
| |
---|---|
Retrieve various parameters of the specified UI control | |
| The ID number of the UI widget. You can retrieve this ID number with |
| Parameter of the UI widget we wish to retrieve, i.e. |
Remarks
get_control_par_str()
is an additional flavor of the command for use with strings (i.e. retrieving text fromui_label
or automation name fromui_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
See Also
General: $CONTROL_PAR_KEY_SHIFT
, $CONTROL_PAR_KEY_ALT
, $CONTROL_PAR_KEY_CONTROL
get_control_par_arr()
| |
---|---|
Retrieve various parameters of the specified UI control | |
| The ID number of the UI widget. You can retrieve this ID number with |
| Parameter of the UI widget we wish to retrieve, i.e. |
| Array index of the UI widget we wish to retrieve |
Remarks
get_control_par_arr()
comes in three additional flavors:get_control_par_arr()
(i.e. retrieving values from a particularui_table
index)get_control_par_str_arr()
(i.e. retrieving automation name of a particularui_xy
cursor)get_control_par_real_arr()
(i.e. retrieving values ofui_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 first cursor for 4 different XY pads in one loop
See Also
General: $CONTROL_PAR_KEY_SHIFT
, $CONTROL_PAR_KEY_ALT
, $CONTROL_PAR_KEY_CONTROL
get_font_id()
| |
---|---|
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 | |
| 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 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
See Also
General: $CONTROL_PAR_FONT_TYPE
get_ui_id()
|
---|
Retrieve the ID number of a UI control |
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/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
See Also
get_ui_wf_property()
| |
---|---|
Returns the values of different properties pertaining to the waveform widget | |
| Variable name of the waveform widget |
| The following properties are available:
|
| 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
See Also
Zone and Slice Functions: find_zone()
Specific: Waveform Flag Constants, Waveform Property Constants
hide_part()
| |
---|---|
Hide specific parts of various widgets | |
| The variable name of the widget |
| Bitmask of visibility states for various parts of UI controls, consisting of the following constants:
|
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()
| |
---|---|
Loads a performance view file (.NCKP) that was created in the Creator Tools GUI Designer | |
| The filename of the N.CKP 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 init callback
This command cannot be used alongside
make_perfview()
The performance view file should be in the
performance_view
subfolder of the resource containerAll 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
|
---|
Activates the performance view for the respective script slot |
Remarks
make_perfview
is only available in the init callbackCannot be used alongside the
load_performance_view()
command
Examples
on init message("") make_perfview set_script_title("Performance View") set_ui_height(6) end on
Many KSP scripts will start something like this
See Also
move_control()
| |
---|---|
Position UI widgets in the standard KONTAKT grid | |
| The variable name of the UI widget |
| The horizontal position of the widget (0 to 6) in grid units |
| The vertical position of the widget (0 to 16) in grid units |
Remarks
move_control()
can be used in all callbacksNote that using
move_control()
outside of the init callback is more CPU intensive, so handle with caremove_control(<variable>, 0, 0)
will hide the UI widgetPixel-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
See Also
General: $CONTROL_PAR_HIDE
move_control_px()
| |
---|---|
Position UI widgets in pixels | |
| The variable name of the UI widget |
| The horizontal position of the widget in pixels |
| The vertical position of the widget in pixels |
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 callbacksNote that using
move_control_px()
outside of the init callback is more CPU intensive, so handle with careIn 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.
See Also
General: $CONTROL_PAR_POS_X
, $CONTROL_PAR_POS_Y
set_control_help()
| |
---|---|
Assigns a text string to be displayed when hovering over a UI widget. The text will appear in KONTAKT's info pane. | |
| The variable name of the UI widget |
| 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
$CONTROL_PAR_HELP
set_control_par()
| |
---|---|
Change various parameters of the specified UI control | |
| The ID number of the UI control. You can retrieve the ID number with |
| Parameter of the UI control we wish to set, i.e. |
| 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 aui_label
, or automation name of aui_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 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
set_control_par_arr()
| |
---|---|
Change various parameters of an element within an array-based UI control, e.g. cursors in the XY pad | |
| The ID number of the UI control. You can retrieve the ID number with |
| Parameter of the UI control we wish to set, e.g. |
| The value of the control parameter we wish to set |
| 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 individualui_xy
cursors).set_control_par_real_arr()
(i.e. values of individualui_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
See Also
General: $CONTROL_PAR_AUTOMATION_ID
, $CONTROL_PAR_AUTOMATION_NAME
Specific: $CONTROL_PAR_CURSOR_PICTURE
, $HIDE_PART_CURSOR
set_knob_defval()
|
---|
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()
|
---|
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()
|
---|
Assign a unit mark to a knob. The following constants are available:
|
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_table_steps_shown()
| |
---|---|
Changes the number of displayed columns in a UI table | |
| The name of the UI table |
| 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
set_script_title()
|
---|
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
set_skin_offset()
|
---|
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
set_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
set_control_par(): set_control_par_str()
General: $CONTROL_PAR_TEXT
set_ui_color()
| |
---|---|
Set the main background color of the performance view | |
| The hexadecimal color value in the following format:
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 the height of a script performance view in grid units | |
| 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 the height of a script performance view in pixels | |
| 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_width_px()
| |
---|---|
Set the width of a script performance view in pixels | |
| 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_wf_property()
| |
---|---|
Sets different properties for the waveform control | |
| The variable of the waveform UI control |
| The following properties are available:
|
| The index of the slice |
| 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
Zone and Slice Functions: find_zone()
Specific: Waveform Flag Constants, Waveform Property Constants