Implements collection and dictionary features. Items are of VARIANT type - i.e. collection can hold items of all automation compatible types.

Current version 2.0.2. Items marked with * are available from version 2.0, Items marked with ** are available from version 2.0.2

Definitions: Sub-collection, VarDictionary tree 

Properties:

Root - Sets/gets VARIANT currently used as a  "root" value. This is the value returned by the Item default property when used without parameters.

Missing - Sets/gets VARIANT currently used as a "missing" element. This is the value returned by the Item default property when the key/index specified does not exist in the collection.

Info - Sets/gets VARIANT used as custom information. This property can be used to attach some application specific data (or object) to the collection object.

Key - returns the item key name.

Item - default, indexed property - retrieves an item from the collection.

Count - returns the items count.

classVersion - returns the the class version as long. Low word contains minor version number, High word contains major version number. Strongly recommended if your application relies on the existing component on the target system. 

_NewEnum - returns IEnumVariant interface. Standard property required to implement collection enumeration - never referred directly in the scripts.

Behavior properties

firstItemAsRoot - Sets/gets Boolean that determines what value to return if the Item property is referenced without index.

itemsAssignmentAllowed - Sets/gets Boolean - allows/disallows items assignment.

enumItems - Sets/gets Boolean - defines the enumeration behavior.

allowUnnamedValues - Sets/gets Boolean - allows/disallows unnamed items.

allowDuplicateNames - Sets/gets Boolean  - allows/denies name duplication for the collection items.

** extractValues - Sets/gets Boolean  - if set to true forces the collection to extract values if objects are assigned/added.

** readOnly - Sets/gets Boolean  - makes the collection read only.

Methods:

Add - Adds new item to the collection.

Clear - Removes all items from the collection.

Remove - Removes item specified from the collection

Set - Sets existing or Adds new item to the collection.

* Clone - Creates a copy of the collection and its sub-collections (if any)

* CreateNew - Creates a new VarDictionary with the same behavior properties

* FindByName - Searches for an item with given name in the collection and its sub-collections.

* FindByValue - Searches for sub-collections containing items with given name and value.

** FindByInfo - Searches for an item with given name in the collection and its sub-collections.

Definitions

Sub-collection: VarDictionary may contain any item that can be hold by a VARIANT variable (all the variables used in the scripting languages are VARIANTs by default). Therefore an item contained in a VarDictionary could be another VarDictionary object that contains other items and may be other VarDictionaries (sub-collections).

VarDictionary tree: The above defines a tree-like structure where the nodes are VarDictionary obejcts and the items in their leaves are anything else - values, other objects etc.

What is contained in a certain VarDictionary depends on its usage. You may want to build such a tree for your own purposes or you may receive it as result of a call to a method of another object. When receiving a VarDictionary object from another method check its documentation to learn what could be contained in it - a few values, set of objects and values or a tree of VarDictionaries.

In all those cases you need only to know VarDictionary object in order to be able to deal with object received. No matter what it contains (a model of a document, set of parameters, some variables etc.) - the basic methods and properties of VarDictionary object will be available for your application. We use this universal collection object in all places where collection is needed. Except a few special cases where VarDictionary is not applicable all the collections returned by other objects or passed to an event handler function in your script are VarDictionaries. 

Thus you could think for VarDictionary object as for a node object or as for a dictionary, or as for a tree. In all the cases it is the same object with the same features and only the role depends on the particular usage.

It is used in:

• ALP to implement Request.Form, Request.QueryString, Request.ServerVariables collections

• ASP Compiler to implement the project tree, variable collections, configuration variables etc.

• ASP Compiler parser to implement the model of the HTML/ASP page.

• Storages and Files to implement the Drive and Contents collections

• And many others.

The component and the entire Pack1 DLL are freeware (with e-mail support only if they are part of a product bought from us). You are permitted to use them in your applications and redistribute them with the application.  

Remarks

VarDictionary class is a multipurpose collection implementation used in many of our products. It keeps compatibility with previous versions and can be used freely in any application without need of licensing. Only requirement is its installation place. We strongly recommend to install it in the Common files\newObjects\ActiveX directory. This directory is typically a subfolder of the Program files folder on the target machine. Installing the DLL in a standard place helps the other setups to update it if needed.