Folders and message lists

Interacting With the Current Folder

The FolderDisplayWidget for the current folder can be accessed via the global variable gFolderDisplay. This object provides many of the functions required for working with folder views. We'll look at some of them below.

Getting the Current nsIMsgFolder

The nsIMsgFolder interface contains many methods and attributes for working with folders. To get the nsIMsgFolder instance for the currently-displayed folder, just use gFolderDisplay.displayedFolder.

Getting the Currently-Selected Message

The FolderDisplayWidget has several ways of getting the currently-selected message(s), depending on what exactly you're trying to do:

• gFolderDisplay.selectedCount: Returns the number of messages currently selected.
• gFolderDisplay.selectedMessage: Returns the first currently-selected message. When using this, be sure that there's only one selected message (or that you only care about the first one). Otherwise, use one of the methods described below.
• gFolderDisplay.selectedMessages: Returns an array of nsIMsgDBHdrs for the selected messages. If a collapsed thread is in there and working with collapsed threads is enabled, this will include the headers for the messages in that collapsed thread.
• gFolderDisplay.selectedMessageUris: Returns an array of the URIs corresponding to the selected messages. Like selectedMessages, this also includes messages in selected collapsed threads when so enabled.

Changing the Current Message Selection

In addition to getting the currently-selected messages, you can also change the selection:

• gFolderDisplay.selectMessage(msgHdr): Selects a single message, as specified by msgHdr (an nsIMsgDBHdr) and scrolls to its position in the message list.
• gFolderDisplay.selectMessages(arrayOfMsgHdrs): Selects all the messages in the array arrayOfMsgHdrs. Like selectMessage, this function will attempt to scroll the view so the entire selection is visible (which may not be possible for large selections).
• gFolderDisplay.clearSelection(): Clears the list of selected messages.

Listing Messages in a Folder

If you have a message folder, and would like to list all the messages in that folder, you can use the .messages attribute, which returns an nsISimpleEnumerator. It's used like this:

// Import the fixIterator() function.
Components.utils.import("resource:///modules/iteratorUtils.jsm");

for (let msgHdr in fixIterator(myFolder.messages,
                               Components.interfaces.nsIMsgDBHdr)) {
  // Do something with msgHdr...
}