Posted by & filed under KSP Scripting (NI Kontakt) - Tutorials, KSP: Custom UI (design).

Unfortunately once the initial wallpaper is set, we can’t change the image anymore. Even not by setting different initial wallpapers for each script tab. Because the last applied wallpaper will be the one and only initial wallpaper for the whole instrument. But we can either offset the initial wallpaper that means moving it via set_skin_offset() or we can use a label element to set up multiple backgrounds. Even dynamically like switching them on a button event. The set_skin_offset method is explained in this article

Download all Resources (nki, images)


makes the current tab visible (outside the edit mode)

set the height of your ui in pixels

sets the name of your tab (only when using more than one tab)

use this command in combination with the variables below to set the background

The (fixed) ID of the instrument wallpaper.

sets the picture name

retrieve the numeric id of the specific ui element (integer)

on ui_control(<variable>)
UI callback, executed whenever the user changes the respective UI element

declare ui_switch $<variable-name>
creates an ui switch (button)

declare ui_label $<variable-name> (<width>,<height>)
creates an ui label, used for an adjustable background graphic. Width and height in grid units which can be set to 1 since your graphic will expands the label anyway

positions an element in the grid use it to move the label to top left corner (0,0) you can also use

to position with the exact pixels

Dynamic, switchable Wallpaper/Background

We use a label UI element and its background property ($CONTROL_PAR_PICTURE) to set multiple background wallpapers. As most UI elements, also the label element allows us to change its background image and its size. So when we create an image of our UI sizes and add it as the label’s background we have a 2nd wallpaper. With one little restriction though. The first 68px (where the Kontakt panel resides) can only be covered by the initial wallpaper. So we should always set an initial wallpaper if we also want to cover this panel otherwise we would have an ugly grayish bg here. Read more here

Since all control elements like labels, knobs, buttons etc are layered according to the declaration order (code position) inside the on init callback, you can easily overlay the initial wallpaper with another wallpaper (label). You can also put your knobs and buttons on top of your second wallpaper then. If you want to use multiple wallpapers you simply replace your “wallpaper label” with a 3rd or 4th,… wallpaper image instead of creating a new label element for each additional wallpaper. To cut it short, the label element becomes a container for all of your additional wallpapers.

  1. create an ui label and add your 1st background graphic with set_control_par_str($label_id ,$CONTROL_PAR_PICTURE,"name-of-your-1st-wallpaper").
  2. Hide it again via set_control_par($label_id ,$CONTROL_PAR_HIDE,$HIDE_WHOLE_CONTROL) because initially we want to show the “initial wallpaper”
  3. now you can access your label and change its background and other properties within any callbacks like on_note or on ui_control callback with set_control_par($label_id ,$CONTROL_PAR_HIDE,$HIDE_PART_NOTHING)

Example (read the explanations in brackets {…} )

on init 
     set_ui_height_px(540) {height of your UI}
     make_perfview {makes this UI visible outside the edit mode}

     {SET: initial wallpaper}
     set_control_par_str($INST_WALLPAPER_ID,$CONTROL_PAR_PICTURE,"wallpaper1") {sets your initial wallpaper which can only be overlayed}

     {SET: vraiables}
     declare $label_id {used to store the label id, later we will use arrays}
     declare $button_id {used to store the button id, later we will use arrays}

     {SET: label / wallpaper 2}
         declare ui_label $wallpaper (0,0) {creates a label "container" for your additional wallpapers}
         $label_id := get_ui_id ($wallpaper) {get the numeric unique id of the label}

         set_control_par_str($label_id ,$CONTROL_PAR_TEXT,"") {clear the default text}
         set_control_par_str($label_id ,$CONTROL_PAR_PICTURE,"wallpaper2") {set background image}
         set_control_par($label_id ,$CONTROL_PAR_HIDE,$HIDE_WHOLE_CONTROL) {hides the whole label because we first use the initial wallpaper}
         move_control_px($wallpaper,0,0) {move to top left position}

         declare ui_switch $button_switch_wallpaper {create a simple button to switch the wallpapers}
         $button_id := get_ui_id ($button_switch_wallpaper) {get the numeric unique id of the button}
    message("") {clears the status bar}
end on

on ui_control($button_switch_wallpaper)
     if ($button_switch_wallpaper = 1)
         set_control_par($label_id ,$CONTROL_PAR_HIDE,$HIDE_PART_NOTHING) {shows your label}
             set_control_par($label_id ,$CONTROL_PAR_HIDE,$HIDE_WHOLE_CONTROL)
     end if  
     message("") {clears the status bar}
end on

How to create a 2nd wallpaper image?

  • use your favorite graphic software and read the Custom UI: Background Image / Wallpaper tutorial.
  • Add a horizontal auxiliary line at 68px  and “draw” your initial wallpaper including the 68px header (which will be behind the Kontakt panel)
  • then create a new layer and draw your 2nd wallpaper below the auxiliary line.
  • take care to make it look flawless so that the header of your initial wallpaper also fits to your second wallpaper. Best way to do so is to use one background texture like in this example:
  • when you are done simply crop your 2nd wallpaper below the header and save it (e.g. as wallpaper2.png)

4 Responses to “KSP Scripting (Kontakt) :: Custom UI: Switchable, Dynamic Background Image / Wallpaper (via label element)”

    • YummyBeats

      yes, you can hide/display knobs/sliders via $CONTROL_PAR_HIDE

      > hide:
      set_control_par([ui - ID], $CONTROL_PAR_HIDE, $HIDE_WHOLE_CONTROL)

      > show:
      set_control_par([ui -ID], $CONTROL_PAR_HIDE, $HIDE_PART_NOTHING)

  1. Leo

    I wonder if it is possible to segregate the images/knobs/sliders in the pictures folder by putting them into separate folders?

    so instead of using directly the


    maybe we can do like this?


    • YummyBeats

      as far as I know this is not possible. You can only use custom paths or subfolders with midi files etc.
      Is it important for you to use subfolders?! I mean at the end you would create one resource container anway, so I gues you just need them for a better overview, right? So instead of using subfolders you could also sort by a file naming system like starting all button images with “btn_” all backgrounds with “bg_” and so on.


Leave a Reply

Your email address will not be published. Required fields are marked *