editor/idl/nsIHTMLEditor.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Daniel Glazman <glazman@netscape.com>
  24  *   Akkana Peck <akkana@netscape.com>
  25  *   Kathleen Brade <brade@netscape.com>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either of the GNU General Public License Version 2 or later (the "GPL"),
  29  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #include "nsISupports.idl"
  42 #include "domstubs.idl"
  43
  44 interface nsIAtom;
  45 interface nsISupportsArray;
  46 interface nsISelection;
  47 interface nsIContentFilter;
  48
  49 %{C++
  50 #define NS_EDITOR_ELEMENT_NOT_FOUND \
  51   NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_EDITOR, 1)
  52
  53 %}
  54 [scriptable, uuid(afc36593-5787-4420-93d9-b2c0ccbf0cad)]
  55
  56 interface nsIHTMLEditor : nsISupports
  57 {
  58 %{C++
  59   typedef short EAlignment;
  60 %}
  61
  62   // used by GetAlignment()
  63   const short eLeft = 0;
  64   const short eCenter = 1;
  65   const short eRight = 2;
  66   const short eJustify = 3;
  67
  68
  69   /* ------------ Inline property methods -------------- */
  70
  71
  72   /**
  73    * AddDefaultProperty() registers a default style property with the editor
  74    *
  75    * @param aProperty   the property to set by default
  76    * @param aAttribute  the attribute of the property, if applicable.
  77    *                    May be null.
  78    *                    Example: aProperty="font", aAttribute="color"
  79    * @param aValue      if aAttribute is not null, the value of the attribute.
  80    *                    Example: aProperty="font", aAttribute="color",
  81    *                             aValue="0x00FFFF"
  82    */
  83   void addDefaultProperty(in nsIAtom aProperty,
  84                           in AString aAttribute,
  85                           in AString aValue);
  86
  87   /**
  88    * RemoveDefaultProperty() unregisters a default style property with the editor
  89    *
  90    * @param aProperty   the property to remove from defaults
  91    * @param aAttribute  the attribute of the property, if applicable.
  92    *                    May be null.
  93    *                    Example: aProperty="font", aAttribute="color"
  94    * @param aValue      if aAttribute is not null, the value of the attribute.
  95    *                    Example: aProperty="font", aAttribute="color",
  96    *                             aValue="0x00FFFF"
  97    */
  98   void removeDefaultProperty(in nsIAtom aProperty,
  99                              in AString aAttribute,
 100                              in AString aValue);
 101
 102   /**
 103    * RemoveAllDefaultProperties() unregisters all default style properties with the editor
 104    *
 105    */
 106   void removeAllDefaultProperties();
 107
 108   /**
 109    * SetInlineProperty() sets the aggregate properties on the current selection
 110    *
 111    * @param aProperty   the property to set on the selection
 112    * @param aAttribute  the attribute of the property, if applicable.
 113    *                    May be null.
 114    *                    Example: aProperty="font", aAttribute="color"
 115    * @param aValue      if aAttribute is not null, the value of the attribute.
 116    *                    May be null.
 117    *                    Example: aProperty="font", aAttribute="color",
 118    *                             aValue="0x00FFFF"
 119    */
 120   void setCSSInlineProperty(in nsIAtom aProperty,
 121                             in AString aAttribute,
 122                             in AString aValue);
 123   void setInlineProperty(in nsIAtom aProperty,
 124                          in AString aAttribute,
 125                          in AString aValue);
 126
 127   /**
 128    * getInlineProperty() gets aggregate properties of the current selection.
 129    * All object in the current selection are scanned and their attributes are
 130    * represented in a list of Property object.
 131    *
 132    * @param aProperty   the property to get on the selection
 133    * @param aAttribute  the attribute of the property, if applicable.
 134    *                    May be null.
 135    *                    Example: aProperty="font", aAttribute="color"
 136    * @param aValue      if aAttribute is not null, the value of the attribute.
 137    *                    May be null.
 138    *                    Example: aProperty="font", aAttribute="color",
 139    *                             aValue="0x00FFFF"
 140    * @param aFirst      [OUT] PR_TRUE if the first text node in the
 141    *                          selection has the property
 142    * @param aAny        [OUT] PR_TRUE if any of the text nodes in the
 143    *                          selection have the property
 144    * @param aAll        [OUT] PR_TRUE if all of the text nodes in the
 145    *                          selection have the property
 146    */
 147   void getInlineProperty(in nsIAtom aProperty,
 148                          in AString  aAttribute,
 149                          in AString  aValue,
 150                          out boolean aFirst,
 151                          out boolean aAny,
 152                          out boolean aAll);
 153
 154   AString getInlinePropertyWithAttrValue(in nsIAtom aProperty,
 155                                            in AString  aAttribute,
 156                                            in AString  aValue,
 157                                            out boolean aFirst,
 158                                            out boolean aAny,
 159                                            out boolean aAll);
 160
 161   /**
 162    * removeAllInlineProperties() deletes all the inline properties from all
 163    * text in the current selection.
 164    */
 165   void removeAllInlineProperties();
 166
 167
 168   /**
 169    * removeInlineProperty() deletes the properties from all text in the current
 170    * selection.  If aProperty is not set on the selection, nothing is done.
 171    *
 172    * @param aProperty   the property to remove from the selection
 173    *                    All atoms are for normal HTML tags (e.g.:
 174    *                    nsIEditorProperty::font) except when you want to
 175    *                    remove just links and not named anchors.
 176    *                    For that, use nsIEditorProperty::href
 177    * @param aAttribute  the attribute of the property, if applicable.
 178    *                    May be null.
 179    *                    Example: aProperty=nsIEditorProptery::font,
 180    *                    aAttribute="color"
 181    *                    nsIEditProperty::allAttributes is special.
 182    *                    It indicates that all content-based text properties
 183    *                    are to be removed from the selection.
 184    */
 185   void removeInlineProperty(in nsIAtom aProperty, in AString  aAttribute);
 186
 187   /**
 188    *  Increase font size for text in selection by 1 HTML unit
 189    *  All existing text is scanned for existing <FONT SIZE> attributes
 190    *  so they will be incremented instead of inserting new <FONT> tag
 191    */
 192   void increaseFontSize();
 193
 194   /**
 195    *  Decrease font size for text in selection by 1 HTML unit
 196    *  All existing text is scanned for existing <FONT SIZE> attributes
 197    *  so they will be decreased instead of inserting new <FONT> tag
 198    */
 199   void decreaseFontSize();
 200
 201   /* ------------ Drag/Drop methods -------------- */
 202
 203   /**
 204    * canDrag decides if a drag should be started
 205    * (for example, based on the current selection and mousepoint).
 206    */
 207   boolean canDrag(in nsIDOMEvent aEvent);
 208
 209   /**
 210    * doDrag transfers the relevant data (as appropriate)
 211    * to a transferable so it can later be dropped.
 212    */
 213   void doDrag(in nsIDOMEvent aEvent);
 214
 215   /**
 216    * insertFromDrop looks for a dragsession and inserts the
 217    * relevant data in response to a drop.
 218    */
 219   void insertFromDrop(in nsIDOMEvent aEvent);
 220
 221   /* ------------ HTML content methods -------------- */
 222
 223   /**
 224    * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.
 225    *   This does NOT consider CSS effect on display type
 226    *
 227    * @param aNode      the node to test
 228    */
 229   boolean nodeIsBlock(in nsIDOMNode node);
 230
 231   /**
 232    * Insert some HTML source at the current location
 233    *
 234    * @param aInputString   the string to be inserted
 235    */
 236   void insertHTML(in AString aInputString);
 237
 238
 239   /**
 240     * Paste the text in the OS clipboard at the cursor position, replacing
 241     * the selected text (if any), but strip out any HTML styles and formatting
 242     */
 243   void pasteNoFormatting(in long aSelectionType);
 244
 245   /**
 246    *  Rebuild the entire document from source HTML
 247    *  Needed to be able to edit HEAD and other outside-of-BODY content
 248    *
 249    *  @param aSourceString   HTML source string of the entire new document
 250    */
 251   void rebuildDocumentFromSource(in AString aSourceString);
 252
 253   /**
 254    * Insert some HTML source, interpreting
 255    * the string argument according to the given context.
 256    *
 257    * @param aInputString   the string to be inserted
 258    * @param aContextStr    Context of insertion
 259    * @param aInfoStr       Related info to aInputString
 260    * @param aFlavor        Transferable flavor, can be ""
 261    * @param aSourceDoc          document where input was dragged from (may be null)
 262    * @param aDestinationNode    location for insertion (such as when dropped)
 263    * @param aDestinationOffset  used with aDestNode to determine insert location
 264    * @param aDeleteSelection    used with aDestNode during drag&drop
 265    * @param aCollapseSelection  used with aDestNode during drag&drop
 266    */
 267   void insertHTMLWithContext(in AString aInputString,
 268                              in AString aContextStr,
 269                              in AString aInfoStr,
 270                              in AString aFlavor,
 271                              in nsIDOMDocument aSourceDoc,
 272                              in nsIDOMNode aDestinationNode,
 273                              in long aDestinationOffset,
 274                              in boolean aDeleteSelection);
 275
 276
 277   /**
 278     * Insert an element, which may have child nodes, at the selection
 279     * Used primarily to insert a new element for various insert element dialogs,
 280     *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
 281     *   be useful for other elements.
 282     *
 283     * @param aElement           The element to insert
 284     * @param aDeleteSelection   Delete the selection before inserting
 285     *     If aDeleteSelection is PR_FALSE, then the element is inserted
 286     *     after the end of the selection for all element except
 287     *     Named Anchors, which insert before the selection
 288     */
 289   void insertElementAtSelection(in nsIDOMElement aElement,
 290                                 in boolean aDeleteSelection);
 291
 292   /**
 293    *   Set the documents title.
 294    */
 295   void setDocumentTitle(in AString aTitle);
 296
 297   /**
 298    *   Set the BaseURL for the document to the current URL
 299    *     but only if the page doesn't have a <base> tag
 300    *   This should be done after the document URL has changed,
 301    *     such as after saving a file
 302    *   This is used as base for relativizing link and image urls
 303    */
 304   void updateBaseURL();
 305
 306
 307   /* ------------ Selection manipulation -------------- */
 308   /* Should these be moved to nsISelection? */
 309
 310   /**
 311     * Set the selection at the suppled element
 312     *
 313     * @param aElement   An element in the document
 314     */
 315   void selectElement(in nsIDOMElement aElement);
 316
 317   /**
 318     * Create a collapsed selection just after aElement
 319     *
 320     * XXX could we parameterize SelectElement(before/select/after>?
 321     *
 322     * The selection is set to parent-of-aElement with an
 323     *   offset 1 greater than aElement's offset
 324     *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
 325     *   be useful for other elements.
 326     *
 327     * @param aElement  An element in the document
 328     */
 329   void setCaretAfterElement(in nsIDOMElement aElement);
 330
 331   /**
 332    * SetParagraphFormat       Insert a block paragraph tag around selection
 333    * @param aParagraphFormat  "p", "h1" to "h6", "address", "pre", or "blockquote"
 334    */
 335   void setParagraphFormat(in AString aParagraphFormat);
 336
 337   /**
 338    * getParagraphState returns what block tag paragraph format is in
 339    * the selection.
 340    * @param aMixed     True if there is more than one format
 341    * @return           Name of block tag. "" is returned for none.
 342    */
 343   AString getParagraphState(out boolean aMixed);
 344
 345   /**
 346    * getFontFaceState returns what font face is in the selection.
 347    * @param aMixed    True if there is more than one font face
 348    * @return          Name of face.  Note: "tt" is returned for
 349    *                  tt tag.  "" is returned for none.
 350    */
 351   AString getFontFaceState(out boolean aMixed);
 352
 353   /**
 354    * getFontColorState returns what font face is in the selection.
 355    * @param aMixed     True if there is more than one font color
 356    * @return           Color string. "" is returned for none.
 357    */
 358   AString getFontColorState(out boolean aMixed);
 359
 360   /**
 361    * getFontColorState returns what font face is in the selection.
 362    * @param aMixed     True if there is more than one font color
 363    * @return           Color string. "" is returned for none.
 364    */
 365   AString getBackgroundColorState(out boolean aMixed);
 366
 367   /**
 368    * getHighlightColorState returns what the highlight color of the selection.
 369    * @param aMixed     True if there is more than one font color
 370    * @return           Color string. "" is returned for none.
 371    */
 372   AString getHighlightColorState(out boolean aMixed);
 373
 374   /**
 375    * getListState returns what list type is in the selection.
 376    * @param aMixed    True if there is more than one type of list, or
 377    *                  if there is some list and non-list
 378    * @param aOL       The company that employs me.  No, really, it's
 379    *                  true if an "ol" list is selected.
 380    * @param aUL       true if an "ul" list is selected.
 381    * @param aDL       true if a "dl" list is selected.
 382    */
 383   void getListState(out boolean aMixed, out boolean aOL, out boolean aUL,
 384                     out boolean aDL);
 385
 386   /**
 387    * getListItemState returns what list item type is in the selection.
 388    * @param aMixed    True if there is more than one type of list item, or
 389    *                  if there is some list and non-list
 390    * @param aLI       true if "li" list items are selected.
 391    * @param aDT       true if "dt" list items are selected.
 392    * @param aDD       true if "dd" list items are selected.
 393    */
 394   void getListItemState(out boolean aMixed, out boolean aLI,
 395                         out boolean aDT, out boolean aDD);
 396
 397   /**
 398    * getAlignment     returns what alignment is in the selection.
 399    * @param aMixed    True if there is more than one type of list item, or
 400    *                  if there is some list and non-list
 401    * @param aAlign    enum value for first encountered alignment
 402    *                  (left/center/right)
 403    */
 404   void getAlignment(out boolean aMixed, out short aAlign);
 405
 406   /**
 407    * Document me!
 408    *
 409    */
 410   void getIndentState(out boolean aCanIndent, out boolean aCanOutdent);
 411
 412   /**
 413    * Document me!
 414    *
 415    */
 416   void makeOrChangeList(in AString aListType, in boolean entireList,
 417                         in AString aBulletType);
 418
 419   /**
 420    * Document me!
 421    *
 422    */
 423   void removeList(in AString aListType);
 424
 425   /**
 426    * Document me!
 427    *
 428    */
 429   void indent(in AString aIndent);
 430
 431   /**
 432    * Document me!
 433    *
 434    */
 435   void  align(in AString aAlign);
 436
 437   /**
 438    * Return the input node or a parent matching the given aTagName,
 439    *   starting the search at the supplied node.
 440    * An example of use is for testing if a node is in a table cell
 441    *   given a selection anchor node.
 442    *
 443    * @param aTagName  The HTML tagname
 444    *  Special input values:
 445    *    Use "href" to get a link node
 446    *      (an "A" tag with the "href" attribute set)
 447    *    Use "anchor" or "namedanchor" to get a named anchor node
 448    *      (an "A" tag with the "name" attribute set)
 449    *    Use "list" to get an OL, UL, or DL list node
 450    *    Use "td" to get either a TD or TH cell node
 451    *
 452    * @param aNode    The node in the document to start the search.
 453    *     If it is null, the anchor node of the current selection is used.
 454    * @return         NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 455    *                 (passes NS_SUCCEEDED macro)
 456    */
 457   nsIDOMElement getElementOrParentByTagName(in AString aTagName,
 458                                             in nsIDOMNode aNode);
 459
 460   /**
 461    * Return an element only if it is the only node selected,
 462    *    such as an image, horizontal rule, etc.
 463    * The exception is a link, which is more like a text attribute:
 464    *    The Anchor tag is returned if the selection is within the textnode(s)
 465    *    that are children of the "A" node.
 466    *    This could be a collapsed selection, i.e., a caret
 467    *    within the link text.
 468    *
 469    * @param aTagName  The HTML tagname or and empty string
 470    *       to get any element (but only if it is the only element selected)
 471    *    Special input values for Links and Named anchors:
 472    *    Use "href" to get a link node
 473    *      (an "A" tag with the "href" attribute set)
 474    *    Use "anchor" or "namedanchor" to get a named anchor node
 475    *      (an "A" tag with the "name" attribute set)
 476    * @return          NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 477    *                  (passes NS_SUCCEEDED macro)
 478    */
 479   nsIDOMElement getSelectedElement(in AString aTagName);
 480
 481   /**
 482    * Output the contents of the <HEAD> section as text/HTML format
 483    */
 484   AString getHeadContentsAsHTML();
 485
 486   /**
 487    * Replace all children of <HEAD> with string of HTML source
 488    */
 489   void replaceHeadContentsWithHTML(in AString aSourceToInsert);
 490
 491   /**
 492    * Return a new element with default attribute values
 493    *
 494    * This does not rely on the selection, and is not sensitive to context.
 495    *
 496    * Used primarily to supply new element for various insert element dialogs
 497    *  (Image, Link, NamedAnchor, Table, and HorizontalRule
 498    *   are the only returned elements as of 7/25/99)
 499    *
 500    * @param aTagName  The HTML tagname
 501    *    Special input values for Links and Named anchors:
 502    *    Use "href" to get a link node
 503    *      (an "A" tag with the "href" attribute set)
 504    *    Use "anchor" or "namedanchor" to get a named anchor node
 505    *      (an "A" tag with the "name" attribute set)
 506    * @return          The new element created.
 507    */
 508   nsIDOMElement createElementWithDefaults(in AString aTagName);
 509
 510   /**
 511    * Insert an link element as the parent of the current selection
 512    *
 513    * @param aElement   An "A" element with a non-empty "href" attribute
 514    */
 515   void insertLinkAroundSelection(in nsIDOMElement aAnchorElement);
 516
 517   /**
 518    * Set the value of the "bgcolor" attribute on the document's <body> element
 519    *
 520    * @param aColor  The HTML color string, such as "#ffccff" or "yellow"
 521    */
 522   void setBackgroundColor(in AString aColor);
 523
 524
 525   /**
 526    * Set an attribute on the document's <body> element
 527    *    such as text, link, background colors
 528    *
 529    * 8/31/00 THIS ISN'T BEING USED? SHOULD WE DROP IT?
 530    *
 531    * @param aAttr   The attribute to be set
 532    * @param aValue  The value of the attribute
 533    */
 534   void setBodyAttribute(in AString aAttr, in AString aValue);
 535
 536   /**
 537    * XXX Used to suppress spurious drag/drop events to workaround bug 50703
 538    * Don't use this method! It will go away after first release!
 539    */
 540   void ignoreSpuriousDragEvent(in boolean aIgnoreSpuriousDragEvent);
 541
 542   /**
 543    * Find all the nodes in the document which contain references
 544    * to outside URIs (e.g. a href, img src, script src, etc.)
 545    * The objects in the array will be type nsIURIRefObject.
 546    *
 547    * @return aNodeList    the linked nodes found
 548    */
 549   nsISupportsArray getLinkedObjects();
 550
 551   /**
 552    * A boolean which is true is the HTMLEditor has been instantiated
 553    * with CSS knowledge and if the CSS pref is currently checked
 554    *
 555    * @return    true if CSS handled and enabled
 556    */
 557   attribute boolean isCSSEnabled;
 558
 559   /**
 560    * Add listener for insertion override
 561    * @param inFilter  function which callers want called during insertion
 562    */
 563   void addInsertionListener(in nsIContentFilter inFilter);
 564
 565   /**
 566    * Remove listener for insertion override
 567    * @param inFilter  function which callers do not want called during insertion
 568    */
 569   void removeInsertionListener(in nsIContentFilter inFilter);
 570
 571   /**
 572    * Returns an anonymous nsDOMElement of type aTag,
 573    * child of aParentNode. If aIsCreatedHidden is true, the class
 574    * "hidden" is added to the created element. If aAnonClass is not
 575    * the empty string, it becomes the value of the attribute "_moz_anonclass"
 576    * @return a DOM Element
 577    * @param aTag             [IN] a string representing the desired type of
 578    *                              the element to create
 579    * @param aParentNode      [IN] the parent node of the created anonymous
 580    *                              element
 581    * @param aAnonClass       [IN] contents of the _moz_anonclass attribute
 582    * @param aIsCreatedHidden [IN] a boolean specifying if the class "hidden"
 583    *                              is to be added to the created anonymous
 584    *                              element
 585    */
 586   nsIDOMElement createAnonymousElement(in AString aTag, in nsIDOMNode aParentNode,
 587                                        in AString aAnonClass, in boolean aIsCreatedHidden);
 588
 589   /**
 590    * returns the deepest container of the selection
 591    * @return a DOM Element
 592    */
 593   nsIDOMElement getSelectionContainer();
 594
 595   /**
 596    * Checks if the anonymous nodes created by the HTML editor have to be
 597    * refreshed or hidden depending on a possible new state of the selection
 598    * @param aSelection [IN] a selection
 599    */
 600   void checkSelectionStateForAnonymousButtons(in nsISelection aSelection);
 601
 602   boolean isAnonymousElement(in nsIDOMElement aElement);
 603
 604   /**
 605    * A boolean indicating if a return key pressed in a paragraph creates
 606    * another paragraph or just inserts a <br> at the caret
 607    *
 608    * @return    true if CR in a paragraph creates a new paragraph
 609    */
 610   attribute boolean returnInParagraphCreatesNewParagraph;
 611 };
 612