Keymaps¶
Keymaps
Import¶
import "_IVLS/source/nodes/Keymaps.ksp"Node: Ivls.Keymaps¶
Uses: Init, Reload
Overview¶
Keymaps
LIBRARY MODULE
Manages per-map, per-key metadata and synchronises it to Kontakt's native key display.
- Up to MAX_MAPS independent keymaps, each mapping 128 keys to category, flow, color, type, name, and latency
- Public macros: keymap.request, keymap.dismiss, keymap.dismiss_all_of, keymap.update_key_*
- Display sync: keymap.push, keymap.push_all, keymap.select_map, keymap.reboot
Constants¶
| Constant | Value | Description |
|---|---|---|
keymap.MAX_MAPS |
16 |
integer |
keymap.NUM_KEYS |
128 |
integer |
API¶
Nodes¶
| Name | Description |
|---|---|
node Ivls.Keymaps |
IVLS node that owns all keymap data structures and the key-management API. |
Const Blocks¶
| Name | Description |
|---|---|
const category |
Enumerates all registered keymap category names. |
Macros¶
| Name | Description |
|---|---|
keymap.dismiss(#category#, #map_i#, #key_i#, #flow#, #type#, #color#, #name#) |
Releases ownership of a key on the given map for the named category, resetting i... |
keymap.dismiss_all_of(#category#, #map_i#) |
Releases ownership of every key owned by the named category on the given map, re... |
keymap.request(#category#, #map_i#, #key_i#, #flow#, #type#, #color#, #name#) |
Requests ownership of a key on the given map for the named category, setting its... |
keymap.update_key_color(#category#, #map_i#, #key_i#, #color#) |
Updates the Kontakt key color for the given key on the given map, but only if th... |
keymap.update_key_latency_us(#category#, #map_i#, #key_i#, #latency#) |
Updates the scheduling latency hint in microseconds for the given key on the giv... |
keymap.update_key_name(#category#, #map_i#, #key_i#, #name#) |
Updates the display name for the given key on the given map, but only if the nam... |
keymap.update_key_type(#category#, #map_i#, #key_i#, #type#) |
Updates the Kontakt key type for the given key on the given map, but only if the... |
Functions¶
| Name | Description |
|---|---|
keymap.push(key_i) |
Pushes the display properties (color, type, name) of a single key on the current... |
keymap.push_all() |
Iterates over all 128 keys and pushes each one to the Kontakt key display for th... |
keymap.reboot() |
Reinitialises all keys and re-registers all key requests. |
keymap.resume() |
Re-enables Kontakt key sync and immediately pushes all keys of the currently sel... |
keymap.select_map(map_i) |
Sets the active keymap index and immediately pushes all 128 keys of the new map ... |
keymap.suspend() |
Disables Kontakt key sync so that batch key operations do not trigger redundant ... |
Nodes¶
node Ivls.Keymaps¶
Callbacks: Init, Reload
IVLS node that owns all keymap data structures and the key-management API.
Const Blocks¶
const category¶
Enumerates all registered keymap category names.
Macros¶
keymap.dismiss(#category#, #map_i#, #key_i#, #flow#, #type#, #color#, #name#)¶
Releases ownership of a key on the given map for the named category, resetting it to its default state if the category owns that key.
| Parameter | Description |
|---|---|
#category# |
category name token to resolve to its enum index |
#map_i# |
map index to dismiss the key on |
#key_i# |
MIDI key number to dismiss |
#flow# |
(unused at dismiss time, kept for API symmetry with request) |
#type# |
(unused at dismiss time, kept for API symmetry with request) |
#color# |
(unused at dismiss time, kept for API symmetry with request) |
#name# |
(unused at dismiss time, kept for API symmetry with request) |
keymap.dismiss_all_of(#category#, #map_i#)¶
Releases ownership of every key owned by the named category on the given map, resetting each to its default state.
| Parameter | Description |
|---|---|
#category# |
category name token to resolve to its enum index |
#map_i# |
map index to sweep for keys owned by this category |
keymap.request(#category#, #map_i#, #key_i#, #flow#, #type#, #color#, #name#)¶
Requests ownership of a key on the given map for the named category, setting its flow, type, color, and name if the key is unclaimed.
| Parameter | Description |
|---|---|
#category# |
category name token to resolve to its enum index |
#map_i# |
map index to request the key on |
#key_i# |
MIDI key number to request |
#flow# |
flow index to associate with this key |
#type# |
Kontakt key type constant |
#color# |
Kontakt key color constant |
#name# |
display name string for the key |
keymap.update_key_color(#category#, #map_i#, #key_i#, #color#)¶
Updates the Kontakt key color for the given key on the given map, but only if the named category owns that key.
| Parameter | Description |
|---|---|
#category# |
category name token to resolve to its enum index |
#map_i# |
map index containing the key to update |
#key_i# |
MIDI key number to update |
#color# |
new Kontakt key color constant |
keymap.update_key_latency_us(#category#, #map_i#, #key_i#, #latency#)¶
Updates the scheduling latency hint in microseconds for the given key on the given map, but only if the named category owns that key.
| Parameter | Description |
|---|---|
#category# |
category name token to resolve to its enum index |
#map_i# |
map index containing the key to update |
#key_i# |
MIDI key number to update |
#latency# |
new latency value in microseconds |
keymap.update_key_name(#category#, #map_i#, #key_i#, #name#)¶
Updates the display name for the given key on the given map, but only if the named category owns that key.
| Parameter | Description |
|---|---|
#category# |
category name token to resolve to its enum index |
#map_i# |
map index containing the key to update |
#key_i# |
MIDI key number to update |
#name# |
new display name string for the key |
keymap.update_key_type(#category#, #map_i#, #key_i#, #type#)¶
Updates the Kontakt key type for the given key on the given map, but only if the named category owns that key.
| Parameter | Description |
|---|---|
#category# |
category name token to resolve to its enum index |
#map_i# |
map index containing the key to update |
#key_i# |
MIDI key number to update |
#type# |
new Kontakt key type constant |
Functions¶
keymap.push(key_i)¶
Pushes the display properties (color, type, name) of a single key on the currently selected map to Kontakt, if Kontakt sync is active.
| Parameter | Type | Description |
|---|---|---|
key_i |
integer | MIDI key number (0..127) to push |
Side effects:
| Name | Type | Purpose |
|---|---|---|
| color | integer | local copy of the key color constant |
| type | integer | local copy of the key type constant |
keymap.push_all()¶
Iterates over all 128 keys and pushes each one to the Kontakt key display for the currently selected map.
Side effects: | Name | Type | Purpose | |------|------|---------| | key_i | integer | loop counter over all MIDI key indices |
keymap.reboot()¶
Reinitialises all keys and re-registers all key requests.
keymap.resume()¶
Re-enables Kontakt key sync and immediately pushes all keys of the currently selected map to refresh the display.
keymap.select_map(map_i)¶
Sets the active keymap index and immediately pushes all 128 keys of the new map to the Kontakt key display.
| Parameter | Type | Description |
|---|---|---|
map_i |
integer | index of the map to select (0..MAX_MAPS-1) |
Side effects: | Name | Type | Purpose | |------|------|---------| | key_i | integer | loop counter over key indices |
keymap.suspend()¶
Disables Kontakt key sync so that batch key operations do not trigger redundant key-display updates.
Example¶
// TODO: Add usage example