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 nsIContent;
  10
  11 webidl Document;
  12 webidl Element;
  13 webidl Node;
  14 webidl Selection;
  15
  16 [scriptable, builtinclass, uuid(87ee993e-985f-4a43-a974-0d9512da2fb0)]
  17 interface nsIHTMLEditor : nsISupports
  18 {
  19 %{C++
  20   typedef short EAlignment;
  21 %}
  22
  23   // used by GetAlignment()
  24   const short eLeft = 0;
  25   const short eCenter = 1;
  26   const short eRight = 2;
  27   const short eJustify = 3;
  28
  29
  30   /* ------------ Inline property methods -------------- */
  31
  32   /**
  33    * SetInlineProperty() sets the aggregate properties on the current selection
  34    *
  35    * @param aProperty   the property to set on the selection
  36    * @param aAttribute  the attribute of the property, if applicable.
  37    *                    May be null.
  38    *                    Example: aProperty="font", aAttribute="color"
  39    * @param aValue      if aAttribute is not null, the value of the attribute.
  40    *                    May be null.
  41    *                    Example: aProperty="font", aAttribute="color",
  42    *                             aValue="0x00FFFF"
  43    */
  44   [can_run_script]
  45   void setInlineProperty(in AString aProperty,
  46                          in AString aAttribute,
  47                          in AString aValue);
  48
  49   /**
  50    * getInlineProperty() gets aggregate properties of the current selection.
  51    * All object in the current selection are scanned and their attributes are
  52    * represented in a list of Property object.
  53    *
  54    * @param aProperty   the property to get on the selection
  55    * @param aAttribute  the attribute of the property, if applicable.
  56    *                    May be null.
  57    *                    Example: aProperty="font", aAttribute="color"
  58    * @param aValue      if aAttribute is not null, the value of the attribute.
  59    *                    May be null.
  60    *                    Example: aProperty="font", aAttribute="color",
  61    *                             aValue="0x00FFFF"
  62    * @param aFirst      [OUT] PR_TRUE if the first text node in the
  63    *                          selection has the property
  64    * @param aAny        [OUT] PR_TRUE if any of the text nodes in the
  65    *                          selection have the property
  66    * @param aAll        [OUT] PR_TRUE if all of the text nodes in the
  67    *                          selection have the property
  68    */
  69   void getInlineProperty(in AString aProperty,
  70                          in AString aAttribute,
  71                          in AString aValue,
  72                          out boolean aFirst,
  73                          out boolean aAny,
  74                          out boolean aAll);
  75
  76   AString getInlinePropertyWithAttrValue(in AString aProperty,
  77                                          in AString aAttribute,
  78                                          in AString aValue,
  79                                          out boolean aFirst,
  80                                          out boolean aAny,
  81                                          out boolean aAll);
  82
  83   /**
  84    * removeAllInlineProperties() deletes all the inline properties from all
  85    * text in the current selection.
  86    */
  87   [can_run_script]
  88   void removeAllInlineProperties();
  89
  90
  91   /**
  92    * removeInlineProperty() removes a property which changes inline style of
  93    * text.  E.g., bold, italic, super and sub.
  94    *
  95    * @param aProperty   Tag name whcih represents the inline style you want to
  96    *                    remove.  E.g., "strong", "b", etc.
  97    *                    If "href", <a> element which has href attribute will be
  98    *                    removed.
  99    *                    If "name", <a> element which has non-empty name
 100    *                    attribute will be removed.
 101    * @param aAttribute  If aProperty is "font", aAttribute should be "face",
 102    *                    "size", "color" or "bgcolor".
 103    */
 104   [can_run_script]
 105   void removeInlineProperty(in AString aProperty, in AString aAttribute);
 106
 107   /**
 108    *  Increase font size for text in selection by 1 HTML unit
 109    *  All existing text is scanned for existing <FONT SIZE> attributes
 110    *  so they will be incremented instead of inserting new <FONT> tag
 111    */
 112   [can_run_script]
 113   void increaseFontSize();
 114
 115   /**
 116    *  Decrease font size for text in selection by 1 HTML unit
 117    *  All existing text is scanned for existing <FONT SIZE> attributes
 118    *  so they will be decreased instead of inserting new <FONT> tag
 119    */
 120   [can_run_script]
 121   void decreaseFontSize();
 122
 123   /* ------------ HTML content methods -------------- */
 124
 125   /**
 126    * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.
 127    *   This does NOT consider CSS effect on display type
 128    *
 129    * @param aNode      the node to test
 130    */
 131   boolean nodeIsBlock(in Node node);
 132
 133   /**
 134    * Insert some HTML source at the current location
 135    *
 136    * @param aInputString   the string to be inserted
 137    */
 138   [can_run_script]
 139   void insertHTML(in AString aInputString);
 140
 141
 142   /**
 143     * Paste the text in the OS clipboard at the cursor position, replacing
 144     * the selected text (if any), but strip out any HTML styles and formatting
 145     */
 146   [can_run_script]
 147   void pasteNoFormatting(in long aSelectionType);
 148
 149   /**
 150    *  Rebuild the entire document from source HTML
 151    *  Needed to be able to edit HEAD and other outside-of-BODY content
 152    *
 153    *  @param aSourceString   HTML source string of the entire new document
 154    */
 155   [can_run_script]
 156   void rebuildDocumentFromSource(in AString aSourceString);
 157
 158   /**
 159     * Insert an element, which may have child nodes, at the selection
 160     * Used primarily to insert a new element for various insert element dialogs,
 161     *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
 162     *   be useful for other elements.
 163     *
 164     * @param aElement           The element to insert
 165     * @param aDeleteSelection   Delete the selection before inserting
 166     *     If aDeleteSelection is PR_FALSE, then the element is inserted
 167     *     after the end of the selection for all element except
 168     *     Named Anchors, which insert before the selection
 169     */
 170   [can_run_script]
 171   void insertElementAtSelection(in Element aElement,
 172                                 in boolean aDeleteSelection);
 173
 174   /**
 175    *   Set the BaseURL for the document to the current URL
 176    *     but only if the page doesn't have a <base> tag
 177    *   This should be done after the document URL has changed,
 178    *     such as after saving a file
 179    *   This is used as base for relativizing link and image urls
 180    */
 181   void updateBaseURL();
 182
 183
 184   /* ------------ Selection manipulation -------------- */
 185   /* Should these be moved to Selection? */
 186
 187   /**
 188     * Set the selection at the suppled element
 189     *
 190     * @param aElement   An element in the document
 191     */
 192   [can_run_script]
 193   void selectElement(in Element aElement);
 194
 195   /**
 196     * Create a collapsed selection just after aElement
 197     *
 198     * XXX could we parameterize SelectElement(before/select/after>?
 199     *
 200     * The selection is set to parent-of-aElement with an
 201     *   offset 1 greater than aElement's offset
 202     *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
 203     *   be useful for other elements.
 204     *
 205     * @param aElement  An element in the document
 206     */
 207   void setCaretAfterElement(in Element aElement);
 208
 209   /**
 210    * SetParagraphFormat       Insert a block paragraph tag around selection
 211    * @param aParagraphFormat  "p", "h1" to "h6", "address", "pre", or "blockquote"
 212    */
 213   [can_run_script]
 214   void setParagraphFormat(in AString aParagraphFormat);
 215
 216   /**
 217    * getParagraphState returns what block tag paragraph format is in
 218    * the selection.
 219    * @param aMixed     True if there is more than one format
 220    * @return           Name of block tag. "" is returned for none.
 221    */
 222   AString getParagraphState(out boolean aMixed);
 223
 224   /**
 225    * getFontFaceState returns what font face is in the selection.
 226    * @param aMixed    True if there is more than one font face
 227    * @return          Name of face.  Note: "tt" is returned for
 228    *                  tt tag.  "" is returned for none.
 229    */
 230   AString getFontFaceState(out boolean aMixed);
 231
 232   /**
 233    * getBackgroundColorState returns what the background color of the selection.
 234    * @param aMixed     True if there is more than one font color
 235    * @return           Color string. "" is returned for none.
 236    */
 237   AString getBackgroundColorState(out boolean aMixed);
 238
 239   /**
 240    * getHighlightColorState returns what the highlight color of the selection.
 241    * @param aMixed     True if there is more than one font color
 242    * @return           Color string. "" is returned for none.
 243    */
 244   AString getHighlightColorState(out boolean aMixed);
 245
 246   /**
 247    * getListState returns what list type is in the selection.
 248    * @param aMixed    True if there is more than one type of list, or
 249    *                  if there is some list and non-list
 250    * @param aOL       The company that employs me.  No, really, it's
 251    *                  true if an "ol" list is selected.
 252    * @param aUL       true if an "ul" list is selected.
 253    * @param aDL       true if a "dl" list is selected.
 254    */
 255   void getListState(out boolean aMixed, out boolean aOL, out boolean aUL,
 256                     out boolean aDL);
 257
 258   /**
 259    * getListItemState returns what list item type is in the selection.
 260    * @param aMixed    True if there is more than one type of list item, or
 261    *                  if there is some list and non-list
 262    *                  XXX This ignores `<li>` element selected state.
 263    *                      For example, even if `<li>` and `<dt>` are selected,
 264    *                      this is set to false.
 265    * @param aLI       true if "li" list items are selected.
 266    * @param aDT       true if "dt" list items are selected.
 267    * @param aDD       true if "dd" list items are selected.
 268    */
 269   void getListItemState(out boolean aMixed, out boolean aLI,
 270                         out boolean aDT, out boolean aDD);
 271
 272   /**
 273    * getAlignment     returns what alignment is in the selection.
 274    * @param aMixed    Always returns false.
 275    * @param aAlign    enum value for first encountered alignment
 276    *                  (left/center/right)
 277    */
 278   void getAlignment(out boolean aMixed, out short aAlign);
 279
 280   /**
 281    * Document me!
 282    *
 283    */
 284   [can_run_script]
 285   void makeOrChangeList(in AString aListType, in boolean entireList,
 286                         in AString aBulletType);
 287
 288   /**
 289    * removeList removes list items (<li>, <dd>, and <dt>) and list structures
 290    * (<ul>, <ol>, and <dl>).
 291    *
 292    * @param aListType  Unused.
 293    */
 294   [can_run_script]
 295   void removeList(in AString aListType);
 296
 297   /**
 298    * Document me!
 299    *
 300    */
 301   [can_run_script]
 302   void indent(in AString aIndent);
 303
 304   /**
 305    * Document me!
 306    *
 307    */
 308   [can_run_script]
 309   void  align(in AString aAlign);
 310
 311   /**
 312    * GetElementOrParentByTagName() looks for an element node whose name matches
 313    * aTagName from aNode or anchor node of Selection to <body> element.
 314    *
 315    * @param aTagName        The tag name which you want to look for.
 316    *                        Must not be empty string.
 317    *                        If "list", the result may be <ul>, <ol> or <dl>
 318    *                        element.
 319    *                        If "td", the result may be <td> or <th>.
 320    *                        If "href", the result may be <a> element
 321    *                        which has "href" attribute with non-empty value.
 322    *                        If "anchor", the result may be <a> which has
 323    *                        "name" attribute with non-empty value.
 324    * @param aNode           If non-null, this starts to look for the result
 325    *                        from it.  Otherwise, i.e., null, starts from
 326    *                        anchor node of Selection.
 327    * @return                If an element which matches aTagName, returns
 328    *                        an Element.  Otherwise, nullptr.
 329    */
 330   Element getElementOrParentByTagName(in AString aTagName,
 331                                       in Node aNode);
 332
 333   /**
 334    * getSelectedElement() returns a "selected" element node.  "selected" means:
 335    * - there is only one selection range
 336    * - the range starts from an element node or in an element
 337    * - the range ends at immediately after same element
 338    * - and the range does not include any other element nodes.
 339    * Additionally, only when aTagName is "href", this thinks that an <a>
 340    * element which has non-empty "href" attribute includes the range, the
 341    * <a> element is selected.
 342    *
 343    * @param aTagName    Case-insensitive element name.
 344    *                    If empty string, this returns any element node or null.
 345    *                    If "href", this returns an <a> element which has
 346    *                    non-empty "href" attribute or null.
 347    *                    If "anchor", this returns an <a> element which has
 348    *                    non-empty "name" attribute or null.
 349    *                    Otherwise, returns an element node whose name is
 350    *                    same as aTagName or null.
 351    * @return            A "selected" element.
 352    */
 353   nsISupports getSelectedElement(in AString aTagName);
 354
 355   /**
 356    * Return a new element with default attribute values
 357    *
 358    * This does not rely on the selection, and is not sensitive to context.
 359    *
 360    * Used primarily to supply new element for various insert element dialogs
 361    *  (Image, Link, NamedAnchor, Table, and HorizontalRule
 362    *   are the only returned elements as of 7/25/99)
 363    *
 364    * @param aTagName  The HTML tagname
 365    *    Special input values for Links and Named anchors:
 366    *    Use "href" to get a link node
 367    *      (an "A" tag with the "href" attribute set)
 368    *    Use "anchor" or "namedanchor" to get a named anchor node
 369    *      (an "A" tag with the "name" attribute set)
 370    * @return          The new element created.
 371    */
 372   [can_run_script]
 373   Element createElementWithDefaults(in AString aTagName);
 374
 375   /**
 376    * Insert an link element as the parent of the current selection
 377    *
 378    * @param aElement   An "A" element with a non-empty "href" attribute
 379    */
 380   [can_run_script]
 381   void insertLinkAroundSelection(in Element aAnchorElement);
 382
 383   /**
 384    * Set the value of the "bgcolor" attribute on the document's <body> element
 385    *
 386    * @param aColor  The HTML color string, such as "#ffccff" or "yellow"
 387    */
 388   [can_run_script]
 389   void setBackgroundColor(in AString aColor);
 390
 391   /**
 392    * A boolean which is true is the HTMLEditor has been instantiated
 393    * with CSS knowledge and if the CSS pref is currently checked
 394    *
 395    * @return    true if CSS handled and enabled
 396    */
 397   attribute boolean isCSSEnabled;
 398
 399   /**
 400    * checkSelectionStateForAnonymousButtons() may refresh editing UI such as
 401    * resizers, inline-table-editing UI, absolute positioning UI for current
 402    * Selection and focus state.  When this method shows or hides UI, the
 403    * editor (and/or its document/window) could be broken by mutation observers.
 404    * FYI: Current user in script is only BlueGriffon.
 405    */
 406   [can_run_script]
 407   void checkSelectionStateForAnonymousButtons();
 408
 409   boolean isAnonymousElement(in Element aElement);
 410
 411   /**
 412    * A boolean indicating if a return key pressed in a paragraph creates
 413    * another paragraph or just inserts a <br> at the caret
 414    *
 415    * @return    true if CR in a paragraph creates a new paragraph
 416    */
 417   attribute boolean returnInParagraphCreatesNewParagraph;
 418 };
 419