ParaView
/builddir/build/BUILD/ParaView-v5.2.0/Utilities/Doxygen/pages/ProxyHints.md
Go to the documentation of this file.
1 Proxy Hints And Annotations {#ProxyHints}
2 ===========================
3 
4 This page documents *Proxy Hints*, which are XML tags accepted under *Hints*
5 for a *Proxy* element in the Server-Manager configuration XMLs.
6 
7 WarnOnRepresentationChange
8 --------------------------
9 Warn the user on changing to a specific representation type.
10 
11 For the motivation behind this hint, see BUG #15117.
12 This is used to indicate to the pqDisplayRepresentationWidget that the user must
13 be prompted with a *'Are you sure?'* if they manually switch to this
14 representation from the UI.
15 
16  <RepresentationProxy ...>
17  ...
18  <Hints>
19  <WarnOnRepresentationChange value="Volume" />
20  </Hints>
21  </RepresentationProxy>
22 
23 ReaderFactory
24 -------------
25 Mark a proxy as reader proxy so that it's used to open files from the **File |
26 Open** dialog.
27 
28 This hint is used to mark a proxy as a reader. It provides the ParaView
29 applicaiton with information about extensions supported by this reader.
30 **extensions** attribute to list the supported extensions e.g. "foo foo.bar" for
31 files named as somename.foo or somename.foo.bar.
32 **filename_patterns** attribute is used to list the filename patterns to match.
33 The format is similar to what one would use for `ls` or `dir` using wildcards e.g.
34 spcth\* to match spcta, spctb etc.
35 
36  <!-- using extensions -->
37  <SourceProxy ...>
38  ...
39  <Hints>
40  <ReaderFactory extensions="[space separated extensions w/o leading '.']"
41  filename_patterns="[space separated filename patters (using wildcards)]"
42  file_description="[user-friendly description]" />
43  </Hints>
44  </SourceProxy>
45 
46 View
47 ----
48 Specify the default view to use for showing the output produced by a
49 source/filter.
50 
51 This hint is used to indicate the name of the view to use by default for showing
52 the output of this source/filter on first *Apply*. To sepecify the view type for
53 a specific output port, you can use the optional attribute **port**.
54 
55  <SourceProxy ...>
56  ...
57  <Hints>
58  <View type="XYChartView" />
59  </Hints>
60  </SourceProxy>
61 
62 Plotable
63 --------
64 Mark output data as plotable in 2D chart views.
65 
66 Chart views in ParaView e.g. **Bar Chart View**, **Line Chart View**, support
67 plotting data of any type. However, since such plots don't use distributed
68 rendering techniques, to avoid accidentally plotting large datasets, the plots
69 by default can only show sources/filters that produce `vtkTable` as the output.
70 If a source/filter doesn't produce a `vtkTable`, but produces data that should
71 indeed be plotted by such views, one can use this hint.
72 
73  <SourceProxy ...>
74  <Hints>
75  <Plotable />
76  </Hints>
77  </SourceProxy>
78 
79 RepresentationType
80 ------------------
81 Specify the representation type to use by default when showing the output from a
82 source/filter in a particular view.
83 
84 This hint is used to indicate the default representation type in any/all views.
85 The **view** attribute is optional. When not specified it matches all views.
86 Likewise, **port** attribute is optional. When not specified it matches all
87 output ports. The hints are processed in order. Hence when specifying multiple
88 Representation elements, start with most restrictive to least restrictive.
89 
90 Note, this hint doesn't control which representaton proxy gets created, but the
91 default value for the "Representation" property on the representation proxy
92 set using `vtkSMRepresentationProxy::SetRepresentationType()`.
93 
94  <SourceProxy ...>
95  ...
96  <Hints>
97  <RepresentationType view="ComparativeRenderView" type="Surface" port="1"/>
98  <RepresentationType view="RenderView" type="Wireframe" />
99  </Hints>
100  </SourceProxy>
101 
102 Representation
103 --------------
104 Specify the representation proxy to create to show the output from a
105 source/filter in a particular view.
106 
107 This hint is used to indicate the representation proxy to create to show the
108 output from a source/filter in a paritcular view, rather than letting the view
109 determine which representation proxy to create. This is rare. The more common
110 use-case of picking the default representation type is satisfied by
111 **RepresentationType** XML hint documented above.
112 
113 The required **view** attribute specifies the view to which the hint applies and
114 should be set to the XML proxy name of the view. The required **type** attribute
115 specifies the XML proxy name for representation to create. The optional
116 **port** attribute can be used to limit the hint to specific output port.
117 
118  <SourceProxy ...>
119  ...
120  <Hints>
121  <Representation view="RenderView" type="TextSourceRepresentation" />
122  </Hints>
123  </SourceProxy>
124 
125 ShowProxyDocumentationInPanel
126 -----------------------------
127 Show an annotation label in the auto-generated panel generated using
128 pqProxyWidget.
129 
130 This hint is used to indicate that the documentation for the proxy should be
131 shown in special label at the top of the panel generated for the proxy. This is
132 useful to show information to the user directly on the panel.
133 
134 The ShowProxyDocumentationInPanel take one optional attribute **type**. The
135 possible values are:
136 1. *description*: (default) to use vtkSMDocumentation::GetDescription(),
137 2. *short_help*: to use vtkSMDocumentation::GetShortHelp(), and
138 3. *long_help*: to use vtkSMDocumentation::GetLongHelp().
139 
140  <SourceProxy ...>
141  <Documentation>
142  Some text that will be shown in the label.
143  </Documentation>
144  ...
145  <Hints>
146  <ShowProxyDocumentationInPanel type="description"/>
147  </Hints>
148  </SourceProxy>
149 
150 
151 ReloadFiles
152 -----------
153 Indicate the property on a reader to use to refresh (or reload) the reader to
154 make it re-read the data files.
155 
156 This hint can be used for readers that support "smart refresh" to re-read files
157 when they are changed. Otherwise, ParaView will use the default mechanism which
158 simply recreated the reader thus forgoing any previous data cached by the
159 reader. The attribute **property** indicates the name of the property on the
160 reader proxy to invoke to make the reader refresh.
161 
162  <SourceProxy>
163  ...
164  <Hints>
165  <ReloadFiles property="Refresh" />
166  </Hints>
167  </SourceProxy>
168 
169 View Annotations
170 ----------------
171 Views support the following annotations:
172 1. **ParaView::DetachedFromLayout**: If set to "True", this annotation will prevent the
173 layout from grabbing the view, enabling custom application developers to assign or
174 position the view themselves. Use `pqObjectBuilder::createView(viewType, server, true)`
175 to create a new view with this annotation added.