Utility components Behavior properties
VarDictionary collection supports a number of behavior properties. Depending on their values collection behavior can be tuned. All the behavior properties are read/write. It is recommended to set them in the code that fills/creates the collection and not write new values in the code that only "reads" the collection, but the actual rules depend on the application specifics and on the collection purpose.

All the properties are by default set to false.

Behavior properties:

firstItemAsRoot - true - configures VarDictionary object to return the first item from the collection if the Item property is used without index/key argument. false - Value set to the Root property will be returned in this case. Also if the firstItemAsRoot property is set to true but collection is empty then Root will be returned. Default: false

itemsAssignmentAllowed - true - allows put/write operations through the Item property, false - attempt to assign a value through the Item property will cause an error. If the assignment is allowed the behavior of the Item property is the same as the Set member. Default: false

enumItems - true - enumerator returned by the _NewEnum property will enumerate the collection items, false - enumerator will enumerate the keys/item names. Default: false

allowUnnamedValues - true - allows addition of unnamed items to the collection (see Add), false - only named items can be added - if the key passed to the Add member is an empty string or VT_EMPTY add operation will fail. Default: false

allowDuplicateNames - true - allows addition of the items with duplicate names, false - if the name passed to the Add method is already used in the collection then the operation will fail. Default: false

extractValues - true - attempts to extract value if the assigned variable contains object. Recourses the objects if needed and uses their default property/method. This affects all the assignment operations except the Info property which remains unchanged. This property allows you to instruct given collection to accept only non-object elements. false - any assignment/add value will succeed.

readOnly - true - all the Add/Set methods will return error. false - normal behavior. This property may be of some use in complex applications where one part passes collections to another.


In most cases allowUnnamedValues and allowDuplicateNames should be set to true or false together, because allowing any count of unnamed items and only one item with a given name may cause confusion. But this is not a requirement - only style recommendation.

Another style recommendation: If the application can be separated logically in two parts - first that creates and fills the collection and second that accesses the items in it, then is recommended to set these properties in the first part and not attempt to change their values in the consuming part of the application. If the consuming part of the application requires behavior change it is recommended for it to restore the original values after finishing its work. Such a dynamic change of the behavior of the collection can be a source for errors in a multithreaded application, thus it is strongly recommended to avoid such kind of techniques in it.

Applies to: VarDictionary

See also: Add method, Root property, Set


newObjects Copyright 2001-2005 newObjects [ ]