Compound proxies in SM

---

This document discusses vtkSMCompoundProxy which has been replaced by vtkSMCompoundSourceProxy. Refer to Compound Source Proxies.

---

Compound proxies support grouping of multiple proxies, saving their state and instantiating them. A compound proxy is created as follows:

compound = vtkSMCompoundProxy()
compound.AddProxy("first", shrink)
compound.AddProxy("second", clip)
compound.AddProxy("this", exodus)

Once a compound proxy is created, the proxies it contains can be obtained through the following methods:

  // Description:
  // Returns a sub-proxy. Returns 0 if sub-proxy does not exist.
  vtkSMProxy* GetProxy(const char* name);

  // Description:
  // Returns a sub-proxy. Returns 0 if sub-proxy does not exist.
  vtkSMProxy* GetProxy(unsigned int index);

  // Description:
  // Returns the name used to store sub-proxy. Returns 0 if sub-proxy does
  // not exist.
  const char* GetProxyName(unsigned int index);

  // Description:
  // Returns the number of sub-proxies.
  unsigned int GetNumberOfProxies();

A compound proxy is capable of saving it's description into a vtkPVXMLElement tree:

definition = compound.SaveDefinition(None)

The compound proxy definition has the same structure as SM state. All references to proxies that are not contained in the compound proxy are removed. Therefore, the compound proxy is self-contained. Compound proxy definition can be registered with the proxy manager:

pm.RegisterCompoundProxyDefinition("macro", compound.SaveDefinition(None))

Once a compound proxy definition is registered with the proxy manager, a new compound proxy can be instantiated with:

newCompound = pm.NewCompoundProxy("macro")

The compound proxy definition can also be saved to a stream with:

  // Description:
  // Serialize (as XML) in the given stream.
  void vtkPVXMLElement::PrintXML(ostream& os, vtkIndent indent);

The proxy manager can load and save compound proxy definitions with:

  // Description:
  // Load compound proxy definitions and register them.
  void LoadCompoundProxyDefinitions(const char* filename);
  void LoadCompoundProxyDefinitions(vtkPVXMLElement* root);

  // Description:
  // Save registered compound proxy definitions.
  void SaveCompoundProxyDefinitions(const char* filename);
  void SaveCompoundProxyDefinitions(vtkPVXMLElement* root);

Furthermore, compound proxy definitions and compound proxies are saved with the server manager state and are restored when the state is loaded.

Here is the documentation of vtkSMCompoundProxy:

// vtkSMCompoundProxy is a proxy that allows grouping of multiple proxies.
// vtkSMProxy has also this capability since a proxy can have sub-proxies.
// However, vtkSMProxy does not allow public access to these proxies. The
// only access is through exposed properties. The main reason behind this
// is consistency. There are proxies that will not work if the program
// accesses the sub-proxies directly. The main purpose of
// vtkSMCompoundProxy is to provide an interface to access the
// sub-proxies. It contains a main proxy and all the proxies that are added
// to the compound proxy are actually added to this proxy. This way, the
// main proxy can be any proxy type (for example a vtkSMSourceProxy). The
// compound proxy is used to access sub-proxies whereas the main proxy is
// used to access properties that are exposed by the group.

Keep in mind that the vtkSMCompoundProxy is merely a simple class that allows access to the sub-proxies of the main proxy. Most of the times, you will want to work with the main proxy when getting/setting properties, updating etc. Another important method is:

  
  // Given a proxy/property pair, expose the property with the
  // given (exposed property) name.
  void vtkSMCompoundProxy::ExposeProperty(const char* proxyName, 
                                          const char* propertyName,
                                          const char* exposedName);

With ExposeProperty, you can expose certain properties of proxies contained in the compound proxy through the compound proxy. This is a good way of designating certain properties as important and accessible through the compound proxy interface.