ParaView
/builddir/build/BUILD/ParaView-v5.2.0/Utilities/Doxygen/pages/PropertyHints.md
Go to the documentation of this file.
1 Property Hints {#PropertyHints}
2 ==============
3 
4 This page documents *Property Hints*, which are xml tags accepted under *Hints*
5 for a *Property* element in Server-Manager configuration XMLs.
6 
7 [TOC]
8 
9 NoDefault
10 ----------
11 Skip setting run-time defaults during initalization.
12 
13 Any property with a domain that is dynamic i.e. depends on run-time
14 values such as data information or the information-only properties, often
15 resets the property value during initialization of the newly created proxy
16 (vtkSMParaViewPipelineController::PostInitializeProxy()). This, however, may
17 be undesirable and one may want the property to simply use the XML default.
18 In that case, use this property hint as follows.
19 
20  <IntVectorProperty ...>
21  ...
22  <Hints>
23  <NoDefault />
24  </Hints>
25  </IntVectorProperty>
26 
27 ComponentLabels
28 -----------------
29 Show vector component labels for double vector properties.
30 
31 A multi-component double vector property may represent several different types
32 of coordinates. It may be useful to provide labels for each component's input
33 to designate which type of vector is being represented.
34 
35  <DoubleVectorProperty ...>
36  ...
37  <Hints>
38  <ShowComponentLabels>
39  <Label component="0" label="X:"/>
40  ...
41  </ShowComponentLabels>
42  </Hints>
43  </DoubleVectorProperty>
44 
45 PlaceholderText
46 ---------------
47 Put a PlaceHolder text in the Text entry widget.
48 
49 For StringVectorProperty elements, one can suggest a place-holder text to use
50 in the UI using the `<PlaceholderText/>` tag.
51 
52  <StringVectorProperty...>
53  ...
54  <Hints>
55  <PlaceholderText>Enter label</PlaceholderText>
56  </Hints>
57  </StringVectorProperty>
58 
59 PropertyLink
60 ------------
61 Link properties to existing proxies at initialization time.
62 
63 PropertyLink hints is typically used to link a non-UI property to a
64 property on some other proxy known to exist when this proxy is created.
65 Consider this, we have a (settings, RenderViewSettings) proxy that created
66 when a new session is initialized in vtkSMParaViewPipelineController::InitializeSession().
67 Now, when a new (views, RenderView) proxy is created, we'd like a few properties
68 from the RenderView proxy to be linked to session wide instance of RenderViewSettings proxy.
69 That way, when the properties on RenderViewSettings proxy are changed, those on all
70 the RenderView proxy instances also change. We use `<PropertyLink/>` hint for such a case.
71 For example, consider the following:
72 
73  <IntVectorProperty command="SetUseOffscreenRenderingForScreenshots"
74  name="UseOffscreenRenderingForScreenshots"
75  number_of_elements="1"
76  default_values="0"
77  panel_visibility="never">
78  <Hints>
79  <PropertyLink group="settings"
80  proxy="RenderViewSettings"
81  property="UseOffscreenRenderingForScreenshots"/>
82  </Hints>
83  </IntVectorProperty>
84 
85 Here, we want the UseOffscreenRenderingForScreenshots property linked with the corresponding
86 property on the RenderViewSettings proxy. When this tag is encountered by
87 vtkSMParaViewPipelineController::PostInitializeProxy(), it will try to locate an
88 existing proxy of registered as (settings, RenderViewSettings).
89 vtkSMParaViewPipelineController::InitializeSession() ensures that all proxies encountered in
90 \c settings group are created and registered using the same group. Thus, when the
91 vtkSMParaViewPipelineController::PostInitializeProxy() looks for (settings, RenderViewSettings)
92 proxy, it will find one and then be able to setup a property link to ensure that the property
93 on the RenderView proxy is kept in sync with the property on the RenderViewSettings proxy.
94 
95 SelectionInput
96 --------------
97 Mark a input as a one that accepts a vtkSelection.
98 
99 Sometimes an input to an algorithm is a vtkSelection, not any other dataset.
100 In ParaView, vtkSelection inputs are treated specially to allow the user
101 to copy active selection from the application. Also, it keeps the application
102 from prompting the user to pick the second input when the filter is created.
103 To indicate to the UI that this input is a selection input, use the
104 `<SelectionInput/>` hint.
105 
106  <InputProperty ...>
107  ...
108  <Hints>
109  <SelectionInput />
110  </Hints>
111  </InputProperty>
112 
113 WidgetHeight
114 ------------
115 Specify height in rows for tabular/tree widgets.
116 
117 Certain widgets that show a tablular widget of rows and columns i.e. any property widget
118 that uses a `pqTreeWidget` including the ones for `ArrayListDomain`, `ArraySelectionDomain`,
119 `EnumerationDomain`, `CompositeTreeDomain`, respect this hint to setup the default size for the
120 tabular/tree widget.
121 
122  <IntVectorProperty command="..." name="...">
123  <CompositeTreeDomain mode="all" name="tree">
124  <RequiredProperties>
125  <Property function="Input" name="Input" />
126  </RequiredProperties>
127  </CompositeTreeDomain>
128  <Hints>
129  <!-- This tag sets the height of the CompositeTreeDomain -->
130  <WidgetHeight number_of_rows="20" />
131  </Hints>
132  </IntVectorProperty>
133 
134 FileChooser
135 ------------
136 Specify supported extensions to list for `pqFileChooserWidget` dialog.
137 
138 For properties using FileListDomain to show a file chooser widget on the
139 Properties panel, sometimes we want to provide a list of extensions expected. In
140 that case, one can use this hint. Note, this is not intended for specifying
141 extensions that a reader supports. For that one uses the `<ReaderFactory>` hint
142 descriped in [ProxyHints](@ref ProxyHints).
143 By default, the file chooser widget will accept only existing files.
144 It is possible to add <UseDirectoryName/> in the <Hints> section to accept only directories,
145 or <AcceptAnyFile/> to accept any filename to export data.
146 
147  <StringVectorProperty animateable="0"
148  command="SetQFileName"
149  name="QFileName"
150  number_of_elements="1"
151  panel_visibility="default">
152  <FileListDomain name="files" />
153  <Documentation>This property specifies the .q (solution) file name for
154  the PLOT3D reader.</Documentation>
155  <Hints>
156  <FileChooser extensions="q" file_description="Solution files" />
157  </Hints>
158  </StringVectorProperty>
159 
160 OmitFromLoadAllVariables
161 ------------
162 Specify that a dataset property be excluded when "Load All Variables" toggle is selected.
163 
164 ParaView has a global toggle named "Load All Variables" that
165 automatically selects all variables in a dataset when loading a
166 file. This hint allows certain values to be omitted from that list
167 (e.g. sidesets, edgesets) so they will not be included by default. The
168 user can still manually select these values to be loaded.
169 
170  <StringVectorProperty command="SetSideSetArrayStatus"
171  element_types="2 0"
172  information_property="SideSetInfo"
173  name="SideSetArrayStatus"
174  number_of_elements_per_command="2"
175  repeat_command="1">
176  <ArraySelectionDomain name="array_list">
177  <RequiredProperties>
178  <Property function="ArrayList"
179  name="SideSetInfo" />
180  </RequiredProperties>
181  </ArraySelectionDomain>
182  <Documentation>An Exodus II file may define subsets of all the
183  <i>boundaries</i>of all the elements in a file as sets in their own
184  right. This property specifies which of those sets should be loaded.
185  Variables, such as boundary conditions, may then be defined over these
186  sets by specifying a single number per side. For example, a hexahedron
187  has 18 sides: 6 faces and 12 edges. Any of these sides may be
188  individually called out in a set and assigned a result value. The
189  accompanying SideSetResultArrayStatus property specifies which
190  variables defined over those sets should be loaded.</Documentation>
191  <Hints>
192  <OmitFromLoadAllVariables />
193  </Hints>
194  </StringVectorProperty>