nsIMsgDBView

The nsIMsgDBView interface handles the display of mail in the threadpane and preview pane of Thunderbird and other XPCOM based mail cients.

Inherits from: nsISupports

Implemented by: @mozilla.org/messenger/msgdbview;1. To create an instance, use:

var dbView = Components.classes[@mozilla.org/messenger/msgdbview;1?type=]
                    .createInstance(Components.interfaces.nsIMsgDBView);

where type designates different types of view's available. Available in the mozilla codebase are types "quicksearch", "threadswithunread", "watchedthreadswithunread", "xfvf" (virtual folders), "search", "group", and "threaded" each with their own implementation of nsIMsgDBView that provides a different sorting/view of the data.

Method overview

void open(in nsIMsgFolder folder, in nsMsgViewSortTypeValue sortType, in nsMsgViewSortOrderValue sortOrder, in nsMsgViewFlagsTypeValue viewFlags, out long count);

void openWithHdrs(in nsISimpleEnumerator aHeaders, in nsMsgViewSortTypeValue aSortType, in nsMsgViewSortOrderValue aSortOrder, in nsMsgViewFlagsTypeValue aViewFlags, out long aCount);

void close();

void init(in nsIMessenger aMessengerInstance, in nsIMsgWindow aMsgWindow, in nsIMsgDBViewCommandUpdater aCommandUpdater);

void sort(in nsMsgViewSortTypeValue sortType, in nsMsgViewSortOrderValue sortOrder);

void doCommand(in nsMsgViewCommandTypeValue command);

void doCommandWithFolder(in nsMsgViewCommandTypeValue command, in nsIMsgFolder destFolder);

void getCommandStatus(in nsMsgViewCommandTypeValue command, out boolean selectable_p, out nsMsgViewCommandCheckStateValue selected_p);

void viewNavigate(in nsMsgNavigationTypeValue motion, out nsMsgKey resultId, out nsMsgViewIndex resultIndex, out nsMsgViewIndex threadIndex, in boolean wrap);

boolean navigateStatus(in nsMsgNavigationTypeValue motion);

nsMsgKey getKeyAt(in nsMsgViewIndex index);

nsIMsgDBHdr getMsgHdrAt(in nsMsgViewIndex index);

nsIMsgFolder getFolderForViewIndex(in nsMsgViewIndex index);

ACString getURIForViewIndex(in nsMsgViewIndex index);

nsIMsgDBView cloneDBView(in nsIMessenger aMessengerInstance, in nsIMsgWindow aMsgWindow, in nsIMsgDBViewCommandUpdater aCommandUpdater);

void getURIsForSelection([array, size_is(count)] out string uris, out unsigned long count);

void getIndicesForSelection([array, size_is(count)] out nsMsgViewIndex indices, out unsigned long count);

void loadMessageByMsgKey(in nsMsgKey aMsgKey);

void loadMessageByViewIndex(in nsMsgViewIndex aIndex);

void loadMessageByUrl(in string aUrl);

void reloadMessage();

void reloadMessageWithAllParts();

void selectMsgByKey(in nsMsgKey key);

void selectFolderMsgByKey(in nsIMsgFolder aFolder, in nsMsgKey aKey);

void onDeleteCompleted(in boolean succeeded);

nsMsgViewIndex findIndexFromKey(in nsMsgKey aMsgKey, in boolean aExpand);

void ExpandAndSelectThreadByIndex(in nsMsgViewIndex aIndex, in boolean aAugment);

void addColumnHandler(in AString aColumn, in nsIMsgCustomColumnHandler aHandler);

void removeColumnHandler(in AString aColumn);

nsIMsgCustomColumnHandler getColumnHandler(in AString aColumn);

Attributes

Attribute	Type	Description
`viewType`	`nsMsgViewTypeValue`	Readonly: Type of view. Constants are defined in `nsMsgViewType`.
`viewFlags`	`nsMsgViewFlagsTypeValue`	Constants are defined in `nsMsgViewFlagsType`.
`sortType`	`nsMsgViewSortTypeValue`	The type of sort being used (i.e. author, date, status, etc). Sort types are defined in `nsMsgViewSortType`.
`sortOrder`	`nsMsgViewSortOrderValue`	Readonly: Constants are defined in `nsMsgViewSortOrder`.
`keyForFirstSelectedMessage`	`nsMsgKey`	Readonly: The key of the first message in the current selection. `nsMsgKey` is defined as an `unsigned long` in MailNewsTypes2.idl.
`viewIndexForFirstSelectedMsg`	`nsMsgViewIndex`	Readonly: The index of the first selected message. `nsMsgViewIndex` is defined as a `unsigned long` in MailNewsTypes2.idl.
`msgFolder`	`nsIMsgFolder`	Readonly: The current folder.
`viewFolder`	`nsIMsgFolder`
`URIForFirstSelectedMessage`	`ACString`	Readonly: URL of the first selected message.
`hdrForFirstSelectedMessage`	`nsIMsgDBHdr`	Readonly: Header of the first selected message.
`numSelected`	`long`	Readonly: The number of messages currently selected.
`msgToSelectAfterDelete`	`nsMsgViewIndex`	Readonly: The index of the message to select after the current one is deleted. `nsMsgViewIndex` is defined as a `unsigned long` in MailNewsTypes2.idl.
`currentlyDisplayedMessage`	`nsMsgViewIndex`	Readonly: The index of the currently displayed message. `nsMsgViewIndex` is defined as a `unsigned long` in MailNewsTypes2.idl.
`suppressMsgDisplay`	`boolean`	Suppress displaying messages. Used when the message pane is collapsed.
`suppressCommandUpdating`	`boolean`	Suppress command updating. Used during folder loading.
`db`	`nsIMsgDatabase`	Readonly: The current database of messages.
`supportsThreading`	`boolean`	Readonly: Does the current database support threading?
`searchSession`	`nsIMsgSearchSession`	The current search session.
`removeRowOnMoveOrDelete`	`boolean`	Readonly:
`usingLines`	`boolean`	Readonly: Use lines for size. If `false` kB are used.

Methods

open()

Opens a folder in the database.

 void open(in nsIMsgFolder folder,
           in nsMsgViewSortTypeValue sortType,
           in nsMsgViewSortOrderValue sortOrder,
           in nsMsgViewFlagsTypeValue viewFlags,
           out long count);

Parameters

folder: The nsIMsgFolder to open.
sortType: A nsMsgViewSortTypeValue designating the sort type used for the folder. Defined in the interface: nsMsgViewSortType.
sortOrder: An nsMsgViewSortOrderValue designating the sort order used for the folder. Defined in the interface: nsMsgViewSortOrder.
viewFlags: Other flags to be used. Defined in the interface: nsMsgViewFlagsType.

Return values

count: Upon return, the count variable may contain the number of messages in the folder.

Note: This return value does not appear to be implemented in the base implementation.

openWithHdrs()

Opens the view with a set of specified headers.

Note: This is not implemented in the base implementation.

 void openWithHdrs(in nsISimpleEnumerator aHeaders,
                   in nsMsgViewSortTypeValue aSortType,
                   in nsMsgViewSortOrderValue aSortOrder,
                   in nsMsgViewFlagsTypeValue aViewFlags,
                   out long aCount);

Parameters

aHeaders: A list of headers to open, arranged in an nsISimpleEnumerator.
aSortType: A nsMsgViewSortTypeValue designating the sort type used for the folder. Defined in the interface: nsMsgViewSortType.
sortOrder: An nsMsgViewSortOrderValue designating the sort order used for the folder. Defined in the interface: nsMsgViewSortOrder.
viewFlags: Other flags to be used. Defined in the interface: nsMsgViewFlagsType.

Return values

aCount: Upon return, the count variable may contain the number of messages loaded.

close()

Close the current list of messages.

 void close();

init()

Initializes the database view for use.

 void init(in nsIMessenger aMessengerInstance,
           in nsIMsgWindow aMsgWindow,
           in nsIMsgDBViewCommandUpdater aCommandUpdater);

Parameters

aMessengerInstance
aMsgWindow
aCommandUpdater

sort()

Sorts the currently loaded messages.

 void sort(in nsMsgViewSortTypeValue sortType,
           in nsMsgViewSortOrderValue sortOrder);

Parameters

sortType: A nsMsgViewSortTypeValue designating the sort type used. Defined in the interface: nsMsgViewSortType.
sortOrder: An nsMsgViewSortOrderValue designating the sort order used for the folder. Defined in the interface: nsMsgViewSortOrder.

doCommand()

Perform a command on the currently loaded messages.

 void doCommand(in nsMsgViewCommandTypeValue command);

Parameters

command: The nsMsgViewCommandTypeValue to perform. Defined in the interface: nsMsgViewCommandType.

doCommandWithFolder()

Perform a command that requires a folder. Typical examples are move or copy commands.

 void doCommandWithFolder(in nsMsgViewCommandTypeValue command,
                          in nsIMsgFolder destFolder);

Parameters

command: The nsMsgViewCommandTypeValue to perform. Defined in the interface: nsMsgViewCommandType.
destFolder: The folder to perform the command with.

getCommandStatus()

Gets the status of a particular command. Used by the Thunderbird UI to determine if the command is available.

 void getCommandStatus(in nsMsgViewCommandTypeValue command,
                       out boolean selectable_p,
                       out nsMsgViewCommandCheckStateValue selected_p);

Parameters

command: The nsMsgViewCommandTypeValue to perform. Defined in the interface: nsMsgViewCommandType.

Return values

selectable_p: The state of the command. true if it is enabled. false if it is disabled.
selected_p: The returned check state of the command. Defined in the interface: nsMsgViewCommandCheckState. This is not used for all commands and will return the notUsed value most of the time.

viewNavigate()

Change the view to show a particular message. This method will automatically expand the destination thread.

 void viewNavigate(in nsMsgNavigationTypeValue motion,
                   out nsMsgKey resultId,
                   out nsMsgViewIndex resultIndex,
                   out nsMsgViewIndex threadIndex,
                   in boolean wrap);

Parameters

motion: The nsMsgNavigationTypeValue. Defined in the interface: nsMsgNavigationType.
wrap: Whether to wrap around messages from the last to first (or vice versa).

Return values

resultId: The key of the result message. nsMsgKey is defined as an unsigned long in MailNewsTypes2.idl.
resultIndex: The index of the result message. nsMsgViewIndex is defined as a unsigned long in MailNewsTypes2.idl.
threadIndex: The index of the new thread. nsMsgViewIndex is defined as a unsigned long in MailNewsTypes2.idl.

navigateStatus()

Indicates if the passed motion type is currently valid.

 boolean navigateStatus(in nsMsgNavigationTypeValue motion);

Parameters

motion: The nsMsgNavigationTypeValue. Defined in ther interface: nsMsgNavigationType.

Return values

True if the motion is available. False otherwise.

getKeyAt()

Gets the key for the message at a particular index.

 nsMsgKey getKeyAt(in nsMsgViewIndex index);

Parameters

index: The index of the message. nsMsgViewIndex is defined as a unsigned long in MailNewsTypes2.idl.

Return value

The key of the message. nsMsgKey is defined as an unsigned long in MailNewsTypes2.idl.

getFolderForViewIndex()

Mainly for search. Gets the folder of the message at a particular index.

 nsIMsgFolder getFolderForViewIndex(in nsMsgViewIndex index);

Parameters

index: The index of the message. nsMsgViewIndex is defined as a unsigned long in MailNewsTypes2.idl.

Return value

The nsIMsgFolder containing the message.

getURIForViewIndex()

Gets the URL for the message at the given index.

 ACString getURIForViewIndex(in nsMsgViewIndex index);

Parameters

index: The index to get the URL for>. nsMsgViewIndex is defined as a unsigned long in MailNewsTypes2.idl.

Return value

A string containing the messages URL.

cloneDBView()

Clones this nsIMsgDBView.

 nsIMsgDBView cloneDBView(in nsIMessenger aMessengerInstance,
                          in nsIMsgWindow aMsgWindow,
                          in nsIMsgDBViewCommandUpdater aCommandUpdater);

Parameters

aMessengerInstance: The nsIMessenger to use in the clone.
aMsgWindow: The nsIMsgWindow to use in the clone.
aCommandUpdater: The nsIMsgDBViewCommandUpdater to use in the clone.

getURIsForSelection()

Gets an arry of URLs for all currently selected messages.

 void getURIsForSelection([array, size_is(count)] out string uris,
                                                  out unsigned long count);

Return values

uris: An array of urls for the selected messages.
count: The number of urls returned.

getIndicesForSelection()

Gets the indicies of the selected messages.

 void getIndicesForSelection([array, size_is(count)] out nsMsgViewIndex indices,
                                                     out unsigned long count);

Return values

indices: The output array of indicies. Each element of the array is an nsMsgViewIndex which is defined as a unsigned long in MailNewsTypes2.idl.
count: The number of indicies returned.

loadMessageByMsgKey()

Loads a message into the message pane.

 void loadMessageByMsgKey(in nsMsgKey aMsgKey);

Parameters

aMsgKey: The Key of the message to load. nsMsgKey is defined as an unsigned long in MailNewsTypes2.idl.

loadMessageByViewIndex()

Loads a message into the message pane.

 void loadMessageByViewIndex(in nsMsgViewIndex aIndex);

Parameters

aIndex: The index of the message to load. nsMsgViewIndex is defined as a unsigned long in MailNewsTypes2.idl.

loadMessageByUrl()

Loads a message into the message pane.

 void loadMessageByUrl(in string aUrl);

Parameters

aUrl: The URL of the message

reloadMessage()

Reload the currently shown message.

 void reloadMessage();

reloadMessageWithAllParts()

Reload the currently shown message with fetchCompleteMessage set to true. This forces everything to be re-downloaded.

 void reloadMessageWithAllParts();

selectMsgByKey()

Selects a message based on its key. Used by "go to folder" feature and "remember last selected message" feature. If key is not found, nothing is selected.

 void selectMsgByKey(in nsMsgKey key);

Parameters

key

The Key of the message to load. nsMsgKey is defined as an unsigned long in MailNewsTypes2.idl.

selectFolderMsgByKey()

Selects a message within a folder by its key. This assumes that the key is somewhere in the displayed messages... I think.

 void selectFolderMsgByKey(in nsIMsgFolder aFolder,
                           in nsMsgKey aKey);

Parameters

aFolder: The nsIMsgFolder to search within.
aKey: The key of the message. nsMsgKey is defined as an unsigned long in MailNewsTypes2.idl.

onDeleteCompleted()

Called when delete is completed on a message. Used to notify the tree that rows are going away.

 void onDeleteCompleted(in boolean succeeded);

Parameters

succeeded: true if the delete was successful.

findIndexFromKey()

Gets the index of a message with a particular key.

 nsMsgViewIndex findIndexFromKey(in nsMsgKey aMsgKey,
                                 in boolean aExpand);

Parameters

aMsgKey: The Key of the message. nsMsgKey is defined as an unsigned long in MailNewsTypes2.idl.
aExpand: Whether or not to expand the thread or group the message is in. Otherwise, the index may be the index of the thread and not the message.

Return value

The index of the message. nsMsgViewIndex is defined as a unsigned long in MailNewsTypes2.idl.

ExpandAndSelectThreadByIndex()

 void ExpandAndSelectThreadByIndex(in nsMsgViewIndex aIndex,
                                   in boolean aAugment);

Parameters

aIndex: The index of the thread to expand and select. nsMsgViewIndex is defined as a unsigned long in MailNewsTypes2.idl.
aAugment: If true then add to current selection. If false then replace current selection.

addColumnHandler()

Attaches a nsIMsgCustomColumnHandler to a specific column (can be a new column or a built in).+

 void addColumnHandler(in AString aColumn,
                       in nsIMsgCustomColumnHandler aHandler);

Parameters

aColumn: The name of the column to add the handler for.
aHandler: The nsIMsgCustomColumnHandler to add.

removeColumnHandler()

Removes a nsIMsgCustomColumnHandler leaving the column to be handled by the system

 void removeColumnHandler(in AString aColumn);

Parameters

aColumn: The name of the column to remove the handler from.

getColumnHandler()

Returns the nsIMsgCustomColumnHandler attached to a specific column, if any.

 nsIMsgCustomColumnHandler getColumnHandler(in AString aColumn);

Parameters

aColumn: The name of the column to get the handler for.