User Interface Controls

ui_button

`declare ui_button $<variable-name>`
Creates a button in the performance view.

Remarks

UI callback for button is triggered when releasing the mouse (on mouse up).
A button cannot be MIDI learned or host automated.

Examples

on init
    declare ui_button $free_sync_button
    $free_sync_button := 1

    set_text($free_sync_button, "Sync")

    make_persistent($free_sync_button)
    read_persistent_var($free_sync_button)

    if ($free_sync_button = 0)
        set_text($free_sync_button, "Free")
    else
        set_text($free_sync_button, "Sync")
    end if
end on

on ui_control ($free_sync_button)
    if ($free_sync_button = 0)
        set_text($free_sync_button, "Free")
    else
        set_text($free_sync_button, "Sync")
    end if
end on

A simple freerun/tempo sync button implementation.

ui_file_selector

`declare ui_file_selector $<variable-name>`
Creates a file selector in the performance view.

Examples

on init
    message("")
    set_ui_height(5)

    declare $load_mf_id := -1
    declare @file_name
    declare @file_path
    declare @basepath
    { set browser path here, for example:
    @basepath := "/Users/username/Desktop/MIDI Files/" }

    declare ui_file_selector $file_browser

    declare $browser_id
    $browser_id := get_ui_id($file_browser)

    set_control_par_str($browser_id, $CONTROL_PAR_BASEPATH, @basepath)
    set_control_par($browser_id, $CONTROL_PAR_FILE_TYPE, $NI_FILE_TYPE_MIDI)
    set_control_par($browser_id, $CONTROL_PAR_COLUMN_WIDTH, 180)
    set_control_par($browser_id, $CONTROL_PAR_HEIGHT, 170)
    set_control_par($browser_id, $CONTROL_PAR_WIDTH, 550)

    move_control_px($file_browser, 66, 2)

    declare ui_button $prev
    declare ui_button $next

    move_control($prev, 5, 1)
    move_control($next, 6, 1)
end on

on async_complete
    if ($NI_ASYNC_ID = $load_mf_id)
        $load_mf_id := -1

        if ($NI_ASYNC_EXIT_STATUS = 0)
            message("MIDI file not found!")
        else
            message("Loaded MIDI File: " & @file_name)
        end if
    end if
end on

on ui_control ($file_browser)
    @file_name := fs_get_filename($browser_id, 0)
    @file_path := fs_get_filename($browser_id, 2)
    $load_mf_id := load_midi_file(@file_path)
end on

on ui_control ($prev)
    { calls 'on ui_control ($file_browser)' }
    fs_navigate($browser_id, 0)
    $prev := 0
end on

on ui_control ($next)
    { calls 'on ui_control ($file_browser)' }
    fs_navigate($browser_id, 1)
    $next := 0
end on

Loading MIDI files via the file selector.

ui_label

`declare ui_label $<variable-name> (<grid-width>, <grid-height>)`
Creates a text or image label in the performance view
`<grid-width>`	The width of the label in grid units (0 to 6)
`<grid-height>`	The height of the label in grid units (0 to 16)

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 (also possible with other UI widgets)

ui_knob

`declare ui_knob $<variable-name> (<min>, <max>, <display-ratio>)`
Creates a knob in the performance view.
`<min>`	The minimum value of the knob.
`<max>`	The maximum value of the knob.
`<display-ratio>`	The knob value is divided by `<display-ratio>` for display purposes.

Examples

on init
    declare ui_knob $Knob_1 (0, 1000, 1)
    declare ui_knob $Knob_2 (0, 1000, 10)
    declare ui_knob $Knob_3 (0, 1000, 100)
    declare ui_knob $Knob_4 (0, 1000, 20)
    declare ui_knob $Knob_5 (0, 1000, -10)
end on

Various display ratios.

on init
    declare $count
    declare !note_class[12]
    !note_class[0] := "C"
    !note_class[1] := "C#"
    !note_class[2] := "D"
    !note_class[3] := "D#"
    !note_class[4] := "E"
    !note_class[5] := "F"
    !note_class[6] := "F#"
    !note_class[7] := "G"
    !note_class[8] := "G#"
    !note_class[9] := "A"
    !note_class[10] := "Bb"
    !note_class[11] := "B"
    declare !note_names [128]

    while ($count < 128)
        !note_names[$count] := !note_class[$count mod 12] & (($count / 12) - 2)

        inc($count)
    end while

    declare ui_knob $Note (0, 127, 1)

    make_persistent($Note)
    read_persistent_var($Note)

    set_knob_label($Note, !note_names[$Note])
end on

on ui_control ($Note)
    set_knob_label($Note, !note_names[$Note])
end on

Knob displaying MIDI note names.

ui_level_meter

`declare ui_level_meter $<variable-name>`
Creates a level meter in the performance view.

Remarks

The level meter can display the output levels of buses, main instrument output, and gain reduction from compressor and limiter effects.

Examples

on init
    declare ui_level_meter $Level1
    declare ui_level_meter $Level2

    attach_level_meter(get_ui_id($Level1), -1, -1, 0, -1)
    attach_level_meter(get_ui_id($Level2), -1, -1, 1, -1)
end on

Creating two volume meters, each displaying one channel of KONTAKT’s instrument output.

ui_menu

`declare ui_menu $<variable-name>`
Creates a drop-down menu in the performance view.

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.

on init
    declare $count
    declare ui_menu $menu

    $count := 0
    while ($count < 20)
        add_menu_item($menu, "Entry #" & $count + 1, $count)

        inc($count)
    end while
end on

Quickly create a menu with many entries.

ui_mouse_area

`declare ui_mouse_area $<variable-name>`
Creates a mouse area in the performance view.

Remarks

A mouse area supports drag and drop of the following file types: audio (WAV, AIF, AIFF, NCW), MIDI and KSP array (NKA).
It is possible to define which types of files are accepted as drop targets and whether to accept just one or multiple files.
The mouse area widget is invisible, but the drop target can be shown or hidden, like any other UI widget.

Examples

on init
    declare ui_mouse_area $waveDnD

    set_control_par(get_ui_id($waveDnD), $CONTROL_PAR_DND_ACCEPT_AUDIO, $NI_DND_ACCEPT_ONE)
    set_control_par(get_ui_id($waveDnD), $CONTROL_PAR_DND_ACCEPT_ARRAY, $NI_DND_ACCEPT_ONE)
    set_control_par(get_ui_id($waveDnD), $CONTROL_PAR_WIDTH, 90)
    set_control_par(get_ui_id($waveDnD), $CONTROL_PAR_HEIGHT, 32)
    set_control_par(get_ui_id($waveDnD), $CONTROL_PAR_RECEIVE_DRAG_EVENTS, 1)

    move_control_px($waveDnD, 66, 2)
end on

A mouse area widget which can accept a single audio or NKA file.

The on ui_control callback is triggered by a drop action. It has 3 built-in arrays:

!NI_DND_ITEMS_AUDIO
!NI_DND_ITEMS_MIDI
!NI_DND_ITEMS_ARRAY

Example UI callback

on ui_control ($waveDnD)
    if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DRAG)
        message("DRAG")
        message("MOUSE OVER CONTROL: " & $NI_MOUSE_OVER_CONTROL)
    end if

    if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP)
        if (num_elements(!NI_DND_ITEMS_AUDIO) = 1)
            wait_async(set_sample(%NI_USER_ZONE_IDS[0], !NI_DND_ITEMS_AUDIO[0]))
        end if
    end if
end on

ui_panel

`declare ui_panel $<variable-name>`
Creates a panel for grouping widgets in the performance view.

Remarks

A panel is a control which can contain one or multiple widgets. Unlike the rest of the UI widgets, panels don’t have size. They are very useful for grouping controls that are meant to be handled together, then one can simultaneously modify the $CONTROL_PAR_HIDE, $CONTROL_PAR_POS_X, $CONTROL_PAR_POS_Y or $CONTROL_PAR_Z_LAYER properties of all the controls contained in that panel. The position of a contained control is relative to the panel’s position. This means that the control’s (0, 0) position is the current (x, y) position of the panel.

Panels can be nested, so they can contain other panels. If $panelA is contained in $panelB, then $panelA will appear in front of $panelB. This is because children panels have a higher Z-layer value than their parent panels. One could use this logic to easily create hierarchies in a performance view.

Examples

on init
    declare ui_panel $mixer
    declare ui_knob $volume (0, 300, 1)
    set_control_par(get_ui_id($volume), $CONTROL_PAR_PARENT_PANEL, get_ui_id($mixer))
end on

Adds the volume knob in the mixer panel.

ui_slider

`declare ui_slider $<variable-name> (<min>, <max>)`
Creates a slider in the performance view.
`<min>`	The minimum value of the slider.
`<max>`	The maximum value of the slider.

Examples

on init
    declare ui_slider $test (0, 100)
    set_control_par(get_ui_id($test), $CONTROL_PAR_DEFAULT_VALUE, 50)
end on

Slider with default value.

on init
    declare ui_slider $test (-100, 100)
    declare $id

    $id := get_ui_id($test)

    $test := 0

    set_control_par($id, $CONTROL_PAR_MOUSE_BEHAVIOUR, 2000)
    set_control_par($id, $CONTROL_PAR_DEFAULT_VALUE, 0)
    set_control_par_str($id, $CONTROL_PAR_PICTURE, "slider")
end on

Creating a bipolar slider by loading a different picture background. See the chapter on the Resource Container in order to learn more about how to use graphical assets with KSP.

ui_switch

`declare ui_switch $<variable-name>`
Creates a switch in the performance view.

Remarks

UI callback for switch is triggered when pressing the mouse (on mouse down).
A switch can be MIDI learned and host automated, as opposed to a button.

Examples

on init
    declare ui_switch $rec_button

    declare $rec_button_id
    $rec_button_id := get_ui_id($rec_button)

    set_control_par($rec_button_id, $CONTROL_PAR_POS_X, 250)
    set_control_par($rec_button_id, $CONTROL_PAR_POS_Y, 5)
    set_control_par($rec_button_id, $CONTROL_PAR_WIDTH, 60)
    set_control_par($rec_button_id, $CONTROL_PAR_HEIGHT, 20)
    set_control_par($rec_button_id, $CONTROL_PAR_TEXT_ALIGNMENT, 1)
    set_control_par_str($rec_button, $CONTROL_PAR_TEXT, "Record")
end on

Switch with various settings utilizing set_control_par() and set_control_par_str().

ui_table

`declare ui_table %<array-name>[columns] (<width>, <height>, <range>)`
Creates a table in the performance view.
`<width>`	The width of the table in grid units (1 ... 6).
`<height>`	The height of the table in grid units (1 ... 16).
`<range>`	The range of the table. If negative values are used, a bipolar table is created.

Remarks

The maximum number of columns in a ui_table is 128.

Examples

on init
    declare ui_table %table_uni[10] (2, 2, 100)
    declare ui_table %table_bi[10] (2, 2, -100)
end on

Unipolar and bipolar tables.

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

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

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

Changes the amount of shown steps (columns) in a table.

on init
    declare ui_table %table[20] (4, 4, 100)
    declare ui_button $button
    declare ui_label $value (1, 1)
end on

on ui_control($button)
    if ($button = 1)
        hide_part(%table, $HIDE_PART_VALUE)
    else
        hide_part(%table, $HIDE_PART_NOTHING)
    end if

    set_text($value, "Step " & $NI_CONTROL_PAR_IDX + 1 & ": " & %table[$NI_CONTROL_PAR_IDX])
end on

Hiding the value indicator in top left corner of the table and replacing it with a value readout in a ui_label.

ui_text_edit

`declare ui_text_edit @<variable-name>`
Creates a text edit field in the performance view.

Examples

on init
    declare ui_text_edit @label_name
    declare ui_label $pattern_lbl (1, 1)

    set_control_par_str(get_ui_id(@label_name), $CONTROL_PAR_TEXT, "empty")
    set_control_par(get_ui_id(@label_name), $CONTROL_PAR_FONT_TYPE, 25)
    set_control_par(get_ui_id(@label_name), $CONTROL_PAR_POS_X, 73)
    set_control_par(get_ui_id(@label_name), $CONTROL_PAR_POS_Y, 2)

    set_text($pattern_lbl, "")

    move_control_px($pattern_lbl, 66, 2)

    make_persistent(@label_name)
end on

on ui_control (@label_name)
    message(@label_name & " it is!")
end on

A text edit field on top of a label.

ui_value_edit

`declare ui_value_edit $<variable-name> (<min>, <max>, <$display-ratio>)`
Creates a value edit field (number box) in the performance view.
`<min>`	The minimum value of the value edit.
`<max>`	The maximum value of the value edit.
`<display-ratio>`	The value is divided by `<display-ratio>` for display purposes. You can also use `$VALUE_EDIT_MODE_NOTE_NAMES` here to display note names instead of numbers.

Examples

on init
    declare ui_value_edit $test (0, 127, $VALUE_EDIT_MODE_NOTE_NAMES)
    set_text($test, "")
    set_control_par(get_ui_id($test), $CONTROL_PAR_WIDTH, 45)
    move_control_px($test, 66, 2)
end on

on note
    $test := $EVENT_NOTE
end on

Value edit displaying note names.

on init
    declare ui_value_edit $test (0, 10000, 1000)
    set_text($test, "Value")
end on

Value edit with three decimal spaces.

ui_waveform

`declare ui_waveform $<variable-name> (<width>, <height>)`
Creates a waveform display for displaying samples and optionally their slices. This widget can also be used to control specific parameters per slice and for MIDI drag and drop functionality.
`<width>`	The width of the waveform in grid units (1 ... 6).
`<height>`	The height of the waveform in grid units (1 ... 16).

Examples

on init
    declare ui_waveform $Waveform (6, 6)
    attach_zone($Waveform, find_zone(”Test”), 0)
end on

Displays the zone which has the name “Test” in the waveform widget. Use a sample named Test.wav (or .aiff, etc.) to test the above code.

ui_wavetable

`declare ui_wavetable $<variable-name>`
Creates a wavetable display in the performance view, visualizing the state of a zone which is used as a wavetable.

Examples

on init
    declare ui_wavetable $wavetable
    set_control_par(get_ui_id($wavetable), $CONTROL_PAR_WT_ZONE, find_zone("Wavetable01"))
end on

Displays the zone “Wavetable01” in the wavetable widget. Use a wavetable named Wavetable01.wav (or .aiff, etc.) to test the above code.

ui_xy

`declare ui_xy ?<array>[num-elements]`
Creates an XY pad in the performance view.

Remarks

The range of each axis on the XY pad is always between 0.0 and 1.0.
The number of cursors in the XY pad, i.e. the interactive elements, is defined by the size of the array. Each index in the array represents one axis of one cursor, so two indices are needed for each cursor. Applying this, if you wanted to create an XY pad with 3 cursors, the size of the XY array would have to be 6 elements.
The maximum size of the XY array is 32 elements, so the maximum number of cursors in a single XY pad is 16.
The even indices of the array hold the X axis value of the cursors, and the odd indices hold the Y axis values. So index 0 is the X value of the first cursor, and index 1 is the Y value of the first cursor.
It is possible to define how the XY pad reacts to mouse interaction using the $CONTROL_PAR_MOUSE_MODE parameter.
Querying $NI_MOUSE_EVENT_TYPE within the on ui_control () callback allows identification of the mouse event type that triggered it.

Examples

on init
    message("")

    make_perfview
    set_ui_height(7)

    declare ui_xy ?myXY[4]

    declare $xyID
    $xyID := get_ui_id(?myXY)

    { define the mouse behaviour }
    set_control_par($xyID, $CONTROL_PAR_MOUSE_MODE, 0)
    set_control_par($xyID, $CONTROL_PAR_MOUSE_BEHAVIOUR_X, 1000)
    set_control_par($xyID, $CONTROL_PAR_MOUSE_BEHAVIOUR_Y, 1000)

    { set automation IDs and parameter names }
    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)

    { position and size }
    move_control_px(?myXY, 216, 50)
    set_control_par($xyID, $CONTROL_PAR_WIDTH, 200)
    set_control_par($xyID, $CONTROL_PAR_HEIGHT, 200)

    { move the cursors around the XY pad }
    ?myXY[0] := 0.25 { cursor 1, X axis }
    ?myXY[1] := 0.75 { cursor 1, Y axis }
    ?myXY[2] := 0.75 { cursor 2, X axis }
    ?myXY[3] := 0.25 { cursor 2, Y axis }
end on

Creating an XY pad control with two cursors and automation information.

User Interface Controls

ui_button

Remarks

Examples

See Also

ui_file_selector

Examples

See Also

ui_label

Examples

See Also

ui_knob

Examples

ui_level_meter

Remarks

Examples

See Also

ui_menu

Examples

See Also

ui_mouse_area

Remarks

Examples

Example UI callback

See Also

ui_panel

Remarks

Examples

See Also

ui_slider

Examples

See Also

ui_switch

Remarks

Examples

See Also

ui_table

Remarks

Examples

See Also

ui_text_edit

Examples

See Also

ui_value_edit

Examples

See Also

ui_waveform

Examples

See Also

ui_wavetable

Examples

See Also

ui_xy

Remarks

Examples

See Also

Search results