ParaView
/builddir/build/BUILD/ParaView-v5.2.0-RC2/Utilities/Doxygen/pages/MajorAPIChanges.md
Go to the documentation of this file.
1 Major API Changes {#MajorAPIChanges}
2 =================
3 
4 This page documents major API/design changes between different versions since we
5 started tracking these (starting after version 4.2).
6 
7 Changes in 5.2
8 --------------
9 
10 ###Removed pqStandardArrayColorMapsBehavior###
11 
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.
19 
20 ###Qt dependencies###
21 
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.
31 
32  include(ParaViewQt) # generally not needed, since auto-included
33  pv_find_package_qt(qt_targets
34  QT4_COMPONENTS QtGui
35  QT5_COMPONENTS Widgets)
36 
37  pv_qt_wrap_cpp(moc_files ${headers})
38  pv_qt_wrap_ui(ui_files ${uis})
39 
40  ...
41  target_link_libraries(${target} LINK_PRIVATE ${qt_targets})
42 
43 ###Multiple input ports with vtkPythonProgrammableFilter###
44 
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*:
49 
50  <SourceProxy name="Name" class="vtkPythonProgrammableFilter" label="label" input_ports="2">
51  <InputProperty name="Source" command="SetInputConnection" port_index="0">
52  [...]
53  </InputProperty>
54  <InputProperty name="Target" command="SetInputConnection" port_index="1">
55  [...]
56  </InputProperty>
57  </SourceProxy>
58 
59 Changes in 5.1
60 --------------
61 
62 ###Removed Cube Axes###
63 
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.
70 
71 ###Removed `pqWriterDialog`###
72 
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
78 has been removed.
79 
80 ###Refactored 3DWidget panels###
81 
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.
90 
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.
94 
95 For example, the **(implicit_functions, Plane)** proxy requested that
96 `pqImplicitPlaneWidget` be used using the following XML hints.
97 
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"
102  name="Origin"
103  number_of_elements="3">
104  ...
105  </DoubleVectorProperty>
106  <DoubleVectorProperty command="SetNormal"
107  default_values="1.0 0.0 0.0"
108  name="Normal"
109  number_of_elements="3">
110  ...
111  </DoubleVectorProperty>
112  <DoubleVectorProperty animateable="1"
113  command="SetOffset"
114  default_values="0.0"
115  name="Offset"
116  number_of_elements="1">
117  </DoubleVectorProperty>
118  <Hints>
119  <PropertyGroup type="Plane">
120  <Property function="Origin" name="Origin" />
121  <Property function="Normal" name="Normal" />
122  </PropertyGroup>
123  <ProxyList>
124  <Link name="Input" with_property="Input" />
125  </ProxyList>
126  </Hints>
127  </Proxy>
128 
129 Since 3D widget panels are now simply custom `pqPropertyWidget` subclasses for a
130 property-group, this code changes are follows:
131 
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"
136  name="Origin"
137  number_of_elements="3">
138  ...
139  </DoubleVectorProperty>
140  <DoubleVectorProperty command="SetNormal"
141  default_values="1.0 0.0 0.0"
142  name="Normal"
143  number_of_elements="3">
144  ...
145  </DoubleVectorProperty>
146  <DoubleVectorProperty animateable="1"
147  command="SetOffset"
148  default_values="0.0"
149  name="Offset"
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" />
156  </PropertyGroup>
157  <Hints>
158  <ProxyList>
159  <Link name="Input" with_property="Input" />
160  </ProxyList>
161  </Hints>
162  </Proxy>
163 
164 Things to note:
165 
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.
169 
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.
174 
175 Available custom property-widgets, the interactive widget they use and the
176 obsolete 3DWidget they correspond to are given in the table below.
177 
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
186 
187 ###Changes to vtkDataArray Subclasses and In-Situ Arrays###
188 
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.
196 
197 The following methods have been deprecated in vtkAOSDataArray:
198 
199 ~~~{.cpp}
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)
204 ~~~
205 
206 The replacements use `TypedTuple` in place of `TupleValue`.
207 
208 Changes in 5.0.1
209 ----------------
210 
211 ###Changes to vtkSMInputArrayDomain###
212 
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.
219 
220 Changes in 5.0
221 --------------
222 
223 ###Changed *Source* property to **GlyphType** on certain representations###
224 
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.
229 
230 
231 ###Changes to caching infrastructure in **vtkPVDataRepresentation** and subclasses###
232 
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.
244 
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.
248 
249 Changes in 4.4
250 --------------
251 
252 ###Refactored pqView widget creation mechanisms###
253 
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.
258 
259 `pqView::getWidget()` is now deprecated. Users should use pqView::widget()
260 instead. This method internally calls the pqView::createWidget() when
261 appropriate.
262 
263 ###Removed vtkPVGenericRenderWindowInteractor, vtkPVRenderViewProxy###
264 
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.
276 
277 This change was done to make it easier to enable interactivity in `pvpython`.
278 
279 See also: vtkSMRenderViewProxy::SetupInteractor(). Subclasses of pqView now pass
280 the interactor created by QVTKWidget to this method to initialize it.
281 
282 See also: vtkSMViewProxyInteractorHelper.
283 
284 ###Refactored Color Preset Management (and UI)###
285 
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.
290 
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.
295 
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
299 XMLs to JSON.
300 
301 ###Changes to `pqViewFrame`###
302 
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)
310 for details.
311 
312 ###Changes to `vtkSMProxyIterator`###
313 
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)`.
320 
321 Changes in 4.3
322 --------------
323 
324 ###Replaced `pqCurrentTimeToolbar` with `pqAnimationTimeWidget`###
325 
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`.
332 
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
338 have now changed).
339 
340 ###Removed the need for plugins to specify a GUI_RESOURCE_FILE###
341 
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):
348 
349  <SourceProxy ...>
350  ...
351  <Hints>
352  <ShowInMenu category="<category-name>" icon="<qt-image-resource>" />
353  </Hints>
354  </SourceProxy>
355 
356 The ability to add filters to the sources menu (as done by a few plugins) is
357 removed by this change.
358 
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.
363 
364 ###Removed pqActiveView (use pqActiveObjects instead)###
365 
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.