BlockDescriptionMarkup
Block description markup table of contents
The block description markup allows a user to specify a high level description of a block. The description documents functionality, parameters, and other information used by the GUI to render the block and configuration parameter window. Check out the descriptive examples below:
Inline markup can be specified inside a C++ source. The CMake function POTHOS_MODULE_UTIL will parse the sources to find markup, convert the markup to JSON, and build the JSON block documentation into the module to be retrieved at runtime.
/*********************************************************************** * |PothosDoc The Name of the Block * * A multi-line description of the block. * With more stuff on this line. * * And another paragraph can begin here. * * |category /My/Category * |keywords each word is searchable * * |param paramKey0[Parameter0 Name] A helpful description of parameter0. * The description may continue on to this line as well. * |default 0 * * |param paramKey1[Parameter1 Name] A helpful description of parameter1. * This parameter will not be visible in the GUI's graph editor page. * |preview disable * * |param paramKey2[Parameter2 Name] A helpful description of parameter2. * This parameter demonstrates enumerated options. * |option [Option 1] 1 * |option [Option 2] 2 * |default 1 * * |factory /path/in/the/block/registry(paramKey0, paramKey1) * |setter setParam1(paramKey1) * |setter setParam2(paramKey2) **********************************************************************/
When not specified, the entry widget for a given property will appear as a line entry widget in the block properties panel. This can be modified with the "widget" field in the parameter description.
* |widget ComboBox(editable=true) * |option [Option 1] 1 * |option [Option 2] 2
ComboBox widget (aka drop-down) displays an enumerated set of options. The list of options comes from the user provided option fields. If the user provides option fields, but does not specify the widget field, then the ComboBox() widget will be automatically chosen. Optional parameters: editable=true, or editable=false. When not specified editable is false. When editable is true, the ComboBox can be edited by the user to provide additional custom values.
* |widget SpinBox(minimum=–2147483648, maximum=2147483647)
SpinBox provides an integer entry widget with increment and decrement buttons. Optional parameters are minimum and maximum which impose a limit on possible integers entered into the widget. When not specified, the minimum and maximum use the full signed integer range.
* |widget DoubleSpinBox(minimum=-1e12, maximum=1e12, step=0.01, decimals=2)
DoubleSpinBox provides an floating-point entry widget with increment and decrement buttons. Optional parameters are minimum, maximum, step, and decimals. The minimum and maximum control the range, step controls the increment and decrement step size, and decimals controls the displayable precision of the floating-point number.
* |widget StringEntry()
The StringEntry widget allows the user to edit a string-type parameter without enclosing the contents in quotes. If the user enters bob, the actual value that gets passed into the evaluator is "bob".
* |widget FileEntry(mode=open)
The FileEntry widget allows the user to enter a string-type parameter that represents a file path. Like the StringEntry widget, the FileEntry entry widget deals with quotes without displaying them in the entry box. Also, the FileEntry widget provides a button that opens a file entry dialog to browse the file system for an "open" or "save" file path. Required parameters: mode=save or mode=open to control the type of file dialog.
* |widget LineEdit()
The LineEdit widget creates a single editable line which can contain any expression string. This is the default widget when the user does not specify the widget field or any options fields.
* |factory /path/in/the/block/registry(paramKey0, paramKey1) * |initializer setParam1(paramKey1) * |setter setParam2(paramKey2)
A method call on the block can either be an initializer or a setter.
- A initializer method can only be called once. Changing a parameter passed into an initializer would constitute a critical change, and the block must therefore be recreated from the factory, and then the initializer applied.
- A setter method can be called an arbitrary number of times. When a setter's parameter is changed, the block is not re-created, rather, only the setters that have changed parameters are called.
Many of the markup fields use special character tokens, like brackets, to separate out the sub-fields. To use a literal bracket in bracket-delineated field, simply escape the bracket with a backslash.
Example escaping a literal bracket:
* |option [Option \[1\]] 1 * |option [Option \[2\]] 2
The JSON markup is the intermediate format that stores all of the block description information in a highly structured manner suitable as input to the GUI.
{
"args" : [
"paramKey0",
"paramKey1",
],
"calls" : [
{
"args" : [
"paramKey1"
],
"name" : "setParam1",
"type" : "setter"
},
{
"args" : [
"paramKey2"
],
"name" : "setParam2",
"type" : "setter"
}
],
"categories" : [
"/My/Category"
],
"docs" : [
"A multi-line description of the block.",
"With more stuff on this line.",
"",
"And another paragraph can begin here."
],
"keywords" : [
"each",
"word",
"is",
"searchable"
],
"name" : "The Name of the Block",
"params" : [
{
"default" : "0",
"desc" : [
"A helpful description of parameter0.",
"The description may continue on to this line as well."
],
"key" : "paramKey0",
"name" : "Parameter0 Name"
},
{
"desc" : [
"A helpful description of parameter1.",
"This parameter will not be visible in the GUI's graph editor page."
],
"key" : "paramKey1",
"name" : "Parameter1 Name",
"preview" : "disable"
},
{
"default" : "1",
"desc" : [
"A helpful description of parameter2.",
"This parameter demonstrates enumerated options."
],
"key" : "paramKey2",
"name" : "Parameter2 Name",
"options" : [
{
"name" : "Option 1",
"value" : "1"
},
{
"name" : "Option 2",
"value" : "2"
}
]
},
],
"path" : "/path/in/the/block/registry"
}
