2.2 Taking up a collection | Microsoft Office Automation with Visual FoxPro

Taking up a collection

The object models of the Office applications (along with most COM servers) contain lots of collections, the OOP world s version of arrays. A collection contains references to a number of objects, generally of the same type, and provides access to those objects. Generally, a collection has a plural name, such as Slides, and contains objects that are referred to in the singular: the Slides collection contains a series of Slide objects. Just to be sure that you re good and confused while looking in the Help file, most of the time, you access the collection by a property of the same name: the Presentation object has a Slides property, which references the Slides collection. The Slides collection references a series of Slide objects. Just remember that the collection is plural (as is usually the property to access it), and the object is singular, and you shouldn t have much trouble.

Most collections, including those in Office, have a few standard methods and properties. The Count property tells you how many items are in the collection. Item, which is a method in some collections and a property in others (it s a method in the Office apps), provides access to the individual members of the collection.

Item typically takes a single parameter or index (number) and returns a reference to that member of the collection. In many cases, you can specify the item you want by name rather than number. For example, consider Visual FoxPro s Projects collection (which is a COM collection, rather than native to VFP). If the TasTrade project is open and is the first open project, you can access it as _VFP.Projects.Item[1] or _VFP.Projects.Item["TasTrade.PJX"].

In addition, most collections let you omit the Item keyword and simply attach the parameter/index to the collection name. So you can write _VFP.Projects["TasTrade.PJX"] or _VFP.Projects[1] and still get a reference to the project.

As with Visual FoxPro s arrays, you can use either square brackets or parentheses to access the elements of a collection. In this book, we use square brackets for both arrays and collections and leave parentheses to indicate functions and methods.

Changing the collection

Once you get past Count and Item, there s more diversity. Most, but not all, collections have an Add method, which allows you to add a new item of the appropriate type to the collection. For example, you use the Add method of Word s Documents collection to create a new, empty document, and the Add method of Excel s Workbooks collection to create a new, empty workbook. In fact, you also use the Add method of Excel s Worksheets collection to add a new worksheet to an existing Workbook.

There s no common technique for removing items from collections. That s because some types of items remove themselves when they no longer belong in the collection. For example, when you close a Workbook in Excel, it removes itself from the Workbooks collection.

The methods that do remove objects from collections tend to belong to the object itself, not to the collections. Although adding and removing may seem like complementary operations to us, from an object point of view, they really aren t. When you re adding, you have only the collection to work with; you don t yet have the thing you re adding. When you re ready to remove it, you have it in hand and can ask it to remove itself. So Add methods belong to collections, while Remove methods (or the methods that cause members to be removed) belong to members of a collection.

Some collections have a fixed number of entries. For example, the Borders collection in Excel represents the four borders of a range. This collection always has four items; there s no way to add items to it or remove items from it. (Word and PowerPoint also have similar Borders collections, with a fixed number of entries.)

Other collections are modified by other actions in the system. For example, Word s Revisions collection contains the changes that have been made to a document. You can t add or remove items directly because they re handled through a different mechanism.