path: root/comm/mailnews/base/public/nsIMsgDBView.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "MailNewsTypes2.idl"

interface nsIMsgFolder;
interface nsIMsgWindow;
interface nsIMessenger;
interface nsIMsgDBHdr;
interface nsIMsgThread;
interface nsIMsgDBViewCommandUpdater;
interface nsIMsgJSTree;
interface nsIMsgDatabase;
interface nsIMsgSearchSession;
interface nsIMsgEnumerator;
interface nsIMsgCustomColumnHandler;

typedef long nsMsgViewNotificationCodeValue;
typedef long nsMsgViewCommandCheckStateValue;
typedef long nsMsgViewCommandTypeValue;
typedef long nsMsgNavigationTypeValue;

[scriptable, uuid(682a18be-fd18-11d4-a5be-0060b0fc04b7)]
interface nsMsgViewSortOrder : nsISupports
{
  const nsMsgViewSortOrderValue none = 0;
  const nsMsgViewSortOrderValue ascending = 1;
  const nsMsgViewSortOrderValue descending = 2;
};

[scriptable, uuid(f28a1cdf-06c3-4e98-8f66-f49991670071)]
interface nsMsgViewType : nsISupports {
  const nsMsgViewTypeValue eShowAllThreads = 0;
  const nsMsgViewTypeValue eShowThreadsWithUnread = 2;
  const nsMsgViewTypeValue eShowWatchedThreadsWithUnread = 3;
  const nsMsgViewTypeValue eShowQuickSearchResults = 4;
  const nsMsgViewTypeValue eShowVirtualFolderResults = 5;
  const nsMsgViewTypeValue eShowSearch = 6;
};

[scriptable, uuid(64852276-1dd2-11b2-8103-afe12002c053)]
interface nsMsgViewFlagsType : nsISupports
{
  /**
   * flags for GetViewFlags
   */
  const nsMsgViewFlagsTypeValue kNone = 0x0;
  const nsMsgViewFlagsTypeValue kThreadedDisplay = 0x1;
  const nsMsgViewFlagsTypeValue kShowIgnored = 0x8;
  const nsMsgViewFlagsTypeValue kUnreadOnly = 0x10;
  const nsMsgViewFlagsTypeValue kExpandAll = 0x20;
  const nsMsgViewFlagsTypeValue kGroupBySort = 0x40;
};

[scriptable, uuid(b94fc200-3008-420a-85c7-67842f133ef8)]
interface nsMsgViewSortType : nsISupports
{
  const nsMsgViewSortTypeValue byNone = 0x11; /* not sorted */
  const nsMsgViewSortTypeValue byDate = 0x12;
  const nsMsgViewSortTypeValue bySubject = 0x13;
  const nsMsgViewSortTypeValue byAuthor = 0x14;
  const nsMsgViewSortTypeValue byId = 0x15;
  const nsMsgViewSortTypeValue byThread = 0x16;
  const nsMsgViewSortTypeValue byPriority = 0x17;
  const nsMsgViewSortTypeValue byStatus = 0x18;
  const nsMsgViewSortTypeValue bySize = 0x19;
  const nsMsgViewSortTypeValue byFlagged = 0x1a;
  const nsMsgViewSortTypeValue byUnread = 0x1b;
  const nsMsgViewSortTypeValue byRecipient = 0x1c;
  const nsMsgViewSortTypeValue byLocation = 0x1d;
  const nsMsgViewSortTypeValue byTags = 0x1e;
  const nsMsgViewSortTypeValue byJunkStatus = 0x1f;
  const nsMsgViewSortTypeValue byAttachments = 0x20;
  const nsMsgViewSortTypeValue byAccount = 0x21;
  const nsMsgViewSortTypeValue byCustom = 0x22;
  const nsMsgViewSortTypeValue byReceived = 0x23;
  const nsMsgViewSortTypeValue byCorrespondent = 0x24;
};

[scriptable, uuid(255d1c1e-fde7-11d4-a5be-0060b0fc04b7)]
interface nsMsgViewNotificationCode : nsISupports
{
  const nsMsgViewNotificationCodeValue none = 0;
  /* No change; this call is just being used to potentially nest other sets of calls
     inside it.  The "where" and "num" parameters are unused.
   */
  const nsMsgViewNotificationCodeValue insertOrDelete = 1;
  /* Some lines have been inserted or deleted.
     The "where" parameter will indicate the first line that has been added or
     removed; the "num" parameter will indicate how many lines, and will be positive on
     an insertion and negative on a deletion.
   */
  const nsMsgViewNotificationCodeValue changed = 2;
  /* Some lines have had their contents changed (e.g., messages have been marked read
    or something.)  "where" indicates the first line with a change; "num" indicates
    how many changed.
   */
  const nsMsgViewNotificationCodeValue all = 4;
  /* Everything changed.  We're now not displaying anything like what we were; we
     probably opened a new folder or something. The FE needs to forget anything it ever knew
     about what was being displayed, and start over.  The "where" and "num" parameters are
     unused.
   */
};

[scriptable, uuid(4ec9248e-0108-11d5-a5be-0060b0fc04b7)]
interface nsMsgViewCommandCheckState : nsISupports
{
  const nsMsgViewCommandCheckStateValue notUsed = 0;
  const nsMsgViewCommandCheckStateValue checked = 1;
  const nsMsgViewCommandCheckStateValue unchecked = 2;
};

[scriptable, uuid(ad36e6cc-0109-11d5-a5be-0060b0fc04b7)]
interface nsMsgViewCommandType : nsISupports
{
  const nsMsgViewCommandTypeValue markMessagesRead = 0;
  const nsMsgViewCommandTypeValue markMessagesUnread = 1;
  const nsMsgViewCommandTypeValue toggleMessageRead = 2;

  const nsMsgViewCommandTypeValue flagMessages = 3;
  const nsMsgViewCommandTypeValue unflagMessages = 4;

  const nsMsgViewCommandTypeValue toggleThreadWatched = 6;

  const nsMsgViewCommandTypeValue deleteMsg = 7;
  const nsMsgViewCommandTypeValue deleteNoTrash = 8;
  const nsMsgViewCommandTypeValue markThreadRead = 9;
  const nsMsgViewCommandTypeValue markAllRead = 10;
  const nsMsgViewCommandTypeValue expandAll = 11;
  const nsMsgViewCommandTypeValue collapseAll = 12;

  const nsMsgViewCommandTypeValue copyMessages = 13;
  const nsMsgViewCommandTypeValue moveMessages = 14;

  const nsMsgViewCommandTypeValue selectAll = 15;
  const nsMsgViewCommandTypeValue downloadSelectedForOffline = 16;
  const nsMsgViewCommandTypeValue downloadFlaggedForOffline = 17;

  const nsMsgViewCommandTypeValue selectThread = 18;
  const nsMsgViewCommandTypeValue selectFlagged = 19;
  const nsMsgViewCommandTypeValue cmdRequiringMsgBody = 20;
  const nsMsgViewCommandTypeValue label0 = 21;
  const nsMsgViewCommandTypeValue label1 = 22;
  const nsMsgViewCommandTypeValue label2 = 23;
  const nsMsgViewCommandTypeValue label3 = 24;
  const nsMsgViewCommandTypeValue label4 = 25;
  const nsMsgViewCommandTypeValue label5 = 26;
  const nsMsgViewCommandTypeValue lastLabel = 26;

  const nsMsgViewCommandTypeValue junk = 27;
  const nsMsgViewCommandTypeValue unjunk = 28;
  const nsMsgViewCommandTypeValue undeleteMsg = 29;

  const nsMsgViewCommandTypeValue applyFilters = 30;
  const nsMsgViewCommandTypeValue runJunkControls = 31;
  const nsMsgViewCommandTypeValue deleteJunk = 32;
};

[scriptable, uuid(65903eb2-1dd2-11b2-ac45-c5b69c1618d7)]
interface nsMsgNavigationType : nsISupports
{
  const nsMsgNavigationTypeValue firstMessage = 1;
  const nsMsgNavigationTypeValue nextMessage = 2;
  const nsMsgNavigationTypeValue previousMessage = 3;
  const nsMsgNavigationTypeValue lastMessage = 4;
  /**
   * must match nsMsgViewCommandTypeValue toggleThreadKilled
   */
  const nsMsgNavigationTypeValue toggleThreadKilled = 5;
  const nsMsgNavigationTypeValue firstUnreadMessage = 6;
  const nsMsgNavigationTypeValue nextUnreadMessage = 7;
  const nsMsgNavigationTypeValue previousUnreadMessage = 8;
  const nsMsgNavigationTypeValue lastUnreadMessage = 9;
  const nsMsgNavigationTypeValue nextUnreadThread = 10;
  const nsMsgNavigationTypeValue nextUnreadFolder = 11;
  const nsMsgNavigationTypeValue nextFolder = 12;
  const nsMsgNavigationTypeValue readMore = 13;
  /**
   * Go back to the previous visited message
   */
  const nsMsgNavigationTypeValue back = 15;
  /**
   * Go forward to the previous visited message
   */
  const nsMsgNavigationTypeValue forward = 16;
  const nsMsgNavigationTypeValue firstFlagged = 17;
  const nsMsgNavigationTypeValue nextFlagged = 18;
  const nsMsgNavigationTypeValue previousFlagged = 19;
  const nsMsgNavigationTypeValue firstNew = 20;
  const nsMsgNavigationTypeValue editUndo = 21;
  const nsMsgNavigationTypeValue editRedo = 22;
  const nsMsgNavigationTypeValue toggleSubthreadKilled = 23;
};

/*
 * The contract ID for this component is @mozilla.org/msgDBView/msgDBViewService;1.
 */
[scriptable, uuid(bcf6afbe-7d4f-11ec-9092-eb4fed0a5aaa)]
interface nsIMsgDBViewService : nsISupports
{
  /**
   * JS-callable service to initialize static variables in nsMsgDBView.cpp
   * upon initialization or when locale changes.
   */
  void initializeDBViewStrings();
};

[scriptable, uuid(fe8a2326-4dd0-11e5-8b8a-206a8aa7a25c)]
interface nsIMsgDBView : nsISupports
{
  /** A shim of XULTreeElement, with only the methods called by nsMsgDBView. */
  void setJSTree(in nsIMsgJSTree tree);

  void open(in nsIMsgFolder folder, in nsMsgViewSortTypeValue sortType, in nsMsgViewSortOrderValue sortOrder, in nsMsgViewFlagsTypeValue viewFlags, out long count);
  void openWithHdrs(in nsIMsgEnumerator 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 applyCommandToIndices(in nsMsgViewCommandTypeValue command,
                             in Array<nsMsgViewIndex> selection);

  readonly attribute nsMsgViewTypeValue viewType;
  attribute nsMsgViewFlagsTypeValue viewFlags;
  /** Assigning to this value does not induce a sort; use the sort() method! */
  attribute nsMsgViewSortTypeValue sortType;
  readonly attribute nsMsgViewSortOrderValue sortOrder;
  /**
   * Reflects the current secondary sort when a secondary sort is in effect.
   *  If the primary sort is by date or id, the value of this attribute is moot.
   * Assigning to this value does not induce a sort; use the sort() method once
   *  to set your secondary sort, then use it again to set your primary sort.
   *  The only conceivable reason to write to this value is if you have a
   *  grouped view where you want to affect the sort order of the (secondary)
   *  date sort.  (Secondary sort is always by date for grouped views.)
   */
  attribute nsMsgViewSortTypeValue secondarySortType;
  /**
   * Reflects the current secondary sort order.
   * Assigning to this value does not induce a sort; use the sort() method for
   *  all primary and secondary sort needs.  The only reason to assign to this
   *  value is to affect the secondary sort of a grouped view.
   */
  attribute nsMsgViewSortOrderValue secondarySortOrder;
  readonly attribute nsMsgKey keyForFirstSelectedMessage;
  readonly attribute nsMsgViewIndex viewIndexForFirstSelectedMsg;
  /**
   * this method will automatically expand the destination thread,
   * if needs be.
   */
  void viewNavigate(in nsMsgNavigationTypeValue motion, out nsMsgKey resultId, out nsMsgViewIndex resultIndex, out nsMsgViewIndex threadIndex, in boolean wrap);

  readonly attribute nsIMsgFolder msgFolder;
  attribute nsIMsgFolder viewFolder; // in the case of virtual folders, the VF db.

  nsMsgKey getKeyAt(in nsMsgViewIndex index);

  /**
   * Get the view flags at the passed in index.
   *
   * @param aIndex - index to get the view flags for
   *
   * @ return - 32 bit view flags (e.g., elided)
   */
  unsigned long getFlagsAt(in nsMsgViewIndex aIndex);

  /**
   * Get the msg hdr at the passed in index
   *
   * @param aIndex - index to get the msg hdr at.
   *
   * @return - msg hdr at the passed in index
   * @exception - NS_MSG_INVALID_DBVIEW_INDEX
   */
  nsIMsgDBHdr getMsgHdrAt(in nsMsgViewIndex aIndex);

  nsIMsgFolder getFolderForViewIndex(in nsMsgViewIndex index); // mainly for search
  AUTF8String getURIForViewIndex(in nsMsgViewIndex index);
  nsIMsgDBView cloneDBView(in nsIMessenger aMessengerInstance, in nsIMsgWindow aMsgWindow, in nsIMsgDBViewCommandUpdater aCommandUpdater);

  /**
   * Provides a list of the message headers for the currently selected messages.
   *  If the "mail.operate_on_msgs_in_collapsed_threads" preference is enabled,
   *  then any collapsed thread roots that are selected will also (conceptually)
   *  have all of the messages in that thread selected and they will be included
   *  in the returned list. The one exception to this is if the front end fails
   *  to summarize the selection, and we fall back to just displaying a single
   *  message. In that case, we won't include the children of the collapsed
   *  thread. However, the numSelected attribute will count those children,
   *  because the summarizeSelection code uses that to know that it should
   *  try to summarize the selection.
   *
   * If the user has right-clicked on a message, this will return that message
   *  (and any collapsed children if so enabled) and not the selection prior to
   *  the right-click.
   *
   * @return an array containing the selected message headers.  You are free to
   *     mutate the array; it will not affect the underlying selection.
   */
  Array<nsIMsgDBHdr> getSelectedMsgHdrs();

  Array<AUTF8String> getURIsForSelection();
  Array<nsMsgViewIndex> getIndicesForSelection();

  readonly attribute AUTF8String URIForFirstSelectedMessage;
  readonly attribute nsIMsgDBHdr hdrForFirstSelectedMessage;

  /**
   * The number of selected messages.  If the
   *  "mail.operate_on_msgs_in_collapsed_threads" preference is enabled, then
   *  any collapsed thread roots that are selected will also conceptually have
   *  all of the messages in that thread selected.
   */
  readonly attribute unsigned long numSelected;
  readonly attribute nsMsgViewIndex msgToSelectAfterDelete;
  readonly attribute nsMsgViewIndex currentlyDisplayedMessage;

  /**
   * Number of messages in view, including messages in collapsed threads.
   * Not currently implemented for threads with unread or watched threads
   * with unread.
   */
  readonly attribute long numMsgsInView;
  // used by "go to folder" feature
  // and "remember last selected message" feature
  // if key is not found, we don't select.
  void selectMsgByKey(in nsMsgKey key);

  void selectFolderMsgByKey(in nsIMsgFolder aFolder, in nsMsgKey aKey);
  // we'll suppress displaying messages if the message pane is collapsed
  attribute boolean suppressMsgDisplay;

  // we'll suppress command updating during folder loading
  attribute boolean suppressCommandUpdating;

  /**
   * Suppress change notifications. This is faster than Begin/EndUpdateBatch
   * on the tree, but less safe in that you're responsible for row invalidation
   * and row count changes.
   */
  attribute boolean suppressChangeNotifications;

  //to notify tree that rows are going away
  void onDeleteCompleted(in boolean succeeded);

  readonly attribute nsIMsgDatabase db;

  readonly attribute boolean supportsThreading;

  attribute nsIMsgSearchSession searchSession;
  readonly attribute boolean removeRowOnMoveOrDelete;

  /**
   * Finds the view index of the passed in msgKey. Note this should not
   * be called on cross-folder views since the msgKey may not be unique.
   *
   * @param aMsgKey - key to find.
   * @param aExpand - whether to expand a collapsed thread to find the key.
   *
   * @return        - view index of msg hdr, -1 if hdr not found.
   */
  nsMsgViewIndex findIndexFromKey(in nsMsgKey aMsgKey, in boolean aExpand);
  /**
   * Finds the view index of the passed in msgHdr.
   *
   * @param aMsgHdr - hdr to find.
   * @param aExpand - whether to expand a collapsed thread to find the hdr.
   *
   * @return        - view index of msg hdr, -1 if hdr not found.
   */
  nsMsgViewIndex findIndexOfMsgHdr(in nsIMsgDBHdr aMsgHdr, in boolean aExpand);

  /**
   * Expands a thread and selects all it's member messages.
   *
   * @param aIndex   - View index of a message in the thread to expand (can be
                       any message which is a member of the thread).
   * @param aAugment - If true, Augment the existing selection.
   *                   If false, replace it.
   */
  void ExpandAndSelectThreadByIndex(in nsMsgViewIndex aIndex, in boolean aAugment);

  /**
   * This method returns the nsIMsgThread object containing the header displayed
   * at the desired row. For grouped views and cross folder saved searches,
   * this will be the view thread, not the db thread.
   *
   * @param aIndex   view index we want corresponding thread object of.
   *
   * @return         the thread object at the requested view index
   */
  nsIMsgThread getThreadContainingIndex(in nsMsgViewIndex aIndex);

  /**
   * Insert rows into the view. The caller should use NoteChange() below to
   * update the view.
   *
   * @param aIndex   view index for insertion start.
   * @param aNumRows number of rows to insert.
   * @param aKey     msgKey.
   * @param aFlags   msgFlags.
   * @param aLevel   treeview indent level.
   * @param aFolder  nsIMsgFolder, required for search/xfvf views.
   */
  void insertTreeRows(in nsMsgViewIndex aIndex, in unsigned long aNumRows,
                      in nsMsgKey aKey, in nsMsgViewFlagsTypeValue aFlags,
                      in unsigned long aLevel, in nsIMsgFolder aFolder);

  /**
   * Remove rows from the view.  The caller should use NoteChange() below to
   * update the view.
   *
   * @param aIndex   view index for removal start.
   * @param aNumRows number of rows to remove.
   */
  void removeTreeRows(in nsMsgViewIndex aIndex, in unsigned long aNumRows);

  /**
   * Notify tree that rows have changed.
   *
   * @param aFirstLineChanged   first view index for changed rows.
   * @param aNumRows            number of rows changed; < 0 means removed.
   * @param aChangeType         changeType.
   */
  void NoteChange(in nsMsgViewIndex aFirstLineChanged, in long aNumRows,
                  in nsMsgViewNotificationCodeValue aChangeType);

  /**
   * Return the view thread corresponding to aMsgHdr. If we're a cross-folder
   * view, then it would be the cross folder view thread, otherwise, the
   * db thread object.
   *
   * @param aMsgHdr message header we want the view thread object of.
   *
   * @return        view thread object for msg hdr.
   */
  nsIMsgThread getThreadContainingMsgHdr(in nsIMsgDBHdr aMsgHdr);

  // use lines or kB for size?
  readonly attribute boolean usingLines;

  // Custom Column Implementation note: see nsIMsgCustomColumnHandler

  // attaches a custom column handler to a specific column (can be a new column or a built in)
  void addColumnHandler(in AString aColumn, in nsIMsgCustomColumnHandler aHandler);

  // removes a custom column handler leaving the column to be handled by the system
  void removeColumnHandler(in AString aColumn);

  // returns the custom column handler attached to a specific column - if any
  nsIMsgCustomColumnHandler getColumnHandler(in AString aColumn);

  /**
   * The custom column to use for sorting purposes (when sort type is
   *  nsMsgViewSortType.byCustom.)
   */
  attribute AString curCustomColumn;

  /**
   * The custom column used for a secondary sort, blank if secondarySort is
   * not byCustom. The secondary sort design is such that the desired secondary
   * is sorted first, followed by sort by desired primary. The secondary is
   * read only, as it is set internally according to this design.
   */
  readonly attribute AString secondaryCustomColumn;
  /**
   * Scriptable accessor for the cell text for a column
   *
   * @param aRow - row we want cell text for
   * @param aColumnName - name of column we want cell text for
   *
   * @returns The cell text for the given row and column, if any.
   * @notes This does not work for custom columns yet.
   */
  AString cellTextForColumn(in long aRow, in AString aColumnName);

  /**
   * Get all of the data needed to display a row. Effectively a combination of
   * CellTextForColumn, GetRowProperties and GetLevel, for performance reasons.
   *
   * @param aRow - Index of the row we want data for.
   * @param aColumnNames - The column names we want cell text for.
   * @param aProperties - The properties of the row.
   * @param aThreadLevel - The thread level of the row.
   *
   * @returns The cell text for the columns in `aColumnNames`.
   */
  Array<AString> cellDataForColumns(in long aRow,
                                    in Array<AString> aColumnNames,
                                    out AString aProperties,
                                    out long aThreadLevel);
};

/* this interface is rapidly morphing from a command updater interface into a more generic
   FE updater interface to handle changes in the view
*/

[scriptable, uuid(ce8f52ee-e742-4b31-8bdd-2b3a8168a117)]
interface nsIMsgDBViewCommandUpdater : nsISupports
{
  /* Eventually we'll flush this out into some kind of rich interface
  which may take specific selection changed type notifications like
  no selections, single selection, multi-selection, etc. For starters,
  we are going to keep it generic. The back end will only push an update
  command status when the # of selected items changes.
  */

  void updateCommandStatus();

  /* displayed message has changed */
  void displayMessageChanged(in nsIMsgFolder aFolder, in AString aSubject, in ACString aKeywords);

  /**
  * allows the backend to tell the front end to re-determine
  * which message we should selet after a delete or move
  */
  void updateNextMessageAfterDelete();

  /**
  * tell the front end that the selection has changed, and may need to be
  * resummarized.
  *
  * @return   true if we did summarize, false otherwise.
  */
  boolean summarizeSelection();

  /**
   * Tell the front end that the selected message was removed and it should update.
   */
  void selectedMessageRemoved();
};

/**
 * A shim of XULTreeElement, with only the methods called by nsMsgDBView.
 */
[scriptable, uuid(c5f6b1a2-f56a-49cb-b863-badf158206d5)]
interface nsIMsgJSTree : nsISupports
{
  void beginUpdateBatch();
  void endUpdateBatch();
  void ensureRowIsVisible(in long index);
  void invalidate();
  void invalidateRange(in long startIndex, in long endIndex);
  void rowCountChanged(in long index, in long count);
  attribute long currentIndex;
};