HISE Docs

ScriptMultipageDialog


This is the scripting reference object to a Multipage Dialog UI component and can be used to programmatically build complex dialogs or load prebuilt dialogs made with the multipagecreator tool. The workflow of using this class is somewhat similar to the Builder class:

  1. Create an instance / reference to the multipage dialog
  2. Add pages / elements using add() or addPage() which returns an integer index so that you can reference the element later
  3. Modify the elements using the supplied index with setElementProperty() or setElementValue()
  4. Attach callbacks to "global events" using setOnFinishCallback() or setOnPageLoad() or specific components using bindCallback()
  5. "Flush" the changes and show the dialog using show()

Note that the state of the dialog is not persistent across compilations so you need to rebuild the dialog everytime you compile. If you want to reset the dialog after the onInit callback, you can use the resetDialog() method which will clear all the pages and internal states.

Hello world example

This code snippet will create a multipage dialog and shows how to use the API to build up a dialog that you can attach HiseScript callbacks to:

// Create a multipage dialog component
const var mp = Content.addMultipageDialog("mp", 0, 0);

// the text property is used as title
mp.set("text", "Hello Dialog!");

// I swear this is the "last" time I'll do this...
mp.set("Font", "Comic Sans MS");

// The width / height properties will define what
// area is masked by the dialog
mp.set("height", 600);

// The actual dialog size is set by those properties
mp.set("DialogWidth", 550);
mp.set("DialogHeight", 500);

// Add two pages
const var firstPage = mp.addPage();
const var secondPage = mp.addPage();

// Add a markdown text
mp.add(firstPage, mp.types.MarkdownText, { Text: "This is some markdown  \n> Noice!" });

// This function will be called when you click the button defined below...
inline function hiseCallback(id, value, state)
{
	Console.print("ID: " + id + ", value: " + value);
}

// Add a button to the second page
mp.add(secondPage, mp.types.Button, 
{ 
   ID: "MyButton", 
   Text: "Click me", 
   // You can bind HiseScript callbacks to react on
   // button clicks like this:
   Code: mp.bindCallback("hiseCallback", hiseCallback, // Create a multipage dialog component
const var mp = Content.addMultipageDialog("mp", 0, 0);

// the text property is used as title
mp.set("text", "Hello Dialog!");

// I swear this is the "last" time I'll do this...
mp.set("Font", "Comic Sans MS");

// The width / height properties will define what
// area is masked by the dialog
mp.set("height", 600);

// The actual dialog size is set by those properties
mp.set("DialogWidth", 550);
mp.set("DialogHeight", 500);

// Add two pages
const var firstPage = mp.addPage();
const var secondPage = mp.addPage();

// Add a markdown text
mp.add(firstPage, mp.types.MarkdownText, { Text: "This is some markdown  \n> Noice!" });

// This function will be called when you click the button defined below...
inline function hiseCallback(id, value, state)
{
	Console.print("ID: " + id + ", value: " + value);
}

// Add a button to the second page
mp.add(secondPage, mp.types.Button, 
{ 
   ID: "MyButton", 
   Text: "Click me", 
   // You can bind HiseScript callbacks to react on
   // button clicks like this:
   Code: mp.bindCallback("hiseCallback", hiseCallback, "string")
});

// Show the dialog
mp.show(true);)
});

// Show the dialog
mp.show(true);


Class methods

add

Adds an element to the parent with the given type and properties.

ScriptMultipageDialog.add(int parentIndex, String type,  var properties)


This will add a UI element to a parent defined by the parentIndex index. The type argument must be a valid type string.

It's highly recommended to use the typelist provided as the ScriptMultipageDialog.types constant.

The properties argument must be a JSON object that will contain the property definitions for the UI element.

For a reference of all available UI elements and their properties, take a look at this list:

Multipage Dialog Reference

addModalPage

Adds a modal page to the dialog that can be populated like a normal page and shown using showModalPage(). Edit on GitHub 

ScriptMultipageDialog.addModalPage()



addPage

Adds a page to the dialog and returns the element index of the page.

ScriptMultipageDialog.addPage()


This will add a page to the dialog and return an integer index that can be used to add elements to the page.

const var mp = Content.addMultipageDialog("mp", 0, 0);

for(i = 0; i < 10; i++)
	mp.addPage();

Make sure to store the page index returned by this function as you will need it to add UI elements to the page later.


addToMacroControl

Adds the knob / button to a macro controller (from 0 to 7). Edit on GitHub 

ScriptMultipageDialog.addToMacroControl(int macroIndex)



bindCallback

Registers a callable object to the dialog and returns the codestring that calls it from within the dialogs Javascript engine. Edit on GitHub 

ScriptMultipageDialog.bindCallback(String id, var callback, var notificationType)



cancel

Closes the dialog (as if the user pressed the cancel button). Edit on GitHub 

ScriptMultipageDialog.cancel()



changed

Call this to indicate that the value has changed (the onControl callback will be executed. Edit on GitHub 

ScriptMultipageDialog.changed()



createLocalLookAndFeel

Returns a local look and feel if it was registered before. Edit on GitHub 

ScriptMultipageDialog.createLocalLookAndFeel(ScriptContentComponent *contentComponent, Component *componentToRegister)



exportAsMonolith

Exports the entire dialog. Edit on GitHub 

ScriptMultipageDialog.exportAsMonolith(var optionalFile)



fadeComponent

Toggles the visibility and fades a component using the global animator. Edit on GitHub 

ScriptMultipageDialog.fadeComponent(bool shouldBeVisible, int milliseconds)



get

returns the value of the property. Edit on GitHub 

ScriptMultipageDialog.get(String propertyName)



getAllProperties

Returns a list of all property IDs as array. Edit on GitHub 

ScriptMultipageDialog.getAllProperties()



getChildComponents

Returns list of component's children Edit on GitHub 

ScriptMultipageDialog.getChildComponents()



getElementProperty

Returns the value for the given element ID. Edit on GitHub 

ScriptMultipageDialog.getElementProperty(int elementId, String propertyId)



getGlobalPositionX

Returns the absolute x-position relative to the interface. Edit on GitHub 

ScriptMultipageDialog.getGlobalPositionX()



getGlobalPositionY

Returns the absolute y-position relative to the interface. Edit on GitHub 

ScriptMultipageDialog.getGlobalPositionY()



getHeight

Returns the height of the component. Edit on GitHub 

ScriptMultipageDialog.getHeight()



getId

Returns the ID of the component. Edit on GitHub 

ScriptMultipageDialog.getId()



getLocalBounds

Returns a [x, y, w, h] array that was reduced by the given amount. Edit on GitHub 

ScriptMultipageDialog.getLocalBounds(float reduceAmount)



getState

returns the state object for the dialog. Edit on GitHub 

ScriptMultipageDialog.getState()



getValueNormalized

Returns the normalized value. Edit on GitHub 

ScriptMultipageDialog.getValueNormalized()



getWidth

Returns the width of the component. Edit on GitHub 

ScriptMultipageDialog.getWidth()



grabFocus

Call this method in order to grab the keyboard focus for this component. Edit on GitHub 

ScriptMultipageDialog.grabFocus()



loadFromDataFile

Loads the dialog from a file (on the disk). Edit on GitHub 

ScriptMultipageDialog.loadFromDataFile(var fileObject)



loseFocus

Call this method in order to give away the focus for this component. Edit on GitHub 

ScriptMultipageDialog.loseFocus()



Navigates to the given page index. Edit on GitHub 

ScriptMultipageDialog.navigate(int pageIndex, bool submitCurrentPage)



resetDialog

Clears the dialog. Edit on GitHub 

ScriptMultipageDialog.resetDialog()



set

Sets the property. Edit on GitHub 

ScriptMultipageDialog.set(String propertyName, var value)



setColour

sets the colour of the component (BG, IT1, IT2, TXT). Edit on GitHub 

ScriptMultipageDialog.setColour(int colourId, int colourAs32bitHex)



setConsumedKeyPresses

Registers a selection of key presses to be consumed by this component. Edit on GitHub 

ScriptMultipageDialog.setConsumedKeyPresses(var listOfKeys)



setControlCallback

Pass a inline function for a custom callback event. Edit on GitHub 

ScriptMultipageDialog.setControlCallback(var controlFunction)



setElementProperty

Sets the property for the given element ID and updates the dialog. Edit on GitHub 

ScriptMultipageDialog.setElementProperty(int elementId, String propertyId,  var newValue)



setElementValue

Sets the value of the given element ID and calls the callback. Edit on GitHub 

ScriptMultipageDialog.setElementValue(int elementId, var value)



setKeyPressCallback

Adds a callback to react on key presses (when this component is focused). Edit on GitHub 

ScriptMultipageDialog.setKeyPressCallback(var keyboardFunction)



setLocalLookAndFeel

Attaches the local look and feel to this component. Edit on GitHub 

ScriptMultipageDialog.setLocalLookAndFeel(var lafObject)



setOnFinishCallback

Registers a function that will be called when the dialog is finished. Edit on GitHub 

ScriptMultipageDialog.setOnFinishCallback(var onFinish)



setOnPageLoadCallback

Registers a function that will be called when the dialog shows a new page. Edit on GitHub 

ScriptMultipageDialog.setOnPageLoadCallback(var onPageLoad)



setPosition

Sets the position of the component. Edit on GitHub 

ScriptMultipageDialog.setPosition(int x, int y, int w, int h)



setPropertiesFromJSON

Restores all properties from a JSON object. Edit on GitHub 

ScriptMultipageDialog.setPropertiesFromJSON( var jsonData)



setStyleSheetClass

Sets the given class selectors for the component stylesheet. Edit on GitHub 

ScriptMultipageDialog.setStyleSheetClass( String classIds)



setStyleSheetProperty

Sets a variable for this component that can be queried from a style sheet. Edit on GitHub 

ScriptMultipageDialog.setStyleSheetProperty( String variableId,  var value,  String type)



setStyleSheetPseudoState

Programatically sets a pseudo state (:hover, :active, :checked, :focus, :disabled) that will be used by the CSS renderer. Edit on GitHub 

ScriptMultipageDialog.setStyleSheetPseudoState( String pseudoState)



setTooltip

Shows a informative text on mouse hover. Edit on GitHub 

ScriptMultipageDialog.setTooltip( String tooltip)



setValueNormalized

Sets the current value from a range 0.0 ... 1.0. Edit on GitHub 

ScriptMultipageDialog.setValueNormalized(double normalizedValue)



setValueWithUndo

Sets the current value and adds it to the undo list. Don't call this from onControl! Edit on GitHub 

ScriptMultipageDialog.setValueWithUndo(var newValue)



setZLevel

Changes the depth hierarchy (z-axis) of sibling components (Back, Default, Front or AlwaysOnTop). Edit on GitHub 

ScriptMultipageDialog.setZLevel(String zLevel)



show

Shows the dialog (with optionally clearing the state. Edit on GitHub 

ScriptMultipageDialog.show(bool clearState)



showControl

Hides / Shows the control. Edit on GitHub 

ScriptMultipageDialog.showControl(bool shouldBeVisible)



showModalPage

Shows a modal page with the given index and the state object. Edit on GitHub 

ScriptMultipageDialog.showModalPage(int pageIndex, var modalState, var finishCallback)



updateContentPropertyInternal

This updates the internal content data object from the script processor. Edit on GitHub 

ScriptMultipageDialog.updateContentPropertyInternal(int propertyId,  var newValue)



updateValueFromProcessorConnection

Updates the value from the processor connection. Call this method whenever the module state has changed and you want to refresh the knob value to show the current state. Edit on GitHub 

ScriptMultipageDialog.updateValueFromProcessorConnection()



Edit on GitHub Next: ScriptPanel

Christoph Hart
24.06.2024