Template File Syntax (Reference) for Version 6 XML Attribute Files

File Layout

All attribute template and instance files must contain the <SMTK_AttributeResource> XML element. The following table shows the XML Attributes that can be included in this XML Element.

XML Attributes for <SMTK_AttributeResource> Element

XML Attribute

Description

Version

Integer value that indicates the SMTK attribute format (Required)

Current value is 6 (latest version)

DisplayHint

Boolean value that indicates if the Attribute Resource should be automatically displayed in an Attribute Editor when loaded into memory.

(Optional - default is false which means the Resource will not automatically be displayed)

This element can contain the following optional children XML Elements:

  • Includes : used for including additional attribute files (see Includes Section)

  • AdvanceLevels : used to define various advance access levels used in GUIs (see Advance Level Section)

  • Categories : used to define workflow specific categories (see Category Section)

  • Analyses : used to define various analysis groups (see Analysis Section)

  • Analysis Configurations: predefined analysis configuration from which the user can choose from (see Analysis Configuration Section)

  • Item Blocks : used to define reusable blocks of Item Definitions(see Item Blocks Section)

  • Definitions : used to define attribute definitions (see Definitions Section)

  • Attributes : used to define attributes

  • Views : used to define various Views (used to create GUIs)

Includes Section

The attribute format supports the ability to include other attribute files. This allows designers to assemble a complete attribute description by referencing attribute files that represent specific aspects. For example a set of attribute definitions may be referenced by several different simulation workflows. Below is an example of including two attribute files both located in a sub-directory IncludeTest.

<Includes>
  <File>includeTest/b.xml</File>
  <File>includeTest/a.xml</File>
</Includes>

Each include file is contained within a File XML Element.

Advance Level Section

This is an optional section used to describe the various access levels used in GUIs created using SMTK’s QT Attribute classes. For example a workflow could consist of the following advance levels:

  • General

  • Intermediate

  • Expert

Using the <AdvanceLevels> element the following represents the above access levels.

<AdvanceLevels>
  <Level Label="General" Color="0.0, 1.0, 0.0"> 0 </Level>
  <Level Label="Intermediate" Color="1.0, 1.0, 0.0"> 1 </Level>
  <Level Label="Expert" Color="1.0, 1.0, 0.0"> 2 </Level>
</AdvanceLevels>

The value of each Level XML Element determines the ordering of the access levels and are used by the items contained within Definitions (see xxx). Notice that in the GUI example, the upper left corner “Show Level” entry is based on the Advance Levels.

Advance Level Element Format

Each advance level is represented by using a <Level> XML Element. The value of the element determines the absolute access level and should not be repeated among sibling Level Elements. The higher the value the more “advance” the level.

The following table shows the XML Attributes that can be included in this XML Element.

XML Attributes for <Level> Element

XML Attribute

Description

Label

String value representing the access level name to be displayed in the GUI (Optional - else the label will be the word Level followed by the advance level)

Color

String value representing the color to be used when displaying items that are associated with this access level. The format is “r, g, b” where r, g, and b are a value between 0 and 1 inclusive (Optional)

Category Section

This is an optional section describing the set of categories used within the file. Attribute and Items Definitions can use these categories to define their category constraints. In addition, analyses are defined as sets of categories. For example, the following xml would define the following categories:

  • Constituent Transport

  • Heat Transfer

  • Flow

  • Time

  • General

<Categories>
  <Cat>Constituent Transport</Cat>
  <Cat>Heat Transfer</Cat>
  <Cat>Flow</Cat>
  <Cat>Time</Cat>
  <Cat>General</Cat>
</Categories>

Each category is contained within a Cat XML Element.

The following table shows the XML Attributes that can be included in <Categories> Element.

XML Attributes for <Categories> Element

XML Attribute

Description

Default

String value representing the default categories a Definition’s Item belongs to when no category is specified.

Property Section for the Attribute Resource

This is an optional section describing a set of properties that should be added to the Attribute Resource. The Property section is defined by a XML Properties node which is composed of a set of children Property nodes as shown below:

<Properties>
  <Property Name="pi" Type="Int"> 42 </Property>
  <Property Name="pd" Type="double"> 3.141 </Property>
  <Property Name="ps" Type="STRING">Test string</Property>
  <Property Name="pb" Type="bool"> YES </Property>
</Properties>

You can also look at data/attribute/attribute_collection/propertiesExample.rst and smtk/attribute/testing/cxx/unitXmlReaderProperties.cxx for a sample XML file and test.

The following table shows the XML Attributes that can be included in <Property> Element.

XML Attributes for <Property> Element

XML Attribute

Description

Name

String value representing the name of the property to be set.

Type

String value representing the type of the property to be set. Note that the value is case insensitive.

The values that the Type attribute can be set to are:

  • int for an integer property

  • double for a double property

  • string for a string property

  • bool for a boolean property

The node’s value is the value of the property being set.

Supported Values for Boolean Properties

The following are supported values for true:

  • t

  • true

  • yes

  • 1

The following are supported values for false:

  • f

  • false

  • no

  • 0

Note that boolean values are case insensitive and any surrounding white-space will be ignored.

Properties and Include Files

If you include an Attribute XML file that also assigns Resource Properties, the include file’s Properties are assigned first. Meaning that the file using the include file can override the Properties set by the include file.

Note - the ability to unset a Property is currently not supported.

Note - Properties are currently not saved in the XML format, but are saved if using the JSON format.

Analysis Section

This is an optional section that define analyses. An analysis is defined as a resource of categories. For example, using the categories defined in the`Category Section`_, the following XML would define two analyses (Ground Water Flow, and Ground Water with Heat Transfer).

<Analyses>
  <Analysis Type="Groundwater Flow">
    <Cat>Flow</Cat>
    <Cat>General</Cat>
    <Cat>Time</Cat>
  </Analysis>
  <Analysis Type="Groundwater Flow with Heat Transfer">
    <Cat>Flow</Cat>
    <Cat>General</Cat>
    <Cat>Heat Transfer</Cat>
    <Cat>Time</Cat>
  </Analysis>
</Analyses>

An analysis can be composed of sub-analyses from which the user can choose. By default, the user can select a subset of these sub-analyses as shown below:

../../_images/analysisExample1.png

Here you see analysis B is composed of 2 optional sub-analyses B-D and B-E. In this case B-E has been selected. An active sub-analysis will add its categories to those of its parent’s analysis. The above example could be rewritten using the concept of sub-analyses:

<Analyses>
  <Analysis Type="Groundwater Flow">
    <Cat>Flow</Cat>
    <Cat>General</Cat>
    <Cat>Time</Cat>
  </Analysis>
  <Analysis Type="Groundwater Flow with Heat Transfer" BaseType="Groundwater Flow">
    <Cat>Heat Transfer</Cat>
  </Analysis>
</Analyses>

You can also indicate if the user must select only one sub-analysis by indicating that the base analysis is Exclusive. In the example below, analysis C has been marked Exclusive and consists of two sub-analyses C-D and C-E. The user must select one of these analyses.

../../_images/analysisExample2.png

If you wish to have the user exclusively choose among the top level analyses, you can add the Exclusive attribute to the Analyses XML node itself as shown below.

<Analyses Exclusive="true">
  <Analysis Type="A">
    <Cat>A</Cat>
  </Analysis>
  <Analysis Type="B">
    <Cat>B</Cat>
  </Analysis>
</Analyses>

Please see smtk/data/attribute/attribute_collection/SimpleAnalysisTest.sbt smtk/data/attribute/attribute_collection/analysisConfigurationExample.sbt for complete examples which can be loaded into ModelBuilder.

Analysis Element Format

Each Analysis is defined within an <Analysis> XML Tag.

The following table shows the XML Attributes that can be included in this XML Element.

XML Attributes for <Analysis> Element

XML Attribute

Description

Type

String value representing the type analysis being defined. Note that the type should be unique with respects to all other analyses being defined. (Required)

BaseType

String value representing the type of the analysis this analysis is a sub-analysis of. (Optional)

Exclusive

Boolean value indicating the sub-analyses of this analysis are exclusive. (Optional)

Required

Boolean value indicating the analysis is required and not optional. (Optional) Note - Required Analyses can not be sub-analyses of an Analyses with Exclusive set to true.

Each Analysis element contains a set of Cat XML Elements.

Analysis Configuration Section

This is an optional section that define analyses configurations. The Analysis Section describes relationship between analyses, while the configuration section defines various analysis configurations from which the user can choose from. Here is an example configuration section from smtk/data/attribute/attribute_collection/analysisConfigurationExample.sbt:

<Configurations AnalysisAttributeType="Analysis">
  <Config Name="Test A" AdvanceReadLevel="5">
    <Analysis Type="A"/>
  </Config>
  <Config Name="Test B" AdvanceWriteLevel="10">
    <Analysis Type="B"/>
  </Config>
  <Config Name="Test B-D">
    <Analysis Type="B">
      <Analysis Type="B-D"/>
    </Analysis>
  </Config>
  <Config Name="Test C">
    <Analysis Type="C"/>
  </Config>
  <Config Name="Test C-D">
    <Analysis Type="C">
      <Analysis Type="C-D"/>
    </Analysis>
  </Config>
  <Config Name="Test C-E">
    <Analysis Type="C">
      <Analysis Type="C-E"/>
    </Analysis>
  </Config>
  <Config Name="Test C-E-F">
    <Analysis Type="C">
      <Analysis Type="C-E">
        <Analysis Type="C-E-F"/>
      </Analysis>
    </Analysis>
  </Config>
</Configurations>
XML Attributes for <Configurations> Element

XML Attribute

Description

AnalysisAttributeType

String value representing the type name for the Attribute Definition used to represent an Analysis Configuration. (Required)

The Configuration Element is composed of a set of Config Elements. Each Config Element represents an Analysis Configuration.

XML Attributes for <Config> Element

XML Attribute

Description

Name

String value representing the configuration’s name (which will also be the name of an Analysis Attribute that represents that configuration). (Required)

AdvanceReadLevel

Integer value representing the configuration’s read access level. If the advance level is set below the configuration’s AdvanceReadLevel, the configuration will not be displayed to the user. (Optional - default is 0)

AdvanceWriteLevel

Integer value representing the configuration’s write access level. If the advance level is set below the configuration’s AdvanceWriteLevel, the user will not be allowed to edit the configuration. (Optional - default is 0)

Each Config Element consists of a nested group of Analysis Elements. Each Analysis Element represents an analysis defined in the Analysis Section. Specifying an Analysis indicates that the analysis is active when the configuration is selected. If the analysis is Exclusive then it must contain an Analysis Element referring to one of its sub-analyses. If it is not Exclusive then it can optionally contain multiple Analysis Elements indicating which sub-analyses should be active.

XML Attributes for <Analysis> Element

XML Attribute

Description

Type

String value representing an analysis type.

Unique Roles Section

There are use cases where the developer would like to enforce a constraint among ComponentItems such that each item cannot point to the same resource component. In order to provide this functionality, we have introduced the concept of unique roles. Roles in this context refers to the roles defined in the resource links architecture and that are referenced in ReferenceItemDefinition. If the role specified in either a Reference or Component Item Definition is include in this section, it is considered unique.

Here is an example of an Unique Role Section

<UniqueRoles>
  <Role ID="10"/>
  <Role ID="0"/>
</UniqueRoles>

In this case roles 10 and 0 are considered to be unique.

Item Blocks Section

Item Definition Blocks allows the reuse of a group of Item Definitions in different Attribute Definitions. Providing a “hasA” relationship as opposed to the currently supported “isA”. These blocks can then be referenced in the “ItemDefinitions” nodes of Attribute or Group Item Definitions or in the “ChildrenDefinitions” nodes for Reference or Value Item Definitions. Blocks themselves can reference other blocks. But care must be taken not to form a recursive relationship. In the parser detects such a pattern it will report an error.

When referencing a Block, the items will be inserted relative to where the Block is being referenced.

Category constraints are inherited as usual and that Blocks can call other blocks. Here is an example of an Item Block:

<ItemBlocks>
  <Block Name="B1">
    <ItemDefinitions>
      <String Name="s1">
        <Categories>
          <Cat>Solid Mechanics</Cat>
        </Categories>
      </String>
      <Int Name="i1"/>
    </ItemDefinitions>
  </Block>
</ItemBlocks>

<Definitions>
  <AttDef Type="Type1">
    <Categories>
      <Cat>Fluid Flow</Cat>
    </Categories>
    <ItemDefinitions>
      <Double Name="foo"/>
      <Block Name="B1"/>
      <String Name="bar"/>
    </ItemDefinitions>
  </AttDef>
  <AttDef Type="Type2">
    <Categories>
      <Cat>Heat Transfer</Cat>
    </Categories>
    <ItemDefinitions>
      <Block Name="B1"/>
      <String Name="str2"/>
    </ItemDefinitions>
  </AttDef>
</Definitions>

See data/attribute/attribute_collection/ItemBlockTest.sbt and smtk/attribute/testing/cxx/unitItemBlocks.cxx for examples.

Note - An Item Block can currently only be used in the XML file that is defined.

Definitions Section

This is an optional section that defines a set of attribute definitions used to generate attributes with a SMTK-based program. This section is created using the <Definitions> XML Element. See the example XML for how to create a set of attribute definitions.

This element can contain the following children XML Elements:

XML Children Elements for <Definitions> Element

XML Child Element

Description

<AttDef>

Defines a new Attribute Definition

See AttDef Element Format.

<Exclusions>

Defines a set of Definitions whose Attributes would mutually exclude each other from being associated to the same Resource/Resource Component (Optional).

See Exclusions Format.

<Prerequisites>

Defines a set of Definitions whose Attributes are required to be associated to a Resource or Resource Component prior to being able to associated Attributes from another Definition to the same Resource or Resource Component (Optional). See Prerequisites Format.

AttDef Element Format

This element define an attribute definition.

This element can contain the following children XML Elements:

XML Children Elements for <AttDef> Element

XML Child Element

Description

<CategoryInfo>

Specifies the local category constraints specified on the Definition

See CategoryInfo Format.

<ItemDefinitions>

Defines the items contained within the attributes generated by this definition (Optional).

See Item Definitions Format.

<AssociationsDef>

Defines the association rules associated with this Definition (Optional). See AssociationsDef Format.

<BriefDescription>

Provides a brief description of the definition (Optional).

<DetailedDescription>

Provides a detailed description of the definition (Optional).

The following table shows the XML Attributes that can be included in this XML Element.

XML Attributes for <AttDef> Element

XML Attribute

Description

Type

String value representing the attribute definition type being defined. (Required).

Note that this value should be unique with respects to all other definitions being defined with this section as well as all definitions being included via the Includes XML Element (See Includes Section)

BaseType

String value representing the attribute defintion that this definition is derived from. (Optional)

Note that the base definition must be defined prior to this definition either in section or in the Includes Section.

Label

String value representing the name display in a GUI (Optional)

Note that if not specified, the Type value is displayed.

Version

Integer value representing the “version” of the definition. (Optional)

This is used for versioning the definition. If not specified then 0 is assumed.

Abstract

Boolean value used to indicate if the definition is abstract or not. (Optional)

If not specified, the definition is not abstract. Note that abstract definitions can not generate attributes.

AdvanceLevel

Integer value used to indicate the advance level associated with the definition and the attributes it generates for reading and modifying. (Optional)

This value should match one of the advance values defined in the Advance Level Section. If not specified, 0 is assumed.

AdvanceReadLevel

Integer value used to indicate the advance level associated with the definition and the attributes it generates for reading. (Optional)

This value should match one of the advance values defined in the Advance Level Section. If not specified, 0 is assumed.

Note if the AdvanceLevel is also specified, AdvanceReadLevel will be ignored.

AdvanceWriteLevel

Integer value used to indicate the advance level associated with the definition and the attributes it generates for modifying. (Optional)

This value should match one of the advance values defined in the Advance Level Section. If not specified, 0 is assumed.

Note if the AdvanceLevel is also specified, AdvanceWriteLevel will be ignored.

Unique

Boolean value used to indicate if the attributes this definition generates are unique with respects to the model entities it associated with. A resource or resource component can only have one unique attribute of a given type associated with it. (Optional)

If not specified, the definition is assumed to be non-unique.

Nodal

Boolean value used to indicate if the attribute effects the nodes of the analysis mesh or the elements. (Optional)

If not specified the definition’s attributes are not nodal.

RootName

String value used to auto-generate names for attributes. (Optional)

If not specified the definition’s type name is used.

Associations

String value indicating what type of model entities this definition’s attributes can be associated on. (Optional)

The information is represented as a string consisting of a set of the following characters separated by vertical bars (|):

v (vertices)

e (edges)

f (faces)

r (volumetric regions)

m (model)

g (groups)

An example would be “e|f” for an attribute which may be associated with both edges and faces. If not specified, the definition’s attributes can not be associated with any model entities.

Note This is an old format and is only for model resource components. Instead you should be using an AssociationsDef XML Element.

NotApplicationColor

String value representing the color to be used when coloring model entities that are not associated with this definition’s attribute. (Optional)

The format is “r, g, b” where r, g, and b are a value between 0 and 1 inclusive. If not specified its value is 0, 0, 0.

Default Color

String value representing the color to be used when coloring model entities that are associated with this definition’s attribute by default. (Optional)

The format is “r, g, b” where r, g, and b are a value between 0 and 1 inclusive. If not specified its value is 0, 0, 0.

CategoryInfo Format

This subsection of an AttDef Element describes the local category constants imposed on the Definition. All Item Definitions belonging to this Definition, as well as all Definitions derived from this, will inherit these constraints unless explicitly told not to.

The category information is divided into two elements:

  • <Include> - represents the set of categories that will make this Definition relevant

  • <Exclude> - represents the set of categories that will make this Definition not relevant.

The children of these elements include <Cat> elements whose values are category names. These elements can optionally include an XML attribute called Combination which can be set to Or or And. If set to And, all of the categories listed must be active in the owning attribute resource in order for the set to be considered satisfied. If Or is specified, then only one of the categories need to be active in order for the set to be satisfied. The default is Or.

The CategotyInfo Element itself can have the following XML Attributes:

XML Attributes for <CategoryInfo> Element

XML Attribute

Description

Combination

String value representing how the Inclusion and Exclusion sets should be combined.

If set to And, then both the Inclusion set must be satisfied and the Exclusion set must not be satisfied in order for the Definition (and the Attributes it generates) to be relevant. If it is set to Or, then either the Inclusion set is satisfied or the Exclusion set is not, in order for the Definition (and the Attributes it generates) to be relevant.

(Optional - Default is And)

InheritanceMode

String value that indicates how the Definition should combine its local category information with the category information inherited from its Base Definition.

If set to And, then its local category information will be and’d with its Base Definition’s. If it is set to Or, then its local category information will be or’d with its Base Definition’s. If it is set to LocalOnly, then the Base Definition’s category information will be ignored.

(Optional - the default is And)

AssociationsDef Format

The format is an extension of the Reference Item Based Definitions. When dealing with Model Resource Components you can use a MembershipMask XML Element to indicate the type of Model Resource Component that can be associated.

<AssociationsDef Name="BC Sets" NumberOfRequiredValues="0" Extensible="true">
  <MembershipMask>edge</MembershipMask>
</AssociationsDef>

The following table shows the XML Attributes that can be included in this XML Element in addition to those supported by Reference Item Definition.

XML Attributes for <AssociationsDef> Element

XML Attribute

Description

OnlyResources

Boolean value indicating that the association is only to Resources. (Optional).

<ReferenceLabels>

Defines the labels that should be displayed next to the Item’s values. This element should only be specified if the Item is either Extensible or has NumberOfRequiredValues > 1.

See Specifying Labels. (Optional)

Exclusions Format

Contains a set of Definition exclusion rules. An exclusion rule is a set of Definitions that exclude each other. This means an Attribute from one of these excluded Definition that is associated with a Resource/ Resource Component will prevent attributes from any of the other excluded Definitions from being associated to the same Resource/Resource Component.

XML Children Elements for <Exclusions> Element

XML Child Element

Description

<Rule>

Defines a new Exclusion Rule

Each exclusion rule is a set of Def XML Elements. Each Def XML Element contains the name of a Definition type.

Note A rule must contain at least 2 Def Elements.

XML Children Elements for <Rule> Element

XML Child Element

Description

<Def>

Contains a Definition Type

Here is an example of an Exclusion Rule where Definitions A and B exclude each other:

<Exclusions>
   <Rule>
     <Def>A</Def>
     <Def>B</Def>
   </Rule>
 </Exclusions>

Prerequisites Format

Contains a set of Definition prerequisite rules. An prerequisite rule refers to a Definition and a set of prerequisite Definitions.

XML Children Elements for <Prerequisites> Element

XML Child Element

Description

<Rule>

Defines a new Prerequisite Rule

Each Prerequisite rule refers to a Definition that has the prerequisite which is represented as a set of Definitions.

XML Attributes for <Rule> Element

XML Attribute

Description

Type

String value representing the Definition type that has the prerequisite

XML Children Elements for <Rule> Element

XML Child Element

Description

<Def>

Contains a Definition Type

Here is an example of an Exclusion Rule where Definition A has a prerequisite requiring that an attribute of Type C must be associated to an object in order to be able to associate an attribute of type A to the same object.

<Prerequisites>
   <Rule Type="A">
     <Def>C</Def>
   </Rule>
 </Prerequisites>

Item Definitions Format

This subsection of an AttDef Element contains the definitions of all the items to be created within the attributes created by the attribute definition. The section is represented by the <ItemDefinitions> XML Element and can contain any of the elements described in the Item Definition Section.

Item Definition Section

All of the XML Elements described within this section can be added to any of the following elements:

  • <ItemDefinitions> of an attribute definition <AttDef> or Group Item Definition <Group>

  • <ChildrenDefinitions> of a Value Item Definition (<Double>, <Int>, <String>)

The types of items currently supported include:
  • Basic Values: Doubles, Integers, and Strings

  • Groups

  • Attribute References

  • Directories and Files

  • Model Information

  • Voids

All the elements can contain the following children XML Elements. Note that each element may have additional XML Children Elements that are specific to it.

This element can contain the following children XML Elements:

Common XML Children Elements for Item Definition Elements

XML Child Element

Description

<CategoryInfo>

Specifies the local category constraints specified on the Item Definition. The format is identical to the one used for Attribute Definitions except that the category inheritance mode controls how the Item Definition’s local category information is combined with the category information it inherits from either its owning Attribute or Item Definition. (Optional)

See CategoryInfo Format.

<BriefDescription>

Provides a brief description of the item (Optional).

<DetailedDescription>

Provides a detailed description of the item (Optional).

All of the elements support the following common XML Attributes. Note that each element may have additional XML Attributes that are specific to it.

Common XML Attributes for Item Definition Elements

XML Attribute

Description

Name

String value representing the name of the item being defined. (Required)

Note that this value should be unique with respects to all other items contained within this attribute definition (including its Base Type).

Label

String value representing the label that should be displayed in the GUI for the item. (Optional - if not specified the Item’s Name will be used)

Note if it is set to ‘ ‘, this will indicate that no label should be displayed..

Version

Integer value representing the “version” of the item. (Optional)

This is used for versioning the item. If not specified then 0 is assumed.

Optional

Boolean value indicating if the item is considered optional or required. (Optional)

If not specified the item is considered to be required.

IsEnabledByDefault

Boolean value indicating if the item is considered to be enabled by default. (Optional)

Note this is only used when Optional=”true”. If not specified, the item is considered to be disabled.

AdvanceLevel

Integer value used to indicate the advance level associated with the item. (Optional)

This value should match one of the advance values defined in the Advance Level Section. If not specified, 0 is assumed.

AdvanceReadLevel

Integer value used to indicate the advance read level associated with the item. (Optional)

This value should match one of the advance values defined in the Advance Level Section. Note that this is ignored if the AdvanceLevel XML Attribute is used.

If not specified, 0 is assumed.

AdvanceWriteLevel

Integer value used to indicate the advance write level associated with the item. (Optional)

This value should match one of the advance values defined in the Advance Level Section. Note that this is ignored if the AdvanceLevel XML Attribute is used.

If not specified, 0 is assumed.

Simple Void Items

A Void Item Definition, represented by a <Void> XML Element, is used to represent boolean information. By itself, it contains no additional information beyond what is specified for the information above and its corresponding item value rely solely on its enabled state. As a result, Void Items are almost always Optional.

Basic Value Items

Basic Value Items include Strings, Integers and Doubles. They are represented as follows:

XML Elements for Basic Value Item Definition.

XML Element

Description

<Int>

Represents an Integer Item Definition

<Double>

Represents a Double Item Definition

<String>

Represents a String Item Definition

Common XML Attributes for Value Item Definition Elements

XML Attribute

Description

NumberOfRequiredValues

Integer value representing the minimum number of values the Item should have. (Optional - if not specified assumed to be 1)

Extensible

Boolean value indicating that the Item’s number of values can be extended past NumberOfRequiredValues. (Optional - if not specified assumed to be false)

MaxNumberOfValues

Integer value representing the maximum number of values the Item can have. A value of 0 means there is no maximum limit. (Optional - if not specified assumed to be 0)

Note - this is only used if Extensible is true.

Units

String value representing the units the Item’s value(s) are specified in. (Optional - if not specified assumed to be “”)

Common XML Children Elements for Basic Value Item Definition Elements

XML Child Element

Description

<DefaultValue>

For Integer, String, and Double items, this element’s text contains the default value for the item. This element is not allowed for other ItemDefinition types. See Specifying Default Values. (Optional)

<RangeInfo>

Defines a value range for the Item’s values.

See Specifying Ranges. (Optional - if not specified there is no range constraint.)

<ComponentLabels>

Defines the labels that should be displayed next to the Item’s values. This element should only be specified if the Item is either Extensible or has NumberOfRequiredValues > 1.

See Specifying Labels. (Optional)

<ExpressionType>

Indicates that the Item’s value(s) can be represented using an expression of the indicated type. (Optional)

<DiscreteInfo>

Indicates that the Item is restricted to a discrete set of values See Modeling Discrete Information Section (Optional)

<ChildrenDefinitions>

A set of Item Definitions that are referenced in the Item’s <DiscreteInfo> element. The contents is identical to an Attribute Definition’s <ItemDefinitions> element. (Optional)

Specifying Default Values

For items that are not discrete and not extensible but do have NumberOfRequiredValues greater than 1, it is possible to provide a different default value for each component. In this case, commas are assumed to separate the values. If you wish to use a different separator, specify the “Sep” attribute on the DefaultValue tag.

For example, a String item with 3 components might use

<DefaultValue Sep=":">Oh, my!:Oh no!:Yes, please.</DefaultValue>

to specify different defaults for each component. You can also use the separator to prevent a default value from having per-component values. For instance, the same String item might use

<DefaultValue Sep=":">Commas, they are my style.</DefaultValue>

to force the default value to have a single entry used to initialize all components.

Specifying Ranges

The RangeInfo Element can indicate the min and/or max value for the an Item’s value(s) as well as indicating if these values are inclusive or exclusive. This element is used for Double or Integer Item Definitions.

XML Children Elements for <RangeInfo> Elements

XML Child Element

Description

<Min>

Sets the minimum value for the Item’s value(s) (Optional)

<Max>

Sets the maximum value for the Item’s value(s) (Optional)

XML Attributes for <Min> / <Max> Elements

XML Attribute

Description

Inclusive

Boolean value indicating if an Item’s value can be set to the min / max value. (Optional - if not specified it is assumed to be false)

In the example below, CommonDouble must be strictly > 0.

<Double Name="CommonDouble" Label="Floating Pt Val" Version="0" NumberOfRequiredValues="1">
  <DefaultValue>3.1415899999999999</DefaultValue>
  <RangeInfo>
    <Min Inclusive="false">0</Min>
  </RangeInfo>
</Double>

Specifying Labels

XML Attributes for <ComponentLabels> Element

XML Attribute

Description

CommonLabel

String Value representing the label that should precede each of the Item’s values when being displayed (Optional)

If each value requires a different label, this element would contain a set of <Label> elements (one for each value) as shown below:

<ComponentLabels>
  <Label>t</Label>
  <Label>u</Label>
  <Label>v</Label>
  <Label>w</Label>
</ComponentLabels>

Note - Individual labels are not supported for extensible Items.

Modeling Discrete Information Section

Used when a Double, Integer, or Double Item is restricted to a set of values. Each value can optionally have an enumeration string associated with that would be displayed in an UI instead of the value in order to improve readability. In addition, an enumeration can have categories associated with it, indicating that in addition to satisfying the Item’s category requirements, these requirements must also be met in order for the Item to be set to that particular value. An enumeration can also have an Advance Level associated with it.

An enumeration can also refer to a subset of the Item’s Children Definitions indicating additional Items that need to be filled out when set to that value.

XML Attributes for <DiscreteInfo> Element

XML Attribute

Description

DefaultIndex

Integer value representing the index of the the Item’s discrete value to be used as the Item’s default value.

XML Children Elements for <DiscreteInfo> Element

XML Child Element

Description

<Value>

Simple form when defining only discrete values without category information or associated Item Definitions.

<Structure>

Complete form which contains a <Value> Element

Note - The DiscreteInfo element can be composed of a mixture of both types of children elements.

Simple Discrete Value Form

The Value Element defines the discrete value as well as an optional enumeration string and/or advance level.

XML Attributes for <Value> Element

XML Attribute

Description

Enum

String value representing the enumeration associated with this discrete value (Optional - if not specified, the value will be used)

AdvanceLevel

Integer value representing the advance level associated with the value. (Optional - if not specified, 0 is assumed)

<Value Enum="e3" AdvanceLevel="1">c</Value>
Structured Discrete Value Form

The Structure Element contains a Value element along with optional category and required Item Definitions.

XML Children Elements for <Structure> Element

XML Child Element

Description

<Value>

Simple form when defining only discrete values without category information or associated Item Definitions. See Simple Discrete Value Form.

<CategoryInfo>

Specifies the additional category constraints associated with this discrete value. The format is identical to the one used for Attribute Definitions except that the category inheritance mode is not used. (Optional)

See CategoryInfo Format.

<Items>

Represents the Children Items that are associated with this discrete value. These names should be defined in the Item’s ChildrenDefinitions element.

<Structure>
   <Value Enum="Specific Enthalpy Function">specific-enthalpy</Value>
   <Items>
     <Item>specific-enthalpy</Item>
   </Items>
 </Structure>

Group Item Definitions

A Group Item Definition is defined as a vector of Item Definitions. The Group Item the Definition produces will refer to the corresponding vector of Items produced as a group. It can also be used to define a set of choices that the user needs to select from. In this case, all of the internal Item Definitions are assumed to be optional.

XML Attributes for <Group> Element

XML Attribute

Description

NumberOfRequiredGroups

Integer value representing the minimum number of Item groups the Item should have. (Optional - if not specified assumed to be 1)

Extensible

Boolean value indicating that the Item’s number of groups can be extended past NumberOfRequiredGroups. (Optional - if not specified assumed to be false)

IsConditional

Boolean value indicating that the Group Item represents a vector of choices. (Optional - if not specified assumed to be false)

Note - this is only used if Extensible is true.

MinNumberOfChoices

Integer value representing the minimum number of choices that need to be selected in order for the item to be considered valid. (Optional - if not specified assumed to be 0)

Note - this is only used if IsConditional is true.

MaxNumberOfChoices

Integer value representing the maximum number of choices that can be selected in order for the item to be considered valid. Setting this to 0 indicates that there is no maximum. (Optional - if not specified assumed to be 0)

Note - this is only used if IsConditional is true.

XML Children Elements for <Group> Element

XML Attribute

Description

<ComponentLabels>

Defines the labels that should be displayed next to the Item’s values. This element should only be specified if the Item is either Extensible or has NumberOfRequiredGroups > 1.

See Specifying Labels. (Optional)

<ItemDefinitions>

Defines the items contained within the group generated by this Item Definition (Optional).

See Item Definitions Format.

Here is an example of a Group Item Definition that represents a sets of choices. Please see smtk/data/attribute/attribute_collection/choiceGroupExample.sbt for more examples.

<Group Name="opt1" Label="Pick At Least 2"
  IsConditional="true" MinNumberOfChoices="2" MaxNumberOfChoices="0">
  <ItemDefinitions>
    <String Name="opt1"/>
    <Int Name="opt2"/>
    <Double Name="opt3"/>
  </ItemDefinitions>
</Group>

It produces the following in ModelBuilder:

../../_images/ChoiceExample.png

Reference Item Based Definitions

A Reference Item Definition creates Items that can refer to other SMTK Persistent Objects such as Resources and Resource Components. It makes use of the queries functionally provided by the various resources. Component and Resource Item Definitions are derived from Reference Item Definition and therefore have many of the same XML attributes and children components in common.

Common XML Attributes for Reference Item Based Definitions

XML Attribute

Description

NumberOfRequiredValues

Integer value representing the minimum number of values the Item should have. (Optional - if not specified assumed to be 1)

Extensible

Boolean value indicating that the Item’s number of values can be extended past NumberOfRequiredValues. (Optional - if not specified assumed to be false)

MaxNumberOfValues

Integer value representing the maximum number of values the Item can have. A value of 0 means there is no maximum limit. (Optional - if not specified assumed to be 0)

Note - this is only used if Extensible is true.

EnforceCategories

Boolean value indicating if the reference item’s validity check should also check to see if the item is pointing to an Attribute that would be considered relevant based on the active categories

HoldReference

Boolean value that indicates whether the item should be forcing the Persistent Object to be kept in memory. (Optional: Default is false)

Note - this is currently used for Operation Parameters to make sure removed Resources and/or Components are kept in memory after the operation runs.

LockType

String value that indicates whether the resource being referred to should be locked. Acceptable values are : DoNotLock, Read or Write (Optional)

Note - this is currently used for Operation Parameters only!

Role

Integer value that sets the Role of the links used by the Reference Item. The main use for setting the Role is to use an Unique Role. See Unique Roles Section.

Common XML Children Elements for Reference Item Based Definitions

XML Attribute

Description

<Accepts>

Defines the set of acceptance rules. In order for a SMTK Persistent Object to be referenced by this item, it must pass at least one of these rules (if any have been specified). These are represented by a set of Resource Elements.

See Resource Query Format. (Optional)

<Rejects>

Defines the set of rejection rules. In order for a SMTK Persistent Object to be referenced by this item, it must not pass any of these rules (if any have been specified). These are represented by a set of Resource Elements.

See Resource Query Format. (Optional)

<ComponentLabels>

Defines the labels that should be displayed next to the Item’s values. This element should only be specified if the Item is either Extensible or has NumberOfRequiredGroups > 1.

See Specifying Labels. (Optional)

<ChildrenDefinitions>

Defines the items contained within the reference item generated by this Item Definition (Optional).

See Item Definitions Format.

<ConditionalInfo>

Defines which of the children items should be considered active based on the type of Persistent Object the Item is referencing.

See Specifying Conditional Information for Reference Items. (Optional)

Resource Query Format

This is represented by a <Resource> Element and represents a query that can be used by ReferenceItems and Attribute Associations.

XML Attributes for <Resource> Element for Resource Queries

XML Attribute

Description

Name

String value that represents a Resource Type Name. For example smtk::attribute::Resource. These names are typically defined in the Resource class’s smtkTypeMacro.

Filter

String value representing a query that is valid for Resources referred by the above Name XML attribute.

(Optional - if not specified, the Item is referencing Resources not Resource Components)

Component Item Definition

Component Items can reference a Resource Component and includes all of the structure for Reference Item Based Definitions.

XML Children Elements for <Component> Element

XML Attribute

Description

<ComponentLabels>

Defines the labels that should be displayed next to the Item’s values. This element should only be specified if the Item is either Extensible or has NumberOfRequiredValues > 1.

See Specifying Labels. (Optional)

Resource Item Definition

Resource Items can reference a Resource and includes all of the structure for Reference Item Based Definitions.

XML Children Elements for <Resource> Element

XML Attribute

Description

<ResourceLabels>

Defines the labels that should be displayed next to the Item’s values. This element should only be specified if the Item is either Extensible or has NumberOfRequiredValues > 1.

See Specifying Labels. (Optional)

Specifying Conditional Information for Reference Items

Provides the ability to activate the Item’s children items based on what the Item is currently pointed to. In the following example, the Item is pointing to a LiquidMaterial the Item will have 2 active children named initialTemp and initialFlow, but if it is pointing to a SolidMaterial it will only have 1 active child named initialTemp.

<ConditionalInfo>
  <Condition Resource="smtk::attribute::Resource" Component="attribute[type='SolidMaterial']">
    <Items>
      <Item>initialTemp</Item>
    </Items>
  </Condition>
  <Condition Component="attribute[type='LiquidMaterial']">
    <Items>
      <Item>initialTemp</Item>
      <Item>initialFlow</Item>
    </Items>
  </Condition>
</ConditionalInfo>
XML Attributes for <Condition> Element

XML Attribute

Description

Resource

String value that represents a Resource Type Name. For example smtk::attribute::Resource. These names are typically defined in the Resource class’s smtkTypeMacro.

(Optional - if not specified, it assumes that Component’s query string is applicable to all Resource Components that passes the Item’s Accept/Reject conditions.)

Component

String value representing a Resource Component query that is valid for Resources referred by the above Resource XML attribute if specified or for Resources that passes the Item’s Accept/Reject conditions if it is not specified.

(Optional - if not specified, the Item is referencing Resources and not Resource Components)

Note - that at least one of the Resource or Component XML Attribute must be specified.

XML Children Elements for <Condition> Element

XML Child Element

Description

<Items>

Represents the Children Items that are associated with this discrete value. These names should be defined in the Item’s ChildrenDefinitions element.

Attribute Section <Attributes>

Todo

Describe attributes and how they are serialized

Views Section <Views>

The Views section of an SBT file contains multiple <View> items, one of which should be marked as a top-level view by adding the TopLevel attribute to it. The top-level view is typically composed of multiple other views, each of which may be defined in the Views section.

Each <View> XML element has attributes and child elements that configure the view. The child elements may include information about which attributes or classes of attributes to present as well as how individual items inside those attributes should be presented to the user.

Common XML Attributes for View Definition Elements

XML Attribute

Description

Type

A string that specifies the View’s type and should match the View class name or alias that was used to register the View implementation with the view::Manager

Title

A string that represents the name of the View

Label

A string that is used in place of the View’s title when it is displayed in the UI.

(Optional - if not specified, the View’s title is used.)

TopLevel

Boolean value indicating whether the view is the root view that should be presented to the user or (if TopLevel is false or omitted) the view is a child that may be included by the toplevel view.

(Optional - assumes it is not a top-level view if not specified.)

Analysis View

Alias and Type name for Analysis Views

Alias

Type Name

Analysis

smtk::extension::qtAnalysisView

An Analysis View represents the analysis structure defined in an Attribute Resource. The View will set an Attribute Resource’s Active Categories based on the choices the user has made in the View. The View will generate both an Attribute Definition and Attribute based on the XML attributes if needed.

<View Type="Analysis" Title="Configurations" AnalysisAttributeName="analysis" AnalysisAttributeType="analysis">
 </View>
XML Attributes for Analysis Views

XML Attribute

Description

AnalysisAttributeName

A string that defines the name of the Attribute representing the Analysis.

Note - this name should be unique within the Attribute Resource

AnalysisAttributeType

A string that defines the type name of the Attribute Definition representing the Analysis structure.

Note - this type name should be unique within the Attribute Resource

Here in an example UI of an Analysis View.

../../_images/analysisViewExample.png

Associations View

Alias and Type name for Associations Views

Alias

Type Name

Associations

smtk::extension::qtAssociationView

An Associations View allows users to change an Attribute’s associations but does not allow the user to change the Attribute’s values.

<View Type="Associations" Title="Materials Associations">
  <AttributeTypes>
    <Att Type="Material">
    </Att>
  </AttributeTypes>
</View>

The XML Element should have one child element called <AttributeTypes>. The <AttributeTypes> element is composed of a set of <Att> Elements. Each <Att> must contain an XML Attribute named Type which refers to an Attribute Definition type name.

The View will provide a drop-down list of all smtk::attribute::Attributes that are of (or derived from) one of the specified Attribute Definition types.

Here in an example UI of an Associations View.

../../_images/associatioViewExample.png

Attribute View

Alias and Type name for Associations Views

Alias

Type Name

Attribute

smtk::extension::qtAttributeViewView

An Attribute View allows users to create, modify, and delete smtk::attribute::Attributes.

<View Type="Attribute" Title="Materials">
  <AttributeTypes>
    <Att Type="Material"/>
  </AttributeTypes>
</View>
XML Attributes specifically for Attribute View Elements

XML Attribute

Description

DisableNameField

A boolean that indicates the user should not be able to edit the names of Attributes

(Optional - default is false)

DisableTopButtons

A boolean that indicates the top buttons (New, Copy, and Delete) should be disabled thereby preventing the user from creating or deleting Attributes.

(Optional - default is false)

HideAssociations

A boolean that indicates if the View GUI should not display association information.

(Optional - default is false)

RequireAllAssociated

A boolean that indicates if all Resource/Resource Components that can be associated to a specific type of Attribute should have an Attribute of that type associated with it in order to be considered valid.

(Optional - default is false)

AvailableLabel

A string that is used to indicate the Resources/Components that could be associated with the Attribute.

(Optional - default is Available)

CurrentLabel

A string that is used to indicate the Resources/Components that are currently associated with the Attribute.

(Optional - default is Current)

AssociationTitle

A string that is the title of the widget used deal with the Attribute’s association information.

(Optional - default is Model Boundary and Attribute Associations)

DisplaySearchBox

A boolean that indicates if the user should be able to search Attributes by name.

(Optional - default is true)

SearchBoxText

A string that is used in the search box to indicate what the box is for.

(Optional - default is Search attributes…)

AttributeNameRegex

A string that is used to determine if the name the user entered for an Attribute is valid.

(Optional - default is there is no constraint on the name of an Attribute)

The XML Element should have one child element called <AttributeTypes>. The <AttributeTypes> element is composed of a set of <Att> Elements. Each <Att> must contain an XML Attribute named Type which refers to an Attribute Definition type name.

The View will provide a drop-down list of all non-abstract smtk::attribute::Definitions that are specified (or derived from) the types mentions in the <AttributeTypes> Element. When the user selects one of the Definitions, it will display all of the existing Attributes that match the type in the list view.

When an attribute is selected from the list, the view also displays editing fields for the items contained by the attribute, and an Association widget for assigning the attribute to resource components. (The associations widget is only displayed if the corresponding Attribute Definition includes associations and the HideAssociations option is not set to true.)

Here in an example UI of an Attribute View.

../../_images/attributeViewExample.png

Group View

Alias and Type name for Group Views

Alias

Type Name

Group

smtk::extension::qtGroupView

A Group View represents a collection of other Views. This collection is laid out based on the Style attribute. The supported styles are:

  • tiled - each child view is displayed vertically in the Group View’s Frame.

  • tabbed - each child view is displayed in its own separate tab.

  • groupbox - each child view is displayed vertically within its own collapsible Frame.

<View Type="Group" Name="TopLevel" FilterByAdvanceLevel="true" TabPosition="North" TopLevel="true">
  <Views>
    <View Title="Set Analysis" />
    <View Title="Materials" />
    <View Title="Boundary Conditions" />
  </Views>
</View>

Here is an example of a Group View with Style set to Tabbed.

../../_images/tabbedViewExample.png

Here is the same Group View with Style set to Tiled.

../../_images/tiledViewExample.png

Finally, here is the same Group View with Style set to GroupBox. In this case one of the children is opened and other is closed.

../../_images/groupBoxViewExample.png
XML Attributes for Group Views

XML Attribute

Description

Style

A string that indicates the style to be used to display the View’s children Views.

(Optional and Case Insensitive - default is tabbed)

ActiveTab

A string that corresponds to a child view name. If set and Style is tabbed, then the corresponding tab will be displayed.

(Optional)

TabPosition

A string that corresponds to which side the tabs of a tabbed Group View should be displayed (north, south, east, or west).

(Optional and Case Insensitive - default is north)

This XML element consists of a single child element called <Views>. The <Views> element contains a list of <View> XML Elements.

XML Attributes for <View>

XML Attribute

Description

Title

String value that refers to an existing View that will be displayed as a child to this one.

Open

A boolean that indicates if the groupbox for that child view should be open or closed.

(Optional - default is closed)

Instance View

Alias and Type name for Instance Views

Alias

Type Name

Instance

smtk::extension::qtInstanceView

An Instance View will display a set of an Attributes for the user to edit.

<View Type="Instanced" Title="General">
  <InstancedAttributes>
    <Att Name="numerics-att" Type="numerics"/>
    <Att Name="outputs-att" Type="outputs" />
    <Att Name="simulation-control-att" Type="simulation-control" />
  </InstancedAttributes>
</View>

The XML Element should have one child element called <InstancedAttributes>. The <InstancedAttributes> element is composed of a set of <Att> Elements.

XML Attributes for <Att> Elements

XML Attribute

Description

Name

A string that indicates the name of the Attribute.

Type

A string that indicates the type of the Attribute.

Style

A string that indicates the Style to be used to display the Attribute.

(Optional)

Here in an example UI of an Associations View.

../../_images/instanceViewExample.png

Item Views

If you wish to customize how items of the chosen attributes are presented, you should add an <ItemViews> child to the <Att> tags in the attribute selectors covered in the previous section. Inside <ItemViews> you can add a <View> tag for each item whose appearance you wish to customize.

Todo

Describe <ItemsViews> children

XML Attributes for Item View Elements

XML Attribute

Description

Type

The name of a widget you would like the application to use to present the item (and potentially its children as well) to users. SMTK provides “Box” (for showing a 3-D bounding box widget), “Point” (for showing a 3-D handle widget), “Line”, “Plane”, “Sphere”, “Cylinder”, “Spline”. These types usually only make sense for Group items, although “Box” can also be used for a Double item with 6 required values (xmin, xmax, ymin, ymax, zmin, zmax). Items may also have custom views provided by the application or external libraries; in that case, the Type specifier will be the string used to register the custom view.

ItemMemberIcon, ItemNonMemberIcon

These attributes are only used for ReferenceItem, ResourceItem, and ComponentItem classes. They specify paths (either on disk or, with a leading colon, to Qt resource files) to images to use as icons that display whether a persistent object is a member of the item or not.