Properties: an Overview


Introduction

With MSBN3's property mechanism you can attach strings and numbers to models and nodes.

This overview illustrates the property mechanism by annotating a simple Visual Basic program. The full program is available in Samples\VB\Properties.bas.

Prerequisite Information

The property mechanism is based on MSBN3 collections and maps. See Collections and Maps: an Overview for important background information.

Starting the Example

To start this example, we create a model called aModel with one node called aNode.

    ' ========================================================================
' Create a model with one node
' ========================================================================

' Create a model
Dim aMSBN As New MSBN3Lib.MSBN
Dim aModel As MSBN3Lib.Model
Set aModel = aMSBN.Models.Add

'Create a node
Dim aNode As MSBN3Lib.Node
Set aNode = aModel.ModelNodes.Add("EngineStart")
aNode.States.Add "Working"
aNode.States.Add "Broken"

Defining Property Types

Before a property value can be attached to a model or node, its type must be defined. The definition tells what values the property can have. The five possibilities are:

Property types are defined by adding PropertyType objects to the model's PropertyTypes collection. This is done with the PropertyTypes collection's Add method. This code shows the definition of 5 property types, one for each possibility.

    ' ========================================================================
' Define 5 property types, call the first ptCost
' ========================================================================

' Define a real-valued property type
Dim ptCost As MSBN3Lib.PropertyType
Set ptCost = aModel.PropertyTypes.Add("Cost", "What does it cost?", PROPTYPETYPE:=pttReal)

' Define a string-valued property type
aModel.PropertyTypes.Add "Category", "What is its category?", PROPTYPETYPE:=pttString

' Define a real-array-valued property type
aModel.PropertyTypes.Add "ScoreList", "What are the scores?", PROPTYPETYPE:=pttReal, IsArray:=True

' Define a string-array-valued property type
aModel.PropertyTypes.Add "NameList", "What are the names?", PROPTYPETYPE:=pttString, IsArray:=True

' Define a enumerated property type
aModel.PropertyTypes.Add "Visibility", "How visible is it?", PROPTYPETYPE:=pttEnumerated, _
EnumValues:="Visible, Semivisible, Invisible"

As with other maps and collections, we can use PropertyTypes's Description property to get a quick summary of its contents.

    Debug.Print aModel.PropertyTypes.Description

Output:

Cost,Category,ScoreList,NameList,Visibility

Attaching Properties to Models and Nodes

With some property types defined, property values can be attached to the model and its nodes. This example shows 3 property values being added to the model.

    ' ========================================================================
' Add 3 properties on the model and 3 on the node
' ========================================================================

'Adding three properties to the model
aModel.Properties.Set ptCost, 80#
aModel.Properties.Set "Category", "Science and Nature"
aModel.Properties.Set "ScoreList", Array(2, 3, 5)

Property values are added using the model or node object's Properties collection. As the example shows, the Set method can used to add an association between PropertyType objects and values. The property type can be specified either via an object (e.g. ptCost) or a string (e.g. "Category") or an integer index into the PropertyTypes collection. The value specified is a OLE variant. In the case of array values, an OLE smart array is used.

A summary of the model's current property settings can be found with Description.

    Debug.Print aModel.Properties.Description

Output:

Cost->80,Category->Science and Nature,ScoreList->Array<REAL>(...)

The Set method can also be used to add properties to nodes.

    
'Adding three properties to the node
aNode.Properties.Set 0, 40
aNode.Properties.Set "NameList", Array("Bobcat", "Sparky")
aNode.Properties.Set "Visibility", "Semivisible"
Debug.Print aNode.Properties.Description

Output:

Cost->40,NameList->Array<STRING>(...),Visibility->1

The value of enumerated property types, like the one named "Visibility", can either be an integer or a string. If a string, it must be in the EnumValues list given when the property type was defined.

Accessing a property value

A property value can be accessed by indexing the Properties collection. (For details see: Properties). The value returned by aModel.Properties("ScoreList") is an array. In the example below,  an element of this array is accessed with "(1)".

    ' ========================================================================
' Access a property value
' ========================================================================
Debug.Print aModel.Properties(ptCost)
Debug.Print aModel.Properties("Category")
Debug.Print aModel.Properties("ScoreList")(1)

Output:

 80 
Science and Nature
3

Changing a property value

A property value can be also be changed using the Properties collection's Set method.

    ' ========================================================================
' Change a property value
' ========================================================================
aNode.Properties.Set ptCost, 70#
aNode.Properties.Set "Visibility", 0
Debug.Print aNode.Properties.Description

Output:

Cost->70,NameList->Array<STRING>(...),Visibility->0

Testing for a property

To test if a model or node has a property, use the the Properties collection's ExistingKey method. Here the node does have the "NameList" property but the model nodes not.

    ' ========================================================================
' Assert that node has the "NameList" property but that the model does not
' ========================================================================
Debug.Assert aNode.Properties.ExistingKey("NameList")
Debug.Assert Not aModel.Properties.ExistingKey("NameList")

Removing a property

To remove a property from a model or node has a property, just set its value to Nothing.

    ' ========================================================================
' Remove the "Name List" property from the node
' ========================================================================
aNode.Properties.Set ptCost, Nothing
Debug.Print aNode.Properties.Description

Output:

NameList->Array<STRING>(...),Visibility->0

For Details See:

Other properties and methods of interest:

For more information about accessing, enumerating, displaying, counting, and editing maps such as PropertyType and Properties, see:

To monitor property changes, see these events: