From ef1984714ae883f010cbe4b278c0c33d7c0f2c42 Mon Sep 17 00:00:00 2001 From: stv Date: Fri, 11 Aug 2006 11:32:18 +0000 Subject: [PATCH] Source code comments added for classes of package DDS --- src/DDS/DDS_DicGroup.cxx | 38 +++++- src/DDS/DDS_DicItem.cxx | 139 ++++++++++++++++++-- src/DDS/DDS_DicItem.h | 80 +++--------- src/DDS/DDS_Dictionary.cxx | 258 ++++++++++++++++++++++++++++++++++++- src/DDS/DDS_Dictionary.h | 3 - src/DDS/DDS_KeyWords.cxx | 66 ++++++++++ src/DDS/DDS_KeyWords.h | 2 +- 7 files changed, 496 insertions(+), 90 deletions(-) diff --git a/src/DDS/DDS_DicGroup.cxx b/src/DDS/DDS_DicGroup.cxx index 4ecf18b3e..56197a523 100644 --- a/src/DDS/DDS_DicGroup.cxx +++ b/src/DDS/DDS_DicGroup.cxx @@ -33,6 +33,15 @@ IMPLEMENT_STANDARD_HANDLE(DDS_DicGroup, MMgt_TShared) IMPLEMENT_STANDARD_RTTIEXT(DDS_DicGroup, MMgt_TShared) +/*! + \class DDS_DicGroup + + This class to provide set of DDS_DicItem objects from one component. +*/ + +/*! + Constructor. Create the group with name \aname. +*/ DDS_DicGroup::DDS_DicGroup( const TCollection_AsciiString& name ) : MMgt_TShared(), myName( name ), @@ -40,15 +49,25 @@ myActiveSystem( UNIT_SYSTEM_SI ) { } +/*! + Copy constructor. +*/ DDS_DicGroup::DDS_DicGroup( const DDS_DicGroup& ) { } +/*! + Get the name of group (component). +*/ TCollection_AsciiString DDS_DicGroup::GetName() const { return myName; } +/*! + Returns the names list of defined unit systems. + Parameter \atheSystems will contains the sequence of string names. +*/ void DDS_DicGroup::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystemSeq ) const { theSystemSeq.Clear(); @@ -61,6 +80,9 @@ void DDS_DicGroup::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystemSeq ) } } +/*! + Returns the label of unit system \aname. If unit system not found then empty string returned. +*/ TCollection_ExtendedString DDS_DicGroup::GetUnitSystemLabel( const TCollection_AsciiString& name ) const { TCollection_ExtendedString aLabel; @@ -69,21 +91,33 @@ TCollection_ExtendedString DDS_DicGroup::GetUnitSystemLabel( const TCollection_A return aLabel; } +/*! + Gets the name of active unit system. +*/ TCollection_AsciiString DDS_DicGroup::GetActiveUnitSystem() const { return myActiveSystem; } +/*! + Sets the name of active unit system. +*/ void DDS_DicGroup::SetActiveUnitSystem( const TCollection_AsciiString& theSystem ) { if ( myUnitSystem.IsBound( theSystem ) ) myActiveSystem = theSystem; } +/*! + Assignment operator. +*/ void DDS_DicGroup::operator=( const DDS_DicGroup& ) { } +/*! + Fill the internal data structures from XML parsed structures. Internal. +*/ void DDS_DicGroup::FillDataMap( const LDOM_Element& theComponentData, const LDOM_Element& theDocElement ) { TCollection_AsciiString aCompName = theComponentData.getAttribute( DDS_Dictionary::KeyWord( "COMPONENT_NAME" ) ); @@ -140,9 +174,9 @@ void DDS_DicGroup::FillDataMap( const LDOM_Element& theComponentData, const LDOM } /*! - Returns DicItem with all attached data + Gets dictionary item with specified identifier \atheID. + If dictionary item not found then null handle returned. */ - Handle(DDS_DicItem) DDS_DicGroup::GetDicItem( const TCollection_AsciiString& theID ) const { Handle(DDS_DicItem) aDicItem; diff --git a/src/DDS/DDS_DicItem.cxx b/src/DDS/DDS_DicItem.cxx index 1582aab3f..12b2a0fd9 100644 --- a/src/DDS/DDS_DicItem.cxx +++ b/src/DDS/DDS_DicItem.cxx @@ -35,6 +35,15 @@ IMPLEMENT_STANDARD_HANDLE(DDS_DicItem, MMgt_TShared) IMPLEMENT_STANDARD_RTTIEXT(DDS_DicItem, MMgt_TShared) +/*! + \class DDS_DicItem + + This class to provide information about datum (phisical characteristic parameter). +*/ + +/*! + Constructor. Creates the instance of empty dictionary item. +*/ DDS_DicItem::DDS_DicItem() : myType( 0 ), myDefValue( 0 ), @@ -46,54 +55,87 @@ myZoomOrder( 2 ) { } +/*! + Copy constructor. Internal. +*/ DDS_DicItem::DDS_DicItem( const DDS_DicItem& ) { } +/*! + Assignment operator. Internal. +*/ void DDS_DicItem::operator=( const DDS_DicItem& ) { } +/*! + Gets the identifier of parameter. +*/ TCollection_AsciiString DDS_DicItem::GetId() const { return myId; } +/*! + Gets the type of parameter. +*/ DDS_DicItem::Type DDS_DicItem::GetType() const { return (DDS_DicItem::Type)myType; } +/*! + Gets the label of the parameter. +*/ TCollection_ExtendedString DDS_DicItem::GetLabel() const { return myLabel; } +/*! + Gets the filter (regular expression) for the parameter values. +*/ TCollection_ExtendedString DDS_DicItem::GetFilter() const { return myFilter; } +/*! + Gets the Required attribute of the parameter. +*/ TCollection_ExtendedString DDS_DicItem::GetRequired() const { return myRequired; } +/*! + Gets the wrong value warning level of the parameter. +*/ DDS_MsgType DDS_DicItem::GetWarningLevel() const { return (DDS_MsgType)myWarnLevel; } +/*! + Gets the long description of the parameter. +*/ TCollection_ExtendedString DDS_DicItem::GetLongDescription() const { return myLongDescr; } +/*! + Gets the short description of the parameter. +*/ TCollection_ExtendedString DDS_DicItem::GetShortDescription() const { return myShortDescr; } +/*! + Gets the name of component - owner of parameter. +*/ TCollection_AsciiString DDS_DicItem::GetComponent() const { TCollection_AsciiString aCompName; @@ -103,11 +145,18 @@ TCollection_AsciiString DDS_DicItem::GetComponent() const return aCompName; } +/*! + Gets the parameter unit of measure for active unit system. +*/ TCollection_AsciiString DDS_DicItem::GetUnits() const { return GetUnits( GetActiveUnitSystem() ); } +/*! + Gets the parameter unit of measure for specified unit system \atheSystem. + If specified unit system doesn't exist then empty string returned. +*/ TCollection_AsciiString DDS_DicItem::GetUnits( const UnitSystem& theSystem ) const { TCollection_AsciiString anUnits; @@ -117,31 +166,54 @@ TCollection_AsciiString DDS_DicItem::GetUnits( const UnitSystem& theSystem ) con return anUnits; } +/*! + Gets the minimum value of parameter for active unit system. + Returned value converted to SI. +*/ Standard_Real DDS_DicItem::GetMinValue() const { return GetMinValue( GetActiveUnitSystem() ); } +/*! + Gets the minimum value of parameter for specified unit system \atheSystem. + Returned value converted to SI. +*/ Standard_Real DDS_DicItem::GetMinValue( const UnitSystem& theUnitsSystem ) const { return FromSI( myMin, theUnitsSystem ); } +/*! + Gets the maximum value of parameter for active unit system. + Returned value converted to SI. +*/ Standard_Real DDS_DicItem::GetMaxValue() const { return GetMaxValue( GetActiveUnitSystem() ); } +/*! + Gets the maximum value of parameter for specified unit system \atheSystem. + Returned value converted to SI. +*/ Standard_Real DDS_DicItem::GetMaxValue( const UnitSystem& theUnitsSystem ) const { return FromSI( myMax, theUnitsSystem ); } +/*! + Gets the precision (number of digit after decimal point) of parameter for active unit system. +*/ Standard_Integer DDS_DicItem::GetPrecision() const { return GetPrecision( GetActiveUnitSystem() ); } +/*! + Gets the precision (number of digit after decimal point) of parameter for specified + unit system \atheSystem. If specified unit system doesn't exist then zero returned. +*/ Standard_Integer DDS_DicItem::GetPrecision( const UnitSystem& theSystem ) const { Standard_Integer aRes = 0; @@ -151,11 +223,21 @@ Standard_Integer DDS_DicItem::GetPrecision( const UnitSystem& theSystem ) const return aRes; } +/*! + Gets the default value of parameter for active unit system. Default value returned as string. + If type of value is numeric (Float or Integer) and default value defined then returned number + converted to SI. +*/ TCollection_ExtendedString DDS_DicItem::GetDefaultValue() const { return GetDefaultValue( GetActiveUnitSystem() ); } +/*! + Gets the default value of parameter for specified unit system \atheSystem. Default value returned + as string. If type of value is numeric (Float or Integer) and default value defined then returned + number converted to SI. +*/ TCollection_ExtendedString DDS_DicItem::GetDefaultValue( const UnitSystem& theSystem ) const { if ( !myDefString.Length() ) @@ -179,11 +261,21 @@ TCollection_ExtendedString DDS_DicItem::GetDefaultValue( const UnitSystem& theSy return aStr; } +/*! + Gets the format string of parameter for active unit system. If argument \atheCanonical + is true then format string will be reduced to sprintf() specification (without extra + non standard qualifiers). +*/ TCollection_AsciiString DDS_DicItem::GetFormat( const Standard_Boolean theCanonical ) const { return GetFormat( GetActiveUnitSystem(), theCanonical ); } +/*! + Gets the format string of parameter for specified unit system \atheSystem. If argument + \atheCanonical is true then format string will be reduced to sprintf() specification + (without extra non standard qualifiers). +*/ TCollection_AsciiString DDS_DicItem::GetFormat( const UnitSystem& theSystem, const Standard_Boolean theCanonical ) const { @@ -212,8 +304,8 @@ TCollection_AsciiString DDS_DicItem::GetFormat( const UnitSystem& theSystem, } /*! - Access valueList:name of the parameter. This string is void if the list is - not defined - then use other properties: Type, DefaultValue, MaxValue, MinValue + Gets name of a list referenced by the parameter. This string is empty if the list + refernce is not defined - then use other properties: Type, DefaultValue, MaxValue, MinValue */ TCollection_ExtendedString DDS_DicItem::GetNameOfValues() const { @@ -221,8 +313,8 @@ TCollection_ExtendedString DDS_DicItem::GetNameOfValues() const } /*! - Access valueList of the parameter. This sequence is empty if the list is - not defined - then use other properties: Type, DefaultValue, MaxValue, MinValue + Gets item names and item ids of a list referenced by the parameter. This sequences is empty if + the list reference is not defined - then use other properties: Type, DefaultValue, MaxValue, MinValue */ Standard_Boolean DDS_DicItem::GetListOfValues( Handle(TColStd_HArray1OfExtendedString)& theStrings, Handle(TColStd_HArray1OfInteger)& theIntegers ) const @@ -233,8 +325,8 @@ Standard_Boolean DDS_DicItem::GetListOfValues( Handle(TColStd_HArray1OfExtendedS } /*! - Access valueList of the parameter. This sequence is empty if the list is not - defined - then use other properties: Type, DefaultValue, MaxValue, MinValue + Gets item names, item ids and item icons of a list referenced by the parameter. This sequences is empty + if the list reference is not defined - then use other properties: Type, DefaultValue, MaxValue, MinValue */ Standard_Boolean DDS_DicItem::GetListOfValues( Handle(TColStd_HArray1OfExtendedString)& theStrings, Handle(TColStd_HArray1OfInteger)& theIntegers, @@ -246,6 +338,10 @@ Standard_Boolean DDS_DicItem::GetListOfValues( Handle(TColStd_HArray1OfExtendedS return !theIntegers.IsNull() && !theStrings.IsNull() && !theIcons.IsNull(); } + +/*! + Gets special values of the parameter. +*/ Standard_Boolean DDS_DicItem::GetSpecialValues( TColStd_MapOfReal& theMap ) const { theMap.Clear(); @@ -266,7 +362,7 @@ Standard_Boolean DDS_DicItem::GetSpecialValues( TColStd_MapOfReal& theMap ) cons } /*! - Returns min value of lateral zooming + Gets minimum value of lateral zooming */ Standard_Real DDS_DicItem::GetMinZoom() const { @@ -274,7 +370,7 @@ Standard_Real DDS_DicItem::GetMinZoom() const } /*! - Returns Max Value of lateral zooming + Gets maximum value of lateral zooming */ Standard_Real DDS_DicItem::GetMaxZoom() const { @@ -282,25 +378,31 @@ Standard_Real DDS_DicItem::GetMaxZoom() const } /*! - Get Order of lateral zooming + Gets order of lateral zooming */ Standard_Real DDS_DicItem::GetZoomOrder() const { return myZoomOrder; } +/*! + Convert value \atheVal to default SI units according to active unit system. +*/ Standard_Real DDS_DicItem::ToSI( const Standard_Real theVal ) const { return ToSI( theVal, GetActiveUnitSystem() ); } +/*! + Convert value \atheVal from default SI units according to active unit system. +*/ Standard_Real DDS_DicItem::FromSI( const Standard_Real theVal ) const { return FromSI( theVal, GetActiveUnitSystem() ); } /*! - Convert value to default SI units according to current units + Convert value to default SI units according to unit system \atheUnitsSystem. */ Standard_Real DDS_DicItem::ToSI( const Standard_Real theVal, const UnitSystem& theUnitsSystem ) const { @@ -312,7 +414,7 @@ Standard_Real DDS_DicItem::ToSI( const Standard_Real theVal, const UnitSystem& t } /*! - Convert value from default SI units according to current units + Convert value from default SI units according to unit system \atheUnitsSystem. */ Standard_Real DDS_DicItem::FromSI( const Standard_Real theVal, const UnitSystem& theUnitsSystem ) const { @@ -324,7 +426,7 @@ Standard_Real DDS_DicItem::FromSI( const Standard_Real theVal, const UnitSystem& } /*! - Returns 'true' if specified data exist. + Returns 'true' if data specified by \aflag exist. */ Standard_Boolean DDS_DicItem::HasData( const Standard_Integer flag ) const { @@ -332,7 +434,7 @@ Standard_Boolean DDS_DicItem::HasData( const Standard_Integer flag ) const } /*! - Parse record in XML file and retrieve information relevant for this data dic item + Parse record in XML file and retrieve information relevant for this dictionary item */ void DDS_DicItem::FillDataMap( TCollection_AsciiString theID, const LDOM_Element& theDatum, const LDOM_Element& theCompElement, const LDOM_Element& theDocElement, @@ -793,7 +895,7 @@ void DDS_DicItem::GetFloatFormat( const TCollection_AsciiString& theFlags, } /*! - Prepares three formants for each unit systems + Prepares formats for each unit systems */ void DDS_DicItem::PrepareFormats( const TCollection_AsciiString& theFormat ) { @@ -915,6 +1017,9 @@ void DDS_DicItem::PrepareFormats( const TCollection_AsciiString& theFormat ) } } +/*! + Split the string \atheStr by spaces and returns substrings in array \aaRes. +*/ void DDS_DicItem::Split( const TCollection_AsciiString& theStr, Handle(TColStd_HArray1OfExtendedString)& aRes ) { aRes.Nullify(); @@ -946,6 +1051,9 @@ void DDS_DicItem::Split( const TCollection_AsciiString& theStr, Handle(TColStd_H } } +/*! + Returns unit structure for given unit system \asys. +*/ DDS_DicItem::UnitData* DDS_DicItem::GetUnitData( const UnitSystem& sys ) const { UnitData* unit = 0; @@ -956,6 +1064,9 @@ DDS_DicItem::UnitData* DDS_DicItem::GetUnitData( const UnitSystem& sys ) const return unit; } +/*! + Gets the active unit system. +*/ DDS_DicItem::UnitSystem DDS_DicItem::GetActiveUnitSystem() const { UnitSystem aSystem; diff --git a/src/DDS/DDS_DicItem.h b/src/DDS/DDS_DicItem.h index 36b30811e..0b9746a6c 100644 --- a/src/DDS/DDS_DicItem.h +++ b/src/DDS/DDS_DicItem.h @@ -47,8 +47,23 @@ class TColStd_SequenceOfExtendedString; class DDS_DicItem : public MMgt_TShared { public: - enum Type { String, Float, Integer, List, Unknown }; - enum Data { MinValue = 0x01, MaxValue = 0x02, DefaultValue = 0x04 }; + /*! Enum describes type of datum value */ + enum Type + { + String, //!< String type of value + Float, //!< Real (double) numeric type of value + Integer, //!< Integer (int) numeric type of value + List, //!< List type of enumerable value + Unknown //!< Unknown or undefined type of value + }; + + /*! Enum describes the flags for existance of domain data */ + enum Data + { + MinValue = 0x01, //!< Flag of minimum value definition existence + MaxValue = 0x02, //!< Flag of maximum value definition existence + DefaultValue = 0x04 //!< Flag of default value definition existence + }; // This struct is intended for map of Format, Units, Precision and Scale struct UnitData @@ -66,114 +81,61 @@ public: DDS_DicItem(); Standard_EXPORT TCollection_AsciiString GetId() const; - // to access Type of the parameter - Standard_EXPORT DDS_DicItem::Type GetType() const; - // to access Type of the parameter - Standard_EXPORT TCollection_ExtendedString GetLabel() const; - // to access Label (name) of the parameter - Standard_EXPORT TCollection_ExtendedString GetFilter() const; - // to access filter (regexp) for the parameter values - Standard_EXPORT TCollection_ExtendedString GetRequired() const; - // to access Required of the parameter - Standard_EXPORT DDS_MsgType GetWarningLevel() const; - // to access wrong value warning level of the parameter - Standard_EXPORT TCollection_ExtendedString GetLongDescription() const; - // to access Long Description of the parameter - Standard_EXPORT TCollection_ExtendedString GetShortDescription() const; - // to access Short Description of the parameter - Standard_EXPORT TCollection_AsciiString GetComponent() const; Standard_EXPORT TCollection_AsciiString GetUnits() const; Standard_EXPORT TCollection_AsciiString GetUnits( const UnitSystem& ) const; - // returns units for indicated unit systems Standard_EXPORT TCollection_ExtendedString GetDefaultValue() const; Standard_EXPORT TCollection_ExtendedString GetDefaultValue( const UnitSystem& ) const; - // to access Default Value of the parameter Standard_EXPORT Standard_Real GetMinValue() const; Standard_EXPORT Standard_Real GetMinValue( const UnitSystem& ) const; - // get Min Value of the parameter, either in specified unit system or in internal units (basic SI) Standard_EXPORT Standard_Real GetMaxValue() const; Standard_EXPORT Standard_Real GetMaxValue( const UnitSystem& ) const; - // get Max Value of the parameter, either in specified unit system or in internal units (basic SI) Standard_EXPORT Standard_Integer GetPrecision() const; Standard_EXPORT Standard_Integer GetPrecision( const UnitSystem& ) const; - // returns precision for indicated unit systems Standard_EXPORT TCollection_AsciiString GetFormat( const Standard_Boolean = Standard_True ) const; Standard_EXPORT TCollection_AsciiString GetFormat( const UnitSystem&, const Standard_Boolean = Standard_True ) const; - // returns format for indicated unit systems - Standard_EXPORT TCollection_ExtendedString GetNameOfValues() const; - // to access valueList:name of the parameter. - // This string is void if the list is not defined - then use other properties: - // Type, DefaultValue, MaxValue, MinValue - Standard_EXPORT Standard_Boolean GetListOfValues( Handle(TColStd_HArray1OfExtendedString)&, Handle(TColStd_HArray1OfInteger)& ) const; - // to access valueList of the parameter - // This sequence is empty if the list not defined - then use other properties: - // Type, DefaultValue, MaxValue, MinValue - Standard_EXPORT Standard_Boolean GetListOfValues( Handle(TColStd_HArray1OfExtendedString)&, Handle(TColStd_HArray1OfInteger)&, Handle(TColStd_HArray1OfExtendedString)& ) const; - // to access valueList of the parameter - // This sequence is empty if the list not defined - then use other properties: - // Type, DefaultValue, MaxValue, MinValue - Standard_EXPORT Standard_Boolean GetSpecialValues( TColStd_MapOfReal& ) const; - // get values from specVal Standard_EXPORT Standard_Real GetMinZoom() const; - // get Min Value of lateral zooming - Standard_EXPORT Standard_Real GetMaxZoom() const; - // get Max Value of lateral zooming - Standard_EXPORT Standard_Real GetZoomOrder() const; - // get Order of lateral zooming Standard_EXPORT Standard_Real ToSI( const Standard_Real ) const; Standard_EXPORT Standard_Real FromSI( const Standard_Real ) const; Standard_EXPORT Standard_Real ToSI( const Standard_Real, const UnitSystem& ) const; Standard_EXPORT Standard_Real FromSI( const Standard_Real, const UnitSystem& ) const; - // convert value to and from default SI units according to current units Standard_EXPORT Standard_Boolean HasData( const Standard_Integer ) const; private: DDS_DicItem( const DDS_DicItem& ); - // Copy constructor - void operator=( const DDS_DicItem& ); - // Assignment operator - void FillDataMap( TCollection_AsciiString, const LDOM_Element&, const LDOM_Element&, const LDOM_Element&, const TColStd_SequenceOfAsciiString& ); - // prepares formants for each unit systems - - void PrepareFormats( const TCollection_AsciiString& ); - // prepares three formats for each unit systems - void GetDefaultFormat(); - // returns three default formants for each unit systems - UnitSystem GetActiveUnitSystem() const; void GetStringFormat( const TCollection_AsciiString&, @@ -181,24 +143,18 @@ private: const TCollection_AsciiString&, const TCollection_AsciiString&, TCollection_AsciiString& ); - // returns format for the string - void GetIntegerFormat( const TCollection_AsciiString&, const TCollection_AsciiString&, const TCollection_AsciiString&, const TCollection_AsciiString&, const Standard_Character, TCollection_AsciiString& ); - // returns format for the integer - void GetFloatFormat( const TCollection_AsciiString&, const TCollection_AsciiString&, const TCollection_AsciiString&, const TCollection_AsciiString&, const Standard_Character, TCollection_AsciiString& ); - // returns format for the float - void Split( const TCollection_AsciiString&, Handle(TColStd_HArray1OfExtendedString)& ); @@ -247,10 +203,8 @@ public: DEFINE_STANDARD_RTTI(DDS_DicItem) }; -// Definition of HANDLE object using Standard_DefineHandle.hxx DEFINE_STANDARD_HANDLE(DDS_DicItem, MMgt_TShared) -// Container class XMLTools_IndexedDataMapOfDicItems (map of handles) DEFINE_BASECOLLECTION(DDS_BaseCollectionOfDicItems, Handle(DDS_DicItem)) DEFINE_INDEXEDDATAMAP(DDS_IndexedDataMapOfDicItems, DDS_BaseCollectionOfDicItems, TCollection_AsciiString, Handle(DDS_DicItem)) diff --git a/src/DDS/DDS_Dictionary.cxx b/src/DDS/DDS_Dictionary.cxx index adaff0469..7e2800357 100644 --- a/src/DDS/DDS_Dictionary.cxx +++ b/src/DDS/DDS_Dictionary.cxx @@ -37,19 +37,214 @@ IMPLEMENT_STANDARD_HANDLE(DDS_Dictionary, MMgt_TShared) IMPLEMENT_STANDARD_RTTIEXT(DDS_Dictionary, MMgt_TShared) +/*! + \class DDS_Dictionary + + This class to provide information about used datums, reading them from 'xml' file + + Datum is the set of parameters described a phisical characteristic. These parameters loaded from + special XML which has following format: + + \hr + + + + + + + ... + + + + + + + + + + [brief_desription_text] + [full_description_text] + + + + ... + + + [list_element_name] + [list_element_name] + ... + [list_element_name] + + + ... + + + + + \hr + + In description of datum file format used internal keys as XML tag and attributes names. + Concrete XML keywords defined by DDS_KeyWords class. + + Describe datum file format more detailed. XML file should have one main tag named as "dictionary" (key "D_URI"). + This tag should contains one or several components. Component is a independent set of datums and unit systems. + Components defined as XML tag named "component" (key "COMPONENT") with attribute "name" (key COMPONENT_NAME). + Component name used as component identifier and should be unique. Component tag can contains: + + \li Tag "unit_systems" (key UNIT_SYSTEMS) defines set of used unit systems. Should exist at least one unit + system named SI ("System International"). If this system not exist then it will be defined automatically. + Each unit system defined by XML tag "unit system" (key UNIT_SYSTEM) under tag "unit_systems" with attributes + "name" (key UNIT_SYSTEM_NAME) and "label" (key UNIT_SYSTEM_LABEL). Name is identifier of unit system. Label is + human readable description. + + \li One or several tag "datum" (key DATUM). For this tag can be defined following attributes: + + \lo Identifier (key DATUM_ID) specify the unique id string for the datum. + \lo Label (key DATUM_LABEL) specify human readable name of the datum. + \lo Units of measure (key DATUM_UNITS) for given unit system. Attribute name consist of a name + of unit system and a keyword got from DDS_KeyWords by key DATUM_UNITS. For example for unit system + named SI and default keyword attribute name will be "SIunits". This attribute should be specified + for each deaclared unit system. Value of this attribute should be string describs units of measure. + Possible designations for units of measure and their multiple prefixes see in package UnitsAPI of + library OpenCascade (files Units.dat and Lexi_Expr.dat). Units of measure will be used for numeric + value conversion from one unit system to another one. + \lo Format (key DATUM_FORMAT) specify the format string which will be used during initial formatting + of value. This string should be specified in sprintf() format. + \lo Filter (key DATUM_FILTER) specify the regualr expression. Each user entered string will be checked up + on matching to this expression (if it defined). Non matched strings will be rejected. + \lo Required value (key DATUM_REQUIRED). If this attributed defined and value is true then user can't + leave a input filed blank (parameter must be always entered). + + Tag "description" (key DESCR) can be defined under the tag "datum". This tag contains two sub tags: + \lo "short description" (key SHORT_D) specify a brief datum description text + \lo "long description" (key LONG_D) specify a detailed description text + + Each tag "datum" define most common parameters of phisical characteristic. + This parameters placed in two groups: + \lo Domain parameters under tag "domain" (key DY_DOMAIN). This tag can contains value description tag + (key VALUE_DESCR) for discrete data or list reference tag (key VALUE_LIST_REF) for enumerable data. + Discrete data described following parameters: + default value (key VD_DEFV) + maximum value (key VD_MAXV) + minimum value (key VD_MINV) + type of value (key VD_TYPE) - possible values: String, Integer, Float, List + Enumerable data described by "list reference" attribute (key VLR_LIST) which reference on + list (see "list definition" tag) by list id. + + \li One or several tag "list definition" (key VALUE_LIST). This tag define the list of items for enumerable + data. Attribute "list id" (key VALUE_LIST_ID) specify the identifier string for the list and attribute + "list name" (key VALUE_LIST_NAME) define a list name string. Each list item described by tag "list value" + (key VALUE_LIST_VALUE) under tag "list definition". Each this tag contains item string text and have + following attributes: + \lo "list item id" (key VALUE_LIST_VALUEID) - integer numerical identifier for item + \lo "list item icon" (key VALUE_LIST_VALUEICON) - icon file name for item + + Below the example of a XML file with use default keywords. + + + + + + + + + + + + + + + + + + + + X coordinate for object + X multiplier of object coordinates. Describe position of object in direction of X axis + + + + + + + + + Y coordinate for object + Y multiplier of object coordinates. Describe position of object in direction of Y axis + + + + + + + + + + + + Name of object + + + + + + + + + + + + + + Side of object + + + + + + left + right + top + bottom + undefined + + + + + + +*/ + +/*! + Constructor. Creates the instance of dictionary. Private method. Use DDS_Dictionary::Get() instead. +*/ DDS_Dictionary::DDS_Dictionary() : MMgt_TShared() { } +/*! + Copy constructor. Internal. +*/ DDS_Dictionary::DDS_Dictionary( const DDS_Dictionary& ) { } +/*! + Assigment operator. Internal. +*/ void DDS_Dictionary::operator=( const DDS_Dictionary& ) { } +/*! + Returns the names list of defined unit systems from all components. + Parameter \atheSystems will contains the sequence of string names. +*/ void DDS_Dictionary::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystems ) const { theSystems.Clear(); @@ -71,6 +266,11 @@ void DDS_Dictionary::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystems ) } +/*! + Returns the names list of defined unit systems from the specified component \atheComponent. + Parameter \atheSystems will contains the sequence of string names. If component not found then + empty list returned. +*/ void DDS_Dictionary::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystems, const TCollection_AsciiString& theComponent ) const { @@ -79,6 +279,10 @@ void DDS_Dictionary::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystems, myGroupMap.FindFromKey( theComponent )->GetUnitSystems( theSystems ); } +/*! + Returns the label of unit system \atheSystem. Function find the given unit system in + all components. If unit system not found in any component then empty string returned. +*/ TCollection_ExtendedString DDS_Dictionary::GetUnitSystemLabel( const TCollection_AsciiString& theSystem ) const { TCollection_ExtendedString aLabel; @@ -87,6 +291,11 @@ TCollection_ExtendedString DDS_Dictionary::GetUnitSystemLabel( const TCollection return aLabel; } +/*! + Returns the label of unit system \atheSystem from component \atheComponent. Function find + the given unit system in the specified component only. If unit system not found in the + component then empty string returned. +*/ TCollection_ExtendedString DDS_Dictionary::GetUnitSystemLabel( const TCollection_AsciiString& theSystem, const TCollection_AsciiString& theComponent ) const { @@ -96,6 +305,10 @@ TCollection_ExtendedString DDS_Dictionary::GetUnitSystemLabel( const TCollection return aLabel; } +/*! + Gets the name of active unit system from first got component. If any component exist then + active unit system name returned or empty string otherwise. +*/ TCollection_AsciiString DDS_Dictionary::GetActiveUnitSystem() const { TCollection_AsciiString aSystem; @@ -104,6 +317,10 @@ TCollection_AsciiString DDS_Dictionary::GetActiveUnitSystem() const return aSystem; } +/*! + Gets the name of active unit system from component \atheComponent. If this component exist + active unit system name returned or empty string otherwise. +*/ TCollection_AsciiString DDS_Dictionary::GetActiveUnitSystem( const TCollection_AsciiString& theComponent ) const { TCollection_AsciiString aSystem; @@ -112,12 +329,20 @@ TCollection_AsciiString DDS_Dictionary::GetActiveUnitSystem( const TCollection_A return aSystem; } +/*! + Sets the active unit system named \atheSystem. This unit system will be activated in all + existing components if component have it. +*/ void DDS_Dictionary::SetActiveUnitSystem( const TCollection_AsciiString& theSystem ) { for ( Standard_Integer i = 1; i <= myGroupMap.Extent(); i++ ) myGroupMap.FindFromIndex( i )->SetActiveUnitSystem( theSystem ); } +/*! + Sets the active unit system named \atheSystem for component \atheComponent. If specified unit + system doesn't exist in the component then function do nothing. +*/ void DDS_Dictionary::SetActiveUnitSystem( const TCollection_AsciiString& theSystem, const TCollection_AsciiString& theComponent ) { @@ -138,6 +363,10 @@ Handle(DDS_Dictionary) DDS_Dictionary::Get() return sDictionary; } +/*! + Load datum definitions in the dictionary from XML file \atheFileName. Returns true if load + successed or false otherwise. +*/ Standard_Boolean DDS_Dictionary::Load( const TCollection_AsciiString theFileName ) { static NCollection_Map _LoadMap; @@ -164,6 +393,10 @@ Standard_Boolean DDS_Dictionary::Load( const TCollection_AsciiString theFileName return Standard_True; } +/*! + Gets XML keyword as LDOMString by specified \akey. If key doesn't exist then empty string + returned. This function provided for convenience. +*/ LDOMString DDS_Dictionary::KeyWord( const TCollection_AsciiString& key ) { LDOMString keyWord; @@ -178,25 +411,25 @@ LDOMString DDS_Dictionary::KeyWord( const TCollection_AsciiString& key ) } /*! - Returns DicItem from specified group with all attached data + Gets dictionary item with specified identifier \atheID from specified component \atheComponent. + If component or item not found then null handle returned. */ - Handle(DDS_DicItem) DDS_Dictionary::GetDicItem( const TCollection_AsciiString& theID, - const TCollection_AsciiString& theGroup ) const + const TCollection_AsciiString& theComponent ) const { Handle(DDS_DicItem) aDicItem; Handle(DDS_DicGroup) aDicGroup; - if ( myGroupMap.Contains( theGroup ) ) - aDicGroup = myGroupMap.FindFromKey( theGroup ); + if ( myGroupMap.Contains( theComponent ) ) + aDicGroup = myGroupMap.FindFromKey( theComponent ); if ( !aDicGroup.IsNull() ) aDicItem = aDicGroup->GetDicItem( theID ); return aDicItem; } /*! - Returns DicItem with all attached data + Gets dictionary item with specified identifier \atheID. Function find the item in all components. + If item not found in any component then null handle returned. */ - Handle(DDS_DicItem) DDS_Dictionary::GetDicItem( const TCollection_AsciiString& theID ) const { Handle(DDS_DicItem) aDicItem; @@ -205,6 +438,9 @@ Handle(DDS_DicItem) DDS_Dictionary::GetDicItem( const TCollection_AsciiString& t return aDicItem; } +/*! + Fill the internal data structures from XML parsed structures. Internal. +*/ void DDS_Dictionary::FillDataMap( const LDOM_Element& theComponentData, const LDOM_Element& theDocElement ) { TCollection_AsciiString aCompName = theComponentData.getAttribute( KeyWord( "COMPONENT_NAME" ) ); @@ -215,6 +451,10 @@ void DDS_Dictionary::FillDataMap( const LDOM_Element& theComponentData, const LD myGroupMap.Add( aCompName, aDicGroup ); } +/*! + Convert numeric value \atheValue from specified unit of measure \atheUnits to SI unit of measure + (mm for Length, radians for Angles, etc). Converted value returned. +*/ Standard_Real DDS_Dictionary::ToSI( const Standard_Real theValue, const Standard_CString theUnits ) { Standard_Real aRetValue = theValue; @@ -232,6 +472,10 @@ Standard_Real DDS_Dictionary::ToSI( const Standard_Real theValue, const Standard return aRetValue; } +/*! + Convert numeric value \atheValue to specified unit of measure \atheUnits from SI unit of measure + (mm for Length, radians for Angles, etc). Converted value returned. +*/ Standard_Real DDS_Dictionary::FromSI( const Standard_Real theValue, const Standard_CString theUnits ) { Standard_Real aRetValue = theValue; diff --git a/src/DDS/DDS_Dictionary.h b/src/DDS/DDS_Dictionary.h index 427e08e1e..9a5d5a886 100644 --- a/src/DDS/DDS_Dictionary.h +++ b/src/DDS/DDS_Dictionary.h @@ -30,8 +30,6 @@ class TCollection_AsciiString; DEFINE_STANDARD_HANDLE(DDS_Dictionary, MMgt_TShared) -// Class to provide information about used parameters, -// reading them from 'xml' file class DDS_Dictionary : public MMgt_TShared { public: @@ -69,7 +67,6 @@ private: void operator=( const DDS_Dictionary& ); - // prepares formants for each unit systems void FillDataMap( const LDOM_Element&, const LDOM_Element& ); private: diff --git a/src/DDS/DDS_KeyWords.cxx b/src/DDS/DDS_KeyWords.cxx index 8ea7f6a97..83be4f3bf 100644 --- a/src/DDS/DDS_KeyWords.cxx +++ b/src/DDS/DDS_KeyWords.cxx @@ -21,6 +21,59 @@ IMPLEMENT_STANDARD_HANDLE(DDS_KeyWords, MMgt_TShared) IMPLEMENT_STANDARD_RTTIEXT(DDS_KeyWords, MMgt_TShared) +/*! + \class DDS_KeyWords + + This object contains the pairs of internal keys and XML tag or attribute names. This class allow to user + define set of XML keywords used in datums definition file. + + Default keywords table: + \li D_URI - dictionary + \li COMPONENT - component + \li COMPONENT_NAME - name + \li UNIT_SYSTEMS - unitSystems + \li UNIT_SYSTEM - system + \li UNIT_SYSTEM_NAME - name + \li UNIT_SYSTEM_LABEL - label + \li DATUM - datum + \li DATUM_ID - id + \li DATUM_LABEL - label + \li DATUM_UNITS - units + \li DATUM_FORMAT - format + \li DATUM_FILTER - filter + \li DATUM_REQUIRED - required + \li VALUE_LIST - valueList + \li VALUE_LIST_ID - listid + \li VALUE_LIST_NAME - name + \li VALUE_LIST_TYPE - type + \li VALUE_LIST_VALUE - value + \li VALUE_LIST_VALUEID - id + \li VALUE_LIST_VALUEICON - icon + \li DY_DOMAIN - domain + \li WARNING_LEVEL - warningLevel + \li WRONG_VALUE - wrongValue + \li VALUE_DESCR - valueDescr + \li VALUE_LIST_REF - listRef + \li DESCR - description + \li LONG_D - longDescr + \li SHORT_D - shortDescr + \li VD_TYPE - type + \li VD_DEFV - default + \li VD_MAXV - max + \li VD_MINV - min + \li VD_SPEC - specVal + \li VLR_LIST - list + \li PRS - presentation + \li LATERAL_ZOOM - lateralZoom + \li LZ_MINV - min + \li LZ_MAXV - max + \li LZ_ORDER - order +*/ + +/*! + Constructor +*/ + DDS_KeyWords::DDS_KeyWords() : MMgt_TShared() { @@ -73,6 +126,10 @@ DDS_KeyWords::DDS_KeyWords() SetKeyWord( "LZ_ORDER", "order" ); } +/*! + Returns the static instance of the class DDS_KeyWords +*/ + Handle(DDS_KeyWords) DDS_KeyWords::Get() { static Handle(DDS_KeyWords) keyWords; @@ -83,6 +140,11 @@ Handle(DDS_KeyWords) DDS_KeyWords::Get() return keyWords; } +/*! + Returns the XML keyword by specified internal key \a key. If the internal key isn't registered + then empty string will be returned. +*/ + TCollection_AsciiString DDS_KeyWords::GetKeyWord( const TCollection_AsciiString& key ) const { TCollection_AsciiString keyWord; @@ -91,6 +153,10 @@ TCollection_AsciiString DDS_KeyWords::GetKeyWord( const TCollection_AsciiString& return keyWord; } +/*! + Register the pair of the internal key \a key and XML keyword \a keyWord. +*/ + void DDS_KeyWords::SetKeyWord( const TCollection_AsciiString& key, const TCollection_AsciiString& keyWord ) { diff --git a/src/DDS/DDS_KeyWords.h b/src/DDS/DDS_KeyWords.h index daee727ba..2161f71f3 100644 --- a/src/DDS/DDS_KeyWords.h +++ b/src/DDS/DDS_KeyWords.h @@ -29,7 +29,7 @@ DEFINE_STANDARD_HANDLE(DDS_KeyWords, MMgt_TShared) class TCollection_AsciiString; -class DDS_KeyWords: public MMgt_TShared +class DDS_KeyWords : public MMgt_TShared { public: Standard_EXPORT static Handle(DDS_KeyWords) Get(); -- 2.39.2