editor/nsIHTMLEditor.idl

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