Component system

The basic building block of Showcase is a Showcase::Component.

Outside the small engine core, everything in Showcase is built of components, and nearly everything editable in the Editor is a component. You can create your own custom components and extend existing Showcase components with your own. For example you could create your own toolbar button and use it with the existing Showcase toolbar, or create a new menu bubble and use it with the regular Showcase finger menu. Or you can create a completely new toolbar and use it with any Showcase component that can have a toolbar attached to it!

There are different kinds of components, for example Video viewer is a widget component, and Email service is a service component.

Structure of a component

A component has a unique name and a schema that defines its properties. See Packages for more information on schema files. Components typically have attributes that affect their behaviour. Attributes are parameters that can be controlled through the Showcase Editor, internally attributes map to Cornerstone Node attributes. Components can also have slots where other components can be added as children.

Components added to a Showcase application form a graph. For example when you create a new Showcase structure, a new graph is created with a single node: the Showcase root component. The root component has slots that appear in the Editor as Overlay, Menu, Main and Background. When you add a widget to Main, it's added to the graph as a child of the root node and gains a node id that identifies this particular copy of the component. Where components can be added is controlled by the components' slots and roles. A component must have a role that matches a slot of another component to be added as a child to that component. You can access the root widget through Showcase::UserInterface.

When a component appears in a running Showcase application, a new Showcase::ComponentInstance of the component is created. For some components, for example all service components, there is typically a single instance of the component. For others there may be any number of instances alive at a time. For example if you have an application with a hotspot that opens a web browser, every time the hotspot is tapped a new instance of the web browser component is created. When a browser is closed, the matching instance is destroyed. Ui components like widget and operator components have a one-to-one correspondence from a widget or operator to component instance. So creating a widget instance also creates a widget, and the instance is alive as long as the widget is alive.

Component types

Widget component

Widget components make up the UI of a Showcase application. When a new instance of a widget component is created, a matching widget is added to the application. For example an Image viewer component creates an Image viewer widget.

When you create your own custom Cornerstone widget, you can add it as component to Showcase with the Showcase widget component macro, for example:

SHOWCASE_WIDGET_COMPONENT("hello-plugins", HelloPluginsWidget)

This way your component uses the standard Showcase::WidgetComponent and Showcase::WidgetInstance classes, and the instance creates your widget. In a similar fashion you can create a component from a Cornerstone plugin widget:

EXPORT_CORNERSTONE_PLUGIN("champagne", "cornerstone.champagne")

If you need more control over the component, you may want to create your own instance class. This grants you access to Showcase engine objects such as components and their instances. You can inherit from Showcase::WidgetInstance, and use this macro to use your instance with your widget:

SHOWCASE_CUSTOM_WIDGET_INSTANCE_COMPONENT("content-example-widget", ContentExampleWidget, ContentExampleWidgetInstance)

Typically users can move and scale widgets in Showcase, and need to pin the widget to interact with its contents, for example to flip through a PDF book. When a widget is pinned, it gets a special CSS class that disables motion. If your widget has advanced input handling, it may be a good idea to have a holder widget that can be moved or pinned, and a child widget that receives input only when the holder is pinned and does the advanced input handling. You can do this easily by using one of the pinnable widget macros, that create the holder and handle the input rules:

SHOWCASE_WIDGET_COMPONENT_AS_PINNABLE("input-visualizer", MultiWidgets::InputVisualizerWidget)

EXPORT_CORNERSTONE_PLUGIN_AS_PINNABLE("missile-command", "Cornerstone.MissileCommand")

Service component

A service component typically offers some functionality for other components in the application, and doesn't create anything visible by itself. For example other components can use the Data gathering service to report their usage, or the Twitter service to search for Tweets. You can access different services through Showcase::ServiceProvider.

You can create your own service by inheriting from Showcase::ServiceInstance. Add your service as component with the service component macro:

SHOWCASE_SERVICE_COMPONENT("email-sending-service", Showcase::EmailService)

Operator component

Operators can add extra functionality to existing widgets without modifying the widget itself. They appear in widget attributes in the Editor, and the same operator can often be used with multiple different widget types. For example when you set Close after idle for widget, a new operator is added to it that monitors the widget's activity and destroys it after an idle period.

You can define your own operator as a component with the macro:

SHOWCASE_OPERATOR_COMPONENT("close-after-idle", Showcase::CloseAfterIdleOperator)