vtkSMProperty.h 15.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
/*=========================================================================

  Program:   ParaView
  Module:    vtkSMProperty.h

  Copyright (c) Kitware, Inc.
  All rights reserved.
  See Copyright.txt or http://www.paraview.org/HTML/Copyright.html for details.

     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the above copyright notice for more information.

=========================================================================*/
Berk Geveci's avatar
Berk Geveci committed
15
// .NAME vtkSMProperty - superclass for all SM properties
16
// .SECTION Description
Berk Geveci's avatar
Berk Geveci committed
17
// Each instance of vtkSMProperty or a sub-class represents a method 
Berk Geveci's avatar
Berk Geveci committed
18 19 20 21 22
// and associated arguments (if any) of a  a vtk object stored on one 
// or more client manager or server nodes. It may have a state and can push 
// this state to the vtk object it refers to. vtkSMPropery only supports
// methods with no arguments. Sub-classes support methods with different
// arguments types and numbers.
23 24 25 26
// A property can also be marked as an "information" property in which case
// it's values are obtained from the server with the UpdateInformation()
// call. This call is forwarded to an information helper. The type of
// the information helper used is specified in the XML file.
Berk Geveci's avatar
Berk Geveci committed
27 28 29 30 31 32 33
// Each property can have one or more sub-properties. The sub-properties
// can be accessed using an iterator. It is possible to create composite
// properties of any depth this way.
// Each property can have one or more domains. A domain represents a
// set of acceptable values the property can have. An Attempt to set a
// value outside the domain will fail. If more than one domain is specified,
// the actual domain is the intersection of all domains.
34 35 36 37 38 39 40 41 42 43 44 45 46 47
// 
// A property can be marked "animateable". "animateable" attribute can have 
// value {0, 1, 2}. 
// 0 :-- property is not animateable at all. 
// 1 :-- property is shown as animateable on the key frame animation interface
//       in the non-advanced mode.
// 2 :-- property is animateable but only shown in the advanced mode.
// Properties that are not vector properties or that don't have domain or that 
// are information_only properties
// can never be animated irrespective of the "animateable" attribute's value.
// All vector properties (vtkSMIntVectorProperty, vtkSMDoubleVectorPropery,
// vtkSMStringVectorProperty, vtkSMIdTypeVectorProperty) by default have
// have animateable="2".
//
48
// A property can be marked "is_internal". "internal" attribute can have 
49
// value {0, 1}.
50 51 52
// 0 :-- property is not internal.
//
// 1 :-- property is internal. Hence, it is not saved when saving SM state
53
//       or batch script. 
54 55
// An instance of vtkSMProperty is always internal. All other concrete subclasses
// are by default not internal (i.e. vtkSMProxyProperty and subclasses and
56
// vtkSMVectorProperty subclasses).
Berk Geveci's avatar
Berk Geveci committed
57 58 59
// .SECTION See Also
// vtkSMProxyProperty vtkSMInputProperty vtkSMVectorProperty
// vtkSMDoubleVectorPropery vtkSMIntVectorPropery vtkSMStringVectorProperty
60
// vtkSMDomain vtkSMInformationHelper
61 62 63 64 65

#ifndef __vtkSMProperty_h
#define __vtkSMProperty_h

#include "vtkSMObject.h"
66
#include "vtkSMMessageMinimal.h" // needed for vtkSMMessage
67
#include "vtkWeakPointer.h" // needed for vtkweakPointer
68

69 70
class vtkClientServerStream;
class vtkPVXMLElement;
71
class vtkSMDocumentation;
72
class vtkSMDomain;
Berk Geveci's avatar
Berk Geveci committed
73
class vtkSMDomainIterator;
74
class vtkSMInformationHelper;
Berk Geveci's avatar
Berk Geveci committed
75
class vtkSMProxy;
76
class vtkSMProxyLocator;
77 78 79
//BTX
struct vtkSMPropertyInternals;
//ETX
80 81 82 83

class VTK_EXPORT vtkSMProperty : public vtkSMObject
{
public:
84
  static vtkSMProperty* New();
85
  vtkTypeMacro(vtkSMProperty, vtkSMObject);
86 87 88
  void PrintSelf(ostream& os, vtkIndent indent);

  // Description:
Berk Geveci's avatar
Berk Geveci committed
89 90
  // The command name used to set the value on the server object.
  // For example: SetThetaResolution
91 92 93
  vtkSetStringMacro(Command);
  vtkGetStringMacro(Command);

94
  // Description:
Berk Geveci's avatar
Berk Geveci committed
95 96 97
  // If ImmediateUpdate is true, the value of the property will
  // be pushed to the server as soon as it is modified. Properties
  // that do not have values can be pushed by calling Modified().
98 99 100
  vtkSetMacro(ImmediateUpdate, int);
  vtkGetMacro(ImmediateUpdate, int);

Berk Geveci's avatar
Berk Geveci committed
101 102
  // Description:
  // Returns true if all values are in all domains, false otherwise.
Berk Geveci's avatar
Berk Geveci committed
103 104
  // The domains will check the unchecked values (SetUncheckedXXX()) 
  // instead of the actual values.
Berk Geveci's avatar
Berk Geveci committed
105 106
  int IsInDomains();

107 108 109 110 111 112
  // Description:
  // Overload of IsInDomains() that provides a mechanism to return the first
  // domain that fails the check. \c domain is set to NULL when all domain
  // checks pass.
  int IsInDomains(vtkSMDomain** domain);

Berk Geveci's avatar
Berk Geveci committed
113 114 115 116 117
  // Description:
  // Overloaded to break the reference loop caused by the 
  // internal domain iterator.
  virtual void UnRegister(vtkObjectBase* obj);

Berk Geveci's avatar
Berk Geveci committed
118
  // Description:
Berk Geveci's avatar
Berk Geveci committed
119 120
  // Creates, initializes and returns a new domain iterator. The user 
  // has to delete the iterator.
Berk Geveci's avatar
Berk Geveci committed
121 122 123 124 125 126
  vtkSMDomainIterator* NewDomainIterator();

  // Description:
  // Returns a domain give a name. 
  vtkSMDomain* GetDomain(const char* name);

127 128 129 130
  // Description:
  // Returns the first domain which is of the specified type.
  vtkSMDomain* FindDomain(const char* classname);

131 132 133 134 135
  // Description:
  // Returns the number of domains this property has. This can be 
  // used to specify a valid index for GetDomain(index).
  unsigned int GetNumberOfDomains();

Berk Geveci's avatar
Berk Geveci committed
136 137 138 139 140
  // Description:
  // Calls Update() on all domains contained by the property
  // as well as all dependant domains. This is usually called
  // after SetUncheckedXXX() to tell all dependant domains to
  // update themselves according to the new value.
141 142 143 144 145
  // Note that when calling Update() on domains contained by
  // this property, a NULL is passed as the argument. This is
  // because the domain does not really "depend" on the property.
  // When calling Update() on dependent domains, the property
  // passes itself as the argument.
146
  void UpdateDependentDomains();
Berk Geveci's avatar
Berk Geveci committed
147

148 149 150 151 152
  // Description:
  // Is InformationOnly is set to true, this property is used to
  // get information from server instead of setting values.
  vtkGetMacro(InformationOnly, int);

153 154 155 156 157 158
  // Description:
  // If IgnoreSynchronization is set to true, this property is used to
  // prevent that property from beeing updated when changed remotely by another
  // collaborative client.
  vtkGetMacro(IgnoreSynchronization, int);

159 160 161 162 163 164
  // Description:
  // Get the associated information property. This allows applications
  // to have access to both the in and out properties. The information
  // property has to be specified in the xml configuration file.
  vtkGetObjectMacro(InformationProperty, vtkSMProperty);

165
  // Description:
166 167 168 169 170 171 172 173
  // Properties can have one or more domains. These are assigned by
  // the proxy manager and can be used to obtain information other
  // than given by the type of the propery and its values.
  void AddDomain(const char* name, vtkSMDomain* dom);

  // Description: 
  // Get/Set if the property is animateable. Non-animateable
  // properties are shown in the GUI only in advanced mode.
174 175 176
  vtkSetMacro(Animateable, int);
  vtkGetMacro(Animateable, int);

177
  // Description:
178 179 180 181 182
  // Get/Set if the property is internal to server manager.
  // Internal properties are not saved in state and should not be
  // displayed in the user interface.
  vtkSetMacro(IsInternal, int);
  vtkGetMacro(IsInternal, int);
183

184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
  // Description:
  // Sets the panel visibility for the property. The value can be
  // one of:
  //   * "default": Show the property by default.
  //   * "advanced": Only show the property in the advanced view.
  //   * "never": Never show the property on the panel.
  //
  // By default, all properties have "advanced" visibility.
  vtkSetStringMacro(PanelVisibility)

  // Description:
  // Returns the panel visibility for the property.
  vtkGetStringMacro(PanelVisibility)

  // Description:
  // Sets the panel visibility to default if the current
  // representation type matches \p representation.
  vtkSetStringMacro(PanelVisibilityDefaultForRepresentation)

  // Description:
  // Returns which representation type the property will be shown by
  // default for.
  vtkGetStringMacro(PanelVisibilityDefaultForRepresentation)

208
  // Description:
209
  // Copy all property values.
210
  virtual void Copy(vtkSMProperty* src);
211 212 213 214 215 216

  // Description:
  // Returns the documentation for this proxy. The return value
  // may be NULL if no documentation is defined in the XML
  // for this property.
  vtkGetObjectMacro(Documentation, vtkSMDocumentation);
217 218 219 220 221 222

  // Description:
  // Iterates over all domains and calls SetDefaultValues() on each
  // until one of then returns 1, implying that it updated
  // the property value. This is used to reset the property
  // to its default value. Currently default values that depend
223 224 225 226 227 228
  // on domain are reset. This method can also be called
  // to reset the property value to the default specified
  // in the configuration XML. If none of the domains
  // updates the property value, then some property subclassess
  // (viz. IntVectorProperty, DoubleVectorProperty and IdTypeVectorProperty)
  // update the current value to that specified in the configuration XML.
229 230
  void ResetToDefault();

231 232 233
  // Description:
  // The label assigned by the xml parser.
  vtkGetStringMacro(XMLLabel);
234

235 236 237 238 239 240
  // Description:
  // If repeatable, a property can have 1 or more values of the same kind.
  // This ivar is configured when the xml file is read and is mainly useful
  // for information (for example from python).
  vtkGetMacro(Repeatable, int);

241 242 243 244 245 246 247 248 249
  // Description:
  // The server manager configuration XML may define <Hints /> element for
  // a property. Hints are metadata associated with the property. The
  // Server Manager does not (and should not) interpret the hints. Hints
  // provide a mechanism to add GUI pertinant information to the server
  // manager XML.  Returns the XML element for the hints associated with
  // this property, if any, otherwise returns NULL.
  vtkGetObjectMacro(Hints, vtkPVXMLElement);

250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
  // Description:
  // Overridden to support blocking of modified events.
  virtual void Modified()
    {
    if (this->BlockModifiedEvents)
      {
      this->PendingModifiedEvents = true;
      }
    else
      {
      this->Superclass::Modified();
      this->PendingModifiedEvents = false;
      }
    }

265 266 267 268
  // Description:
  // Get the proxy to which this property belongs. Note that is this property is
  // belong to a sub-proxy of a proxy, the returned value will indeed be that
  // sub-proxy (and not the outer container proxy).
269
  vtkSMProxy* GetParent();
270

271 272 273 274
  // Flag used to ignore property when building Proxy state for Undo/Redo state.
  // The default value is false.
  virtual bool IsStateIgnored() { return this->StateIgnored; }

Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
275
//BTX
276 277 278 279
protected:
  vtkSMProperty();
  ~vtkSMProperty();

280
  friend class vtkSMSessionProxyManager;
281
  friend class vtkSMProxy;
282
  friend class vtkSMSubPropertyIterator;
Berk Geveci's avatar
Berk Geveci committed
283
  friend class vtkSMDomainIterator;
Berk Geveci's avatar
Berk Geveci committed
284
  friend class vtkSMSourceProxy;
Berk Geveci's avatar
Berk Geveci committed
285
  friend class vtkSMDomain;
286
  friend class vtkSMPropertyModificationUndoElement;
287 288

  // Description:
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
289
  // Let the property write its content into the stream
290
  virtual void WriteTo(vtkSMMessage* msg);
291 292

  // Description:
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
293
  // Let the property read and set its content from the stream
294 295
  virtual void ReadFrom( const vtkSMMessage*, int vtkNotUsed(message_offset),
                         vtkSMProxyLocator*) {};
296

Berk Geveci's avatar
Berk Geveci committed
297 298 299
  // Description:
  // Set the appropriate ivars from the xml element. Should
  // be overwritten by subclass if adding ivars.
Berk Geveci's avatar
Berk Geveci committed
300 301
  virtual int ReadXMLAttributes(vtkSMProxy* parent, 
                                vtkPVXMLElement* element);
302

303
  // Description:
Berk Geveci's avatar
Berk Geveci committed
304 305
  // Update all proxies referred by this property (if any). Overwritten
  // by vtkSMProxyProperty and sub-classes.
306 307
  virtual void UpdateAllInputs() {};

308
  // Description:
Berk Geveci's avatar
Berk Geveci committed
309
  // The name assigned by the xml parser. Used to get the property
310 311 312
  // from a proxy. Note that the name used to obtain a property
  // that is on a subproxy may be different from the XMLName of the property,
  // see the note on ExposedProperties for vtkSMProxy.
Berk Geveci's avatar
Berk Geveci committed
313
  vtkSetStringMacro(XMLName);
314 315 316 317 318 319 320
  
  // Description:
  // The name assigned by the xml parser. Used to get the property
  // from a proxy. Note that the name used to obtain a property
  // that is on a subproxy may be different from the XMLName of the property,
  // see the note on ExposedProperties for vtkSMProxy.
  vtkGetStringMacro(XMLName);
Berk Geveci's avatar
Berk Geveci committed
321

Berk Geveci's avatar
Berk Geveci committed
322
  // Description:
Berk Geveci's avatar
Berk Geveci committed
323 324
  // Internal. Used during XML parsing to get a property with
  // given name. Used by the domains when setting required properties.
Berk Geveci's avatar
Berk Geveci committed
325 326 327
  vtkSMProperty* NewProperty(const char* name);

  // Description:
Berk Geveci's avatar
Berk Geveci committed
328 329
  // Internal. Used by the domains that require this property. They
  // add themselves as dependents.
330
  void AddDependent(vtkSMDomain* dom);
Berk Geveci's avatar
Berk Geveci committed
331 332

  // Description:
Berk Geveci's avatar
Berk Geveci committed
333
  // Removes all dependents.
334
  void RemoveAllDependents();
Berk Geveci's avatar
Berk Geveci committed
335

336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
  // Description:
  // Save the property state in XML.
  // This method create the property definition and rely on SaveStateValues
  // to fill this definition with the concrete property values
  virtual void SaveState(vtkPVXMLElement* parent, const char* property_name,
                         const char* uid, int saveDomains=1);
  // Description:
  // This method must be overiden by concrete class in order to save the real
  // property data
  virtual void SaveStateValues(vtkPVXMLElement* propertyElement);

  // Description:
  // Save property domain
  virtual void SaveDomainState(vtkPVXMLElement* propertyElement, const char* uid);

351 352 353 354
  // Description:
  // Updates state from an XML element. Returns 0 on failure.
  virtual int LoadState(vtkPVXMLElement* element, vtkSMProxyLocator* loader);

355 356 357
  void SetHints(vtkPVXMLElement* hints);
  vtkPVXMLElement* Hints;

358 359
  char* Command;

360 361 362
  vtkSMPropertyInternals* PInternals;

  int ImmediateUpdate;
363
  int Animateable;
364
  int IsInternal;
365

366
  char* XMLName;
367 368
  char* XMLLabel;
  vtkSetStringMacro(XMLLabel);
369

370 371 372
  char* PanelVisibility;
  char* PanelVisibilityDefaultForRepresentation;

Berk Geveci's avatar
Berk Geveci committed
373 374
  vtkSMDomainIterator* DomainIterator;

375 376 377
  vtkSetMacro(InformationOnly, int);
  int InformationOnly;

378 379 380
  vtkSetMacro(IgnoreSynchronization, int);
  int IgnoreSynchronization;

381 382
  vtkSMInformationHelper* InformationHelper;

Berk Geveci's avatar
Berk Geveci committed
383
  void SetInformationProperty(vtkSMProperty* ip);
384
  vtkSMProperty* InformationProperty;
385 386 387

  vtkSMDocumentation* Documentation;
  void SetDocumentation(vtkSMDocumentation*);
388 389 390 391

  // Subclass may override this if ResetToDefault can reset to default
  // value specified in the configuration file.
  virtual void ResetToDefaultInternal() {};
392

393 394
  int Repeatable;

395 396 397 398 399 400 401 402 403 404 405 406 407 408
  // Description:
  // Block/unblock modified events, returns the current state of the block flag.
  bool SetBlockModifiedEvents(bool block)
    {
    bool prev = this->BlockModifiedEvents;
    this->BlockModifiedEvents = block;
    return prev;
    }

  // Description:
  // Returns if any modified evetns are pending.
  // This gets cleared when Modified() is called.
  vtkGetMacro(PendingModifiedEvents, bool);

409
  // Proxy is not reference-counted to avoid reference loops.
410
  void SetParent(vtkSMProxy* proxy);
411

412
  vtkWeakPointer<vtkSMProxy> Proxy;
413

414 415 416 417 418 419
  // Flag used to ignore property when building Proxy state for Undo/Redo state.
  // The default value is false.
  bool StateIgnored;
  vtkSetMacro(StateIgnored, bool);
  vtkBooleanMacro(StateIgnored, bool);

420 421 422
private:
  vtkSMProperty(const vtkSMProperty&); // Not implemented
  void operator=(const vtkSMProperty&); // Not implemented
423

424 425 426 427
  // Description:
  // Given the string, this method will create and set a well-formated
  // string as XMLLabel.
  void CreatePrettyLabel(const char* name);
428 429 430

  bool PendingModifiedEvents;
  bool BlockModifiedEvents;
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
431
//ETX
432 433 434
};

#endif