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