ScriptedViewport
Create a reference to a Viewport UI component and modify its values.
const var Viewport1 = Content.getComponent("Viewport1");
Class methods
addToMacroControl
Adds the knob / button to a macro controller (from 0 to 7). Edit on GitHub
ScriptedViewport.addToMacroControl(int macroIndex)
changed
Call this to indicate that the value has changed (the onControl callback will be executed. Edit on GitHub
ScriptedViewport.changed()
createLocalLookAndFeel
Returns a local look and feel if it was registered before. Edit on GitHub
ScriptedViewport.createLocalLookAndFeel(ScriptContentComponent *contentComponent, Component *componentToRegister)
fadeComponent
Toggles the visibility and fades a component using the global animator. Edit on GitHub
ScriptedViewport.fadeComponent(bool shouldBeVisible, int milliseconds)
get
returns the value of the property. Edit on GitHub
ScriptedViewport.get(String propertyName)
getAllProperties
Returns a list of all property IDs as array. Edit on GitHub
ScriptedViewport.getAllProperties()
getChildComponents
Returns list of component's children Edit on GitHub
ScriptedViewport.getChildComponents()
getGlobalPositionX
Returns the absolute x-position relative to the interface. Edit on GitHub
ScriptedViewport.getGlobalPositionX()
getGlobalPositionY
Returns the absolute y-position relative to the interface. Edit on GitHub
ScriptedViewport.getGlobalPositionY()
getHeight
Returns the height of the component. Edit on GitHub
ScriptedViewport.getHeight()
getId
Returns the ID of the component. Edit on GitHub
ScriptedViewport.getId()
getLocalBounds
Returns a [x, y, w, h] array that was reduced by the given amount. Edit on GitHub
ScriptedViewport.getLocalBounds(float reduceAmount)
getOriginalRowIndex
Returns the index of the original data passed into setTableRowData. Edit on GitHub
ScriptedViewport.getOriginalRowIndex(int rowIndex)
getValue
Returns the current value. Edit on GitHub
ScriptedViewport.getValue()
getValueNormalized
Returns the normalized value. Edit on GitHub
ScriptedViewport.getValueNormalized()
getWidth
Returns the width of the component. Edit on GitHub
ScriptedViewport.getWidth()
grabFocus
Call this method in order to grab the keyboard focus for this component. Edit on GitHub
ScriptedViewport.grabFocus()
loseFocus
Call this method in order to give away the focus for this component. Edit on GitHub
ScriptedViewport.loseFocus()
sendRepaintMessage
Manually sends a repaint message for the component. Edit on GitHub
ScriptedViewport.sendRepaintMessage()
set
Sets the property. Edit on GitHub
ScriptedViewport.set(String propertyName, var value)
setColour
sets the colour of the component (BG, IT1, IT2, TXT). Edit on GitHub
ScriptedViewport.setColour(int colourId, int colourAs32bitHex)
setConsumedKeyPresses
Registers a selection of key presses to be consumed by this component. Edit on GitHub
ScriptedViewport.setConsumedKeyPresses(var listOfKeys)
setControlCallback
Pass a inline function for a custom callback event. Edit on GitHub
ScriptedViewport.setControlCallback(var controlFunction)
setEventTypesForValueCallback
Specify the event types that should trigger a setValue() callback.
ScriptedViewport.setEventTypesForValueCallback(var eventTypeList)
If you want the table to store the current selection in its value slot (for saving & restoring), you can supply a list of event types that trigger a call to setValue()
. The parameter must be a array of strings from this list:
["Selection", "SingleClick", "DoubleClick", "ReturnKey" ]
The value that is stored is either the row index (starting with 0) or if you're in multi-column mode, an array with the data [columnIndex, rowIndex]
(again, zero-based).
Be aware that using this method will also make the table use the undo manager if the useUndoManager
flag is set.
Note that if you have assigned a callback to the table with setTableCallback
, the JSON object of the callback will have set the type to SetValue
or Undo
if you call setValue()
or Engine.undo()
, so you should handle those cases gracefully in your callback too.
setKeyPressCallback
Adds a callback to react on key presses (when this component is focused). Edit on GitHub
ScriptedViewport.setKeyPressCallback(var keyboardFunction)
setLocalLookAndFeel
Attaches the local look and feel to this component. Edit on GitHub
ScriptedViewport.setLocalLookAndFeel(var lafObject)
setPosition
Sets the position of the component. Edit on GitHub
ScriptedViewport.setPosition(int x, int y, int w, int h)
setPropertiesFromJSON
Restores all properties from a JSON object. Edit on GitHub
ScriptedViewport.setPropertiesFromJSON( var jsonData)
setStyleSheetClass
Sets the given class selectors for the component stylesheet. Edit on GitHub
ScriptedViewport.setStyleSheetClass( String classIds)
setStyleSheetProperty
Sets a variable for this component that can be queried from a style sheet. Edit on GitHub
ScriptedViewport.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
ScriptedViewport.setStyleSheetPseudoState( String pseudoState)
setTableCallback
Set a function that is notified for all user interaction with the table.
ScriptedViewport.setTableCallback(var callbackFunction)
You can assign a callback that will be executed whenever there is an user interaction with the table:
- selection changes (using keyboard or mouse clicks)
- click / double click on cells
- deleting a row (pressing delete when one or multiple rows are selected)
- slider drag
- button click
The parameter you pass in must be a function with a single parameter, which will hold a JSON object with the callback data. It will have these properties:
Property | Type | Description |
Type | String | A string indicating the callback type. This can be one of these values: "Slider"
, "Button"
, "Selection"
, "Click"
, "DoubleClick"
, "ReturnKey"
, "DeleteRow"
|
rowIndex | int | the (zero-based) row index |
columnID | String | the ID of the column as defined with the setColumnData function. |
value | number or object | Depending on the callback type, this is either the value of the UI element (slider or button) or the entire row data for the other event types. |
setTableColumns
Define the columns of the table. This can only be done in the onInit callback.
ScriptedViewport.setTableColumns(var columnMetadata)
This method can be used to define the column layout of the table. It expects a single argument with a list of JSON objects for every column you want to add to your table. This function must be called after setting the table metadata and before populating the table with row data.
Property | Type | Description |
ID | String | A unique ID for each column. |
Type | String | Defines the UI element for the given column. This can be either "Text"
, "Button"
, "Slider"
or "ComboBox"
. |
Label | String | A string that is used for the column header. If this is undefined, the ID property will be used instead. |
Focus | bool | If MultiColumnMode is enabled, this will control whether a left / right key press will focus this cell. Set to false if you want to skip that column (default is true). |
Visible | bool | By default all columns are visible, but you can hide a column in order to use the ID as hidden metadata. |
MinWidth | int | the minimum size of the column. |
MaxWidth | int | the maximum width of the column. -1 for auto-fit |
Width | int | the standard width of the column. If undefined, it will use the minimum width. |
Sliders
If the column should be a slider you will have these additional properties:
Property | Type | Description |
MinValue | double | the minimum value. |
MaxValue | double | the maximum value. |
SkewFactor | double | the skew factor. |
StepSize | double | the step size. |
You can override the default look and feel of the slider with the "drawLinearSlider" method.
Buttons
If the column should display a button, you can use these additional properties:
Property | Type | Description |
Toggle | bool | whether the button is momentary or has a toggle state. |
Text | String | The text to show on the display. |
You can override the default look and feel of the button with the "drawToggleButton" method.
Comboboxes
If the columns should display a Combobox, you can use these additional properties:
Property | Type | Description |
items | Array | The list of items you want to show |
ValueMode | String | defines how the value is supposed to be interpreted. |
Value | var | defines the default value of the combobox. The format of the value is defined by the ValueMode property |
Text | String | The text to show when nothing is selected. |
The ValueMode
property defines how the value is supposed to be interpreted. There are three options:
- "ID" uses a one-based integer (so the first value is 1). This is how the combobox in HISE works and is the default
- "Index" uses a zero-based integer (so the first value is 0).
- "Text" expects a string as value and searches the items to set it to the respective entry
The properties Value
and items
are dynamic, which means that you can pass in a JSON object into setTableRowData() to define different item lists for different rows:
const var ModTable = Content.getComponent("Viewport1");
ModTable.setTableMode({
"MultiColumnMode": false,
"HeaderHeight": 32,
"RowHeight": 32,
"ScrollOnDrag": false
});
ModTable.setTableRowData([
{
"Source": "Source",
"Mode":
{
"items": ["Yes", "No", "Maybe"],
"Value": "No"
}
},
{
"Source": "Other Source",
"Mode":
{
"items": ["Some other item", "Second"],
"Value": "Second"
}
}]);
ModTable.setTableColumns([
{
"ID": "Source",
"Type": "Text",
"MinWidth": 150
},
{
"ID": "Mode",
"Type": "ComboBox",
"MinWidth": 80,
"Toggle": true,
"Text": "Default",
"ValueMode": "Text"
}
]);
You can override the default look and feel of the combobox with the "drawComboBox" method.
setTableMode
Turns this viewport into a table with the given metadata. This can only be done in the onInit callback.
ScriptedViewport.setTableMode(var tableMetadata)
Calling this function will turn this Viewport into a table with multiple columns and dynamic row data. The function expects a JSON object as single argument which contains some metadata properties that define the appearance and behaviour of the table.
Property | Type | Description |
MultiColumnMode | bool | If enabled, the table will treat each column as individual data entity (see above for a detailed explanation of this mode). |
HeaderHeight | int | The height of the column header. If this is 0, it will be hidden. |
RowHeight | int | the height of each row. |
MultiSelection | bool | if enabled, this allows selection of multiple rows at once. |
ScrollOnDrag | bool | if enabled, dragging the mouse will scroll the viewport (like on a web browser). If disabled, you'll need to use the scrollbars. |
SliderRangeIdSet | String | if you're using sliders in a cell, you can define which ID set is used to fetch the range limits. This is useful if you're displaying JSON data with a fixed format (eg. the output of Midiautomationhandler.getAutomationDataObject()
). The possible values are "scriptnode"
, "ScriptComponent"
, "MidiAutomation"
and "MidiAutomationFull"
(check the console output for a list of range ids that is used when you call this method with this property). |
CallbackOnSliderDrag | bool | This controls whether the sliders in the table will send a update while dragging or just when you lift the mouse button. In some cases, you will need to skip the updates while dragging because it will spawn a heavyweight operation that you only want to perform once (eg. when setting the automation data from the JSON object). |
This function needs to be called before any other function related to tables. Also be aware that calling this function is only possible during the onInit callback.
Multi-column mode
If you set the MultiColumnMode
property to true, it will cause repaints whenever you hover over cells. This can be useful if you want to arrange your data in a 2D space (eg. if you're creating a browser that displays multiple files in a row). You can also use setValue()
with a [columnIndex, rowIndex]
array to set the active cell programatically (and if the viewport has the saveInPreset
flag, it will cause a callback when you load user presets).
In this mode, the viewport will also support horizontal navigation with the left-right arrow keys and it will fire the table callback whenever a cell has changed.
Please be aware that the default appearance will still highlight the entire row, so you need to customize the drawTableCell
function with a LAF object. In this callback, the selected
property will stil be true for the entire row, but you can use the clicked
and hover
property to figure out which cell is active / hovered.
setTableRowData
Update the row data for the table.
ScriptedViewport.setTableRowData(var tableData)
If you have setup this Viewport as a table, you can use this method in order to populate the rows of the table.
The argument must be a list of JSON objects, which must define a value for every column ID:
- Button columns must be true or false
- Slider columns must be a number
- Text columns must be a string
The data you pass in will not be copied, so if you modify the data, it will update the table content.
Also dragging the slider or clicking the button in a column will update the values in this object (so you don't have to do this manually in the table callback).
setTableSortFunction
Sets a custom function that can be used in order to sort the table if the user clicks on a column header. Edit on GitHub
ScriptedViewport.setTableSortFunction(var sortFunction)
setTooltip
Shows a informative text on mouse hover. Edit on GitHub
ScriptedViewport.setTooltip( String tooltip)
setValueNormalized
Sets the current value from a range 0.0 ... 1.0. Edit on GitHub
ScriptedViewport.setValueNormalized(double normalizedValue)
setValueWithUndo
Sets the current value and adds it to the undo list. Don't call this from onControl! Edit on GitHub
ScriptedViewport.setValueWithUndo(var newValue)
setZLevel
Changes the depth hierarchy (z-axis) of sibling components (Back, Default, Front or AlwaysOnTop). Edit on GitHub
ScriptedViewport.setZLevel(String zLevel)
showControl
Hides / Shows the control. Edit on GitHub
ScriptedViewport.showControl(bool shouldBeVisible)
updateContentPropertyInternal
This updates the internal content data object from the script processor. Edit on GitHub
ScriptedViewport.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
ScriptedViewport.updateValueFromProcessorConnection()