Difference between revisions of "ServerManager XML Hints"

From KitwarePublic
Jump to: navigation, search
(Expose proxy in GUI menu)
(One intermediate revision by the same user not shown)
Line 20: Line 20:
 
===Hide/Show a property===
 
===Hide/Show a property===
  
A Property hint with a show attribute can be used to hide or show a property within the automatically generated object inspector panel.
+
The <tt>panel_visibility</tt> attribute can be used to change the visibility of a property in the properties panel.  
 +
 
 +
Valid values are:
 +
 
 +
* <tt>"default"</tt> - always shown on the panel
 +
* <tt>"advanced"</tt> - only shown when the advanced button is clicked
 +
* <tt>"never"</tt> - 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">
 
<source lang="xml">
   <Hints>
+
   <IntVectorProperty name="PhiResolution" panel_visibility="advanced">
    <Property name="[property name]" show="0" />
+
   </IntVectorProperty>
   </Hints>
+
 
</source>
 
</source>
  
 
Since almost all editable properties are by default shown in the automatically generated object inspector panel, this is most often used to hide the property.  The need for this can occur when the property must be declared in the XML so that the default value for the VTK object's ivar is wrong or when the value needs to be changed programmatically, but allowing the user to directly change it is either confusing or could invalidate the state.
 
Since almost all editable properties are by default shown in the automatically generated object inspector panel, this is most often used to hide the property.  The need for this can occur when the property must be declared in the XML so that the default value for the VTK object's ivar is wrong or when the value needs to be changed programmatically, but allowing the user to directly change it is either confusing or could invalidate the state.
  
One example where this hint is used relatively frequently is for the vtkFileSeriesReader, which is reused for several readers and has a state switch called UseMetaFile that toggles between reading a list of files and reading a single text case file listing the actual files to read.  The XML proxy definition must declare a UseMetaFile property to set it to the appropriate state, but you don't want the user to ever change the value because it would invalidate the reader.  Thus, you get proxy code like the following.
+
One example where this attribute is used relatively frequently is for the vtkFileSeriesReader, which is reused for several readers and has a state switch called UseMetaFile that toggles between reading a list of files and reading a single text case file listing the actual files to read.  The XML proxy definition must declare a UseMetaFile property to set it to the appropriate state, but you don't want the user to ever change the value because it would invalidate the reader.  Thus, you get proxy code like the following.
  
 
<source lang="xml">
 
<source lang="xml">
Line 36: Line 43:
 
                       command="SetUseMetaFile"
 
                       command="SetUseMetaFile"
 
                       number_of_elements="1"
 
                       number_of_elements="1"
                       default_values="1">
+
                       default_values="1"
 +
                      panel_visibility="never">
 
       <BooleanDomain name="bool" />
 
       <BooleanDomain name="bool" />
 
       <Documentation>
 
       <Documentation>
Line 42: Line 50:
 
       </Documentation>
 
       </Documentation>
 
     </IntVectorProperty>
 
     </IntVectorProperty>
  ...
 
    <Hints>
 
      <!-- This property is here simply to set it. -->
 
      <Property name="UseMetaFile" show="0" />
 
    </Hints>
 
</source>
 
 
A rare but valid use of this hint is to show a property that is normally hidden.  An example of a property that is normally hidden is the first property in a reader marked as a FileListDomain.  Normally it causes problems to allow the user to change the file name of a reader after it has been created (or rather, it is easier to delete the reader and create a new one).  However, there are some rare cases where you really do need to show that property, so you can override this behavior.
 
 
<source lang="xml">
 
    <Hints>
 
      <Property name="FileName" show="1"/>
 
    </Hints>
 
 
</source>
 
</source>
  

Revision as of 09:36, 28 August 2012

NOTE: This is under development and may not cover all available hints

Proxy Hints

These are hints added to proxies.

Mark proxy as a reader

  • Used to mark a proxy under the "sources" group as a reader.
  • extensions attribute is used to list the supported extensions e.g. "foo foo.bar" for files named as somename.foo or somename.foo.bar.
  • filename_patterns attribute is used to list the filename patterns to match. The format is similar to what one would use for "ls" using wildcards e.g. spcth* to match spcta, spctb etc.
 <Hints>
   <ReaderFactory extensions="[space separated extensions w/o leading '.']"
                  filename_patterns="[space separated filename patters (using wildcards)]"
                  file_description="[user-friendly description]" />
 </Hints>

Hide/Show a property

The panel_visibility attribute can be used to change the visibility of a property in the properties panel.

Valid values 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:

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

Since almost all editable properties are by default shown in the automatically generated object inspector panel, this is most often used to hide the property. The need for this can occur when the property must be declared in the XML so that the default value for the VTK object's ivar is wrong or when the value needs to be changed programmatically, but allowing the user to directly change it is either confusing or could invalidate the state.

One example where this attribute is used relatively frequently is for the vtkFileSeriesReader, which is reused for several readers and has a state switch called UseMetaFile that toggles between reading a list of files and reading a single text case file listing the actual files to read. The XML proxy definition must declare a UseMetaFile property to set it to the appropriate state, but you don't want the user to ever change the value because it would invalidate the reader. Thus, you get proxy code like the following.

    <IntVectorProperty name="UseMetaFile"
                       command="SetUseMetaFile"
                       number_of_elements="1"
                       default_values="1"
                       panel_visibility="never">
      <BooleanDomain name="bool" />
      <Documentation>
        This hidden property must always be set to 1 for this proxy to work.
      </Documentation>
    </IntVectorProperty>

Default View

  • Used to pick a default view type.
  • Does not support picking a view type for multiple output-ports just yet.
 <Hints>
   <!-- View can be used to specify the preferred view for the proxy -->
   <View type="XYChartView" />
 </Hints>


Mark Data Plotable

  • ParaView charts can support plotting any type of data, however since plotting is client-side, we don't want the user to accidentally try to plot really large datasets.
  • So we mark certain filters/sources are plot-able.
  • A source/filter producing vtkTable is always plot-able by default.
  <Hints>
    <Plotable />
  </Hints>

Don't hide input dataset

  • When a filter is applied, ParaView hides the input dataset(s) by default in the active view.
  • In some cases, this is not the expected behavior e.g. Slice filter. In that case, use this hint.
  • Accepted values:
 0 ==> don't replace the input at all
 1 ==> replace the input (default behavior)
 2 ==> replace the input only if it is "Surface" or "Surface With Edges" and is totally opaque.
  <Hints>
    <Visibility replace_input="0" />
  </Hints>

Property Hints

These are hints added to Properties.

Selection Input

  • If a filter needs to use the "active selection", one can use this hint.
  • Only used by auto-generated Properties panel.
  • Specified on a Input property that can take in a vtkSelection.
  <InputProperty name="Selection"
       command="SetSelectionConnection">
       <DataTypeDomain name="input_type">
         <DataType value="vtkSelection"/>
       </DataTypeDomain>
       <Documentation>
         The input that provides the selection object.
       </Documentation>
       <Hints>
         <!-- This tag alerts the auto-generated panels and input selection
              that this input is a selection.  It should use the special
              selection GUI. -->
         <SelectionInput />
       </Hints>
  </InputProperty>

Summary Panel

  • Indicates that the property should be shown in the summary panel.
  • Used by auto-generated Properties panel.
 
  <DoubleVectorProperty name="Radius"
                        command="SetRadius"
                        number_of_elements="1"
                        animateable="1"
                        default_values="0.5" >
    <DoubleRangeDomain name="range" min="0"/>
    <Documentation>
      This property specifies the radius of the sphere.
    </Documentation>
    <Hints>
      <!-- Indicates that this property should be shown in the summary panel -->
      <ShowInSummaryPanel/>
    </Hints>
  </DoubleVectorProperty>

Grouping Properties

So you can use widget input.

   <PropertyGroup type="Line" label="Elevation Widget">
      <Property function="Point1WorldPosition" name="LowPoint" />
      <Property function="Point2WorldPosition" name="HighPoint" />
   </PropertyGroup>

ParaView 3.12 XML update

Expose proxy in GUI menu

To show a source proxy or a filter inside the menu of ParaView we use a hint. The category attribute allow to specify in which sub-menu this proxy should be in but it is totally optional.

       <SourceProxy ...>
           <Hints>
              <ShowInMenu category="PersoFilter"/>
           </Hints>
       </SourceProxy>

TimeSeries readers

Previously we use to have TimeSerieReader proxy, now we can simply deal with regular source proxy and custom server side code. The following code snippet show what should be done now.

   <SourceProxy si_class="vtkSIFileSeriesReaderProxy" [same attrs as before]>
      ...
   </SourceProxy>

instead of

   <FileSeriesReaderProxy [some params]>
      ...
   </FileSeriesReaderProxy>

Disable property for UndoRedo states

Now properties can be escaped from the GetFullState() method that is used for the undo/redo state by providing an extra attribute inside xml proxy definition.

   <Proxy name="ComparativeViewBase">
      <DoubleVectorProperty name="ViewTime"
        command="SetViewTime"
        number_of_elements="1"
        state_ignored="1" <---------------------- NEW FLAG
        default_values="none">
        <DoubleRangeDomain name="range"/>
        <Documentation>
          The pipeline update time for this view.
          This gets passed to all representations added to this view.
        </Documentation>
      </DoubleVectorProperty>
   ...