ParaView/Properties Panel: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
Line 26: Line 26:


pqProxyWidget can also be created and used in other parts of the application whenever an widget needs to be shown to edit properties of a proxy e.g. change exporter or writer parameters when exporting views or writing data files.
pqProxyWidget can also be created and used in other parts of the application whenever an widget needs to be shown to edit properties of a proxy e.g. change exporter or writer parameters when exporting views or writing data files.
=TOBEUPDATED=


=== The pqPropertiesPanel class ===
=== The pqPropertiesPanel class ===

Revision as of 19:14, 28 April 2013

Starting with version 3.98.0, ParaView presents the users with a Properties Panel for changing parameters for the pipeline modules (aka. filters, readers, sources) as well as those for displays/representations i.e. controlling how the generated data is displayed in the views. This panel replaces the Object Inspector and its Properties and Display tabs.

Key Features

Figure 1 Properties Panel for Sphere source showing default properties.
  1. Object Inspector presented Module and Display parameters on separate tabs, which meant users had to switch between the tabs regularly. The revised Properties Panel enables users to change both types of parameters from the same panel. The parameters are still grouped separately (as Properties and Display) and can be shown/hidden by clicking on the separator buttons.
  2. The panel enables separating properties suitable for the default and advanced views. This makes it possible to keep the widgets shown on the panel to a minimal set by default, with the ability for advanced users to access those less frequently used parameters by click on the gear icon at the top of the panel.
  3. Users can also search for parameters using their labels by typing in the Search box at the top of the panel. The Search always searches through all available parameters, basic or advanced, irrespective of the mode the panel is currently in.
  4. Plugins and custom applications developers can write extensions to provide custom widgets for individual parameters, rather than having to write customizations for the entire panel. This ensures that the features such as searching, toggling basic/advanced views, continue to work irrespective irrespective of whether the panel has customizations. This also makes it possible for developers to focus on the just the parameter that needs customizations, rather than have to deal with all the other parameters.
  5. Widgets shown in the default view i.e. non-advanced view, can be context sensitive e.g. when user switches to "Slice" representation for an Uniform Rectilinear Grid dataset, the Slice Direction and Slice Offset parameters become available in the default view.

Implementation Details

The classes that encapsulate the core functionality for the Properties Panel are as follows:

pqPropertiesPanel (base-class: QWidget)

pqPropertiesPanel is a QWidget subclass that correspond to the entire panel widget i.e. the search bar, the buttons, etc. It keeps tracks of creating panels for sources/representations as they are created, cleaning them up when the corresponding proxies get destroyed, and showing the panels for the active source/representation, and such. It doesn't have any logic to control how the panels for proxies are created. For that, it simply uses pqProxyWidget. Typically, the panels shows two separate pqProxyWidget instances, one for the parameters of the filter/source proxy and another for the parameters of the active display/representation.

pqProxyPanel (base-class: QWidget)

pqProxyWidget represents a panel for a vtkSMProxy. pqProxyWidget creates widgets for each of the properties (or proxy groups) of the proxy respecting any registered pqPropertyWidgetInterface instances to create custom widgets. pqProxyWidget is used by pqPropertiesPanel to create panels for the source/filter and the display/representation sections of the panel.

pqProxyWidget doesn't show any widgets in the panel by default (after constructor). Use filterWidgets() or updatePanel() to show widgets matching the given criteria.

pqProxyWidget can also be created and used in other parts of the application whenever an widget needs to be shown to edit properties of a proxy e.g. change exporter or writer parameters when exporting views or writing data files.

TOBEUPDATED

The pqPropertiesPanel class

The central class in the new properties panel framework is pqPropertiesPanel. It inherits QWidget and by default is placed in a QDockWidget in the lower-left of the ParaView window. The two main API methods are setProxy(pqProxy *proxy) and setRepresentation(pqRepresentation *repr). The setProxy() method is called each time the current proxy is changed (e.g. the user creates a new sphere source or clicks a different object in the pipeline inspector) and will populate the top-half of the panel with the controls for the proxy. The setRepresentation() method is called each time the current representation changes (e.g. a different representation is select in the representation combo-box) and will populate the bottom-half of the panel with controls for the representation.

When the current proxy or representation changes the properties panel will read the XML object for each property in the proxy and create the appropriate subclass of pqPropertyWidget for it. This is done through the static pqPropertiesPanel::createWidgetForProperty(vtkSMProperty *property, vtkSMProxy *proxy, QWidget *parent = 0) method. This method is static so that other parts of ParaView can use it to provide a GUI widget for controlling a specific property on a proxy. The pqPropertyWidget class has a number of subclasses which implement a wide range of controls for each type of ParaView property (e.g. IntVectorProperty, StringVectorProperty, etc.).

The pqPropertyWidget class

The pqPropertyWidget class is the base class for all widgets controlling the value of a vtkSMProperty. A few generic implementations are provided for ParaView's property types:

  • pqIntVectorPropertyWidget for vtkSMIntVectorProperty
  • pqDoubleVectorPropertyWidget for vtkSMDoubleVectorProperty
  • pqStringVectorPropertyWidget for vtkSMStringVectorProperty
  • pqProxyVectorPropertyWidget for vtkSMProxyVectorProperty

Furthermore each of the basic property widget types will specialize and display themseleves based on the domain(s) of the property. For example, a vtkSMIntVectorProperty with a vtkSMBooleanRangeDomain will display a QCheckBox.

The pqPropertyWidget class has a fairly simple API:

<source lang="cpp"> class pqPropertyWidget { public:

 virtual void apply(); // apply settings (copy value from widget to property on the server)
 virtual void reset(); // reset settings (copy value from the property on the server to the widget)

signals:

 void modified(); // emitted when the widget's value changes

}; </source>

And, as mentioned before, the easiest way to create a property widget for a given property is with the static pqPropertiesPanel::createWidgetForProperty(vtkSMProperty *property, vtkSMProxy *proxy, QWidget *parent = 0) method.

XML Attributes

The XML for the proxy and property definitions allow for developers to control how the controls for their proxy are shown to the user.

Panel Visibility

The panel_visibility attribute allows for the visibility of the widget on the panel to be modified.

Valid values for panel_visibility are:

  • "default" - always shown on the panel
  • "advanced" - only shown when the advanced button is clicked
  • "never" - never shown on the panel

For example, the following property will only be shown when the user clicks the advanced button in the properties panel:

<source lang="xml">

 <IntVectorProperty name="PhiResolution" panel_visibility="advanced">
 </IntVectorProperty>

</source>

Custom Panel Widgets

A custom panel widget for a property can be specified with the panel_widget property.

Some builtin custom widgets are:

  • color_selector: a color-swatch button for changing a single color
  • display_representation_selector: for selecting representations
  • texture_selector: for loading textures from files
  • command_button: displays a button that when clicked will invoke the property's command on the proxy

For example:

<source lang="xml"> <DoubleVectorProperty command="SetEdgeColor"

                     default_values="0 0 0.5"
                     name="EdgeColor"
                     panel_widget="color_selector"
                     panel_visibility="advanced">

</DoubleVectorProperty> </source>

Debuging

Setting the PV_DEBUG_PANELS enviornmental variable will cause the pqPropertiesPanel class to print out the reason for creating each property widget.

For example, after doing export PV_DEBUG_PANELS, running ParaView, and creating a Sphere source the following will be printed:

Creating panel widgets for the Sphere proxy: 
  - Center ( Center ) gets a pqDoubleVectorPropertyWidget containing a "List of QLineEdit's for an DoubleVectorProperty with an DoubleRangeDomain (range) and more than one element" 
  - Radius ( Radius ) gets a pqDoubleVectorPropertyWidget containing a "List of QLineEdit's for an DoubleVectorProperty with an DoubleRangeDomain (range) and more than one element" 
  - ThetaResolution ( Theta Resolution ) gets a pqIntVectorPropertyWidget containing a "List of QLineEdit's for an IntVectorProperty with an IntRangeDomain (range) and more than one element" 
  - StartTheta ( Start Theta ) gets a pqDoubleVectorPropertyWidget containing a "pqDoubleRangeWidget for an DoubleVectorProperty with a single element and a DoubleRangeDomain (range) with a minimum and a maximum" 
  - EndTheta ( End Theta ) gets a pqDoubleVectorPropertyWidget containing a "pqDoubleRangeWidget for an DoubleVectorProperty with a single element and a DoubleRangeDomain (range) with a minimum and a maximum" 
  - PhiResolution ( Phi Resolution ) gets a pqIntVectorPropertyWidget containing a "List of QLineEdit's for an IntVectorProperty with an IntRangeDomain (range) and more than one element" 
  - StartPhi ( Start Phi ) gets a pqDoubleVectorPropertyWidget containing a "pqDoubleRangeWidget for an DoubleVectorProperty with a single element and a DoubleRangeDomain (range) with a minimum and a maximum" 
  - EndPhi ( End Phi ) gets a pqDoubleVectorPropertyWidget containing a "pqDoubleRangeWidget for an DoubleVectorProperty with a single element and a DoubleRangeDomain (range) with a minimum and a maximum" 

Auto-Apply

The new properties panel retains the "auto-apply" functionality of the previous properties panel. This is implemented by automatically calling pqPropertiesPanel::apply() whenever a property widget is modified. The auto-apply function can be set by the user in the Edit->Settings menu or progromatically with the pqPropertiesPanel::setAutoApply(bool enabled) method. Additionally, a time delay may be introduced with the pqPropertiesPanel::setAutoApplyDelay(int msec) method.