Vuo  0.9.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Developing an Input Editor

In the Vuo Editor, a user can edit the value of certain types of input ports by double-clicking on the port's constant flag, then using the widget that pops up. This widget is called an input editor. For example, the user can double-click on a VuoText input port to pop up a text box, or a VuoBoolean input port to pop up a menu, or a VuoInteger input port to pop up a spin box or slider. If a port type doesn't already have an input editor, you can create one.

When input editors are created for you

For a port type whose underlying data type is an enum, Vuo automatically provides a menu input editor. The menu items are constructed by calling MyType_allowedValues() and MyType_summaryFromValue().

If your port type is not an enum, or if you'd like to override the default input editor for an enum type, you can implement a custom input editor. Read on for details.

Quick start

The easiest way to start developing an input editor is with the example Qt project provided with the Vuo SDK. This example project includes a port type, an input editor for the port type, and a node class that demonstrates the input editor.

First, be able to build the example project as-is:

  1. Install Qt and Qt Creator.
  2. Make a copy of the example Qt project for an input editor (example/type/menuInputEditor).
  3. Open the project in Qt Creator.
  4. Set VUO_FRAMEWORK_PATH and QT_ROOT to the correct paths for your system.
  5. Build your Qt project (Build > Build All).

The next time you start Vuo Editor, the example.greet node class should appear in the Node Library, and the node's language input port should have a menu input editor that lets you select a language.

To create your own input editor based on the example project:

  1. Create Qt project(s) for your node classes and port types (see Developing a Node Class and Developing a Port Type).
  2. Modify as indicated by the comments in that file.
  3. Remove example.greet.c, ExampleLanguage.h, and ExampleLanguage.c.
  4. In all project file names and contents, replace ExampleLanguage with the name of your port type (e.g. MyType).
  5. In, change the implementation of MyTypeInputEditor::setUpMenuTree() to use your port type.

Writing an input editor

An input editor is a Qt plugin that implements the plugin interface defined by the VuoInputEditorFactory class. To do this, you need to implement a derived class of VuoInputEditorFactory and a derived class of VuoInputEditor.

You can either derive from the VuoInputEditor class directly, or you can derive one of the classes provided in the Vuo SDK (framework/resources/inputEditorWidgets) for your convenience:

In addition to the derived classes, the input editor needs a JSON-formatted metadata file containing the name of the port type that this input editor can edit. For an example of the correct format, see ExampleLanguageInputEditor.json in the example Qt project.

Building an input editor

Since the Vuo Editor loads its input editor plugins at runtime, you need to build your input editor to a dynamic library.

Typically, you'll want to do this by building the input editor with a Qt project that uses CONFIG += plugin in its .pro file. For an example, see the example Qt project (example/type/menuInputEditor).

Installing an input editor

Since the Vuo Editor looks for input editor plugins in ~/Library/Application Support/Vuo/Modules/ and /Library/Application Support/Vuo/Modules/, you need to place your built input editor in one of these folders. For more information about these folders, see the Vuo Manual.

If you're using the example Qt project, then when you build the project, the compiled port type is automatically placed in ~/Library/Application Support/Vuo/Modules/.

Otherwise, you need to manually move the built input editor (.dylib) file to one of these folders.

After that, the next time you start the Vuo Editor, your input editor should pop up when you double-click on any input port of that port type.

Allowing a port to customize its input editor

Some input editors allow a port to specify how the input editor will be displayed. For example, the VuoInputEditorInteger input editor allows a VuoInteger port to specify a minimum value, maximum value, and step size for its slider widget. If either the minimum or maximum is unspecified, the VuoInputEditorInteger instead displays a spin box widget.

In the implementation of a node class, the VuoInputData macro's optional second argument is a JSON-formatted set of details about the port. These details are passed to the VuoInputEditor::show function's details argument. Your input editor can use these details in any way you want to control how the input editor will be displayed.

For example, the VuoInputEditorReal input editor uses JSON keys "suggestedMin", "suggestedMax", and "suggestedStep". A node class implementation can optionally use those keys when defining a VuoReal port, for example:

VuoInputData(VuoReal, {"default":0.0,"suggestedMin":0.0,"suggestedMax":1.0}) input