CustomObjectPanels

This page is to answer some questions asked by ParaView users when customizing the GUI.

Object Panels are the panels for editing object properties.

ParaView3 contains automatic panel generation code which is suitable for most objects. If you find your object doesn't have a good auto-generated panel, you can make your own. There are different classes you can derive from depending on how much customization you need to do, or how much existing code you can leverage.

   * pqObjectPanel - the base class for all object panels with limited functionality.
   * pqNamedObjectPanel - if your widgets (line edit, combo boxes, etc..) have names corresponding with the server manager XML, then this class will automatically hook those widgets up with the server manager.
   * pqLoadedFormObjectPanel - if you want to design your form in the Qt Designer, you get a .ui file as a result. You can use this class to load the .ui file. If the names of widgets created in the Qt Designer correspond with server manager objects, they will automatically be hooked up.
   * pqAutoGeneratedObjectPanel - a panel that has widgets automatically created based on the properties of server manager objects. You can extend this if you have small adjustments to make or small features to add. 

pqObjectPanel has a pqPropertyLinks instance. This instance is used to manage "links" between server manager properties and the GUI. When a server manager property changes, the GUI is updated. When a GUI property is changed, it is queued up until accept() is called when properties will be set on the vtkSMProperties. To create a link, you call pqPropertyLinks::addPropertyLink().

pqPropertyLinks uses pqSMAdaptor as the api for setting/getting values. pqSMAdaptor supports boolean/int/double/string and lists of those. If the GUI has a property that isn't compatible, an adaptor is needed to do the conversion. An example of that would be converting QRgb to 3 or 4 doubles for rgb or rgba.

An example of that is converting a QRgb color value to 3 r,g,b double values.
QColorDialog color <--> QRgb adapator <--> pqPropertyLinks <--> pqSMAdaptor <--> vtkSMProperty

If you use a pqNamedObjectPanel, these links will automatically be created for you given the names of the QObjects match the name of the vtkSMProperty they correspond with. These links are created by the pqNamedWidgets class, which pqNamedObjectPanel uses, and it supports a limited set of Qt Widgets (QLineEdit, QSlider, QSpinBox, etc..).

As an example, if you want to use a QDateEdit widget, you'll have to write your own adaptor to convert the date to a string or number. And since pqNamedWidgets doesn't know what to do with it, you'll have to create the links yourself using pqPropertyLinks.