Base class for all fields used in the ML. More...
#include <mlField.h>
Classes | |
| struct | Flags |
| Flags for internal usage. More... | |
Public Member Functions | |
Initialization | |
| Field (const std::string &name=std::string()) | |
Constructor: Creates a field with name. | |
| virtual | ~Field () |
| Destructor: Destroy field and remove all connection to fields an sensors. | |
Ownership | |
| FieldContainer * | getFieldContainer () const |
| Get the field container of the field (which may be NULL). | |
Field identifiers | |
| const std::string & | getName () const |
| Returns name of field. | |
| void | setName (const std::string &name) |
Sets the name of field. Should be called only once after or while construction. | |
| std::string | getFullName () const |
| Returns "fieldContainerType(instanceName).fieldName" (if field container is available, otherwise only field name is returned). | |
Field annotations | |
| bool | isOutputOnly () const |
| Returns if this field is marked as pure output field. | |
| void | setOutputOnly (bool outputOnly=true) |
| Mark field as a pure output field that is never read by its module. | |
Access to field value | |
| virtual void | setStringValue (const std::string &value)=0 |
Set field value as string value. | |
| virtual std::string | getStringValue () const =0 |
| Returns the value of the field as string value. | |
| virtual MLint | isValidValue () |
| Returns true (=1) if the field's value is valid; otherwise false (=0) is returned. | |
| void | copyCStringValue (char *valueBuffer, MLint bufferSize) |
Copies the value of the field (as character string) into the specified buffer valueBuffer. | |
| MLint | getCStringValueSize () |
| Returns the length of the character string of the string value of the field. | |
Protected Member Functions | |
| void | attachSourceField (Field *field) |
Inserts a field as source field in this instance, i.e., from now on *this might receive values and/or notifications from that field. | |
| void | detachSourceField (Field *field) |
Removes a source field from this instance. If not found then this call does nothing. | |
| void | detachFieldInternal (Field *field) |
| Only remove the given field from the destination list. | |
| virtual void | setValueFromField (const Field &field) |
Sets the value of this field from the given field. | |
Protected Attributes | |
| std::string | _name |
| The name of this field. | |
| std::vector< FieldSensor * > | _sensors |
| List of field sensors. | |
| std::vector< Field * > | _destinationFields |
| List of (target) fields which shall be set to the value of this field or which shall be notified only if this field is changed or notified. | |
| std::vector< Field * > | _sourceFields |
| List of (source) fields, which will notify this field or which will copy their value to this field. | |
| FieldContainer * | _fieldContainer |
| The owning field container. | |
| Flags | _flags |
Static Protected Attributes | |
| static MLint | _enableNotifications |
| Flag which disables the notification process of field (sensors) globally. | |
Friends | |
| class | FieldContainer |
Connecting and notification of field sensors and fields | |
| void | attachFieldSensor (FieldSensor *sensor) |
Attaches a field sensor sensor of this class instance in both directions. | |
| void | detachFieldSensor (FieldSensor *sensor) |
Detaches the field sensor sensor of this class instance in both directions. | |
| void | detachFieldSensors () |
| Detaches all field sensors of this class instance in both directions. | |
| void | attachField (OutputConnectorField *targetField) |
| This calls attachField(targetField, false). | |
| void | attachField (BaseField *targetField) |
| void | attachField (SoNodeField *targetField) |
| void | attachField (NotifyField *targetField) |
| void | attachField (Field *targetField, bool propagateValueOnConnect) |
Connects this class instance with the target field targetField. | |
| void | detachField (Field *targetField) |
Disconnects connections between target field targetField and this instance. | |
| void | detachSourceFields () |
| Disconnects all source fields of this instance in both directions. | |
| void | detachDestinationFields () |
| Disconnects all target fields of this instance in both directions. | |
| void | detachAllFields () |
| Disconnects all source and target fields of this instance in both directions. | |
| size_t | getNumDestinationFields () |
| Returns the number of destination fields which could receive notifications or value sets. | |
| Field * | getDestinationField (size_t index) |
Returns destination field at index. Returns NULL if index is out of range. | |
| size_t | getNumSourceFields () |
| Returns the number of source fields which could send notifications or value sets. | |
| Field * | getSourceField (size_t index) |
Returns the source field at index. Returns NULL if index is out of range. | |
| virtual void | touch (FieldSensor::Strength strength=FieldSensor::CHANGED) |
| Notifies all connected fields and field sensors. | |
| void | enableNotifications (bool flag) |
Enables or disables notification of attached fields and field sensors when the field value is set or notified (by notifyAttachments() or set*Value() -methods), depending on the parameter flag. | |
| bool | areNotificationsEnabled () |
| Returns whether the notification mechanism for this field (e.g., when field values are set) is enabled (see enableNotifications(bool) ). | |
| static void | enableNotificationsGlobally (bool flag) |
Enables or disables globally the notification mechanism for all fields and field sensors when field values are set or notified (by notifyAttachments() or set*Value() methods), depending on the parameter flag. | |
| static bool | areNotificationsEnabledGlobally () |
| Returns whether the notification mechanism for all fields (e.g., when field values are set) is enabled (see enableNotificationsGlobally(bool) ) Usually it is false(=0) within all calls of Module::calc* methods to avoid that field changes within these methods recursively start the calculation process of the ML. | |
| static MLint & | enableNotificationsCounterState () |
| Provides read/write access to the current counter state (see enableNotificationsGlobally(bool) ). | |
Detailed Description
Base class for all fields used in the ML.
Thread-safety: This class is not thread-safe and should only be used from the main thread.
This class is used to encapsulate image processing parameters in so-called fields. There are many derived classes for the different specialized parameter types. Usually the derived classes have the names of the types they encapsulate, e.g., IntField, EnumField or StringField. The management of parameters as fields have the following advantages:
- Fields force a standardized access to the parameters and can be read/set as string values and as normal typed values. So different fields can interchange their values via strings and no type casting is necessary
- Since the value access goes via access methods parameter changes and accesses can be detected and user defined action can be executed. For example on a field change
- user defined callback methods can be executed
- the value can be propagated to another, attached field
In detail, a field is a container for
- an individual field name (parameter name)
- a value (access also via strings string)
- a type identification for the value
- test code to check whether the value is in the correct range
- a list of elements of the class FieldSensor which contains callback functions called when the parameter is changed
- a list of elements of the class Field which shall be notified or updated in the case that the parameter is changed
Constructor & Destructor Documentation
◆ Field()
| ml::Field::Field | ( | const std::string & | name = std::string() | ) |
Constructor: Creates a field with name.
◆ ~Field()
|
virtual |
Destructor: Destroy field and remove all connection to fields an sensors.
Member Function Documentation
◆ areNotificationsEnabled()
| bool ml::Field::areNotificationsEnabled | ( | ) |
Returns whether the notification mechanism for this field (e.g., when field values are set) is enabled (see enableNotifications(bool) ).
◆ areNotificationsEnabledGlobally()
|
static |
Returns whether the notification mechanism for all fields (e.g., when field values are set) is enabled (see enableNotificationsGlobally(bool) ) Usually it is false(=0) within all calls of Module::calc* methods to avoid that field changes within these methods recursively start the calculation process of the ML.
Outside it usually will be true.
◆ attachField() [1/5]
| void ml::Field::attachField | ( | BaseField * | targetField | ) |
◆ attachField() [2/5]
| void ml::Field::attachField | ( | Field * | targetField, |
| bool | propagateValueOnConnect ) |
Connects this class instance with the target field targetField.
If propagateValueOnConnect is true, the field value is immediately set on targetField, otherwise the value is only propagated on later field changes.
◆ attachField() [3/5]
| void ml::Field::attachField | ( | NotifyField * | targetField | ) |
◆ attachField() [4/5]
| void ml::Field::attachField | ( | OutputConnectorField * | targetField | ) |
This calls attachField(targetField, false).
Attaching without a second parameter is allowed only for OutputConnectorFields, BaseFields, NotifyField and SoNode fields. If you encounter code which does not build because a different Field class is passed, then change your code to handle field changes in Module::handleNotification() instead.
◆ attachField() [5/5]
| void ml::Field::attachField | ( | SoNodeField * | targetField | ) |
◆ attachFieldSensor()
| void ml::Field::attachFieldSensor | ( | FieldSensor * | sensor | ) |
Attaches a field sensor sensor of this class instance in both directions.
◆ attachSourceField()
|
protected |
Inserts a field as source field in this instance, i.e., from now on *this might receive values and/or notifications from that field.
◆ copyCStringValue()
| void ml::Field::copyCStringValue | ( | char * | valueBuffer, |
| MLint | bufferSize ) |
Copies the value of the field (as character string) into the specified buffer valueBuffer.
The maximum bufferSize is considered and the value is copied only partially if necessary.
◆ detachAllFields()
| void ml::Field::detachAllFields | ( | ) |
Disconnects all source and target fields of this instance in both directions.
◆ detachDestinationFields()
| void ml::Field::detachDestinationFields | ( | ) |
Disconnects all target fields of this instance in both directions.
◆ detachField()
| void ml::Field::detachField | ( | Field * | targetField | ) |
Disconnects connections between target field targetField and this instance.
◆ detachFieldInternal()
|
protected |
Only remove the given field from the destination list.
◆ detachFieldSensor()
| void ml::Field::detachFieldSensor | ( | FieldSensor * | sensor | ) |
Detaches the field sensor sensor of this class instance in both directions.
◆ detachFieldSensors()
| void ml::Field::detachFieldSensors | ( | ) |
Detaches all field sensors of this class instance in both directions.
◆ detachSourceField()
|
protected |
Removes a source field from this instance. If not found then this call does nothing.
◆ detachSourceFields()
| void ml::Field::detachSourceFields | ( | ) |
Disconnects all source fields of this instance in both directions.
◆ enableNotifications()
| void ml::Field::enableNotifications | ( | bool | flag | ) |
Enables or disables notification of attached fields and field sensors when the field value is set or notified (by notifyAttachments() or set*Value() -methods), depending on the parameter flag.
◆ enableNotificationsCounterState()
|
static |
Provides read/write access to the current counter state (see enableNotificationsGlobally(bool) ).
Please use this only if you have a detailed understanding of the internal ML programming!
◆ enableNotificationsGlobally()
|
static |
Enables or disables globally the notification mechanism for all fields and field sensors when field values are set or notified (by notifyAttachments() or set*Value() methods), depending on the parameter flag.
Calls can be nested since internally a counter is used for enabling/disabling. Please use this only if you have a detailed understanding of the internal ML programming!
◆ getCStringValueSize()
|
inline |
◆ getDestinationField()
| Field * ml::Field::getDestinationField | ( | size_t | index | ) |
Returns destination field at index. Returns NULL if index is out of range.
◆ getFieldContainer()
|
inline |
◆ getFullName()
| std::string ml::Field::getFullName | ( | ) | const |
Returns "fieldContainerType(instanceName).fieldName" (if field container is available, otherwise only field name is returned).
(mainly useful for debugging/error prints)
◆ getName()
|
inline |
◆ getNumDestinationFields()
| size_t ml::Field::getNumDestinationFields | ( | ) |
Returns the number of destination fields which could receive notifications or value sets.
◆ getNumSourceFields()
| size_t ml::Field::getNumSourceFields | ( | ) |
Returns the number of source fields which could send notifications or value sets.
◆ getSourceField()
| Field * ml::Field::getSourceField | ( | size_t | index | ) |
Returns the source field at index. Returns NULL if index is out of range.
◆ getStringValue()
|
pure virtual |
Returns the value of the field as string value.
IMPORTANT: The returned string is a temporary local string which is only valid while evaluating the calling expression. setStringValue must be able to interpret this returned string correctly. Must be implemented in derived class.
Implemented in ml::BoolField, ml::IntField, ml::EnumField, ml::FloatField, ml::DoubleField, ml::StringField, ml::NotifyField, ml::OutputConnectorField, ml::InputConnectorField, ml::BaseField, ml::SoNodeField, ml::PointerField, ml::Vector2Field, ml::Vector3Field, ml::Vector4Field, ml::Vector5Field, ml::Vector6Field, ml::Vector10Field, ml::Matrix2Field, ml::Matrix3Field, ml::MatrixField, ml::Matrix5Field, ml::Matrix6Field, ml::MLDataTypeField, ml::ImageVectorField, ml::SubImageBoxField, ml::SubImageBoxdField, ml::UniversalTypeField, ml::ListField< T >, ml::ListField< double >, ml::ListField< MLint >, ml::ListField< Vector2 >, ml::ListField< Vector3 >, and ml::ListField< Vector4 >.
Referenced by ml::StringField::getValue().
◆ isOutputOnly()
| bool ml::Field::isOutputOnly | ( | ) | const |
Returns if this field is marked as pure output field.
◆ isValidValue()
|
inlinevirtual |
Returns true (=1) if the field's value is valid; otherwise false (=0) is returned.
The default implementation always returns 1 (= true). Must be overloaded in derived class if value is not always valid.
Reimplemented in ml::OutputConnectorField, ml::InputConnectorField, and ml::UniversalTypeField.
◆ setName()
|
inline |
◆ setOutputOnly()
| void ml::Field::setOutputOnly | ( | bool | outputOnly = true | ) |
Mark field as a pure output field that is never read by its module.
◆ setStringValue()
|
pure virtual |
Set field value as string value.
Must be implemented in derived class.
Implemented in ml::NotifyField, ml::OutputConnectorField, ml::InputConnectorField, ml::FloatField, ml::DoubleField, ml::StringField, ml::BaseField, ml::SoNodeField, ml::PointerField, ml::Vector2Field, ml::Vector3Field, ml::Vector4Field, ml::Vector5Field, ml::Vector6Field, ml::Vector10Field, ml::Matrix2Field, ml::Matrix3Field, ml::MatrixField, ml::Matrix5Field, ml::Matrix6Field, ml::MLDataTypeField, ml::ImageVectorField, ml::SubImageBoxField, ml::SubImageBoxdField, ml::UniversalTypeField, ml::BoolField, ml::IntField, ml::EnumField, ml::ListField< T >, ml::ListField< double >, ml::ListField< MLint >, ml::ListField< Vector2 >, ml::ListField< Vector3 >, and ml::ListField< Vector4 >.
Referenced by ml::StringField::setValue().
◆ setValueFromField()
|
protectedvirtual |
Sets the value of this field from the given field.
The default implementation just does a setStringValue(field.getStringValue())), but it can be derived in subclasses to avoid the string conversion.
Reimplemented in ml::BoolField, ml::IntField, ml::FloatField, ml::DoubleField, ml::BaseField, ml::SoNodeField, ml::Vector2Field, ml::Vector3Field, ml::Vector4Field, ml::Vector5Field, ml::Vector6Field, ml::Vector10Field, ml::Matrix2Field, ml::Matrix3Field, ml::MatrixField, ml::Matrix5Field, ml::Matrix6Field, ml::ImageVectorField, ml::SubImageBoxField, ml::SubImageBoxdField, ml::IntListField, ml::DoubleListField, ml::Vector2ListField, ml::Vector3ListField, and ml::Vector4ListField.
◆ touch()
|
virtual |
Notifies all connected fields and field sensors.
First for all callback methods of connected field sensors are called, and then all notify methods of all connected fields. Note: Fields connected to connected fields are also recursively updated. The cyclic notifications which can occur in this case are suppressed by temporary flags within fields. Fields which are already within a chain of notified fields are not notified again. The parameter strength indicates how strong the primary notification starting from this field is. The default is CHANGED which means that the observed subject has been changed. Using NO_CHANGE e.g., means that only a notification is desired but no change which e.g., means that output fields of Modules are not reset. Note that strength has nothing to do with value transfer to attached fields!
Reimplemented in ml::OutputConnectorField.
Friends And Related Symbol Documentation
◆ FieldContainer
|
friend |
Member Data Documentation
◆ _destinationFields
|
protected |
◆ _enableNotifications
|
staticprotected |
◆ _fieldContainer
|
protected |
◆ _flags
◆ _name
|
protected |
◆ _sensors
|
protected |
◆ _sourceFields
|
protected |
The documentation for this class was generated from the following file:
- MeVis/Foundation/Sources/ML/include/mlField.h
