/ HALion Developer Resource / HALion Macro Page / Controls /

Template List

On this page:

• Description
• Properties
• Template List Callbacks
  • onTemplateListViewDrop
  • onTemplateListGetDragInfo
  • onTemplateListDrop
  • onTemplateListDropFeedback
  • onTemplateListDropDone
• Example

Description

A Template List can be used to create child templates from a single referenced template, where each instance of the referenced template can be used to control different parameter scopes, for example. The look of the Template List rows and columns is determined by the referenced template which you can choose in the Template property. Depending on the Layout property, the templates are arranged in a row, a column, or in a grid. The templates are arranged without spacing or graphic separators. If spacing or graphic separators are desired, they must be part of the referenced template.

❕ For a better understanding of template lists, read the tutorial Creating a Template List.

Properties

Jump to Top

Template List Callbacks

(Since HALion 7.0)

To enable the graphic reordering, the Order option must be active and either onTemplateListViewDrop or onTemplateListDrop must be implemented in a UI script.

❕ In order for the onTemplateListDrop function to be called, the Drag Info property of the template referenced in the Template List must be set.

onTemplateListViewDrop

This callback is called when the drop is done. If you need more advanced control over the drag and drop operation, you can use the callbacks described below as an alternative.

onTemplateListViewDrop(viewname, fromindex, toindex)

Jump to Top

❕ The callback onTemplateListViewDrop is a simplified callback that replaces the callbacks onTemplateListDropFeedback, onTemplateListDrop and onTemplateListDropDone from below. The callback onTemplateListViewDrop cannot be combined with the callbacks just mentioned.

onTemplateListGetDragInfo

onTemplateListGetDragInfo(viewname, draginfo, index)

Description

Callback for the source of the drag operation when the operation starts. The string in draginfo is taken from the Drag Info property of the template referenced in the Template List. The Drag Info property must be set inside the referenced template. To enable the graphic reordering of the elements, the Order option must be active and at least the onTemplateListDrop callback must be implemented in a UI script. The onTemplateListDrop callback can be omitted if no graphic reordering is required.

Arguments

Return Values

The function can return a table with the following keys:

❕ If both of the 'copy' and 'move' return values are set to true, the 'copy' argument in the callbacks onTemplateListDrop, onTemplateListDropFeedback, and onTemplateListDropDone will depend upon whether the Alt/Cmd-key was utilized during the drag operation. The 'copy' argument in these callbacks will be true if the Alt/Cmd-key was used and false if it was not. If one or both of the 'copy' and 'move' return values are false, the use of the Alt/Cmd-key has no effect, and the 'copy' argument in the mentioned callbacks will depend solely on the 'copy' return value.

Jump to Top

onTemplateListDrop

onTemplateListDrop(viewname, draginfo, toindex, offset, copy)

Description

Callback for the target of the drag operation when the drop is executed. In order for the function to be called, the Drag Info property of the template referenced in the Template List must be set. Otherwise, the reordering will not work, even if the Order option of the Template List is active.

Arguments

Jump to Top

onTemplateListDropFeedback

onTemplateListDropFeedback(viewname, draginfo, toindex, offset, copy)

Description

Callback for the target of the drag operation when an element is held over it. If implemented it can control the graphical feedback for the potential drop operation by returning a template to indicate the drop destination or reject dropping the element.

Arguments

Return Values

The function can return a table with the following keys:

❕ When using onTemplateListDropFeedback: Since the default of accept is false, you must at least return accept=true.

Jump to Top

onTemplateListDropDone

onTemplateListDropDone(viewname, draginfo, index, copy)

This callback is called when the drop operation is complete. Since the arguments of the callback refer to the source of the drag operation, it can be used to make modifications to the corresponding source Template List using additional functions.

Arguments

Jump to Top

❕ If you want the change of the order of graphical elements to affect the program structure, e.g. the order of alternating layers or the order of effects within a bus, this must be implemented separately with dedicated functions.

Example

The subsequent example is presented as illustrative guide to kickstart your own solution-building process.

To explore the example:

1. Load Template List.vstpreset.
2. Open the Macro Page Designer, activate Show/Hide Script Output Messages.
3. Click Test Macro page , then drag and drop elements from the left to the right template list and vice versa.
4. Use the Alt/Cmd-key to copy elements.
5. Read the output messages of the script.

Reading the output messages of the script should help to understand how the callbacks work and how to use them.

-- Create row names through a parameter.
rowNames = {}
 
for i = 1, 5 do 
 rowNames[i] = "Row "..tostring(i) 
end 
 
defineParameter{name="RowNames", strings=rowNames,}

currentViewname = ""

-- The following example accepts dropping of elements only from other template lists.

function onTemplateListGetDragInfo(viewname, draginfo, index)
	print("onTemplateListGetDragInfo:", "viewname = "..viewname, "draginfo = "..draginfo, "index = "..index)
	currentViewname = viewname
	return{info = index, copy=true, move=true}
end

function onTemplateListDropFeedback(viewname, draginfo, toindex, offset, copy)
	print("onTemplateListDropFeedback:", "viewname = "..viewname, "draginfo = "..draginfo, "toindex = "..toindex, "offset = "..offset, "copy = "..tostring(copy))
	local acceptDrop = false
	if viewname ~= currentViewname then
	acceptDrop = true
	end
	return{accept=acceptDrop, insert=false, template="DropFrame", resize=true,}
end

function onTemplateListDrop(viewname, draginfo, toindex, offset, copy)
	print("onTemplateListDrop:", "viewname = "..viewname, "draginfo = "..draginfo, "toindex = "..toindex, "offset = "..offset, "copy = "..tostring(copy))
	if viewname ~= currentViewname then
		local fromindex = tonumber(draginfo)
		if copy then
			rowNames[toindex] = rowNames[fromindex]
		else
			local rowName = table.remove(rowNames, fromindex)
			table.insert(rowNames, toindex, rowName)
		end
		defineParameter{name="RowNames", strings=rowNames,}
	end
end

function onTemplateListDropDone(viewname, draginfo, index, copy)
	print("onTemplateListDropDone:", "viewname = "..viewname, "draginfo = "..draginfo, "index = "..index, "copy = "..tostring(copy))
end