Files
ThirdParty-6/ParaView-5.0.1/ParaViewCore/ServerManager/Core/vtkSMProperty.h

589 lines
22 KiB
C++

/*=========================================================================
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.
=========================================================================*/
// .NAME vtkSMProperty - superclass for all SM properties
// .SECTION Description
// Each instance of vtkSMProperty or a sub-class represents a method
// and associated arguments (if any) of 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. vtkSMProperty only supports
// methods with no arguments. Sub-classes support methods with different
// arguments types and numbers.
//
// Property is typically meant for pushing its values to athe VTK object.
// However, a property may be marked as an InformationOnly property
// in which case its values are obtained from the server with the
// UpdateInformation() call.
//
// Each non-information property can have one or more domains. A domain represents a
// set of acceptable values the property can have. Domains provide applications
// mechanisms to extract semantic information from a property.
//
// A property has two kinds of values: regular (or checked) values and unchecked
// values. Regular values are the ones that are pushed to the VTK object when
// the property is updated. These are the ones that get saved in state, etc.
// Unchecked values are provided so that domains can update their conditions
// without having the change the property's value e.g. if the domain range for the
// IsoContour property changes based on the value of the ArrayName property
// which selects the array to contour with, the can set the unchecked value on
// the ArrayName property to each of the available arrays to determine what the
// domain would be without having to modify the property and update its VTK
// object. If a property has no unchecked-values explicitly set, then the "Get"
// methods that access the unchecked-values should simply return the checked
// values. If the checked values are changed, the unchecked values are reset to
// match the checked values.
//
// A property fires the following events:
//
// \li \b vtkCommand::ModifiedEvent : fired when property's value(s) is(are)
// modified. This must be fired only when values are really changed, not
// just the "set" methods are called. This event must be fired no matter
// how the property's values are changed.
//
// \li \b vtkCommand::UncheckedPropertyModifiedEvent : fired when the property's
// unchecked-value(s) is(are) changed. Note that when a property's
// checked values change, it's unchecked values are reset to match the
// checked values, so technically,
// vtkCommand::UncheckedPropertyModifiedEvent must be fired every time
// vtkCommand::ModifiedEvent is fired.
//
// \li \b vtkCommand::DomainModifiedEvent : fired when any of this properties
// domain's fire the same event.
//
// Properties are typically constructed from ServerManager XML configuration
// files. Attributes available on a Property XML are as follows:
//
// \li \b name: \c string: This is the name for the property. This typically
// ends up being the name used by the Proxy to refer to this property. It
// must be unique for all properties on a Proxy.
//
// \li \b label: \c string:This is the user-friendly label. Ideally, the label
// should be same as the name, however traditionally that hasn't been the
// case.
//
// \li \b command: \c string: This is the name of the method to call on the VTK
// update for the property.
//
// \li \b repeatable or \b repeat_command: \c{0, 1}: This used to indicate that
// the command can be called repeatedly to update the VTK object. e.g.
// for multiple inputs, one must call AddInput(..) repeatedly. It also
// implies that the number of elements/items in the property can change.
//
// \li \b information_only: \c{0, 1}: When set, it implies that this property
// is used to obtain values from the VTK object, rather than the default
// behavior which is to set values on the VTK object.
//
// \li \b information_property: \c string: Value is the name of the property on the
// proxy to which this property belongs that can is information_only
// property corresponding to this. This is useful when the variable that
// this property sets can be changed by other means besides this property
// e.g. through interaction. Applications can use this information to
// update the value of this property to reflect the VTK-side state.
//
// \li \b immediate_update: \c{0, 1}: When set, the Proxy will attempt to push
// the value for this property to the VTK object as soon as the property
// is changed. It is no longer common and should be avoided. It may be
// deprecated in near future.
//
// \li \b state_ignored: \c{0, 1}: When set, changes to this property are not
// captured in undo-redo stacks. Unlike is_internal, the value for this
// property is saved in state files.
//
// \li \b ignore_synchronization: \c{0, 1}: When set, changes to this property
// are not synchronized among client-processes in collaborative mode.
//
// \li \b is_internal: \c{0, 1}: When set, the property is treated as internal
// which implies that it will not be shown in the UI; it value will not
// be pushed when the proxy is created, nor saved in state files or
// undo-redo stacks.
//
// \li \b animateable: \c{0, 1}: When set, the property is considered as
// animatable which the UI can use to build the animation interface.
//
// \li \b panel_visibility: \c{default, advanced, never}: Indicates to the UI
// that the widget corresponding to this property should be shown in the
// default or advanced mode, or never at all.
//
// \li \b panel_widget: \c string: provides a hint to the UI to determine which
// what widget to create to edit this property.
//
// \li \b no_custom_default: \c{0, 1}: When set, vtkSMSettings will neither
// change the value of a property upon creation nor save the property
// value as a default.
//
#ifndef vtkSMProperty_h
#define vtkSMProperty_h
#include "vtkPVServerManagerCoreModule.h" //needed for exports
#include "vtkSMObject.h"
#include "vtkSMMessageMinimal.h" // needed for vtkSMMessage
#include "vtkWeakPointer.h" // needed for vtkweakPointer
class vtkClientServerStream;
class vtkPVXMLElement;
class vtkSMDocumentation;
class vtkSMDomain;
class vtkSMDomainIterator;
class vtkSMInformationHelper;
class vtkSMPropertyLink;
class vtkSMProxy;
class vtkSMProxyLocator;
//BTX
struct vtkSMPropertyInternals;
//ETX
class VTKPVSERVERMANAGERCORE_EXPORT vtkSMProperty : public vtkSMObject
{
public:
static vtkSMProperty* New();
vtkTypeMacro(vtkSMProperty, vtkSMObject);
void PrintSelf(ostream& os, vtkIndent indent);
// Description:
// The command name used to set the value on the server object.
// For example: SetThetaResolution
vtkSetStringMacro(Command);
vtkGetStringMacro(Command);
// Description:
// 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().
vtkSetMacro(ImmediateUpdate, int);
vtkGetMacro(ImmediateUpdate, int);
// Description:
// Returns true if all values are in all domains, false otherwise.
// The domains will check the unchecked values (SetUncheckedXXX())
// instead of the actual values.
int IsInDomains();
// 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);
// Description:
// Overloaded to break the reference loop caused by the
// internal domain iterator.
virtual void UnRegister(vtkObjectBase* obj);
// Description:
// Creates, initializes and returns a new domain iterator. The user
// has to delete the iterator.
vtkSMDomainIterator* NewDomainIterator();
// Description:
// Returns a domain give a name.
vtkSMDomain* GetDomain(const char* name);
// Description:
// Returns the first domain which is of the specified type.
vtkSMDomain* FindDomain(const char* classname);
// Description:
// Returns the number of domains this property has. This can be
// used to specify a valid index for GetDomain(index).
unsigned int GetNumberOfDomains();
// 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.
// 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.
// @deprecated This method is no longer needed. Dependent domains are now
// automatically updated when a property fires
// vtkCommand::UncheckedPropertyModifiedEvent. The implementation has been
// changed to do nothing and the method will be removed in future releases.
VTK_LEGACY(void UpdateDependentDomains());
// Description:
// Is InformationOnly is set to true, this property is used to
// get information from server instead of setting values.
vtkGetMacro(InformationOnly, int);
// 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);
// 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);
// Description:
// 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:
// Add a link to a property whose value should be synchronized
// with this property value.
virtual void AddLinkedProperty(vtkSMProperty* targetProperty);
// Description:
// Remove a link to a property added with AddLinkedProperty()
virtual void RemoveLinkedProperty(vtkSMProperty* targetProperty);
// Description:
// Remove a link from the source property. This is a useful way for
// target properties to unlink themselves from a source property prior to,
// for instance, the deletion of the target property instance. This
// method only does any work if this instance was passed as the
// argument to AddLinkedProperty() on a different property instance
// at some point. Otherwise, it is a no-op.
virtual void RemoveFromSourceLink();
// Description:
// Get/Set if the property is animateable. Non-animateable
// properties are shown in the GUI only in advanced mode.
vtkSetMacro(Animateable, int);
vtkGetMacro(Animateable, int);
// Description:
// 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);
// Description:
// Sets whether the property should ignore custom default settings.
vtkSetMacro(NoCustomDefault, int);
// Description:
// Gets whether the property should ignore custom default settings.
vtkGetMacro(NoCustomDefault, int);
// 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 "default" 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)
// Description:
// Sets the name of the custom panel widget to use for the property.
vtkSetStringMacro(PanelWidget)
// Description:
// Returns name of the panel widget for the property.
vtkGetStringMacro(PanelWidget)
// Description:
// Copy all property values. This will copy both checked and unchecked values,
// if applicable.
virtual void Copy(vtkSMProperty* src);
// 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);
// Description:
// Simply calls this->ResetToDomainDefaults() and if that returns false, calls
// this->ResetToXMLDefaults().
void ResetToDefault();
// Description:
// For properties that support specifying defaults in XML configuration, this
// method will reset the property value to the default values specified in the
// XML. Default implementation does nothing.
virtual void ResetToXMLDefaults() {}
// Description:
// Iterates over all domains and call SetDefaultValues() on each domain until
// the first one returns true i.e. indicate that it can set a default value
// and did so. Returns true if any domain can setup a default value for this
// property. Otherwise false.
// vtkSMVectorProperty overrides this method to add support for settting
// default values using information_property.
virtual bool ResetToDomainDefaults(bool use_unchecked_values=false);
// Description:
// The label assigned by the xml parser.
vtkGetStringMacro(XMLLabel);
// 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);
// 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);
// 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);
void SetHints(vtkPVXMLElement* hints);
// Description:
// Overridden to support blocking of modified events.
virtual void Modified()
{
if (this->BlockModifiedEvents)
{
this->PendingModifiedEvents = true;
}
else
{
this->Superclass::Modified();
this->PendingModifiedEvents = false;
}
}
// 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).
vtkSMProxy* GetParent();
// Flag used to ignore property when building Proxy state for Undo/Redo state.
// The default value is false.
virtual bool IsStateIgnored() { return this->StateIgnored; }
// Description:
// Returns true if the property's value is different from the default value.
// This is used as a hint by the state saving code to determine if the value
// should be written to the file or if the defaults are sufficient.
virtual bool IsValueDefault() { return false; }
// Description:
// Returns true if the property has a domain with required properties. This
// typically indicates that the property has a domain whose values change at
// runtime based on input dataset or file being processed.
bool HasDomainsWithRequiredProperties();
//BTX
protected:
vtkSMProperty();
~vtkSMProperty();
friend class vtkSMSessionProxyManager;
friend class vtkSMProxy;
friend class vtkSMSubPropertyIterator;
friend class vtkSMDomainIterator;
friend class vtkSMSourceProxy;
friend class vtkSMDomain;
friend class vtkSMPropertyModificationUndoElement;
// Description:
// Let the property write its content into the stream
virtual void WriteTo(vtkSMMessage* msg);
// Description:
// Let the property read and set its content from the stream
virtual void ReadFrom( const vtkSMMessage*, int vtkNotUsed(message_offset),
vtkSMProxyLocator*) {};
// Description:
// Set the appropriate ivars from the xml element. Should
// be overwritten by subclass if adding ivars.
virtual int ReadXMLAttributes(vtkSMProxy* parent,
vtkPVXMLElement* element);
// Description:
// Update all proxies referred by this property (if any). Overwritten
// by vtkSMProxyProperty and sub-classes.
virtual void UpdateAllInputs() {};
// 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.
vtkSetStringMacro(XMLName);
// Description:
// Internal. Used during XML parsing to get a property with
// given name. Used by the domains when setting required properties.
vtkSMProperty* NewProperty(const char* name);
// Description:
// Internal. Used by the domains that require this property. They
// add themselves as dependents.
void AddDependent(vtkSMDomain* dom);
// Description:
// Removes all dependents.
void RemoveAllDependents();
// Description:
// Calls Update() on all domains contained by the property
// as well as all dependant domains. This is autimatically called
// after SetUncheckedXXX() to tell all dependant domains to
// update themselves according to the new value.
// 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.
void UpdateDomains();
// 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);
// Description:
// Updates state from an XML element. Returns 0 on failure.
virtual int LoadState(vtkPVXMLElement* element, vtkSMProxyLocator* loader);
vtkPVXMLElement* Hints;
char* Command;
vtkSMPropertyInternals* PInternals;
int ImmediateUpdate;
int Animateable;
int IsInternal;
int NoCustomDefault;
char* XMLName;
char* XMLLabel;
vtkSetStringMacro(XMLLabel);
char* PanelVisibility;
char* PanelVisibilityDefaultForRepresentation;
char* PanelWidget;
vtkSMDomainIterator* DomainIterator;
vtkSetMacro(InformationOnly, int);
int InformationOnly;
vtkSetMacro(IgnoreSynchronization, int);
int IgnoreSynchronization;
vtkSMInformationHelper* InformationHelper;
void SetInformationProperty(vtkSMProperty* ip);
vtkSMProperty* InformationProperty;
vtkSMDocumentation* Documentation;
void SetDocumentation(vtkSMDocumentation*);
int Repeatable;
// 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);
// Proxy is not reference-counted to avoid reference loops.
void SetParent(vtkSMProxy* proxy);
vtkWeakPointer<vtkSMProxy> Proxy;
// 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);
// Links for properties that "subscribe" to changes to this property.
vtkSMPropertyLink* Links;
private:
vtkSMProperty(const vtkSMProperty&); // Not implemented
void operator=(const vtkSMProperty&); // Not implemented
// Callback to fire vtkCommand::DomainModifiedEvent every time any of the
// domains change.
void InvokeDomainModifiedEvent();
// Description:
// Given the string, this method will create and set a well-formated
// string as XMLLabel.
void CreatePrettyLabel(const char* name);
bool PendingModifiedEvents;
bool BlockModifiedEvents;
//ETX
};
#define vtkSMPropertyTemplateMacroCase(typeSMProperty, type, prop, call) \
if (typeSMProperty* SM_PROPERTY = typeSMProperty::SafeDownCast(prop)) \
{ \
(void) SM_PROPERTY; \
typedef type SM_TT; \
call; \
}
#define vtkSMVectorPropertyTemplateMacro(prop, call) \
vtkSMPropertyTemplateMacroCase(vtkSMDoubleVectorProperty, double, prop, call) \
vtkSMPropertyTemplateMacroCase(vtkSMIntVectorProperty, int, prop, call) \
vtkSMPropertyTemplateMacroCase(vtkSMIdTypeVectorProperty, vtkIdType, prop, call) \
vtkSMPropertyTemplateMacroCase(vtkSMStringVectorProperty, vtkStdString, prop, call) \
#endif