A drawback of using automation is that calls between the applications are relatively slow.  To ensure that your scripts run quickly it is important to reduce the number of calls between the applications.  In Multiframe we have introduced list objects that provide a means of accessing and manipulating the properties a number of objects in a single statement.  List objects are similar to collections in that they store a number of objects in an array.  However, list objects can store an arbitrary group of objects while collections store all the instances of a particular type of object.  For example, the Nodes collection provides a reference to all the nodes in a frame.  An arbitrary subset of these nodes can be stored using the NodeList object.

Each collection of objects in Multiframe has a corresponding list object that may be used to store an arbitrary list of objects.  All list objects have a number of common properties and methods for manipulating their content.  These are summarised in the tables below.

The behaviour and use of these properties is described in detail in the following sections.  Each list object also has a number of properties that it inherits from the objects it contains.  These properties can be used to access the properties of each of the objects contained within the list.  For example, the NodeList object has Label, x, y, z and Pinned properties that are used to access the properties of all the node objects contained within the list.  In general, list objects have most of the properties of the objects contained within the list.  The properties of individual list objects used in the Multiframe object model are not described in detail within this manual.  Instead, a general description of how these properties are derived from the properties of the objects contained in the list is provided in this chapter. 

List objects differ from the other objects and collections in Multiframe object model, as they do not have a direct representation within the Multiframe user interface.  When declaring a list object, a new instance must be created by declaring the object using the New keyword.  For example

Dim myList as New Multiframe.ElementList
Dim myOtherList as New Multiframe.NodeList

The list objects have just two properties that are common to all list objects.  The Count property of a list object returns the number of items in the list while the Unique property determines if each item in the list must be unique. That is to say that any object can only appear in the list once.  If a list is set to contain only unique items then adding any items to a list that are already in the list will have no effect and no error message will be returned.  Furthermore, if a list is set unique then all duplicate items will be removed from this list. By default all items in a list are not required to be unique.  A useful application of a unique list is illustrated below in which the number of sections used in the frame is computed.

Dim myElList As New Multiframe.ElementList
Dim mySectList As New Multiframe.SectionList

'Get list of all elements in frame
myElList.Add mfApp.Frame.Elements

'Get list of sections used by each element
mySectList.Add myElList.section

'Get list of sections used in Frame
mySectList.Unique = True

’Tell user how many sections used in the frame.
MsgBox mySectList.Count & " sections are used in the frame"

’Nullify objects
Set myElList = Nothing
Set mySectList = Nothing

In addition to the properties common to all lists, each list object has many of the same properties as the objects it contains.  However, these properties do not return a single value but a variant containing an array of values, each array entry corresponding to the value of the property for each item within the list.  For example, the NodeList object has x, y and z properties describing the location of the nodes in the list.  Each property returns an array of real number values representing the position of each node in the list.

The properties of a list may also be used to set the values of properties of objects referenced by the list.  In this case the property of the list can be set equal to a single value, in which case the same value will be applied to all items within the list, or the property can be set equal to an array of values that specifies a separate value for each item in the list.  In the following example, the x-coordinate of all nodes in a frame are scales by a factor of 2.5.  The script firstly extracts all the x-coordinates of each node into an array.  The values in this array are then multiplied by a factor of 2.5.  This array is then used to set the x-coordinates of the nodes in the list.  The final line of the script then sets the z-coordinate of all the nodes in the list to zero.

Dim myNodeList as New Multiframe.NodeList
Dim myVar as Variant

’Add all nodes in frame to a list of nodes
myNodeList.Add mfApp.Frame.Nodes

’Get x coordinates of nodes
myVar = myNodeList.x

’Scale x coords of nodes by factor of 2.5
For i=1 to Ubound(myVar)
  myVar(i)= myVar(i)*2.5
Next

’Set coordinates of nodes
myNodeList.x = myVar
myNodeList.z = 0.0

This script execute much faster than one that loops over each node in the frame and sets each coordinate separately as it significantly reduces the number of subroutine calls made between Multiframe and the host application.  This script requires only three (3) inter application calls to retrieve and set the coordinates of the node.  When compared to the three (3) calls per node required when looping over the individual nodes in the frame the savings in time are significant.

An item is added to a list using the Add method.  By adding an item to a list we are adding a reference to that item to the list.  This should not be confused with the Add methods of the collection objects that create new items within the frame.  To complement this method, the Remove method is used to remove items from the list. These methods take one or more variant parameters that specify the items to be added to the list.  List of nodes, elements and other objects modelling the frame require only a single parameter that identifies the items to be added or removed from the list.  As it is a variant value any value representing a single object or a number of objects contained by the list would be valid. For example, the contents of an ElementList object could be specified in any of the following ways

Dim myElList as New Multiframe.ElementList
Dim myOtherList as New Multiframe.ElementList

’Add items to lists
myElList.Add 6           ‘Add element 6 to list
myElList.Add mfApp.Frame.Elements(2) ‘Add element using element object
myOtherList.Add “1,2,5-10”      ‘Add list of elements to list
myElList.Add myOtherList        ‘Add another list

myElList.Clear                  ’Remove all elements from list
myElList.Add mfApp.Frame.Elements ‘Add entire collection

’Nullify objects
Set myElList = nothing
Set myOtherList = nothing

This example uses the Clear method of the list object. This method, which is common to all list objects, removes all items from the list.  List of items such as loads or sections allow for two parameters to be used as part of the Add method in order to specify the items to be added to the list.  In these cases, the objects to be referenced by the list cannot be referenced by only their index or number and require a second parameter to specify a load case, section group or result type.  The following code demonstrates how to create list of element loads.

Dim myList as New Multiframe.ElementLoadList
 
With mfApp.Frame
  ’Add items to lists using loads index within a load case
  myList.Add 6,2                ‘Add load 6 from load case 2
  myList.Add “1-5”,2            ‘Add loads 1 to 5 from case 2
  myList.Add “6-10”,”DL + LL”   ‘Add loads from “DL+LL” case
  myList.Add “1,5,9”,.LoadCases(1) ’Add loads from 1st case

  ’Add loads using objects
  myList.Add .LoadCases(1).ElementLoads(2) ‘Add load using load object
  myList.Add .LoadCases(1).ElementLoads    ‘Add collection of loads

End With

All of the items in a list can be deleted from a frame using the Delete method of a list object.  Do not confuse this method with the Remove method that only removes a reference to an object from the list. The following code uses list objects to delete all the loads applied to a group of elements.

Dim myElList as New Multiframe.ElementList
Dim myLoadList as New Multiframe.ElementLoadList
 
’Create list of elements
myElList.Add “1-10”

’Get list of all loads applied to these elements
Set myLoadList = myElList.Loads

’Delete these loads
myLoadList.Delete

The Find method of a list object is used to search the items in the list for objects with properties matching a specified criterion.  This fianl section of the manual is dedicated to this method.