Utility components VarDictionary collection
For overview information and ClassID/ProgID of the classes see the newObjects collection overview 

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:

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

prop_rw.gif (218 bytes) 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.

prop_rw.gif (218 bytes) 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.

prop_r.GIF (130 bytes) Key - returns the item key name.

prop_rw.gif (218 bytes) Item - default, indexed property - retrieves an item from the collection.

prop_r.GIF (130 bytes) Count - returns the items count.

prop_r.GIF (130 bytes) 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. 

prop_r.GIF (130 bytes) _NewEnum - returns IEnumVariant interface. Standard property required to implement collection enumeration - never referred directly in the scripts.

Behavior properties

prop_rw.gif (218 bytes) firstItemAsRoot - Sets/gets Boolean that determines what value to return if the Item property is referenced without index.

prop_rw.gif (218 bytes) itemsAssignmentAllowed - Sets/gets Boolean - allows/disallows items assignment.

prop_rw.gif (218 bytes) enumItems - Sets/gets Boolean - defines the enumeration behavior.

prop_rw.gif (218 bytes) allowUnnamedValues - Sets/gets Boolean - allows/disallows unnamed items.

prop_rw.gif (218 bytes) allowDuplicateNames - Sets/gets Boolean  - allows/denies name duplication for the collection items.

**prop_rw.gif (218 bytes) extractValues - Sets/gets Boolean  - if set to true forces the collection to extract values if objects are assigned/added.

**prop_rw.gif (218 bytes) readOnly - Sets/gets Boolean  - makes the collection read only.

Methods:

method.gif (107 bytes) Add - Adds new item to the collection.

method.gif (107 bytes) Clear - Removes all items from the collection.

method.gif (107 bytes) Remove - Removes item specified from the collection

method.gif (107 bytes) Set - Sets existing or Adds new item to the collection.

*method.gif (107 bytes) Clone - Creates a copy of the collection and its sub-collections (if any)

*method.gif (107 bytes) CreateNew - Creates a new VarDictionary with the same behavior properties

*method.gif (107 bytes) FindByName - Searches for an item with given name in the collection and its sub-collections.

*method.gif (107 bytes) FindByValue - Searches for sub-collections containing items with given name and value.

**method.gif (107 bytes) 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.

newObjects Copyright 2001-2005 newObjects [ ]