Containers and Interfaces

Introduction

When designing a Ventuz scene, certain combinations of nodes or design patterns occur over and over again. For example, user interface elements like buttons or sliders are designed once and then used throughout the presentation to create a consistent look and feel. The only aspects that change are perhaps the size, position and label.

Another common theme when designing complex presentations is that there is some semantic structure to the scene. There might be a certain subtree of the scene that is responsible for presenting the user interface, another for talking to external devices, yet another for rendering a collection of images. Having all of those nodes in one visual space is not only confusing but outright unnecessary.

In both cases, Container Nodes improve productivity as they enable the author to combine nodes to a new customized type of node. Picking up on the UI button example above, a button may require a geometry, multiple textures, keyframe animations and much more. All of those nodes can be put into one container, thus having the container act as a single node representing the button. The individual nodes are hidden from the main hierarchy level making the scene easier to understand and instead of duplicating the subtree, only the "button node" needs to be duplicated.

Creating a Container

A new container is created in the same way as all other nodes, by dragging  the Hierarchy or Content Container to the respective part of the scene. Since this is a very generic node and a scene often contains different containers, it is advisable to give it an appropriate name right away by double clicking  on the name of the node. It can even be assigned a new icon by selecting the node and then choosing Node/Icon/Open in the main menu bar. Nodes can be added to a Container by cutting them from the hierarchy, navigating into the Container and then pasting them or just create them inside the Container directly.

Merge to Container

An alternative way is to select a node and then use Node/Merge To Container from the main menu bar. This will replace the selected subtree with a container and place the removed nodes inside the container.
Since Ventuz 4.03.xx beside merging a selection to a Hierarchy Container it is also possible to merge content nodes to Content Container.
There are basically four different ways of merging:

• Selection in Hierarchy Editor
  1. A single Hierarchy Node is selected with children.
     If all selected nodes (including value suppliers) are only connected to this partial tree - the merge is performed and a new Hierarchy Container is created

2. A single HE node is selected without children click +CTRL.
   Only the single HE node is merged with all its suppliers - a new Hierarchy Container is inserted at the previous location. The icon of the previously selected HE node is exposed. Outputs and multi-links are maintained.

• Selection in Content Editor
  1. Only CE nodes are selected.
     All nodes are merged into a new Content Container. Bindings that pointed outside the selection are re-created by new exposings.

2. A single HE node is selected and optional one or multiple CE nodes.
   Basically the same as Selection in Hierarchy Editor (2) (above) but only the selected CE nodes are merged. Bindings that pointed outside the selection are re-created by new exposings and the icon of the previously selected HE node is exposed.

Navigation

All container nodes can be easily recognized by their gray triangle on the left inside of the node icon. By double clicking  on that triangle or pressing ENTER, the editor leaves the current hierarchy level and switches to the inside of the container. When inside a container, the starting point of the hierarchy is not the familiar scene root T-junction, but the container root, a white triangle. Double clicking  on that icon or pressing BACK takes the Hierarchy Editor out of the current container. In addition, a button bar appears at the bottom of the Hierarchy Editor when inside a container. This shows the path of containers starting from the scene root and is especially helpful when working with nested containers. Click  any of the buttons to switch to that container level. Pressing  inside the Hierarchy Editor will display a popup window with the Hierarchy Container structure of the complete scene. This overview can also be used for navigation; just click on the desired container.

Outputs

By default, a Hierarchy Container is created with one Output Node already inside it. An Output represents a connection back up to the parent hierarchy level and allows nodes or subtrees to be placed behind the Container.

Inside the Container, the Output nodes represent all nodes behind the container on the parent level. This can be used to encapsulate some functionality inside a Container while leaving a degree of freedom to the user of the Container. As an example, consider someone constructing an animated picture frame inside a container. All the geometries, textures and so on that directly contribute to the frame are inside the Container, but the content that should be rendered inside the frame are kept out of it. This improves reusability and avoids forcing the user to step into the container every time the framed content is to be changed.

Exposing Properties

While a Container is primarily designed to hide the complexity of its implementation, there are usually some properties of the encapsulated nodes that need to be adjustable from outside the Container. A button may allow the user to change its color and label, a movie player my require a file name to work correctly and so on.

To expose a property, click  on the name of the property in the Property Editor and choose Expose/Edit... from the appearing context menu. The name and category of the property as it will appear on the Container can either be kept the same as on the original node or be reassigned in the dialog that opens. Press OK and the square to the left of the property name will change to green, symbolizing that this is now an exposed property. Note that exposed property names have to be unique within a container. Exposing two properties with the same name will not only confuse other Ventuz operators but can also disrupt the binding logic.

Exposed input and output properties of a Container can be seen either when selecting the container node on its parent hierarchy level or by going into the Container and deselecting everything.

To quickly expose a property without changing its name or category, click  the small square to the left of the property. To quickly unexpose a property, click  on the square. A double-click will bring up the Expose dialog.

Sealing Containers

Sometimes an author wants to distribute some customized functionality to another user. The end-user should be able to render and tweak the functionality but not be able to see how it is done. In such a case, the functionality can be wrapped into a container which is than sealed (via Node/Seal Container). There are two types of seals:

• Simple Seal: This acts like a write-protection on the container. A user cannot step into the container while it is sealed but anyone can remove the seal by using Node/Seal Container again to unseal the container.
• Permanent Seal: This permanently removes all possibilities to get inside the Container. This type of seal cannot be undone, therefore the author is advised to create a backup of the unsealed state somewhere.

Interfaces

When working extensively with Containers, inevitably in-use Containers will require modification. Whether it is a bug that needs to be fixed or additional functionality added, the change is done in one instance and manually has to be transferred to all other instances. The usual method to do this is to remove all other instances, duplicate the modified version and manually reconstruct all pre-existing bindings.

Interfaces are an extension of the Container idea to address the above, and other, problems. They define which properties a Container has to provide in order to be used in a certain part of the scene. A Container Interface keeps its properties (and therefore its bindings as well) intact even when the encapsulated nodes are removed. When the content of a container is replaced, new exposings can fulfill the interface properties.

Defining an Interface

To define an interface, a Container with exposed properties is required. When selecting the Container, an "Interface" button appears at the bottom of the Property Editor. Press it and the container is upgraded to an Interface Container, which is visualized by two lines that close the gap in the brackets that surround the node icon.

When changing a Container to an Interface Container, all exposed properties become interface properties. The difference between them is that interface properties remain defined on the interface even when the property is no longer exposed. All properties exposed after that automatically become interface properties as well.

When removing a node that exposes a property, the interface property stays intact but is visualized in a light gray color. To remove an interface property definition, either double  click on the interface property and press Exclude or use the CleanUp button at the bottom of the Property Editor to remove all interface properties without an corresponding exposing node.

An interface property that is disconnected from its exposing node keeps its last valid value.

Expose Properties to an existing Interface

To expose a property to an existing Interface Property,  click and select the desired interface property under the Expose... menu or  click on the small square to the left of the property to popup a choice of existing interface properties. Please note that only interface properties of the correct type will be listed!

Replacing Interface Content

When using drag & drop with an Interface Container, all containers in the scene with an interface defined are highlighted with a dark gray border. When dragging  the selected container over such an interface container, the target's border changes to red. Releasing  in this state will not remove the original node but replace the targets content with that of the source node. The same behavior is achieved by using Edit/Copy and Edit/Paste Container Content from the main menu.

In addition, Ventuz will try to reconnect as many interface properties as possible via its Interface Matching Algorithm. Exposed and Interface Properties match each other if they fulfill the following requirements:

1. Property Type must be identical: Input Value, Output Value, Method, Event
   1. If the type is Input or Output Value, the SubType must be identical
   2. (float, integer, string, matrix, …)
2. Property Names must be identical.
3. The names are compared case sensitive while the category is ignored.

This matching also works when dragging Interface Containers from the Repository. To improve the quality of automatic reconnection, ensure that all properties have unique names.

Copyright 2004-2016 Ventuz Technology Group