Now N.I.'s manual is pretty laconic about $CONTROL_PAR_PICTURE_STATE. All it says is : "the picture state of the control for tables, value edits and labels."
... So, what is a picture state ? And what values can I give it ? (Anything to do with 1 to 6, maybe ?)
For some reason, they explain this in the Developers Guide (which dates back to Kontakt 4), but I don't think it's in the regular KSP manual. So if you don't have this already, here is the documentation from the Developers' Guide:
5.5 Preparing Image Files
5.5.1 Accompanying Text File
Each image must be accompanied by a text (.txt) file of the same name containing important information on how KONTAKT should read this image. If a text file is not provided, any image file in the user picture folder will have a default one generated. If the image file is in the factory folder a text file will not be generated, but the image will be read by KONTAKT as if the values were set to default.
Here is an example of the content of one of these text files:
Has Alpha Channel: yes
Number of Animations: 6
Horizontal Animation: no
Vertical Resizable: no
Horizontal Resizable: yes
Fixed Top: 0
Fixed Bottom: 0
Fixed Left: 0
Fixed Right: 17
The list explained:
Has Alpha Channel: (yes or no) tells KONTAKT whether or not the image file contains a transparent (alpha) layer. If in doubt, set this to “yes”, as this will cause no problems either way.
Number of animations: sets the number of frames in the image. KONTAKT then equally divides the image using this number.
Horizontal Animation: (yes or no) designates in what direction the image should be split.
Vertical Resizable: (yes or no) if set to yes, it is possible to adjust the height of the image file in KONTAKT using the $CONTROL_PAR_HEIGHT constant in the set_control_par command.
Horizontal Resizable: (yes or no) if set to yes, it is possible to adjust the width of the image file in KONTAKT using the using the $CONTROL_PAR_WIDTH constant.
Fixed Top/Bottom/Left/Right: if you wish to be able to resize an image, but keep a certain area around the edge intact, simply set the number of pixels in the desired area. In the above example, the image is able to be resized horizontally, but the 17 pixels on the right side of the image will not be stretched.
It is important to note that KONTAKT is currently very sensitive about text file line break encoding. In our experience, the safest software to use is Notepad on Windows. This is unfortunately also true for scripts that link to external text files.
Please take note that wallpapers also need a text file although the text file’s parameters will be ignored.
5.5.2 Animations
Image files to be used in KONTAKT must be saved as *.png files. In order for KONTAKT to treat the image correctly, it must be provided in as stack of animations. So if you want one knob with 100 states, you need to build a very long image with all of these states in a row or column. KONTAKT will read the file top to bottom or left to right, depending on the setting of the .txt file. So your lowest value for a knob should be at the top or left and the highest at the bottom or right.
5.5.3 Switches and Dropdowns
Switches and Dropdowns should always have six animations, in a set order:
State
- 1 Off
- 2 On
- 3 Off, mouse down
- 4 On, mouse down
- 5 Off, mouse over
- 6 On, mouse over
The following script will illustrate the different states of a switch.
► First, copy the image and text files “switch_state_example” to the KONTAKT 4 user pictures folder. Then copy and paste the following script into a new KONTAKT instrument:
on init
make_perfview
declare ui_switch $switch_states
set_control_par_str(get_ui_id($switch_states),$CONTROL_PAR_TEXT,"")
set_control_par_str(get_ui_id($switch_states),$CONTROL_PAR_PICTURE,...
"switch_state_example")
end on
This will produce a single button that changes color depending on its state:
State
1 Off Black
2 On Red
3 Off, mouse down Orange
4 On, mouse down Yellow
5 Off, mouse over Purple
6 On, mouse over Green
Image files must always have six animations, even if you only plan to use the basic on/off. In this case, just triplicate the two on/off animations to bring the total up to six.