This section summarizes all API methods for creating your own macros. For more details you may take a look at the files macrobase.h and macroextended.h.
The API is separated in the following groups:
Macro setup
All methods in this section must be called in the macro’s constructor. They are used to define a macro’s properties and its interface to Impresario.
void setName |
( |
const std::wstring & |
strName ) |
| |
Sets the macro's display name in Impresario. This method has to be called once in the macro's constructor.
- Parameters:
-
| strName |
Display name of the macro in Impresario |
- Since API Version: 1.0.0
- See also:
- Setting up macro information
|
void setGroup |
( |
const std::wstring & |
strGroup ) |
| |
Sets the macro's group. The group is used in Impresario's group filter in the macro selection window. This method has to be called once in the macro's constructor to assign the macro a group.
- Parameters:
-
| strGroup |
Group the macro should belong to. The group name is case sensitive. |
- Since API Version: 1.0.0
- See also:
- Setting up macro information
|
void setCreator |
( |
const std::wstring & |
strCreator ) |
| |
Sets the name of the programmer who created the macro. This name is used in Impresario's creator filter in the macro selection window. This method has to be called once in the macro's constructor to assign the macro a creator.
- Parameters:
-
| strCreator |
Name of the programmer who created the macro. The name is case sensitive. |
- Since API Version: 1.0.0
- See also:
- Setting up macro information
|
void setDescription |
( |
const std::wstring & |
strDescription ) |
| |
Sets the macro's description. The description is displayed beneath Impresario's macro selection window if help is switched on. This method has to be called once in the macro's constructor to assign the macro a short description.
- Parameters:
-
| strDescription |
Short description of the macro. |
- Since API Version: 1.0.0
- See also:
- Setting up macro information
|
void setPropertyWidgetComponent |
( |
const std::wstring & |
strPropWidgetFile ) |
| |
This method allows to override Impresario's default QML widget for dislaying and changing parameters. If you have your own widget for your macro
you need to call this method in the macro's constructor.
- Parameters:
-
| strPropWidgetFile |
File name of the QML component to be used as alternative display for parameters of this macro. |
- Since API Version: 1.0.0
- See also:
- Advanced parameter presentation
|
template<typename T> |
bool addInput |
( |
const std::wstring & |
name, |
|
|
const std::wstring & |
description ) |
| |
Adds an input port of type T to the macro. For type T any type may be used. This method must be called
in the macro's constructor once for each input port to be declared.
- Parameters:
-
| name |
Name of the input port. This name must not be empty. |
| description |
Description of the input port. |
- Returns:
-
true if the input port was added successfully, false otherwise.
- Since API Version: 1.0.0
- See also:
- Setting up macro input and output ports
|
template<typename T> |
bool addOutput |
( |
const std::wstring & |
name, |
|
|
const std::wstring & |
description ) |
| |
Adds an output port of type T to the macro. For type T any type may be used. This method must be called
in the macro's constructor once for each output port to be declared.
- Parameters:
-
| name |
Name of the output port. This name must not be empty. |
| description |
Description of the output port. |
- Returns:
-
true if the output port was added successfully, false otherwise.
- Since API Version: 1.0.0
- See also:
- Setting up macro input and output ports
|
template<typename T> |
bool addParameter |
( |
const std::wstring & |
name, |
|
|
const std::wstring & |
description, |
|
|
const T & |
tDefaultValue, |
|
|
const std::wstring & |
qmlUIComponent = L"", |
|
|
const std::wstring & |
qmlUIProperties = L"", |
|
|
const ParameterValueConverter<T> & |
converter = ParameterValueConverter<T>() ) |
| |
Adds a parameter to the macro. This method must be
called in the macro's constructor once for each
parameter to be declared. Parameters appear in the
macro's property window in the order they are declared
in the constructor.
- Parameters:
-
| name |
Name of the parameter. The name must not be empty. |
| description |
Description of the parameter's meaning.
This discription is displayed beneath the macro
property window if help is switched on. |
|
tDefaultValue |
Default value for the parameter. |
| qmlUIComponent |
Name (i.e. file name) of the QML component to be used to display and change the parameter in Impresario's
property window. By default a simple line edit component will be used. |
| qmlUIProperties |
String holding default properties for the QML component defined in the previous parameter. |
| converter |
ParameterValueConverter instance used to convert the parameter's value to and from std::wstring.
Usually the default converter handles all simple data types sufficiently. For complex types a specialized converter has to be provided. |
- Returns:
-
true if the parameter was added successfully, false otherwise.
- Since API Version: 1.0.0
- See also:
- Setting up macro parameters
|
Overridables
The following methods need to overridden in a macro class. These methods are called by Impresario.
virtual MacroBase* clone ( ) |
| |
Called by Impresario every time the macro is added to a process graph. This method always has to be overriden otherwise the macro cannot
be used in Impresario. The base implementation just returns nullptr.
- Returns:
-
A pointer to a new created instance of the macro class.
- Since API Version: 1.0.0 - Obsolete since API Version: 1.0.1
|
virtual Status onInit ( ) |
| |
Called by Impresario as the first event before processing starts. Override this method if you need special one time preparation
for processing in the onApply() method. The base implementation just returns Ok.
- Returns:
-
Return
Ok to indicate Impresario to continue processing.
Return Error to terminate processing with an error message immediately.
- Since API Version: 1.0.0
- See also:
- Processing data
|
virtual Status onApply ( ) |
| |
Called by Impresario for every new set of input data during processing. Override this method to process data at the input ports.
The base implementation just returns Ok.
- Returns:
-
Return
Ok to indicate Impresario to continue processing.
Return Error to terminate processing with an error message immediately.
Return Stop to indicate Impresario to stop processing.
- Since API Version: 1.0.0
- See also:
- Processing data
|
virtual Status onExit ( ) |
| |
Called by Impresario after processing has been stopped by the user, by a macro, or by an error. Override this method if you need
special clean up after processing. The base implementation just returns Ok.
- Returns:
-
Return
Ok to indicate Impresario success.
Return Error to indicate Impresario an error.
- Since API Version: 1.0.0
- See also:
- Processing data
|
virtual void onParametersChanged |
( |
ParameterSet & |
parameters ) |
| |
Called by Impresario before the calls to onInit(), onApply(), and onExit().
Before the call to onInit() all parameters are reported as changed to allow for proper initialization. In further calls only
parameters are reported which have been changed since the last time.
Override this method the be notified of every parameter change. The base implementation does nothing.
- Parameters:
-
| parameters |
std::set<unsigned int> with zero-based indices of all parameters which have been changed in the meantime. |
- Since API Version: 1.0.0
- See also:
- Processing data
|
Access methods
Access methods provide access to inputs, outputs, and parameters in the overridden methods onInit(), onApply(),
onExit(),and onParametersChanged() and must be called only there.
template<typename T> |
const T* accessInput |
( |
std::size_t |
index ) |
| |
Access data of an input port.
- Parameters:
-
| index |
Zero based index of the input to be accessed. Inputs are sorted in the same order as declared in the macro's constructor
with calls to addInput. |
- Returns:
-
Pointer to a constant object of type
T or nullptr in case
the input is not connected in Impresario's process graph.
- Since API Version: 1.0.0
- See also:
- Processing data
|
template<typename T> |
T& accessOutput |
( |
std::size_t |
index ) |
| |
Access data of an output port.
- Parameters:
-
| index |
Zero based index of the output to be accessed. Outputs are sorted in the same order as declared in the macro's constructor
with calls to addOutput. |
- Returns:
-
Writable reference to an object of type
T.
- Since API Version: 1.0.0
- See also:
- Processing data
|
template<typename T> |
const T& getParameterValue |
( |
std::size_t |
index ) |
| |
Access current value of a parameter with the given index.
- Parameters:
-
| index |
Zero based index of the parameter to be accessed. Parameters are sorted in the same order as declared in the macro's constructor
with calls to addParameter. |
- Returns:
-
Read-only reference to an object of type
T containing the parameter's current value.
- Since API Version: 1.0.0
- See also:
- Processing data
|
template<typename T> |
void setParameterValue |
( |
std::size_t |
index, |
const T & |
value ) |
| |
Sets the parameter of the given index to the new value.
- Parameters:
-
| index |
Zero based index of the parameter to be accessed. Parameters are sorted in the same order as declared in the macro's constructor
with calls to addParameter. |
| value |
New value for parameter. |
- Since API Version: 1.0.0
- See also:
- Processing data
|
Miscellaneous
The following methods are available for providing more information.
void setErrorMsg |
( |
const std::wstring & |
strErrorMsg ) |
| |
Can be used to set an error message which is read by Impresario in case one of the overridden methods onInit(),
onApply(), and onExit() return Error. Otherwise this message won't be displayed.
- Parameters:
-
| strErrorMsg |
Error message to be displayed in Impresario. |
- Since API Version: 1.0.0
- See also:
- Processing data
|