Understanding ProxyListDomain

Overview

This document describes the how the vtkSMProxyListDomain is used inside ParaView 3.0.

Server Manager

• vtkSMProxyListDomain is just like any other domain, as far as the server manager is concerned. It is defined in the configuration xml for any proxy property. The configuration defines the types (group, name) of all proxies that can be contained in the domain. eg:

 <ProxyProperty name="ClipPlane" command="SetClipPlane">
   <ProxyListDomain name="proxy_list">
     <Proxy group="implicit_functions" name="Plane" />
     <Proxy group="implicit_functions" name="Box" />
     <Proxy group="implicit_functions" name="Sphere" />
   </ProxyListDomain>
 </ProxyProperty>

• When the domain is instantiated and the configuration is loaded, (in other words when a proxy with this domain is created using vtkSMProxyManager::NewProxy()), the vtkSMProxyListDomain sets up its internal data structure to provide the list of allowed proxy types (group, name) as defined in the configuration. It does not create any proxies on its own.

• vtkSMProxyListDomain provides API to add instances of vtkSMProxy to the domain. These are to be added by the GUI, if at all.
• vtkSMProxyListDomain can seralize itself when state is saved/loaded. While loading is the proxy indicated in the state is missing, it simply skips the proxy. This allows the GUI to add non-registered proxies to any proxy list domain without breaking state loading/saving.

GUI

Internal Proxies in a pqProxy

• A pqProxy is created for every important vtkSMProxy registered. Many a times, there may be other proxies associated with that proxy, eg. implicit function proxies etc. may be associated with a filter/source proxy. The GUI can create "associated" proxies and add them as internal proxies. Internal proxies get registered under special groups, so that they are undo/redo-able, and state save-restore-able. The pqProxy makes sure that the internal proxies are unregistered when the main proxy is unregistered. When state is loaded, the GUI does not create new internal proxies if they are already present in the state file, thus the internal proxies get reused.

ProxyListDomains and Internal Proxies

• Whenever ParaView 3.0 GUI sees a property that has a proxy list domain it assumes that the property can have a value that is a proxy of any of the types indicated in the domain.
• When a proxy is registered under "sources", PV creates a pqPipelineSource object (or subclass) for it. pqPipelineSource constructor iterates over all properties and finds properties with "proxy_list" domain. For all proxy list domains, it instantiates new proxies for all the types indicated in the domain and adds them to the domain as well as adding them as internal proxies (as explained earlier).

Auto-Generated Panels

• Now the AutoGenerated panels creates a selection box for every proxy property that has a proxy list domain and uses a pqSignalAdaptorProxyList adaptor to connect the property and the GUI.
• This adaptor changes the property depending upon the user's selection, just what adaptors are supposed to do. Additionally, is the user selection proxy has Hints which indicate that a 3D widget can be used to control the proxy, then the 3D widget is created and linked with the controlled proxy. It also packs the 3D widget's GUI into the panel.
• This makes it possible to use 3D widgets in auto-generated panels.