1 Major API Changes {#MajorAPIChanges}
4 This page documents major API/design changes between different versions since we
5 started tracking these (starting after version 4.2).
10 ###Removed pqStandardArrayColorMapsBehavior###
12 Setting the default colormaps from a Qt Behavior was causing inconsistent results
13 between the ParaView UI and pvpython/pvbatch. Adding these default settings was
14 moved into the server manager. To override these defaults, use
15 vtkSMSettings::AddCollectionFromX with a priority greater than 0. The settings
16 affected are the default colormap for arrays with names vtkBlockColors and
17 AtomicNumbers. With these settings moved, the Qt behavior
18 pqStandardArrayColorMapsBehavior no longer does anything and so it has been removed.
22 Starting with 5.2, ParaView natively supports Qt 4 and Qt 5. To simplify writing
23 code with either dependency, we now have a new CMake file `ParaViewQt.cmake`
24 that gets included by `PARAVIEW_USE_FILE`. This provides new macros that be used
25 to find qt (`pv_find_package_qt`), wrap cpp (`pv_qt_wrap_cpp`), ui
26 (`pv_qt_wrap_ui`), or add resources (`pv_qt_add_resources`) instead of using
27 `qt4_` or `qt4_` specific versions based on whether the app is being built with
28 Qt4 or Qt5. `pv_find_package_qt` accepts optional `QT5_COMPONENTS` and
29 `QT4_COMPONENTS` which can be used to list the Qt component dependencies for
30 each of the versions. e.g.
32 include(ParaViewQt) # generally not needed, since auto-included
33 pv_find_package_qt(qt_targets
35 QT5_COMPONENTS Widgets)
37 pv_qt_wrap_cpp(moc_files ${headers})
38 pv_qt_wrap_ui(ui_files ${uis})
41 target_link_libraries(${target} LINK_PRIVATE ${qt_targets})
43 ###Multiple input ports with vtkPythonProgrammableFilter###
45 vtkPythonProgrammableFilter can now accept multiple input ports if the number
46 of input ports is defined in the XML plugin file with the *input_ports* attribute.
47 The different input ports are then defined with InputProperty having each a
48 different *port_index*:
50 <SourceProxy name="Name" class="vtkPythonProgrammableFilter" label="label" input_ports="2">
51 <InputProperty name="Source" command="SetInputConnection" port_index="0">
54 <InputProperty name="Target" command="SetInputConnection" port_index="1">
62 ###Removed Cube Axes###
64 Cube axes, including support in UI, Python as well as the related ParaView
65 specific classes e.g. `vtkCubeAxesRepresentation`, `pqCubeAxesEditorDialog`, and
66 `pqCubeAxesPropertyWidget` have been removed. The cube
67 axes was replaced by a generally preferred axes annotation implementation called
68 **Axes Grid**. While the two are not compatible (API-wise or visually), using
69 Axes Grid generates a more pleasing visualization.
71 ###Removed `pqWriterDialog`###
73 `pqWriterDialog` was used by `pqSaveDataReaction` to show a dialog for the user to
74 change the writer's properties. However, since the class was added, we have
75 created a new, more generic, pqProxyWidgetDialog that also allows the user to
76 save his choices to the application settings. `pqSaveDataReaction` now simply
77 uses `pqProxyWidgetDialog` instead of `pqWriterDialog`. `pqWriterDialog` class
80 ###Refactored 3DWidget panels###
82 3DWidget panels were subclasses of `pqObjectPanel`, the Properties panel
83 hierarchy that has been deprecated since 4.0. This version finally drops support
84 for these old 3D widget panels. The new implementation simply uses the
85 `pqPropertyWidget` infrastructure. A 3D widget panel is nothing more than a custom
86 `pqPropertyWidget` subclass for a property-group (`vtkSMPropertyGroup`) which
87 creates an interactive widget to be shown in the active view to help the users
88 change the values for properties in the property-group using this interactive
89 widget, in addition to standard Qt-based UI elements.
91 If you have a filter or proxy indicating that the Properties panel use one of
92 the standard 3D widgets for controlling certain properties on that proxy, you
93 specified that using `<Hints>` in the Proxy's XML definition.
95 For example, the **(implicit_functions, Plane)** proxy requested that
96 `pqImplicitPlaneWidget` be used using the following XML hints.
98 <Proxy class="vtkPVPlane" name="Plane">
99 <InputProperty is_internal="1" name="Input" />
100 <DoubleVectorProperty command="SetOrigin"
101 default_values="0.0 0.0 0.0"
103 number_of_elements="3">
105 </DoubleVectorProperty>
106 <DoubleVectorProperty command="SetNormal"
107 default_values="1.0 0.0 0.0"
109 number_of_elements="3">
111 </DoubleVectorProperty>
112 <DoubleVectorProperty animateable="1"
116 number_of_elements="1">
117 </DoubleVectorProperty>
119 <PropertyGroup type="Plane">
120 <Property function="Origin" name="Origin" />
121 <Property function="Normal" name="Normal" />
124 <Link name="Input" with_property="Input" />
129 Since 3D widget panels are now simply custom `pqPropertyWidget` subclasses for a
130 property-group, this code changes are follows:
132 <Proxy class="vtkPVPlane" name="Plane">
133 <InputProperty is_internal="1" name="Input" />
134 <DoubleVectorProperty command="SetOrigin"
135 default_values="0.0 0.0 0.0"
137 number_of_elements="3">
139 </DoubleVectorProperty>
140 <DoubleVectorProperty command="SetNormal"
141 default_values="1.0 0.0 0.0"
143 number_of_elements="3">
145 </DoubleVectorProperty>
146 <DoubleVectorProperty animateable="1"
150 number_of_elements="1">
151 </DoubleVectorProperty>
152 <PropertyGroup label="Plane Parameters" panel_widget="InteractivePlane">
153 <Property function="Origin" name="Origin" />
154 <Property function="Normal" name="Normal" />
155 <Property function="Input" name="Input" />
159 <Link name="Input" with_property="Input" />
166 - The `<PropertyGroup>` tag is no longer specified under `<Hints>`.
167 - The `panel_widget` attribute is used to indicate which custom widget to create
168 for this property group.
170 The functions for properties in the group supported by each type 3D widget (or
171 interactive widget as we now will call them) can be found by looking at the
172 documentation of each of the custom widget listed below. For the most past,
173 these have remained unchanged for previous function names.
175 Available custom property-widgets, the interactive widget they use and the
176 obsolete 3DWidget they correspond to are given in the table below.
178 New Widget | panel_widget | Interactive Widget used | Obsolete 3DWidget name
179 -----------|--------------|-------------------------|-------------------------------------
180 pqBoxPropertyWidget |InteractiveBox | BoxWidgetRepresentation | pqBoxWidget
181 pqHandlePropertyWidget | InteractiveHandle | HandleWidgetRepresentation | pqHandleWidget, pqPointSourceWidget
182 pqImplicitPlanePropertyWidget | InteractivePlane | ImplicitPlaneWidgetRepresentation | pqImplicitPlaneWidget
183 pqLinePropertyWidget | InteractiveLine | LineSourceWidgetRepresentation | pqLineWidget, pqDistanceWidget, pqLineSourceWidget
184 pqSpherePropertyWidget | InteractiveSphere | SphereWidgetRepresentation | pqSphereWidget, pqOrbitWidget
185 pqSplinePropertyWidget | InteractiveSpline or InteractivePolyLine | SplineWidgetRepresentation or PolyLineWidgetRepresentation | pqSplineWidget, pqPolyLineWidget
187 ###Changes to vtkDataArray Subclasses and In-Situ Arrays###
189 vtkDataArray can now support alternate memory layouts via the
190 vtkAOSDataArrayTemplate or other subclasses of
191 vtkGenericDataArray. While the older (and slower) vtkTypedDataArray
192 and vtkMappedDataArray interfaces still exist, they should not be used
193 and direct vtkGenericDataArray subclasses are preferred. See
194 http://www.vtk.org/Wiki/VTK/Tutorials/DataArrays for more details on
195 working with the new arrays.
197 The following methods have been deprecated in vtkAOSDataArray:
200 void GetTupleValue(vtkIdType tupleIdx, ValueType *tuple)
201 void SetTupleValue(vtkIdType tupleIdx, const ValueType *tuple)
202 void InsertTupleValue(vtkIdType tupleIdx, const ValueType *tuple)
203 vtkIdType InsertNextTupleValue(const ValueType *tuple)
206 The replacements use `TypedTuple` in place of `TupleValue`.
211 ###Changes to vtkSMInputArrayDomain###
213 vtkSMInputArrayDomain has changed the meaning of **"any"** attribute type. It
214 now includes field data arrays. To exclude field data arrays from the field
215 selection, change this to **"any-except-field"**. This is also the default for
216 vtkSMInputArrayDomain, hence simply removing the `attribute_type` field is also
217 an acceptable solution and is the recommended approach so that the XML can work
218 without changes in earlier versions of ParaView as well.
223 ###Changed *Source* property to **GlyphType** on certain representations###
225 *Source* property on representations, which was not exposed in the UI has been
226 changed to *GlyphType* to better match its role. Since this property was not
227 exposed earlier, this change should not affect any users except custom
228 applications that explicitly used this property.
231 ###Changes to caching infrastructure in **vtkPVDataRepresentation** and subclasses###
233 To avoid extra work and sync issues when propagating **UseCache** and
234 **CacheKey** flags from a vtkPVView to vtkPVDataRepresentation,
235 vtkPVDataRepresentation was updated to directly obtain thet values for these
236 flags from the view. To enable this, vtkPVDataRepresentation saves a weak
237 reference to the View it's being added to in vtkPVDataRepresentation::AddToView
238 and vtkPVDataRepresentation::RemoveFromView. Subclasses of
239 vtkPVDataRepresentation didn't consistently call the superclass implementation,
240 hence any representation subclass should ensure that it calls the superclass
241 implementations of AddToView and RemoveFromView for this to work correctly.
242 vtkPVView::AddRepresentationInternal checks for this and will raise a runtime
243 error if a representaiton is encountered that didn't properly set its View.
245 The above change also makes **vtkPVDataRepresentation::SetUseCache** and
246 **vtkPVDataRepresentation::SetCacheKey** obsolete. Subclasses no longer need to
247 provide any implementation for these methods and they should simply be removed.
252 ###Refactored pqView widget creation mechanisms###
254 pqView now adds a pure virtual method pqView::createWidget(). Subclasses should
255 override that method to create the QWidget in which the view is *rendered*. In
256 the past the subclasses implemented their own mechanisms to create the widget
257 and return it when `getWidget()` was called the first time.
259 `pqView::getWidget()` is now deprecated. Users should use pqView::widget()
260 instead. This method internally calls the pqView::createWidget() when
263 ###Removed vtkPVGenericRenderWindowInteractor, vtkPVRenderViewProxy###
265 ParaView was subclassing vtkRenderWindowInteractor to create
266 `vtkPVGenericRenderWindowInteractor` to handle interaction. That piece of code
267 was potentially derived from an older implementation of
268 vtkRenderWindowInteractor and hence did what it did. Current implementation of
269 vtkRenderWindowInteractor lets the vtkInteractionStyle (and subclasses) do all
270 the heavy lifting. ParaView did that to some extent (since it has a
271 vtkPVInteractorStyle), but will was relying on
272 `vtkPVGenericRenderWindowInteractor`, `vtkPVRenderViewProxy` to propagate
273 interaction/still renders and other things. This has been refactored. ParaView
274 no longer uses a special vtkRenderWindowInteractor. All logic is handled by
275 observers on the standard vtkRenderWindowInteractor.
277 This change was done to make it easier to enable interactivity in `pvpython`.
279 See also: vtkSMRenderViewProxy::SetupInteractor(). Subclasses of pqView now pass
280 the interactor created by QVTKWidget to this method to initialize it.
282 See also: vtkSMViewProxyInteractorHelper.
284 ###Refactored Color Preset Management (and UI)###
286 The color preset management has been completely refactored for this release.
287 This makes presets accessible to Python clients.
288 `vtkSMTransferFunctionPresets` is the class that manages the presets in the
289 *ServerManager* layer.
291 On the UI side, `pqColorPresetModel`, `pqColorPresetManager`, and
292 `pqColorMapModel` no longer exist. They have been replaced by `pqPresetDialog`.
293 Since the UI is completely redesigned, tests in custom applications
294 that used the color preset dialog will need to be updated as well.
296 The preset themselves are now serialized as JSON in the same form as the
297 settings JSON. ColorMaps in legacy XML format are still loadable from the UI. At
298 the same time, a tool `vtkLegacyColorMapXMLToJSON` is available to convert such
301 ###Changes to `pqViewFrame`###
303 Commit [afaf6a510](https://gitlab.kitware.com/paraview/paraview/commit/afaf6a510ecb872c49461cd850022817741e1558)
304 changes the internal widgets created in `pqViewFrame` to add a new `QFrame` named
305 **CentralWidgetFrame** around the rendering viewport. While this shouldn't break any
306 code, this will certainly break tests since the widgets have changed. The change to the testing
307 XML is fairly simple. Just add the **CentralWidgetFrame** to the widget hierarchy at the appropriate
308 location. See the original
309 [merge request](https://gitlab.kitware.com/paraview/paraview/merge_requests/167)
312 ###Changes to `vtkSMProxyIterator`###
314 `vtkSMProxyIterator::Begin(const char* groupName)` now additionally
315 sets the iterator mode to iterate over one group. This will likely
316 break any code that uses this method, since the iterated data list will
317 change. To recover the original functionality of the iterator, simply call
318 `vtkSMProxyIterator::SetModeToAll()` after calling
319 `vtkSMProxyIterator::Begin(const char* groupName)`.
324 ###Replaced `pqCurrentTimeToolbar` with `pqAnimationTimeWidget`###
326 `pqCurrentTimeToolbar` was a `QToolbar` subclass designed to be used in an
327 application to allow the users to view/change the animation time. We
328 reimplemented this class as `pqAnimationTimeWidget` making it a `QWidget`
329 instead of `QToolbar` to make it possible to use that in other widgets e.g.
330 `pqTimeInspectorWidget`. `pqAnimationTimeToolbar` was also changed to use
331 `pqAnimationTimeWidget` instead of `pqCurrentTimeToolbar`.
333 Besides just being a cleaner implementation (since it uses `pqPropertyLinks`
334 based linking between ServerManager and UI), `pqAnimationTimeWidget` also allows
335 applications to change the animation *play mode*, if desired. The rest of the
336 behavior of this class is similar to `pqCurrentTimeToolbar` and hence should not
337 affect applications (besides need to update any tests since the widget names
340 ###Removed the need for plugins to specify a GUI_RESOURCE_FILE###
342 It is cleaner and easier to update one xml file for each plugin.
343 Hints in the server manager xml file already perform the same functionality and
344 the GUI xml file was deprecated. Sources are now added to the **Sources** menu
345 and filters are added to the **Filters** menu when they are detected in the server
346 xml file. To place sources/filters in a category, add the following hint to the
347 Proxy XML element (`category` and `icon` attributes are optional):
352 <ShowInMenu category="<category-name>" icon="<qt-image-resource>" />
356 The ability to add filters to the sources menu (as done by a few plugins) is
357 removed by this change.
359 This change also modifies how readers are detected. Readers now must provide a
360 hint to the ReaderManager in the server xml file to be detected as readers rather
361 than sources. The backwards compatibility behavior that assumed any source with
362 a FileName attribute was a reader has been removed.
364 ###Removed pqActiveView (use pqActiveObjects instead)###
366 `pqActiveView` was a long deprecated class which internally indeed used
367 pqActiveObjects. `pqActiveView` has now been removed. Any code using
368 `pqActiveView` can switch to using pqActiveObjects with very few code changes.