Working with Folders: The Folders Collection

[Previous] [Next]

The MAPIFolder object in Outlook represents a single folder, whereas the Folders collection represents a group of MAPIFolder objects. To add a little bit more confusion, a MAPIFolder can have a Folders collection of MAPIFolder objects. This is due to Outlook's support of host subfolders under another folder. The following section describes the properties and methods of the MAPIFolder object.

MAPIFolder Object Properties

The MAPIFolder object contains many properties, but you should have to use only a subset of them. The next section describes the most important properties and how you can use them in your applications. For a complete list of the methods and properties for the MAPIFolder object, refer to the Olform.hlp file on the companion CD.

DefaultItemType Property

This property returns the Outlook default item type for the folder, such as olContactItem (2), olTaskItem (3), and olMailItem (0). Even though a certain Outlook type might be the default item type for a folder, you cannot have other types of items in the folder. For a complete list of constants in Outlook, see the Olform.hlp file. The following code block checks the default item type for a folder and displays this to the user.

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oInbox = oNS.GetDefaultFolder(6)         longDefaultItem = oInbox.DefaultItemType         Select case longDefaultItem             case 0                 txtType = "MailItem"             case 1                 txtType = "AppointmentItem"             case 2                 txtType = "ContactItem"             case 3                 txtType = "TaskItem"             case 4                 txtType = "JournalItem"             case 5                 txtType = "NoteItem"             case 6                 txtType = "PostItem"         end Select         msgbox "The default item type for this folder is: " & txtType     End Sub 

DefaultMessageClass Property

The DefaultMessageClass property, which is read-only, returns a string that contains the default message class set for the folder. For most folders in your mailbox, this default will be a standard message class such as IPM.Note or IPM.Contact. However, for your application folders, this default can be any valid message class for your custom forms, such as IPM.Contact.Account info or IPM.Task.Project Tracking. The following code loops through all top-level folders in your mailbox and tells you what the default message class is for each folder:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         oCurrentUser = oNS.CurrentUser.Name         set oMAPIFolder = oNS.Folders("Mailbox - " & oCurrentUser)         set oMAPIFolders = oMAPIFolder.Folders         For each Folder in oMAPIFolders         msgbox "The default message class for " & Folder.Name & _             " is: " & Folder.DefaultMessageClass         next     End Sub 

Description Property

The Description property corresponds to the text description you type for your custom forms in the General tab in the properties for the folder. This property is a read/write string, so you can modify it programmatically. Use this description field to help the users of your application know what the form is used for in your application. The following code sets the description for the built-in Outlook Contact folder:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oFolder = oNS.GetDefaultFolder(10)         oFolder.Description = "This folder is used for personal contacts."     End Sub 

Folders Property

As mentioned earlier, Outlook folders can have subfolders. The Folders property on a MAPIFolder object returns all the folders that the current folder contains.

Items Property

The Items property returns a collection containing the Outlook items in the folder. From the returned collection, you can manipulate individual items based on their types. For example, if the folder contains task items, you can assign or mark complete tasks programmatically using the TaskItem object. (This object is described later.) The following code shows how you can use the Items property in your application to return the items in a folder:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oInbox = oNS.GetDefaultFolder(6)         set oItems = oInbox.Items         intCount = oItems.Count         msgbox "There are " & intCount & " items in the folder."     End Sub 

UnreadItemCount Property

The UnreadItemCount property returns the number of unread items in the folder. This property makes it easier to retrieve this commonly requested number because you don't have to scroll and count all the unread items or create a filter to count the unread items. The following code sample displays the number of unread messages in your Inbox:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oFolder = oNS.GetDefaultFolder(6)         msgbox "The number of unread messages is " & _             oFolder.UnreadItemCount     End Sub 

MAPIFolder Object Methods

All MAPIFolder object methods are important to learn. Some are self-explanatory, such as Display, MoveTo, and CopyTo. One method in particular—the GetExplorer method—requires a bit of explanation. Its flexibility makes it very powerful in your applications, but if you're not careful using it, it can cause problems in your Outlook application.

GetExplorer Method

The GetExplorer method returns a new, inactive Explorer object with the current folder object as its initial folder. Once the inactive Explorer object is returned, you can use the Display method to display the Explorer. GetExplorer also takes an optional argument, which is the type of navigation the returned Explorer object should have. The constants this argument will take are olFolderDisplayNormal (0), olFolderDisplayFolderOnly (1), and olFolderDisplayNoNavigation (2). The first mode, olFolderDisplayNormal, is exactly like the standard Outlook client with an Outlook bar, a message panel, and a folder banner. The second mode, olFolderDisplayFolderOnly, will display the Explorer with no folder list or Outlook bar. The final mode, olFolderDisplayNoNavigation, displays the Explorer in the most restrictive way, without any navigation capabilities at all; the user will not be able to switch to any other folder besides the one in the Explorer.

Don't forget to destroy Explorer objects—both active and inactive—in your code, or you will leave Outlook running on the machine after you think it is shut down. It is good practice to kill all Explorer objects that are not needed in the Item_Close event. We'll look at how to do this later on in this supplement.

The following code opens up three folders by using the three different modes of the GetExplorer method:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oInbox = oNS.GetDefaultFolder(6)         set oCalendar = oNS.GetDefaultFolder(9)         set oContacts = oNS.GetDefaultFolder(10)         set oExplorerMode0 = oInbox.GetExplorer(0)         oExplorerMode0.Display         set oExplorerMode1 = oCalendar.GetExplorer(1)         oExplorerMode1.Display         set oExplorerMode2 = oContacts.GetExplorer(2)         oExplorerMode2.Displa     End Sub