Presets API

Save and load complete configuration presets.

Preset Operations

All preset operations open a native file dialog. They take no arguments and resolve with a PresetOperationResult.


type PresetOperationResult = { success: boolean; error?: string };

`dmn.presets.save(): Promise<PresetOperationResult>`

Saves the current configuration to a preset file. Opens a file save dialog.


const result = await dmn.presets.save();
if (result.success) {
  console.log('Preset saved');
} else {
  console.error('Save failed:', result.error);
}

`dmn.presets.load(): Promise<PresetOperationResult>`

Loads a preset file and applies it to the current configuration. Opens a file picker dialog.


const result = await dmn.presets.load();
if (result.success) {
  console.log('Preset loaded');
} else {
  console.error('Load failed:', result.error);
}

`dmn.presets.saveTab(): Promise<PresetOperationResult>`

Saves only the currently selected tab (its key mappings and layout) as a tab preset file. Opens a file save dialog.


const result = await dmn.presets.saveTab();

`dmn.presets.loadTab(): Promise<PresetOperationResult>`

Loads a tab preset file into the currently selected tab. Opens a file picker dialog. Tab presets carry no tabOrder or barCount, so they never change the global tab order. Element collections stored in the file (keys, stats, graphs, knobs, sprites) replace the tab’s contents wholesale, so elements missing from the file’s tab are removed. Older presets that lack a collection entirely leave those elements untouched.


const result = await dmn.presets.loadTab();

Snapshot Event

`dmn.presets.onSnapshot(callback): Unsubscribe`

Subscribes to preset load completions. Receives the full snapshot of applied data (key mappings, positions, tabs, mode, etc.) in a single event.

Position collections in the snapshot carry element id values that were freshly issued during this load. Applying a preset rekeys every element with new UUIDs, so IDs from the preset file or from a previous load never survive into the applied state, and loading the same preset twice produces two different ID sets. Re-resolve any cached element IDs from this snapshot.


interface PresetSnapshot {
  // Entries use the KeySlot union (string | MultiKeySlot)
  keys: KeyMappings;
  positions: KeyPositions;
  statPositions: StatItemPositions;
  graphPositions: GraphItemPositions;
  knobPositions: KnobItemPositions;
  spritePositions: SpritePositions;
  customTabs: CustomTab[];
  tabOrder: string[];
  barCount: number;
  selectedKeyType: string;
  tabNoteOverrides: TabNoteOverrides;
}
 
const unsub = dmn.presets.onSnapshot((snapshot) => {
  console.log('Preset loaded:', snapshot.selectedKeyType);
  console.log('Key mappings:', snapshot.keys);
});

Individual change events (onChanged, onPositionsChanged, etc.) are not emitted during preset load. Use onSnapshot to detect preset loads.

Example Usage


// @id preset-manager
 
if (dmn.window.type !== 'main') return;
 
// Save preset menu item
dmn.ui.contextMenu.addGridMenuItem({
  id: 'save-preset',
  label: 'Save Preset',
  onClick: async () => {
    const result = await dmn.presets.save();
    if (result.success) {
      await dmn.ui.dialog.alert('Preset saved!');
    }
  },
});
 
// Load preset menu item
dmn.ui.contextMenu.addGridMenuItem({
  id: 'load-preset',
  label: 'Load Preset',
  onClick: async () => {
    const confirmed = await dmn.ui.dialog.confirm(
      'This will overwrite the current configuration. Continue?',
    );
    if (confirmed) {
      const result = await dmn.presets.load();
      if (result.success) {
        await dmn.ui.dialog.alert('Preset loaded!');
      }
    }
  },
});
 
dmn.plugin.registerCleanup(() => {
  dmn.ui.contextMenu.clearMyMenuItems();
});