gecko-dev/editor/idl/nsIEditorShell.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.0 (the "NPL"); you may not use this file except in
 * compliance with the NPL.  You may obtain a copy of the NPL at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the NPL is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
 * for the specific language governing rights and limitations under the
 * NPL.
 *
 * The Initial Developer of this code under the NPL is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
 * Reserved.
 */
 
#include "nsISupports.idl"
#include "domstubs.idl"
#include "nsIFileSpec.idl"
#include "nsISupportsArray.idl"
#include "nsIDocumentStateListener.idl"

%{C++

class nsIDOMWindow;
class nsIDOMDocument;
class nsIDOMSelection;
class nsIDOMElement;
class nsIDOMNode;
%}

interface nsIFileSpec;

[scriptable, uuid(9afff72b-ca9a-11d2-96c9-0060b0fb9956)]
interface nsIEditorShell : nsISupports
{
  readonly attribute nsIDOMDocument    editorDocument;
  readonly attribute nsIDOMSelection   editorSelection;
  
%{C++

  enum {
    eDocumentStatusUnmodified,
    eDocumentStatusModified
  };
%}
  readonly attribute boolean              documentModified;
  
  attribute wstring    paragraphFormat;
  attribute long       wrapColumn;
   
  /* Setup */
  void SetEditorType(in wstring editorType);

  void SetToolbarWindow(in nsIDOMWindow win);
  void SetContentWindow(in nsIDOMWindow win);
  void SetWebShellWindow(in nsIDOMWindow win);
  void LoadUrl(in wstring url);
  
  /** Register a doc state listener. This gets added to a list of listeners
     which are registered with the editor when that gets instantiated.
     If the LoadUrl fails, this listener will not receive any notifcations.
     If you call this after the editor has been instantiated, it calls through
     to editor::AddDocumentStateListener().
  */
  void RegisterDocumentStateListener(in nsIDocumentStateListener docListener);
  /** Unregister a listener.
     If you call this after the editor has been instantiated, it calls through
     to editor::RemoveDocumentStateListener().
  */
  void UnregisterDocumentStateListener(in nsIDocumentStateListener docListener);
  
  void Init();
  
  /* Commands */
  void NewWindow();
  void Open();

  /** 
   *  @param saveAs false to try to save to existing file
   *          If document is not already saved, it is treated as true
   *          so filename is prompted.
   *  @param saveCopy       
   *          true if we are saving off a copy of the document
   *          without changing the disk file associated with the doc.
   *          This would correspond to a 'Save Copy As' menu command
   *          (currently not in our UI)
   *  return value
   *          true if file was really saved.
   *          false if there is some problem with saving or user
   *          executed "Cancel" when prompted for a filename to save
   */  
  boolean SaveDocument(in boolean saveAs, in boolean saveCopy);
  
  /** These are for simpler access and we ignore if user Cancels*/
  /** This is SaveDocument(false, false) */
  void Save();
  /** This is SaveDocument(true, false) */
  void SaveAs();
  /** Check if current document has changes and prompt to save if it does.
   *  return value:
   *         false ONLY if user executed "Cancel" in the SaveAs dialog
   *         true if no changes in doc, or file was saved successfully
   */
  boolean  CheckAndSaveDocument();

  void CloseWindow();
  void Print();
  void Exit();
  
  void Undo();
  void Redo();
  
  void Cut();
  void Copy();
  void Paste();
  void PasteAsQuotation();
  void PasteAsCitedQuotation(in wstring cite);
  
  void InsertAsQuotation(in wstring quotedText);
  void InsertAsCitedQuotation(in wstring quotedText, in wstring cite);
  
  void SelectAll();
  void DeleteSelection(in PRInt32 action);
  
  void Find();
  void FindNext();

  /* General Utilities */
  /* Get string from the Editor's localized string bundle */
  wstring GetString(in wstring name);

  /* Charset Menu */
  wstring GetDocumentCharacterSet();
  void SetDocumentCharacterSet(in wstring characterSet);
  
  /* Structure change */
  void InsertText(in wstring textToInsert);
  void InsertSource(in wstring textToInsert);
  void InsertBreak();
  
  void InsertList(in wstring listType);
  void Indent(in wstring indent);
  void Align(in wstring align);
  
  /** Element insert and property editing */

  /** Return an element only if it is the only node selected,
    *    such as an image, horizontal rule, etc.
    * The exception is a link, which is more like a text attribute:
    *    The Anchor tag is returned if the selection is within the textnode(s)
    *    that are children of the "A" node.
    *    This could be a collapsed selection, i.e., a caret within the link text.
    *
    * tagName:  The HTML tagname or and empty string 
    *       to get any element (but only if it is the only element selected)
    *    Special input values for Links and Named anchors:
    *    Use "href" to get a link node
    *      (an "A" tag with the "href" attribute set)
    *    Use "anchor" or "namedanchor" to get a named anchor node
    *      (an "A" tag with the "name" attribute set)
    */
  nsIDOMElement GetSelectedElement(in wstring tagName);

  /** Return the input node or a parent matching the given aTagName,
    *   starting the search at the supplied node.
    * An example of use is for testing if a node is in a table cell
    *   given a selection anchor node.
    *
    * tagName:  The HTML tagname
    *    Special input values for Links and Named anchors:
    *    Use "href" to get a link node 
    *      (an "A" tag with the "href" attribute set)
    *    Use "anchor" or "namedanchor" to get a named anchor node
    *      (an "A" tag with the "name" attribute set)
    *
    * node:    The node in the document to start the search
    *     If it is null, the anchor node of the current selection is used
    */
  nsIDOMElement GetElementOrParentByTagName(in wstring tagName, in nsIDOMNode node);

  /** Return a new element with default attribute values
    * 
    * This does not rely on the selection, and is not sensitive to context.
    * 
    * Used primarily to supply new element for various insert element dialogs
    *  (Image, Link, NamedAnchor, Table, and HorizontalRule 
    *   are the only returned elements as of 7/25/99)
    *
    * tagName:  The HTML tagname
    *    Special input values for Links and Named anchors:
    *    Use "href" to get a link node
    *      (an "A" tag with the "href" attribute set)
    *    Use "anchor" or "namedanchor" to get a named anchor node
    *      (an "A" tag with the "name" attribute set)
    */
  nsIDOMElement CreateElementWithDefaults(in wstring tagName);

  /** Insert an element, which may have child nodes, at the selection
    * Used primarily to insert a new element for various insert element dialogs,
    *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
    *   be useful for other elements.
    *
    * element:           The element to insert
    * deleteSelection:   Delete the selection before inserting
    *     If deleteSelection is PR_FALSE, then the element is inserted 
    *     after the end of the selection for all element except
    *     Named Anchors, which insert before the selection
    */  
  void InsertElement(in nsIDOMElement element, in boolean deleteSelection);

  /** Insert an link element as the parent of the current selection
    *
    * element   An "A" element with a non-empty "href" attribute
    */
  void InsertLinkAroundSelection(in nsIDOMElement anchorElement);
  void SelectElement(in nsIDOMElement element);
  void SetSelectionAfterElement(in nsIDOMElement element);

  /** Table insert and delete methods.  Done relative to selected cell or
   * cell containing the selection anchor.
   */
  void InsertTableCell(in PRInt32 number, in boolean after);
  void InsertTableRow(in PRInt32 number, in boolean after);
  void InsertTableColumn(in PRInt32 number, in boolean after);
  void DeleteTable();
  void DeleteTableCell(in PRInt32 number);
  void DeleteTableRow(in PRInt32 number);
  void DeleteTableColumn(in PRInt32 number);
  void JoinTableCells();

  /** Scan through all rows and add cells as needed so 
    *   all locations in the cellmap are occupied.
    *   Used after inserting single cells or pasting
    *   a collection of cells that extend past the
    *   previous size of the table
    * If aTable is null, it uses table enclosing the selection anchor
    */
  void NormalizeTable(in nsIDOMElement tableElement);

  /** Get the indexes from layout's cellmap */
  PRInt32 GetRowIndex(in nsIDOMElement cellElement);
  PRInt32 GetColumnIndex(in nsIDOMElement cellElement);

  /** Get the number of rows in a table from the layout's cellmap 
    * If tableElement is null, it will try to find enclosing table of selection anchor
    */
  PRInt32 GetTableRowCount(in nsIDOMElement tableElement);

  /* Get the number of columns in a table from the layout's cellmap
    * If tableElement is null, it will try to find enclosing table of selection anchor
    */
  PRInt32 GetTableColumnCount(in nsIDOMElement tableElement);

  /* Get cell at a location in the layout's cellmap
     returns null when past last cell in a row or column */
  /* Get a cell and associated data from the layout frame  based on cell map coordinates (0 index) */
  nsIDOMElement GetCellAt(in nsIDOMElement tableElement, in PRInt32 rowIndex, in PRInt32 colIndex);
  /* Get cell at a location in the layout's cellmap with associated data 
     returns null when past last cell in a row or column */
  nsIDOMElement GetCellDataAt(in nsIDOMElement tableElement, in PRInt32 rowIndex, in PRInt32 colIndex,
                              out PRInt32 startRowIndex, out PRInt32 startColIndex,
                              out PRInt32 rowSpan, out PRInt32 colSpan, out boolean isSelected);
  
  /**** end of table editing *****/

  /* Get list of embedded objects, e.g. for mail compose */
  nsISupportsArray GetEmbeddedObjects();

  /* Formatting */
  void SetTextProperty(in wstring prop, in wstring attr, in wstring value);
  void RemoveTextProperty(in wstring prop, in wstring attr);
  void GetTextProperty(in wstring prop, in wstring attr, in wstring value, out boolean firstHas, out boolean anyHas, out boolean allHas);
  void SetBodyAttribute(in wstring attr, in wstring value);
  void SetBackgroundColor(in wstring color);

  void ApplyStyleSheet(in wstring url);
    
  /* Output.
   * format is mime type, e.g. text/html;
   * See nsIEditor.h for legal flag values.
   */
  /* Get the contents, for output or other uses */
  wstring GetContentsAs(in wstring format, in PRUint32 flags);

  /* Debugging: dump content tree to stdout */
  void DumpContentTree();

  /* Utility */
  wstring GetLocalFileURL(in nsIDOMWindow parent, in wstring filterType);

  /**
   * Tests if a node is a BLOCK element according the the HTML 4.0 DTD
   *   This does NOT consider CSS effect on display type
   */
  boolean NodeIsBlock(in nsIDOMNode node);

  /**
   * This is similar to nsIDOMNode::cloneNode(),
   *   it assures the attribute nodes of the destination are identical with the source node
   *   by copying all existing attributes from the source and deleting those not in the source.
   *   This is used when the destination node (element) already exists
   *
   * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
   * destNode     the destination element to operate on
   * sourceNode   the source element to copy attributes from
   */
  void CloneAttributes(in nsIDOMNode destNode, in nsIDOMNode sourceNode);

  void BeginBatchChanges();
  void EndBatchChanges();
  void RunUnitTests();

  void StartLogging(in nsIFileSpec logFile);
  void StopLogging();
};


%{C++
extern nsresult
NS_NewEditorShell(nsIEditorShell** aEditorShell);
%}