HelloPlugins.cpp

This tutorial teaches you the basics of developing plugins for MT Showcase. It adds a simple new widget with a single editable attribute to Showcase.

Screenshot of the HelloPlugins widget

We will create a new custom widget and add it as a component to Showcase. First include the necessary header files. This will be a widget component, so include Showcase::WidgetComponent. We'll use TextWidget from Cornerstone as the base of our new widget, so include TextWidget as well:

#include <Showcase/WidgetComponent.hpp>

#include <MultiWidgets/TextWidget.hpp>

Then create a new widget class by inheriting from TextWidget. For this example we'll just set a custom CSS class for this widget so we can customize its look.

class HelloPluginsWidget : public MultiWidgets::TextWidget
{
public:
  HelloPluginsWidget()
  {
    addCSSClass("hello-plugins");
  }
};

We use the convenient SHOWCASE_WIDGET_COMPONENT macro to define this widget as a widget component in Showcase. It will use the basic Showcase::WidgetComponent as the component class, and Showcase::WidgetInstance as the instance class. When an instance of this component is created, it will create a HelloPluginsWidget as its widget. This component can be referenced with component name hello-plugins.

SHOWCASE_WIDGET_COMPONENT("hello-plugins", HelloPluginsWidget)

Next we create the HelloPlugins package. Create a directory package under the HelloPlugins directory. We want to apply some custom CSS, so create a data folder, and add a hello-plugins.css file under it. Define the default text and looks for the new widget:

.hello-plugins {
  text: "Hello world!";
  size: 250px 150px;
  text-align: center;

  background: #02132dB0;
  border: 5px solid #23427080;
}

We can also add a screenshot and description to be displayed in the Editor for this component. So add a description.html and hello-plugins.png in the package directory.

Description.html:

<img src="operator-example.png" />

<p>This is an example of an MT Showcase plugin operator. The operator can be
added to a standard Showcase content widget, such as an Image viewer. When a
user drags the host widget so it collides with an Image viewer, an image popup
is displayed.</p>

Next we define our component. Create a hello-plugins.schema file under the package directory. We will allow adding this widget in the main layer in a Showcase structure, so add the role main to it. We will also want to make the text editable. We inherited from TextWidget, which has an attribute text that controls the text the widget displays. We will expose this attribute in the Editor by defining the attribute in the schema. Note that widgets have several attributes by default, but only attributes defined in the schema are visible and editable in the Editor. You can add your own attributes to your widgets, but for this example we just use the default TextWidget attributes.

{
  "roles" : [ "main" ],

  "attributes" : [
    {
      "attribute-name": "text",
      "type": "string",
      "ui-name": "Displayed text",
      "default" : "Hello world!",
      "description": "This is an example attribute. The text defined here will be displayed in a text box in the app."
    }
  ]
}

Finally we create a package file that ties everything together, call it hello-plugins.package. We define a name and version for our package, and the single component it adds. We leave required Showcase version as SHOWCASE_VERSION for convenience, so it will work with any version of Showcase without updating the package file. Note that the plugin must still be recompiled when Showcase is updated.

{
  "name" : "Hello plugins",
  "package-version" : "1.0.0",
  "libraries" : [ "HelloPlugins-SHOWCASE_VERSION" ],
  "required-showcase-version" : "SHOWCASE_VERSION",
  "components" : {
    "hello-plugins" : {
      "type" : "ui",
      "data-folders" : [ "data" ],
      "css-files" : [ "hello-plugins.css" ],
      "schema" : "hello-plugins.schema",
      "description" : "description.html",
      "ui-name" : "Hello plugins"
    }
  }
}

Add the compiled library under the package directory as well. The final structure of the package directory is

package/
├── data
│   └── hello-plugins.css
├── hello-plugins.package
├── hello-plugins.schema
├── description.html
├── hello-plugins.png
└── libHelloPlugins-[version].so

Full source code of HelloPlugins.cpp:

#include <Showcase/WidgetComponent.hpp>

#include <MultiWidgets/TextWidget.hpp>

namespace ShowcaseExamples {
class HelloPluginsWidget : public MultiWidgets::TextWidget
{
public:
  HelloPluginsWidget()
  {
    addCSSClass("hello-plugins");
  }
};

SHOWCASE_WIDGET_COMPONENT("hello-plugins", HelloPluginsWidget)
}