Page tree
Skip to end of metadata
Go to start of metadata

startUndoBlock(name, id)


Function to combine multiple undo entries into one undo block. For example, if your script inserts several elements into the program, you might want to be able to remove all the elements in one single undo operation. The function returns an ID for identifying the undo block. This ID can be used as second argument in later calls to startUndoBlock for combining the undo blocks that refer to this ID.  The name argument will be used as entry in the undo history. If multiple undo blocks are combined, only the name of the last undo block will be used. This function must be terminated using endUndoBlock. If startUndoBlock is called within a callback function, endUndoBlock is called automatically when the callback function ends.

Available in: Controller.


nameThis will be displayed as entry in the undo history.string
idSet this to combine the undo blocks that refer to this ID.number

Return Values

Returns an ID that can be used to identify the undo block.

Example 1

-- Change param1, then param2.
-- The changes of param1 and param2 are combined into one undo entry.
function param1Changed()
  id = startUndoBlock("param1 Changed")
function param2Changed()
  startUndoBlock("param2 Changed", id)
defineParameter{ name = "param1", onChanged = param1Changed }
defineParameter{ name = "param2", onChanged = param2Changed }

Example 2

To use the following script:

  1. Download Program.vstpreset.
  2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
  3. Create an empty program and add a script module.
  4. Paste the script into the text editor of the script module and execute the script.
  5. Check the entries in the undo history with and without undo block.


-- insert elements from Program.vstpreset into the current program

-- get the file path for user VST presets
path = getUserPresetPath()

-- load VST preset
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")

-- get elements from loadedProgram
midiModule = loadedProgram:findMidiModules()[1] -- first MIDI module in loadedProgram
subLayer = loadedProgram:findLayers()[1] -- first layer in loadedProgram
bus = loadedProgram:findBusses()[1] -- first bus in loadedProgram
program = this.program
-- begin the undo block
startUndoBlock("Insert Modules") -- only this entry will display in the undo history

	-- insert elements
	if midiModule then
    	program:insertMidiModule(midiModule, 1)
	if subLayer then
    	program:insertLayer(subLayer, 1)
	if bus then
    	program:insertBus(bus, 1)

endUndoBlock() -- terminate the undo block


  1. Second proofread done