Source code

Revision control

Other Tools

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "domstubs.idl"

interface nsIContent;
interface nsIArray;

webidl Document;
webidl Element;
webidl Node;
webidl Selection;

[scriptable, builtinclass, uuid(87ee993e-985f-4a43-a974-0d9512da2fb0)]
interface nsIHTMLEditor : nsISupports
{
%{C++
  typedef short EAlignment;
%}

  // used by GetAlignment()
  const short eLeft = 0;
  const short eCenter = 1;
  const short eRight = 2;
  const short eJustify = 3;


  /* ------------ Inline property methods -------------- */

  /**
   * SetInlineProperty() sets the aggregate properties on the current selection
   *
   * @param aProperty   the property to set on the selection
   * @param aAttribute  the attribute of the property, if applicable.
   *                    May be null.
   *                    Example: aProperty="font", aAttribute="color"
   * @param aValue      if aAttribute is not null, the value of the attribute.
   *                    May be null.
   *                    Example: aProperty="font", aAttribute="color",
   *                             aValue="0x00FFFF"
   */
  [can_run_script]
  void setInlineProperty(in AString aProperty,
                         in AString aAttribute,
                         in AString aValue);

  /**
   * getInlineProperty() gets aggregate properties of the current selection.
   * All object in the current selection are scanned and their attributes are
   * represented in a list of Property object.
   *
   * @param aProperty   the property to get on the selection
   * @param aAttribute  the attribute of the property, if applicable.
   *                    May be null.
   *                    Example: aProperty="font", aAttribute="color"
   * @param aValue      if aAttribute is not null, the value of the attribute.
   *                    May be null.
   *                    Example: aProperty="font", aAttribute="color",
   *                             aValue="0x00FFFF"
   * @param aFirst      [OUT] PR_TRUE if the first text node in the
   *                          selection has the property
   * @param aAny        [OUT] PR_TRUE if any of the text nodes in the
   *                          selection have the property
   * @param aAll        [OUT] PR_TRUE if all of the text nodes in the
   *                          selection have the property
   */
  void getInlineProperty(in AString aProperty,
                         in AString aAttribute,
                         in AString aValue,
                         out boolean aFirst,
                         out boolean aAny,
                         out boolean aAll);

  AString getInlinePropertyWithAttrValue(in AString aProperty,
                                         in AString aAttribute,
                                         in AString aValue,
                                         out boolean aFirst,
                                         out boolean aAny,
                                         out boolean aAll);

  /**
   * removeAllInlineProperties() deletes all the inline properties from all
   * text in the current selection.
   */
  [can_run_script]
  void removeAllInlineProperties();


  /**
   * removeInlineProperty() removes a property which changes inline style of
   * text.  E.g., bold, italic, super and sub.
   *
   * @param aProperty   Tag name whcih represents the inline style you want to
   *                    remove.  E.g., "strong", "b", etc.
   *                    If "href", <a> element which has href attribute will be
   *                    removed.
   *                    If "name", <a> element which has non-empty name
   *                    attribute will be removed.
   * @param aAttribute  If aProperty is "font", aAttribute should be "face",
   *                    "size", "color" or "bgcolor".
   */
  [can_run_script]
  void removeInlineProperty(in AString aProperty, in AString aAttribute);

  /**
   *  Increase font size for text in selection by 1 HTML unit
   *  All existing text is scanned for existing <FONT SIZE> attributes
   *  so they will be incremented instead of inserting new <FONT> tag
   */
  [can_run_script]
  void increaseFontSize();

  /**
   *  Decrease font size for text in selection by 1 HTML unit
   *  All existing text is scanned for existing <FONT SIZE> attributes
   *  so they will be decreased instead of inserting new <FONT> tag
   */
  [can_run_script]
  void decreaseFontSize();

  /* ------------ HTML content methods -------------- */

  /**
   * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.
   *   This does NOT consider CSS effect on display type
   *
   * @param aNode      the node to test
   */
  boolean nodeIsBlock(in Node node);

  /**
   * Insert some HTML source at the current location
   *
   * @param aInputString   the string to be inserted
   */
  [can_run_script]
  void insertHTML(in AString aInputString);


  /**
    * Paste the text in the OS clipboard at the cursor position, replacing
    * the selected text (if any), but strip out any HTML styles and formatting
    */
  [can_run_script]
  void pasteNoFormatting(in long aSelectionType);

  /**
   *  Rebuild the entire document from source HTML
   *  Needed to be able to edit HEAD and other outside-of-BODY content
   *
   *  @param aSourceString   HTML source string of the entire new document
   */
  [can_run_script]
  void rebuildDocumentFromSource(in AString aSourceString);

  /**
    * 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.
    *
    * @param aElement           The element to insert
    * @param aDeleteSelection   Delete the selection before inserting
    *     If aDeleteSelection 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
    */
  [can_run_script]
  void insertElementAtSelection(in Element aElement,
                                in boolean aDeleteSelection);

  /**
   *   Set the BaseURL for the document to the current URL
   *     but only if the page doesn't have a <base> tag
   *   This should be done after the document URL has changed,
   *     such as after saving a file
   *   This is used as base for relativizing link and image urls
   */
  void updateBaseURL();


  /* ------------ Selection manipulation -------------- */
  /* Should these be moved to Selection? */

  /**
    * Set the selection at the suppled element
    *
    * @param aElement   An element in the document
    */
  [can_run_script]
  void selectElement(in Element aElement);

  /**
    * Create a collapsed selection just after aElement
    *
    * XXX could we parameterize SelectElement(before/select/after>?
    *
    * The selection is set to parent-of-aElement with an
    *   offset 1 greater than aElement's offset
    *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
    *   be useful for other elements.
    *
    * @param aElement  An element in the document
    */
  void setCaretAfterElement(in Element aElement);

  /**
   * SetParagraphFormat       Insert a block paragraph tag around selection
   * @param aParagraphFormat  "p", "h1" to "h6", "address", "pre", or "blockquote"
   */
  [can_run_script]
  void setParagraphFormat(in AString aParagraphFormat);

  /**
   * getParagraphState returns what block tag paragraph format is in
   * the selection.
   * @param aMixed     True if there is more than one format
   * @return           Name of block tag. "" is returned for none.
   */
  [can_run_script]
  AString getParagraphState(out boolean aMixed);

  /**
   * getFontFaceState returns what font face is in the selection.
   * @param aMixed    True if there is more than one font face
   * @return          Name of face.  Note: "tt" is returned for
   *                  tt tag.  "" is returned for none.
   */
  AString getFontFaceState(out boolean aMixed);

  /**
   * getBackgroundColorState returns what the background color of the selection.
   * @param aMixed     True if there is more than one font color
   * @return           Color string. "" is returned for none.
   */
  AString getBackgroundColorState(out boolean aMixed);

  /**
   * getHighlightColorState returns what the highlight color of the selection.
   * @param aMixed     True if there is more than one font color
   * @return           Color string. "" is returned for none.
   */
  AString getHighlightColorState(out boolean aMixed);

  /**
   * getListState returns what list type is in the selection.
   * @param aMixed    True if there is more than one type of list, or
   *                  if there is some list and non-list
   * @param aOL       The company that employs me.  No, really, it's
   *                  true if an "ol" list is selected.
   * @param aUL       true if an "ul" list is selected.
   * @param aDL       true if a "dl" list is selected.
   */
  [can_run_script]
  void getListState(out boolean aMixed, out boolean aOL, out boolean aUL,
                    out boolean aDL);

  /**
   * getListItemState returns what list item type is in the selection.
   * @param aMixed    True if there is more than one type of list item, or
   *                  if there is some list and non-list
   * @param aLI       true if "li" list items are selected.
   * @param aDT       true if "dt" list items are selected.
   * @param aDD       true if "dd" list items are selected.
   */
  [can_run_script]
  void getListItemState(out boolean aMixed, out boolean aLI,
                        out boolean aDT, out boolean aDD);

  /**
   * getAlignment     returns what alignment is in the selection.
   * @param aMixed    True if there is more than one type of list item, or
   *                  if there is some list and non-list
   * @param aAlign    enum value for first encountered alignment
   *                  (left/center/right)
   */
  [can_run_script]
  void getAlignment(out boolean aMixed, out short aAlign);

  /**
   * Document me!
   *
   */
  [can_run_script]
  void makeOrChangeList(in AString aListType, in boolean entireList,
                        in AString aBulletType);

  /**
   * removeList removes list items (<li>, <dd>, and <dt>) and list structures
   * (<ul>, <ol>, and <dl>).
   *
   * @param aListType  Unused.
   */
  void removeList(in AString aListType);

  /**
   * Document me!
   *
   */
  [can_run_script]
  void indent(in AString aIndent);

  /**
   * Document me!
   *
   */
  void  align(in AString aAlign);

  /**
   * GetElementOrParentByTagName() looks for an element node whose name matches
   * aTagName from aNode or anchor node of Selection to <body> element.
   *
   * @param aTagName        The tag name which you want to look for.
   *                        Must not be empty string.
   *                        If "list", the result may be <ul>, <ol> or <dl>
   *                        element.
   *                        If "td", the result may be <td> or <th>.
   *                        If "href", the result may be <a> element
   *                        which has "href" attribute with non-empty value.
   *                        If "anchor", the result may be <a> which has
   *                        "name" attribute with non-empty value.
   * @param aNode           If non-null, this starts to look for the result
   *                        from it.  Otherwise, i.e., null, starts from
   *                        anchor node of Selection.
   * @return                If an element which matches aTagName, returns
   *                        an Element.  Otherwise, nullptr.
   */
  Element getElementOrParentByTagName(in AString aTagName,
                                      in Node aNode);

  /**
   * getSelectedElement() returns a "selected" element node.  "selected" means:
   * - there is only one selection range
   * - the range starts from an element node or in an element
   * - the range ends at immediately after same element
   * - and the range does not include any other element nodes.
   * Additionally, only when aTagName is "href", this thinks that an <a>
   * element which has non-empty "href" attribute includes the range, the
   * <a> element is selected.
   *
   * @param aTagName    Case-insensitive element name.
   *                    If empty string, this returns any element node or null.
   *                    If "href", this returns an <a> element which has
   *                    non-empty "href" attribute or null.
   *                    If "anchor", this returns an <a> element which has
   *                    non-empty "name" attribute or null.
   *                    Otherwise, returns an element node whose name is
   *                    same as aTagName or null.
   * @return            A "selected" element.
   */
  nsISupports getSelectedElement(in AString aTagName);

  /**
   * 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)
   *
   * @param aTagName  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)
   * @return          The new element created.
   */
  [can_run_script]
  Element createElementWithDefaults(in AString aTagName);

  /**
   * Insert an link element as the parent of the current selection
   *
   * @param aElement   An "A" element with a non-empty "href" attribute
   */
  [can_run_script]
  void insertLinkAroundSelection(in Element aAnchorElement);

  /**
   * Set the value of the "bgcolor" attribute on the document's <body> element
   *
   * @param aColor  The HTML color string, such as "#ffccff" or "yellow"
   */
  [can_run_script]
  void setBackgroundColor(in AString aColor);

  /**
   * Find all the nodes in the document which contain references
   * to outside URIs (e.g. a href, img src, script src, etc.)
   * The objects in the array will be type nsIURIRefObject.
   *
   * @return aNodeList    the linked nodes found
   */
  nsIArray getLinkedObjects();

  /**
   * A boolean which is true is the HTMLEditor has been instantiated
   * with CSS knowledge and if the CSS pref is currently checked
   *
   * @return    true if CSS handled and enabled
   */
  attribute boolean isCSSEnabled;

  /**
   * checkSelectionStateForAnonymousButtons() may refresh editing UI such as
   * resizers, inline-table-editing UI, absolute positioning UI for current
   * Selection and focus state.  When this method shows or hides UI, the
   * editor (and/or its document/window) could be broken by mutation observers.
   * FYI: Current user in script is only BlueGriffon.
   */
  [can_run_script]
  void checkSelectionStateForAnonymousButtons();

  boolean isAnonymousElement(in Element aElement);

  /**
   * A boolean indicating if a return key pressed in a paragraph creates
   * another paragraph or just inserts a <br> at the caret
   *
   * @return    true if CR in a paragraph creates a new paragraph
   */
  attribute boolean returnInParagraphCreatesNewParagraph;
};