<< Click to Display Table of Contents >> Using collections

The fourth group of members of the Application object are pointers to collections.

Collections are, as their name indicates, lists of objects belonging together. For example, there is a collection called Application.Workbooks that contains all open documents and a collection called Application.RecentFiles with all files that are listed in the history section of the File menu.

There are two standardized ways of accessing collections and PlanMaker supports both. The more simple way is through the Item property that is part of every collection:

' Display the name of the first open document:

MsgBox pm.Application.Workbooks.Item(1).Name

' Close the (open) document "Test.pmdx":

pm.Application.Workbooks.Item("Test.pmdx").Close

If you wish to list all open documents, for example, first find out the number of open documents through the standardized Count property, then access the objects one by one:

' Return the names of all open documents:

For i = 1 To pm.Application.Workbooks.Count

  MsgBox pm.Application.Workbooks.Item(i).Name

Next i

Every collection contains, by definition, the Count property which lets you retrieve the number of entries in the collection and the Item property that lets you directly access one entry.

Item always accepts the number of the desired entry as an argument. Where it makes sense, it is also possible to pass other arguments to Item, for example file names. You have seen this already above, when we passed both a number and a file name to Item.

For most collections, there is a matching object type for their individual entries. The collection Windows, for example, an individual entry that is returned by Item is of the type Window – note the use of the singular! One entry of the Workbooks collection is called Workbook, and an entry of the RecentFiles collection is called RecentFile.

A more elegant approach to collections: For Each ... Next

There is a more elegant way to access all entries in a collection consecutively: BasicMaker also supports the For Each statement:

' Display the names of all open documents

Dim x As Object

For Each x In pm.Application.Workbooks

  MsgBox x.Name

Next x

This gives the same results as the method previously described:

For i = 1 To pm.Application.Workbooks.Count

  MsgBox pm.Application.Workbooks.Item(i).Name

Next i

Additional properties and methods of collections

Some collections may have their own properties and methods, in addition to the standard members Item and Count. For example, if you wish to create an empty document in PlanMaker, this is achieved by adding a new entry to its Workbooks collection:

pm.Application.Workbooks.Add   ' create empty document