Server Hints

Overview

ParaView3 currently provides a basic mechanism to create "auto-generated" graphical user interfaces for proxies. The auto-generated panels iterate over a proxy's properties, querying each property for its type (int, double, etc), the number of elements within multi-element properties, and the property domain. Based on this information, appropriate Qt widgets are created and linked to the property. A property might be represented using a single Qt widget (e.g: a combo-box for an enumeration property), two Qt widgets (e.g: a slider control and a spin control for a single floating-point property), or multiple Qt widgets (e.g: six line edit controls for a bounding-box property).

By default, an auto-generated panel is available for every type of SM proxy that is displayed in the Object Inspector. Developers also have the option of creating "custom" panels for proxies, which hand-generate Qt widgets and link them to proxy properties. Custom panels provide the developer with significant flexibility to pick-and-choose which properties to display and how to represent them. Properties may be displayed using special user interface components and the interaction among components may be governed by special-purpose logic. Currently, custom panels are the only means to use 3D widgets to control a proxy.

Requirements

Despite the flexibility of custom panels, it has become apparent that many of their features (such as 3D widgets) must be made to work for auto-generated panels, to support two main requirements:

• Custom Filters - a custom filter defined by the user will contain one-to-many proxies, plus their connections, their links, and information on which properties to "expose" to the end-user. Because the user interface for a custom filter may contain an arbitrary set of properties originating across more-than-one proxy, custom panels that are designed to represent an entire proxy cannot be used. Requiring the creator of a custom filter to design a custom user interface panel for that filter would negate the value of creating the custom filter to begin with. Thus, custom filters will require robust auto-generated panels, capable of supporting arbitrarily-complex user interfaces including important features such as 3D widgets.

• Advanced Usability Features - we have proposed usability features for ParaView3 that include a "Most Recently Used Property" panel, and/or user designated "Favorite" properties. In either case, the idea is that, once a user has setup a visualization, they will likely need to do repetitive "tweaking" of only a handful of properties, which might be spread across multiple filters. By combining these properties into a single panel, repetitive back-and-forth switching among proxies can be eliminated. As with custom filters, this requires an auto-generated panel that can display a rich and aesthetic user interface that joins properties from multiple sources.

Derived Requirements

Creating smarter auto-generated user interfaces is not technically difficult, given sufficient contextual information about the purpose of a property. Currently, such information isn't always available: a property of type double with three elements might be a 3D coordinate, a 3D vector, three numbers that are otherwise unrelated, or something else entirely. If the auto-generated UI code knew which one it was, it could supply the appropriate interface: a 3D point widget, a 3D direction widget, three line edit controls, etc.

Similarly, properties may often need to be "grouped" into a higher-level abstraction. Two three-element double properties could represent the end-points of a line. Or they could be the origin and normal for a plane. Or they could be two unrelated 3D points. Again, given sufficient information about the two properties, the auto-generation code could create a 3D line widget, a 3D implicit plane widget, or two 3D point widgets, respectively.

Design

Proxies should expose "hints" that provide clients with additional metadata that can be used for intelligent user interface auto-generation. These hints are, in a way, an extension to property domains since they describe the role of a property, not just its range of allowable values. Hints are exposed by the proxy rather than the individual properties, since a hint may "group" multiple properties together.

Hints are emphatically not specific to any given user interface or client-side technology. A hint describes what a property (or properties) is, not what it looks like. It is still up to individual client implementations to interpret hint information and determine how to render a property/properties. As an example, it would be appropriate for a hint to specify that two properties should be treated as a plane (origin + normal). It would not be necessary for a hint to say "use a 3D implicit plane widget here", since that is a decision to be made by the client.

Implementation

Hints in Server Manager

Hints can be added to any proxy definition as follows:

 <Proxy name="...." ....>
   ....
   <Hints>
     ....
   </Hints>
 </Proxy>

To obtain the hints for any proxy, one can use any of the following:

• vtkPVXMLElement* vtkSMProxy::GetHints() : returns hints for an proxy instace.
• vtkPVXMLElement* vtkSMProxyManager::GetHints(const char* group, const char* type) : returns hints for a type of proxy without creating an object for it.

As is clear from the above API, the server manager does not process the hints at all. It simply provides the XML subtree to the GUI to process.

Supported Hints

Here is a list of hints supported by the ParaView3 GUI.

PropertyGroup

• Implies that the collection of properties indicated in this group are to be clubbed together by the GUI as a single entity. eg.

 <PropertyGroup type="Plane">
    <Property name="Center" function="Origin" />
    <Property name="Normal" function="Normal" />
 </PropertyGroup>

• Optional argument type can be use by the GUI to indicate the type of composite widget (may be a 3D widget) that can be used to control all the groupped properties.
• Nested Property elements indicate which properties form the proxy are groupped under the current group. Each property may have a function. This helps the GUI is mapping the properties to different functions provided by the composite widget. In case of the given example, the GUI will use an ImplicitPlaneWidget to control the properties Center and Normal for the proxy. The implicit plane widget's Origin is mapped to the property Center while the widget's Normal is mapped to the property Normal.