DDS_Dictionary Class Reference

This class provides an information about used datums, reading them from XML file. More...

---

Detailed Description

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:

  <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>

  

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:
  1. Identifier (key DATUM_ID) specifies the unique id string for the datum.
  2. Label (key DATUM_LABEL) specifies human readable name of the datum.
  3. 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.
  4. 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.
  5. 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.
  6. Required value (key DATUM_REQUIRED). If this attributed si defined and its value is 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:
  1. "list item id" (key VALUE_LIST_VALUEID) - integer numerical identifier for the item
  2. "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:
  1. "short description" (key SHORT_D) specifies a brief datum description text
  2. "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:

1. 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
2. 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.

  <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>