+Handle(DDS_Dictionary) DDS_Dictionary::myDictionary = Handle(DDS_Dictionary)();
+
+/*!
+ \class DDS_Dictionary
+ \brief This class provides an information about used datums,
+ reading them from XML file.
+
+ There is the only instance of the class DDS_Dictionary in the application
+ which can be retrieved by method Get().
+
+ Datum is a set of parameters describing a phisical characteristic.
+ These parameters are loaded from the XML file which has the following format:
+
+ \verbatim
+ <D_URI>
+ <COMPONENT COMPONENT_NAME="component_name">
+ <UNIT_SYSTEMS>
+ <UNIT_SYSTEM UNIT_SYSTEM_NAME="[system_internal_name]" UNIT_SYSTEM_LABEL="[system_label]">
+ <UNIT_SYSTEM UNIT_SYSTEM_NAME="[system_internal_name]" UNIT_SYSTEM_LABEL="[system_label]">
+ ...
+ <UNIT_SYSTEM UNIT_SYSTEM_NAME="[system_internal_name]" UNIT_SYSTEM_LABEL="[system_label]">
+ </UNIT_SYSTEMS>
+
+ <DATUM DATUM_UNITS="[base_system_internal_name]" DATUM_FORMAT="[sprintf_format_specification]"
+ DATUM_ID="[datum_id]" DATUM_LABEL="[datum_label]" DATUM_REQUIRED="[requred_value]"
+ DATUM_FILTER="[string_regular_expression]">
+ <DY_DOMAIN>
+ <VALUE_DESCR VD_DEFV="[default_value]" VD_MAXV="[max_value]" VD_MINV="[min_value]" VD_TYPE="[value_type]"/>
+ <VALUE_LIST_REF VLR_LIST="[referenced_list_id]"/>
+ </DY_DOMAIN>
+ <DESCR>
+ <SHORT_D>[brief_desription_text]</SHORT_D>
+ <LONG_D>[full_description_text]</LONG_D>
+ </DESCR>
+ <OPTIONS>
+ <OPTION OPTION_NAME="[option_name_1]">[option_value_1]</OPTION>
+ <OPTION OPTION_NAME="[option_name_2]">[option_value_2]</OPTION>
+ ...
+ <OPTION OPTION_NAME="[option_name_n]">[option_value_n]</OPTION>
+ </OPTIONS>
+ </DATUM>
+
+ ...
+
+ <VALUE_LIST VALUE_LIST_ID="[list_id]" VALUE_LIST_NAME="[list_name]">
+ <VALUE_LIST_VALUE VALUE_LIST_VALUEID="[list_element_id]" VALUE_LIST_VALUEICON="[list_element_icon_file]">[list_element_name]</VALUE_LIST_VALUE>
+ <VALUE_LIST_VALUE VALUE_LIST_VALUEID="[list_element_id]" VALUE_LIST_VALUEICON="[list_element_icon_file]">[list_element_name]</VALUE_LIST_VALUE>
+ ...
+ <VALUE_LIST_VALUE VALUE_LIST_VALUEID="[list_element_id]" VALUE_LIST_VALUEICON="[list_element_icon_file]">[list_element_name]</VALUE_LIST_VALUE>
+ </VALUE_LIST>
+
+ ...
+
+ </COMPONENT>
+ </D_URI>
+
+ \endverbatim
+
+ In above description of the datum XML file format internal keys are used as XML tags
+ and attributes names. Real XML keywords are defined by DDS_KeyWords class.
+
+ XML file should have one main tag named "dictionary" (key "D_URI"). This tag
+ should contain one or several components.
+ Component is an independent set of datums and units systems.
+ Components are defined by XML tag named "component" (key "COMPONENT") with
+ attribute "name" (key COMPONENT_NAME).
+ Component name is used as component identifier and should be unique.
+
+ Component tag can contain:
+
+ - Tag "unit_systems" (key UNIT_SYSTEMS) defines a set of used units systems.
+ At least one unit system named SI ("System International") should exist.
+ If this system does not exist, it will be created automatically.
+ Each units system is defined by XML tag "unit system" (key UNIT_SYSTEM) under
+ the tag "unit_systems" with attributes "name" (key UNIT_SYSTEM_NAME)
+ and "label" (key UNIT_SYSTEM_LABEL). Name is an identifier of the units system and
+ label is its human readable description.
+
+ - One or several tags "datum" (key DATUM). For this tag the following attributes
+ can be defined:
+ -# Identifier (key DATUM_ID) specifies the unique id string for the datum.
+ -# Label (key DATUM_LABEL) specifies human readable name of the datum.
+ -# Measure units (key DATUM_UNITS) for the given units system. Attribute name
+ defines a name of units system and a keyword got from DDS_KeyWords by key DATUM_UNITS.
+ For example, for "SI" units system and default keyword the attribute name is "SIunits".
+ This attribute should be specified for each declared units system.
+ Value of this attribute should be a string describing measure units.
+ For possible designations for measure units and their multiple prefixes
+ please refer to the UnitsAPI package of the OpenCascade library
+ (files Units.dat and Lexi_Expr.dat). Measure units are used for numerical
+ values conversion from one units system to another one.
+ -# Format (key DATUM_FORMAT) specifies the format string which will be used
+ during initial formatting of the value. This string should be specified
+ in sprintf() format.
+ -# Filter (key DATUM_FILTER) specifies the regualr expression. The value (string)
+ entered by the user will be checked up to match to this regular expression
+ (if it defined). Non matched strings will be rejected.
+ -# Required value (key DATUM_REQUIRED). If this attributed si defined and its value
+ is \c true then user can't leave an input non-filled - parameter must be explicitly
+ entered by the user).
+
+ - One or several tags "list definition" (key VALUE_LIST). Each such tag defines
+ the list of items for enumerable data. Attribute "list id" (key VALUE_LIST_ID)
+ specifies the identifier string for the list and attribute "list name"
+ (key VALUE_LIST_NAME) defines a list name string. Each list item is described
+ by tag "list value" (key VALUE_LIST_VALUE) under the tag "list definition".
+ Each this tag contains item string text and have the following attributes:
+ -# "list item id" (key VALUE_LIST_VALUEID) - integer numerical identifier for
+ the item
+ -# "list item icon" (key VALUE_LIST_VALUEICON) - icon file name for the item
+
+ Tag "datum" can have child subtags "description" and "options".
+
+ - Tag "description" (key DESCR) contains two sub tags:
+ -# "short description" (key SHORT_D) specifies a brief datum description text
+ -# "long description" (key LONG_D) specifies a detailed description text
+
+ - Tag "options" (key OPTIONS) contains one or more sub tags "option" (key OPTION).
+ Each of these XML elements should contain text option value and attribute
+ "name" (key OPTION_NAME) which specifies option name.
+
+ Each tag "datum" defines most common parameters of phisical characteristic.
+ These parameters are placed in two groups:
+ -# Domain parameters under the tag "domain" (key DY_DOMAIN). This tag can
+ contain value description tag (key VALUE_DESCR) for descrete data which is
+ described by 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 are String, Integer, Float, List
+ -# list reference tag (key VALUE_LIST_REF) for enumerable data described by
+ "list reference" attribute (key VLR_LIST) which references to the list
+ (see "list definition" tag) by list id.
+
+ Below is an example of the XML file using default keywords.
+
+ \verbatim
+ <datadictionary version="1.0">
+ <component name="My Component">
+
+ <!-- specify two unit systems -->
+
+ <unitSystems>
+ <system name="SI" label="System international">
+ <system name="AS" label="Anglo - sacson system">
+ </unitSystems>
+
+ <!-- specify datum -->
+ <!-- units of measure for SI - meters (m), for AS - inches (in) -->
+ <datum SIunits="m" ASunits="in" format="%.25f" id="X" label="X coordinate" required="">
+ <domain>
+ <!-- default value not specified -->
+ <valueDescr default="" max="999999999.999" min="0.000" type="Float"/>
+ </domain>
+ <description>
+ <shortDescr>X coordinate for object</shortDescr>
+ <longDescr>X multiplier of object coordinates. Describe position of object in direction of X axis</longDescr>
+ </description>
+ </datum>
+
+ <datum SIunits="m" ASunits="in" format="%.25f" id="Y" label="Y coordinate" required="">
+ <domain>
+ <valueDescr default="" max="999999999.999" min="0.000" type="Float"/>
+ </domain>
+ <description>
+ <shortDescr>Y coordinate for object</shortDescr>
+ <longDescr>Y multiplier of object coordinates. Describe position of object in direction of Y axis</longDescr>
+ </description>
+ </datum>
+
+ <!-- datum for object name with filter which not allow to input more that 8 letters,
+ numbers or unerscores with first letter only -->
+ <datum format="%.8us" id="ObjectName" label="Name" required="yes"
+ filter="^([A-Z]+)([A-Z,0-9,_]*)$">
+ <domain>
+ <!-- limits and default not specified, type is string -->
+ <valueDescr default="" max="" min="" type="String" />
+ </domain>
+ <description>
+ <!-- long description not specified -->
+ <shortDescr>Name of object</shortDescr>
+ </description>
+ </datum>
+
+
+ <!-- datum for enumeration of side -->
+ <datum format="" id="Side" label="Side" required="">
+ <domain>
+ <!-- default list item is item with id 0 -->
+ <valueDescr default="0" type="List"/>
+ <!-- list reference on list named "side_list" -->
+ <listRef list="side_list"/>
+ </domain>
+ <description>
+ <shortDescr>Side of object</shortDescr>
+ </description>
+ </datum>
+
+ <!-- list definition for enumeration of side -->
+ <valueList listid="side_list" name="Side">
+ <value id="1">left</value>
+ <value id="2">right</value>
+ <value id="3">top</value>
+ <value id="4">bottom</value>
+ <value id="0">undefined</value>
+ </valueList>
+
+ </component>
+ </datadictionary>
+ \endverbatim
+*/
+
+/*!
+ \brief Constructor.
+
+ Create an instance of the dictionary. Can not be used directly.
+ Use Get() method instead.
+*/