ML Reference
ml::EnumField Class Reference

Field to encapsulate an enumerated value. More...

#include <mlFields.h>

Inheritance diagram for ml::EnumField:
ml::Field ml::TypedEnumField< EnumType >

Classes

struct  EnumEntry
 Defines the entry for one enum value. More...
 

Public Member Functions

 EnumField (const std::string &name, const std::string enumerationItemNames[], size_t numEnumerationItems)
 Implements the runtime type system interface for this class. More...
 
 EnumField (const std::string &name, const char *const *enumerationItemNames, size_t numEnumerationItems)
 Constructor, creates a field with a name to manage an enum value. More...
 
 EnumField (const std::string &name, const std::vector< std::string > &enumerationItemNames)
 Constructor, creates a field with a name to manage an enum value. More...
 
 ~EnumField () override
 Destroys this field and releases internally allocated memory. More...
 
void setStringValue (const std::string &value) override
 Sets value of the field to the enum item with given name value. More...
 
void setStringValueDefaulted (const std::string &value)
 If value equals one of the enum item names, set the field to this item, otherwise set it to the first item of the enum. More...
 
void setEnumValue (int enumValue)
 Sets field value to enumValue. More...
 
void updateEnumValue (int enumValue)
 Sets field value to enumValue, but only touch field if the new value is different from the old value. More...
 
std::string getStringValue () const override
 Returns the value of the field as string value. More...
 
int getEnumValue () const
 Returns the current enum value as integer. More...
 
const EnumEntrygetEnumEntryAtIndex (size_t index) const
 Returns the enum entry at given index, which allows to enumerate all existing enum entries. More...
 
size_t getNumEnumerationItems () const
 Returns the number of registered enum values defined in constructor. More...
 
void setValue (int enumValue)
 Same as setEnumValue(). More...
 
void updateValue (int enumValue)
 Same as updateEnumValue(). More...
 
int getValue () const
 Same as getEnumValue(). More...
 
- Public Member Functions inherited from ml::Field
 Field (const std::string &name=std::string())
 Constructor: Creates a field with name. More...
 
virtual ~Field ()
 Destructor: Destroy field and remove all connection to fields an sensors. More...
 
FieldContainergetFieldContainer () const
 Get the field container of the field (which may be NULL). More...
 
const std::string & getName () const
 Returns name of field. More...
 
void setName (const std::string &name)
 Sets the name of field. Should be called only once after or while construction. More...
 
std::string getFullName () const
 Returns "fieldContainerType(instanceName).fieldName" (if field container is available, otherwise only field name is returned). More...
 
bool isOutputOnly () const
 Returns if this field is marked as pure output field. More...
 
void setOutputOnly (bool outputOnly=true)
 Mark field as a pure output field that is never read by its module. More...
 
virtual MLint isValidValue ()
 Returns true (=1) if the field's value is valid; otherwise false (=0) is returned. More...
 
void copyCStringValue (char *valueBuffer, MLint bufferSize)
 Copies the value of the field (as character string) into the specified buffer valueBuffer. More...
 
MLint getCStringValueSize ()
 Returns the length of the character string of the string value of the field. More...
 
void attachFieldSensor (FieldSensor *sensor)
 Attaches a field sensor sensor of this class instance in both directions. More...
 
void detachFieldSensor (FieldSensor *sensor)
 Detaches the field sensor sensor of this class instance in both directions. More...
 
void detachFieldSensors ()
 Detaches all field sensors of this class instance in both directions. More...
 
void attachField (OutputConnectorField *targetField)
 This calls attachField(targetField, false). More...
 
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. More...
 
void detachField (Field *targetField)
 Disconnects connections between target field targetField and this instance. More...
 
void detachSourceFields ()
 Disconnects all source fields of this instance in both directions. More...
 
void detachDestinationFields ()
 Disconnects all target fields of this instance in both directions. More...
 
void detachAllFields ()
 Disconnects all source and target fields of this instance in both directions. More...
 
size_t getNumDestinationFields ()
 Returns the number of destination fields which could receive notifications or value sets. More...
 
FieldgetDestinationField (size_t index)
 Returns destination field at index. Returns NULL if index is out of range. More...
 
size_t getNumSourceFields ()
 Returns the number of source fields which could send notifications or value sets. More...
 
FieldgetSourceField (size_t index)
 Returns the source field at index. Returns NULL if index is out of range. More...
 
virtual void touch (FieldSensor::Strength strength=FieldSensor::CHANGED)
 Notifies all connected fields and field sensors. More...
 
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. More...
 
bool areNotificationsEnabled ()
 Returns whether the notification mechanism for this field (e.g., when field values are set) is enabled (see enableNotifications(bool) ). More...
 

Protected Member Functions

void _initialize (const std::string &name="", size_t numEnums=0, int *valuePtr=nullptr)
 Initializes this field. More...
 
void _setEnumerationNames (const std::string enumNames[])
 Sets the enumeration item names. More...
 
void _setEnumerationNames (const char *const *enumNames)
 Sets the enumeration item names. More...
 
void _setEnumerationNames (const std::vector< std::string > &enumNames)
 Sets the enumeration item names. More...
 
void _setEnumerationNames (const std::vector< EnumField::EnumEntry > &enumValues, int initialValue)
 Sets the enumeration item names. More...
 
 EnumField ()
 Protected constructor to allow derived classes. More...
 
- Protected Member Functions inherited from ml::Field
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. More...
 
void detachSourceField (Field *field)
 Removes a source field from this instance. If not found then this call does nothing. More...
 
void detachFieldInternal (Field *field)
 Only remove the given field from the destination list. More...
 
virtual void setValueFromField (const Field &field)
 Sets the value of this field from the given field. More...
 

Protected Attributes

int * _valuePtr
 Points to the variable containing the field value; we use an integer to be compatible to normal enum types. More...
 
int _internalValue
 Stores the int value (if no external deprecated reference was given). More...
 
bool _linearEntries
 Stores if enum entry values start at 0 and increase by 1. More...
 
std::vector< EnumEntry_entries
 Stores the possible enum values and names. More...
 
- Protected Attributes inherited from ml::Field
std::string _name
 The name of this field. More...
 
std::vector< FieldSensor * > _sensors
 List of field sensors. More...
 
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. More...
 
std::vector< Field * > _sourceFields
 List of (source) fields, which will notify this field or which will copy their value to this field. More...
 
FieldContainer_fieldContainer
 The owning field container. More...
 
Flags _flags
 

Additional Inherited Members

- Static Public Member Functions inherited from ml::Field
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. More...
 
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. More...
 
static MLintenableNotificationsCounterState ()
 Provides read/write access to the current counter state (see enableNotificationsGlobally(bool) ). More...
 
- Static Protected Attributes inherited from ml::Field
static MLint _enableNotifications
 Flag which disables the notification process of field (sensors) globally. More...
 

Detailed Description

Field to encapsulate an enumerated value.

Definition at line 362 of file mlFields.h.

Constructor & Destructor Documentation

◆ EnumField() [1/4]

ml::EnumField::EnumField ( const std::string &  name,
const std::string  enumerationItemNames[],
size_t  numEnumerationItems 
)

Implements the runtime type system interface for this class.

Constructor, creates a field with a name to manage an enum value. The value range for the enum value is [0, numEnumerationItems-1]. The value names are defined by enumerationItemNames. The maximum number of enum entries is ML_INT32_MAX, minimum is 1; exceeding that will lead to fatal errors, even on 64 bit systems. Note that enumerationItemNames must contain at least numEnumerationItems string values.

◆ EnumField() [2/4]

ml::EnumField::EnumField ( const std::string &  name,
const char *const *  enumerationItemNames,
size_t  numEnumerationItems 
)

Constructor, creates a field with a name to manage an enum value.

The value range for the enum value is [0, numEnumerationItems-1]. The value names are defined by enumerationItemNames. The maximum number of enum entries is ML_INT32_MAX, minimum is 1; exceeding that will lead to fatal errors, even on 64 bit systems. Note that enumerationItemNames must contain at least numEnumerationItems string values.

◆ EnumField() [3/4]

ml::EnumField::EnumField ( const std::string &  name,
const std::vector< std::string > &  enumerationItemNames 
)

Constructor, creates a field with a name to manage an enum value.

The field creates the value buffer internally. The value range for the enum value is [0, enumerationItemNames.size-1]. The value names are defined by enumerationItemNames. The maximum number of enum entries is ML_INT32_MAX, minimum is 1; exceeding that will lead to fatal errors, even on 64 bit systems. The default enum value is 0.

◆ ~EnumField()

ml::EnumField::~EnumField ( )
override

Destroys this field and releases internally allocated memory.

◆ EnumField() [4/4]

ml::EnumField::EnumField ( )
inlineprotected

Protected constructor to allow derived classes.

Definition at line 480 of file mlFields.h.

Member Function Documentation

◆ _initialize()

void ml::EnumField::_initialize ( const std::string &  name = "",
size_t  numEnums = 0,
int *  valuePtr = nullptr 
)
protected

Initializes this field.

◆ _setEnumerationNames() [1/4]

void ml::EnumField::_setEnumerationNames ( const char *const *  enumNames)
protected

Sets the enumeration item names.

◆ _setEnumerationNames() [2/4]

void ml::EnumField::_setEnumerationNames ( const std::string  enumNames[])
protected

Sets the enumeration item names.

◆ _setEnumerationNames() [3/4]

void ml::EnumField::_setEnumerationNames ( const std::vector< EnumField::EnumEntry > &  enumValues,
int  initialValue 
)
protected

Sets the enumeration item names.

◆ _setEnumerationNames() [4/4]

void ml::EnumField::_setEnumerationNames ( const std::vector< std::string > &  enumNames)
protected

Sets the enumeration item names.

◆ getEnumEntryAtIndex()

const EnumEntry& ml::EnumField::getEnumEntryAtIndex ( size_t  index) const

Returns the enum entry at given index, which allows to enumerate all existing enum entries.

Allowed indices are [0 - getNumEnumerationItems()-1]. No bounds check is performed!

◆ getEnumValue()

int ml::EnumField::getEnumValue ( ) const

Returns the current enum value as integer.

◆ getNumEnumerationItems()

size_t ml::EnumField::getNumEnumerationItems ( ) const

Returns the number of registered enum values defined in constructor.

◆ getStringValue()

std::string ml::EnumField::getStringValue ( ) const
overridevirtual

Returns the value of the field as string value.

setStringValue must be able to interpret this returned string correctly. On invalid enumValues the first string item is returned.

Implements ml::Field.

◆ getValue()

int ml::EnumField::getValue ( ) const
inline

Same as getEnumValue().

Definition at line 449 of file mlFields.h.

◆ setEnumValue()

void ml::EnumField::setEnumValue ( int  enumValue)

Sets field value to enumValue.

◆ setStringValue()

void ml::EnumField::setStringValue ( const std::string &  value)
overridevirtual

Sets value of the field to the enum item with given name value.

If the value enum item is not found, the call is ignored. The comparison is done case-sensitive.

Implements ml::Field.

◆ setStringValueDefaulted()

void ml::EnumField::setStringValueDefaulted ( const std::string &  value)

If value equals one of the enum item names, set the field to this item, otherwise set it to the first item of the enum.

◆ setValue()

void ml::EnumField::setValue ( int  enumValue)
inline

Same as setEnumValue().

Definition at line 443 of file mlFields.h.

◆ updateEnumValue()

void ml::EnumField::updateEnumValue ( int  enumValue)

Sets field value to enumValue, but only touch field if the new value is different from the old value.

◆ updateValue()

void ml::EnumField::updateValue ( int  enumValue)
inline

Same as updateEnumValue().

Definition at line 446 of file mlFields.h.

Member Data Documentation

◆ _entries

std::vector<EnumEntry> ml::EnumField::_entries
protected

Stores the possible enum values and names.

Definition at line 476 of file mlFields.h.

◆ _internalValue

int ml::EnumField::_internalValue
protected

Stores the int value (if no external deprecated reference was given).

Definition at line 470 of file mlFields.h.

◆ _linearEntries

bool ml::EnumField::_linearEntries
protected

Stores if enum entry values start at 0 and increase by 1.

Definition at line 473 of file mlFields.h.

◆ _valuePtr

int* ml::EnumField::_valuePtr
protected

Points to the variable containing the field value; we use an integer to be compatible to normal enum types.

Definition at line 467 of file mlFields.h.


The documentation for this class was generated from the following file: