HISE Docs

Multipage Dialog Reference

The Multipage Dialog component provides a comprehensive set of tools to develop complex dialogs. The available elements are divided into three primary categories: UI Elements, Actions, and Layout.

You can use them either in the multipagecreator app in a graphical editor, or build them up programmatically using the Scripting API to the ScriptMultipageDialog .

This document contains a autogenerated list of all available elements and properties.

Note for using it through the scripting API: If the property supplies any Options , the value must be one of the listed strings, otherwise it will require either a bool value or a string.

Layout

These elements are used to arrange the UI elements (and actions) on the dialog and supply generic elements like spacers & text paragraphs. The multipage dialog uses a row / column system that you can use to create almost any 2D arrangement of layouts:

--------List--------
--------List--------
--------List--------
Column|Column|-List-
------|------|-List-
--------List--------

Branch

ID Description
ID The ID of the branch. This will be used as key to fetch the value from the global state to determine which child to show.

Column

ID Description
ID The ID. This will be used for identification in some logic cases
Class The CSS class that is applied to the container
Style Additional inline properties that will be used by the UI element
UseChildState If ticked, then this list will save its child element values in a sub object of the global state.

EventLogger

ID Description

HtmlElement

ID Description
HtmlElement A UI element defined by HTML markup language
ID The ID for the element (used as key in the state var .
Code The HTML code
Class The CSS class that is applied to the UI element.
Style Additional inline properties that will be used by the UI element

Image

ID Description
Image A component with fix columns and a dynamic amount of rows
ID The ID for the element (used as key in the state var .
Source The image source - either a URL or a asset reference
Options : None,
Class The CSS class that is applied to the UI element.
Style Additional inline properties that will be used by the UI element

List

ID Description
ID The ID of the list. This will be used for identification in some logic cases
UseChildState If ticked, then this list will save its child element values in a sub object of the global state.
Text The title text that is shown at the header bar.
Class The CSS class that is applied to the container
Style Additional inline properties that will be used by the UI element
Foldable If ticked, then this list will show a clickable header that can be folded
Folded If ticked, then this list will folded as default state

MarkdownText

A field to display text messages with markdown support

ID Description
ID The ID for the element.
Text The text content in markdown syntax.
Class The CSS class that is applied to the action UI element (progress bar & label).
Style Additional inline properties that will be used by the UI element

Placeholder

A basic component placeholder for any juce::Component

ID Description
ID The ID for the element (used as key in the state var .
ContentType The C++ class name that will be used for the content.
 The class must be derived from juce::Component and hise::multipage::PlaceholderContentBase
Class The CSS class that is applied to the UI element.
Style Additional inline properties that will be used by the UI element

SimpleText

A field to display text messages with markdown support

ID Description
ID The ID for the element (used as key in the state var .
Text The plain text content.
Class The CSS class that is applied to the action UI element (progress bar & label).
Style Additional inline properties that will be used by the UI element

Spacer

A simple spacer for convenient layouting.

ID Description

UI Elements

The elements in this category can be used to interact with the dialog (through buttons, comboboxes or text inputs).

Button

A Button lets you enable / disable a boolean option or can be grouped together with other tickboxes to create a radio group with an exclusive selection option

ID Description
ID The ID for the element (used as key in the state var .
Enabled Whether to allow user input for the element
InitValue The initial value for the UI element
UseInitValue Whether to initialise the state object with the init value
Required If this is enabled, the tickbox must be selected in order to proceed to the next page, otherwise it will show a error message. This is particularly useful for eg. accepting TOC
Trigger If this is enabled, the button will fire the action with the same ID when you click it, otherwise it will store its value (either on/off or radio group index in the global state
Text The label next to the Button
Help The markdown content that will be shown when you click on the help button
Tooltip The tooltip that will be applied when hovering the element
ButtonType The appearance of the button.
Options : Toggle, Text, Icon

Choice

A Choice can be used to select multiple fixed options with a drop down menu

ID Description
ID The ID for the element (used as key in the state var .
Enabled Whether to allow user input for the element
InitValue The initial value for the UI element
UseInitValue Whether to initialise the state object with the init value
Text The label next to the Choice
Help The markdown content that will be shown when you click on the help button
Tooltip The tooltip that will be applied when hovering the element
EmptyText A text that will be displayed if nothing is selected
Items A string with one item per line
Custom If ticked, then you can use the markdown syntax to create complex popup menu configurations.
ValueMode Defines how to store the value in the data object (either as text, integer index or one-based integer ID
Options : Text, Index, ID

CodeEditor

ID Description

ColourChooser

A colour chooser that will store the colour as 0xAARRGGBB value into the data object.

ID Description
ID The ID for the element (used as key in the state var .
Enabled Whether to allow user input for the element
InitValue The initial value for the UI element
UseInitValue Whether to initialise the state object with the init value
Text The label next to the ColourChooser
Help The markdown content that will be shown when you click on the help button
Tooltip The tooltip that will be applied when hovering the element

FileSelector

Select a file using a native file browser or text input.

ID Description
ID The ID for the element (used as key in the state var .
Enabled Whether to allow user input for the element
InitValue The initial value for the UI element
UseInitValue Whether to initialise the state object with the init value
Text The label next to the FileSelector
Help The markdown content that will be shown when you click on the help button
Tooltip The tooltip that will be applied when hovering the element
Directory Whether the file selector should be able to select directories vs. files.
Wildcard The file wildcard for filtering selectable files
SaveFile Whether the selected file will be opened or saved.
Required Whether a file / directory must be selected

Table

A component with fix columns and a dynamic amount of rows

ID Description
ID The ID for the element (used as key in the state var .
Columns The list of columns - one per line using a pseudo CSS syntax for name , max-width , min-width and width properties.
Items The list of rows - one per line using comma for separating cells
ValueMode How the table stores the selected item (either the zero based index of the selected row or the [column, row] position of the clicked cell
Options : Row, Grid, FirstColumnText
Multiline Allows selection of multiple rows / cells
FilterFunction A function in the root namespace that will be called to filter the items.
Class The CSS class that is applied to the UI element.
Style Additional inline properties that will be used by the UI element

TagList

A dynamic list of clickable tags.

ID Description
ID The ID for the element (used as key in the state var .
Items The list of tags - one per line
Class The CSS class that is applied to the UI element.
Style Additional inline properties that will be used by the UI element

TextInput

A TextInput lets you enter a String

ID Description
ID The ID for the element (used as key in the state var .
Enabled Whether to allow user input for the element
InitValue The initial value for the UI element
UseInitValue Whether to initialise the state object with the init value
Text The label next to the TextInput
Help The markdown content that will be shown when you click on the help button
Tooltip The tooltip that will be applied when hovering the element
EmptyText The text to show when the text field is empty.
Required If this is enabled, the text input must be a non-empty String
ParseArray If this is enabled, the text input will parse comma separated values as Array.
Multiline If this is enabled, the text editor will allow multiline editing
Autofocus If this is enabled, the text editor will gain the focus when the page is loaded
Height The height (in pixels) for the editor (if used in multiline mode).
Items A string with one item per line that will show up in the autocomplete popup.
CallOnTyping Enables the value change callback for every key input (instea of when pressing return

Actions

The elements in this category will perform an action when triggered. There are two subtypes of actions:

  1. Synchronous actions which do not take a long time and are executed immediately (like writing a short text file to disk)
  2. Asynchronous actions which will perform a heavyweight operation and are deferred to a background thread which are then executed in a queue.

AppDataFileWriter

Writes a string to a file from the app data folder.

This takes the global property UseGlobalAppDataFolder into account so make sure that this aligns with your project settings!

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Target The target file. Select one of the available file types and it will resolve correctly on macOS / Windows / Linux.
Options : LinkFile, LicenseFile

CommandLineTask

An action element that launches a child process and executes a terminal command.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
Code The terminal command that should be executed.

CopyAsset

An action element that will copy an embedded file to a given location.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
Source The source of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
Target The target of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
Overwrite Whether the file should overwrite the existing file or not

CopySiblingFile

An action element that will copy an embedded file to a given location.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
Options : systemID, currentTime,
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
Source The source of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
Target The target of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
Overwrite Whether the file should overwrite the existing file or not

DownloadTask

An action element that will download a file from a URL.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
Source The source of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
Target The target of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
ExtraHeaders The URL to the file that you want to download.
UsePost Whether to use a POST or GET request for the download

DummyWait

An action element that simulates a background task with a progress bar. You can use that during development to simulate the UX before implementing the actual logic.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
NumTodo The number of iterations that this action is simulating.
FailIndex The index of the iteration that should cause a failure. If zero or bigger then NumTodo, then the operation succeeds.
WaitTime The duration in milliseconds between each iteration. This makes the duration of the entire task WaitTime * NumTodo

HlacDecoder

An action element that will extract a HR1 archive to the specified target directory.

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
UseTotalProgress Whether to display the total progress or the progress for each ch1 file in the progress bar.
Source The source of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
Target The target of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
SupportFullDynamics Whether to support the HLAC Full Dynamics mode.

HttpRequest

An action element that will perform a HTTP request.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
Source The source URL (without parameters).
Parameters The URL parameters as JSON object
ExtraHeaders The extra headers that are supplied with the HTTP request.
UsePost Whether to use a POST or GET request.
ParseJSON Whether to parse the server response as JSON or interpret it as raw string
Code The extra headers that are supplied with the HTTP request.

JavascriptFunction

An action element that will perform a block of Javascript code. You can read / write data from the global state using the state.variableName syntax.

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,

LambdaTask

An action element that will perform a customizable task.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
Function The full function class name (Class::functionName ) that will be used as lambda

Launch

Shows either a file in the OS file browser or opens an internet browser to load a URL

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The target to be launched. If this is a URL, it will launch the internet browser, if it's a file, it will open the file
Args Additional (command-line) arguments. If this is not empty, the string will be passed as argument

Skip

An action element that simply skips the page that contains this element. This can be used in order to skip a page with a branch (eg. if one of the options doesn't require additional information.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
Options : company, product, version,
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,

UnzipTask

An action element that will download a file from a URL.)

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
Options : company, product, version,
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Text The label text that will be shown next to the progress bar.
Source The source of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
Target The target of the operation. Can be an URL, an absolute path or a variable ID that holds an absolute path / URL
Overwrite Whether to use overwrite existing files or not
Cleanup Whether to remove the archive after it was extracted successfully
SkipFirstFolder Whether to skip the first folder hierarchy in the source archive.
 This is useful if your archive has all files in a subdirectory and you want to extract the archive directly to the specified target.
SkipIfNoSource Whether to silently skip the extraction process or throw an error message if the source doesn't exist. Use this option if you conditionally download the archive before extracting.

Constants

CopyProtection

ID Description

DirectoryScanner

An action object that loads & stores values to a settings file

ID Description
ID The ID for the directory list. This will store an array of filenames in the global state
Source The source for the root directory
RelativePath Whether to store the full path or just the filename
Wildcard A wildcard filter for the file scanner
Directory Whether to look for child files or child directories

FileLogger

Adding this will start logging any events to a customizable file location so you can track the process

ID Description
Filename The target name. This can be a combination of a state variable and a child path, eg. $targetDirectory/Logfile.txt

OperatingSystem

ID Description

PersistentSettings

An action object that loads & stores values to a settings file

ID Description
ID The ID of the constant. This will be used as tag name of the root element of the file.
Filename The filename of the setting file. This should only be the filename without path or file extension
UseProject Whether to use the project name as subdirectory (APPDATA/Company/Project vs. APPDATA/Company/ ));
ParseJSON Whether to use JSON or XML for the file
UseChildState Whether to store the settings as root properties or as child element with a single value property (only used in XML format
Items A list of default values that are used for the setting. One line per item with the syntax key:value .

PluginDirectories

ID Description

ProjectInfo

ID Description

RelativeFileLoader

Writes the absolute path of a relative file reference into the state object

ID Description
ID The ID of the action. This will determine whether the action is tied to a global state value. If not empty, the action will only be performed if the value is not zero.
Options : company, product, version,
EventTrigger The event that will trigger the action
Options : OnPageLoad , OnPageLoadAsync , OnSubmit , OnCall ,
Required whether the file / directory must exist in order to continue.
SpecialLocation The special location type (stolen from the JUCE enum) for the root directory
Options : userHomeDirectory, userDocumentsDirectory, userDesktopDirectory, userMusicDirectory, userMoviesDirectory, userPicturesDirectory, userApplicationDataDirectory, commonApplicationDataDirectory, commonDocumentsDirectory, tempDirectory, currentExecutableFile, currentApplicationFile, invokedExecutableFile, hostApplicationPath, windowsSystemDirectory, globalApplicationsDirectory, parentDirectory
RelativePath An (optional) subpath that will be applied to the file path
Join Discussion Next: RNBO Import

Christoph Hart
23.06.2024