<< 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.Documents 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 TextMaker 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 tm.Application.Documents.Item(1).Name

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

tm.Application.Documents.Item("Test.tmdx").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 tm.Application.Documents.Count

 MsgBox tm.Application.Documents.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. Individual entries of the collection Windows, for example, that are returned by Item are of the type Window – note the use of the singular! One entry of the Documents collection is called Document, and one 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 tm.Application.Documents

 MsgBox x.Name

Next x

This gives the same results as the method previously described:

For i = 1 To tm.Application.Documents.Count

 MsgBox tm.Application.Documents.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 TextMaker, this is achieved by adding a new entry to its Documents collection:

tm.Application.Documents.Add   ' Create an empty document