KSPリファレンスマニュアル 7 - ユーザーインターフェースウィジェット（User Interface Widgets）

KSPリファレンスマニュアル 7 - ユーザーインターフェースウィジェット（User Interface Widgets）


ui_button

declare ui_button $<variable-name>

パフォーマンスビューにボタンを作成します。

補足

  • ボタンのUIコールバックは、マウスボタンを離したとき（マウスアップ時）にトリガーされます。

  • ボタンはMIDIラーンやホストオートメーションの対象にできません。

例

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

フリーランとテンポシンクを切り替えるボタンのシンプルな実装例です。

関連項目

ui_switch


ui_file_selector

declare ui_file_selector $<variable-name>

パフォーマンスビューにファイルセレクターを作成します。

例

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

ファイルセレクターを使ってMIDIファイルを読み込みます。

関連項目

fs_navigate()


ui_label

declare ui_label $<variable-name> (<grid-width>, <grid-height>)

パフォーマンスビューにテキストまたは画像のラベルを作成します

<grid-width>

ラベルの幅をグリッド単位で指定します（1〜6）

<grid-height>

ラベルの高さをグリッド単位で指定します（1〜16）

例

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

サイズの異なる2つのラベルです

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

ラベルの背景を非表示にします（他のUIウィジェットでも同様に可能です）

関連項目

set_text()

add_text_line()

hide_part()


ui_level_meter

declare ui_level_meter $<variable-name>

パフォーマンスビューにレベルメーターを作成します。

補足

  • レベルメーターは、インストゥルメントバスの出力レベル、インストゥルメントのメイン出力、およびコンプレッサーやリミッターのエフェクトによるゲインリダクションを表示できます。

例

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

音量メーターを2つ作成し、それぞれにKontaktのインストゥルメント出力の1チャンネルを表示します。

関連項目

attach_level_meter()

特定のUIウィジェット: $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


ui_knob

declare ui_knob $<variable-name> (<min>, <max>, <display-ratio>)

パフォーマンスビューにノブを作成します。

<min>

ノブの最小値を指定します。

<max>

ノブの最大値を指定します。

<display-ratio>

表示の際、ノブの値は<display-ratio>で除算されます。

例

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

さまざまなディスプレイレシオの例です。

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

MIDIノートネームを表示するノブです。


ui_menu

declare ui_menu $<variable-name>

パフォーマンスビューにドロップダウンメニューを作成します。

例

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

シンプルなメニューです。

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

多数の項目を持つメニューを手早く作成します。

関連項目

add_menu_item()

get_menu_item_str()

get_menu_item_value()

get_menu_item_visibility()

set_menu_item_str()

set_menu_item_value()

set_menu_item_visibility()


ui_mouse_area

declare ui_mouse_area $<variable-name>

パフォーマンスビューにマウスエリアを作成します。

補足

  • マウスエリアは、次のファイルタイプのドラッグ＆ドロップに対応します。オーディオ（WAV, AIF, AIFF, NCW）、MIDI、そしてKSPの配列（NKA）です。

  • ドロップ先として受け入れるファイルの種類と、1つだけを受け入れるか複数を受け入れるかを定義できます。

  • マウスエリアウィジェット自体は表示されませんが、ドロップ先は他のUIウィジェットと同様に表示と非表示を切り替えられます。

例

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

オーディオファイルまたはNKAファイルを1つだけ受け入れられるマウスエリアウィジェットです。

on ui_controlコールバックは、ドロップ操作によってトリガーされます。3つのビルトイン配列を持ちます。

!NI_DND_ITEMS_AUDIO
!NI_DND_ITEMS_MIDI
!NI_DND_ITEMS_ARRAY

UIコールバックの例

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ウィジェット: $NI_MOUSE_EVENT_TYPE, $NI_MOUSE_EVENT_TYPE_DND_DROP, $NI_MOUSE_EVENT_TYPE_DND_DRAG, $NI_MOUSE_OVER_CONTROL


ui_panel

declare ui_panel $<variable-name>

パフォーマンスビューでウィジェットをグループ化するためのパネルを作成します。

補足

  • パネルは、1つまたは複数のウィジェットを格納できるコントロールです。他のUIウィジェットとは違い、パネルにはサイズがありません。まとめて扱いたいコントロールをグループ化するのに非常に便利で、そのパネルに含まれるすべてのコントロールの$CONTROL_PAR_HIDE、$CONTROL_PAR_POS_X、$CONTROL_PAR_POS_Y、$CONTROL_PAR_Z_LAYERの各プロパティを一度にまとめて変更できます。格納されたコントロールの位置は、パネルの位置からの相対値になります。つまり、コントロールの（0, 0）の位置が、パネルの現在の（x, y）の位置になります。

  • パネルは入れ子にできるので、パネルの中に別のパネルを格納できます。$panelAが$panelBに格納されている場合、$panelAは$panelBの手前に表示されます。これは、子のパネルが親のパネルよりも高いZレイヤー値を持つためです。この仕組みを使えば、パフォーマンスビューの中に階層を簡単に作れます。

例

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

mixerパネルにvolumeノブを追加します。

関連項目

一般: $CONTROL_PAR_PARENT_PANEL


ui_slider

declare ui_slider $<variable-name> (<min>, <max>)

パフォーマンスビューにスライダーを作成します。

<min>

スライダーの最小値を指定します。

<max>

スライダーの最大値を指定します。

例

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

デフォルト値を設定したスライダーです。

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

別の画像を背景として読み込み、バイポーラーのスライダーを作成します。KSPでグラフィックのアセットを扱う方法について詳しくは、リソースコンテナの章を参照してください。

関連項目

ui_knob

set_control_par_arr()

特定のUIウィジェット: $CONTROL_PAR_MOUSE_BEHAVIOUR


ui_switch

declare ui_switch $<variable-name>

パフォーマンスビューにスイッチを作成します。

補足

  • スイッチのUIコールバックは、マウスボタンを押したとき（マウスダウン時）にトリガーされます。

  • ボタンとは違い、スイッチはMIDIラーンやホストオートメーションの対象にできます。

例

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

set_control_par()とset_control_par_str()を使って、さまざまな設定を行ったスイッチです。

関連項目

ui_button


ui_table

declare ui_table %<array-name>[num-elements] (<grid-width>, <grid-height>, <range>)

パフォーマンスビューにテーブルを作成します。

<width>

テーブルの幅をグリッド単位で指定します（1〜6）。

<height>

テーブルの高さをグリッド単位で指定します（1〜16）。

<range>

テーブルのレンジです。負の値を使うと、バイポーラーのテーブルが作成されます。

補足

  • テーブルに置ける列（要素）の最大数は128です。

例

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

ユニポーラーとバイポーラーのテーブルです。

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

テーブルに表示するステップ（列）の数を変更します。

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

テーブルの左上隅にある値インジケーターを非表示にし、代わりにラベルへ値を読み出して表示します。

関連項目

set_table_steps_shown()

hide_part()

特定のUIウィジェット: $NI_CONTROL_PAR_IDX


ui_text_edit

declare ui_text_edit @<variable-name>

パフォーマンスビューにテキスト編集フィールドを作成します。

例

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

ラベルの上に重ねたテキスト編集フィールドです。

関連項目

@ (string variable)


ui_value_edit

declare ui_value_edit $<variable-name> (<min>, <max>, <$display-ratio>)

パフォーマンスビューに値編集フィールド（ナンバーボックス）を作成します。

<min>

値編集フィールドの最小値を指定します。

<max>

値編集フィールドの最大値を指定します。

<display-ratio>

表示の際、値は<display-ratio>で除算されます。

ここで$VALUE_EDIT_MODE_NOTE_NAMESを使うと、数値の代わりにノートネームを表示することもできます。

例

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

ノートネームを表示する値編集フィールドです。

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

小数点以下3桁を表示する値編集フィールドです。

関連項目

特定のUIウィジェット: $CONTROL_PAR_SHOW_ARROWS, $VALUE_EDIT_MODE_NOTE_NAMES


ui_waveform

declare ui_waveform $<variable-name> (<grid-width>, <grid-height>)

サンプルと、必要に応じてそのスライスを表示する波形ディスプレイを作成します。このウィジェットは、スライスごとに特定のパラメーターを制御する用途や、MIDIのドラッグ＆ドロップ機能にも使えます。

<width>

波形の幅をグリッド単位で指定します（1〜6）。

<height>

波形の高さをグリッド単位で指定します（1〜16）。

例

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

「Test」という名前のZoneを波形ウィジェットに表示します。上記のコードを試すには、Test.wav（または.aiffなど）という名前のサンプルを使ってください。

関連項目

set_ui_wf_property()

get_ui_wf_property()

attach_zone()

ゾーンとスライスの関数: find_zone()

特定のUIウィジェット: Waveform Flag Constants, Waveform Property Constants, $CONTROL_PAR_WAVE_COLOR, $CONTROL_PAR_BG_COLOR, $CONTROL_PAR_WAVE_CURSOR_COLOR, $CONTROL_PAR_SLICEMARKERS_COLOR, $CONTROL_PAR_BG_ALPHA


ui_wavetable

declare ui_wavetable $<variable-name>

ウェーブテーブルとして使われているZoneの状態を可視化するウェーブテーブルディスプレイを、パフォーマンスビューに作成します。

例

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

「Wavetable01」というZoneをウェーブテーブルウィジェットに表示します。上記のコードを試すには、Wavetable01.wav（または.aiffなど）という名前のウェーブテーブルを使ってください。

関連項目

set_control_par()

ゾーンとスライスの関数: find_zone()

特定のUIウィジェット: $CONTROL_PAR_WT_VIS_MODE, $NI_WT_VIS_2D, $NI_WT_VIS_3D, $CONTROL_PAR_WAVE_COLOR, $CONTROL_PAR_BG_COLOR, $CONTROL_PAR_BG_ALPHA, $CONTROL_PAR_WAVE_COLOR, $CONTROL_PAR_WAVE_ALPHA, $CONTROL_PAR_WAVE_END_COLOR, $CONTROL_PAR_WAVE_END_ALPHA, $CONTROL_PAR_WAVETABLE_END_COLOR, $CONTROL_PAR_WAVETABLE_END_ALPHA, $CONTROL_PAR_PARALLAX_X, $CONTROL_PAR_PARALLAX_Y, $CONTROL_PAR_WT_ZONE


ui_xy

declare ui_xy ?<array-name>[num-elements]

パフォーマンスビューにXYパッドを作成します。

補足

  • XYパッドの各軸のレンジは、常に0.0から1.0の間になります。

  • XYパッド内のカーソル、すなわち操作できる要素の数は、配列のサイズによって決まります。配列の各インデックスが1つのカーソルの1つの軸に対応するため、カーソル1つにつき2つのインデックスが必要です。したがって、カーソルが3つあるXYパッドを作りたい場合、XY配列のサイズは6でなければなりません。

  • XY配列の最大サイズは32要素なので、1つのXYパッドに置けるカーソルの最大数は16です。

  • 配列の偶数インデックスはカーソルのX軸の値を、奇数インデックスはY軸の値を保持します。つまり、インデックス0は最初のカーソルのX値、インデックス1は最初のカーソルのY値です。

  • $CONTROL_PAR_MOUSE_MODEコントロールパラメーターを使って、XYパッドがマウス操作にどう反応するかを定義できます。

  • $NI_MOUSE_EVENT_TYPEをon ui_controlコールバックの中で参照すると、そのコールバックをトリガーしたマウスイベントの種類を判別できます。

例

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

2つのカーソルとオートメーション情報を持つXYパッドコントロールを作成します。

関連項目

set_control_par_arr()

一般: set_control_par_str_arr()

特定のUIウィジェット: $HIDE_PART_CURSOR, $NI_CONTROL_PAR_IDX, $CONTROL_PAR_MOUSE_MODE, $CONTROL_PAR_ACTIVE_INDEX, $CONTROL_PAR_CURSOR_PICTURE, $CONTROL_PAR_MOUSE_BEHAVIOUR_X, $CONTROL_PAR_MOUSE_BEHAVIOUR_Y

参照元情報：User Interface Widgets
https://docs.native-instruments.com/online-guides/ksp-manual/en/user-interface-widgets