Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 678 insertions, 0 deletions

diff --git a/editor/nsIEditor.idl b/editor/nsIEditor.idl
new file mode 100644
index 0000000000..c32b06c605
--- /dev/null
+++ b/editor/nsIEditor.idl
@@ -0,0 +1,678 @@
+/* -*- Mode: C++; tab-width: 4; 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"
+
+%{C++
+#include "mozilla/Debug.h"
+%}
+
+interface nsISelectionController;
+interface nsIDocumentStateListener;
+interface nsIEditActionListener;
+interface nsIInlineSpellChecker;
+interface nsITransferable;
+
+webidl Document;
+webidl Element;
+webidl Node;
+webidl Selection;
+
+%{C++
+namespace mozilla {
+class EditorBase;
+class HTMLEditor;
+class TextEditor;
+} // namespace mozilla
+%}
+
+[scriptable, builtinclass, uuid(094be624-f0bf-400f-89e2-6a84baab9474)]
+interface nsIEditor  : nsISupports
+{
+%{C++
+  typedef short EDirection;
+  typedef short EStripWrappers;
+%}
+  const short eNone = 0;
+  const short eNext = 1;
+  const short ePrevious = 2;
+  const short eNextWord = 3;
+  const short ePreviousWord = 4;
+  const short eToBeginningOfLine = 5;
+  const short eToEndOfLine = 6;
+
+%{C++
+  static bool EDirectionIsValid(EDirection aDirectionAndAmount) {
+    return aDirectionAndAmount == nsIEditor::eNone ||
+           aDirectionAndAmount == nsIEditor::eNext ||
+           aDirectionAndAmount == nsIEditor::ePrevious ||
+           aDirectionAndAmount == nsIEditor::eNextWord ||
+           aDirectionAndAmount == nsIEditor::ePreviousWord ||
+           aDirectionAndAmount == nsIEditor::eToBeginningOfLine ||
+           aDirectionAndAmount == nsIEditor::eToEndOfLine;
+  }
+  static bool EDirectionIsValidExceptNone(EDirection aDirectionAndAmount) {
+    return aDirectionAndAmount != nsIEditor::eNone &&
+           EDirectionIsValid(aDirectionAndAmount);
+  }
+
+  /**
+   * Return true if nsIEditor::EDirection value means the direction of pressing
+   * `Backspace` key.
+   */
+  [[nodiscard]] static bool DirectionIsBackspace(
+    EDirection aDirectionAndAmount) {
+    MOZ_ASSERT(EDirectionIsValid(aDirectionAndAmount));
+    return aDirectionAndAmount == nsIEditor::ePrevious ||
+           aDirectionAndAmount == nsIEditor::ePreviousWord ||
+           aDirectionAndAmount == nsIEditor::eToBeginningOfLine;
+  }
+
+  /**
+   * Return true if nsIEditor::EDirection value means the direction of pressing
+   * `Delete` key (forwardDelete).
+   */
+  [[nodiscard]] static bool DirectionIsDelete(
+    EDirection aDirectionAndAmount) {
+    MOZ_ASSERT(EDirectionIsValid(aDirectionAndAmount));
+    return aDirectionAndAmount == nsIEditor::eNext ||
+           aDirectionAndAmount == nsIEditor::eNextWord ||
+           aDirectionAndAmount == nsIEditor::eToEndOfLine;
+  }
+%}
+
+  const short eStrip = 0;
+  const short eNoStrip = 1;
+
+  // If you want an HTML editor to behave as a plaintext editor, specify this
+  // flag.  Note that this is always set if the instance is a text editor.
+  const long eEditorPlaintextMask       = 0x0001;
+  // We don't support single line editor mode with HTML editors.  Therefore,
+  // don't specify this for HTML editor.
+  const long eEditorSingleLineMask      = 0x0002;
+  // We don't support password editor mode with HTML editors.  Therefore,
+  // don't specify this for HTML editor.
+  const long eEditorPasswordMask        = 0x0004;
+  // When the editor should be in readonly mode (currently, same as "disabled"),
+  // you can specify this flag with any editor instances.
+  // NOTE: Setting this flag does not change the style of editor.  This just
+  // changes the internal editor's readonly state.
+  // NOTE: The readonly mode does NOT block XPCOM APIs which modify the editor
+  // content.  This just blocks edit operations from user input and editing
+  // commands (both HTML Document.execCommand and the XUL commands).
+  // FIXME: XPCOM methods of TextEditor may be blocked by this flag.  If you
+  // find it, file a bug.
+  const long eEditorReadonlyMask        = 0x0008;
+  // If you want an HTML editor to work as an email composer, specify this flag.
+  // And you can specify this to text editor too for making spellchecker for
+  // the text editor should work exactly same as email composer's.
+  const long eEditorMailMask            = 0x0020;
+  // allow the editor to set font: monospace on the root node
+  const long eEditorEnableWrapHackMask  = 0x0040;
+  // If you want to move focus from an HTML editor with tab navigation,
+  // specify this flag.  This is not available with text editors becase
+  // it's always tabbable.
+  // Note that if this is not specified, link navigation is also enabled in
+  // the editable content.
+  const long eEditorAllowInteraction    = 0x0200;
+  // when this flag is set, the internal direction of the editor is RTL.
+  // if neither of the direction flags are set, the direction is determined
+  // from the text control's content node.
+  const long eEditorRightToLeft         = 0x0800;
+  // when this flag is set, the internal direction of the editor is LTR.
+  const long eEditorLeftToRight         = 0x1000;
+  // when this flag is set, the editor's text content is not spell checked.
+  const long eEditorSkipSpellCheck      = 0x2000;
+
+  /*
+   * The valid values for newlines handling.
+   * Can't change the values unless we remove
+   * use of the pref.
+   */
+  const long eNewlinesPasteIntact                = 0;
+  const long eNewlinesPasteToFirst               = 1;
+  const long eNewlinesReplaceWithSpaces          = 2;
+  const long eNewlinesStrip                      = 3;
+  const long eNewlinesReplaceWithCommas          = 4;
+  const long eNewlinesStripSurroundingWhitespace = 5;
+
+  readonly attribute Selection selection;
+
+  [can_run_script]
+  void setAttributeOrEquivalent(in Element element,
+                                in AString sourceAttrName,
+                                in AString sourceAttrValue,
+                                in boolean aSuppressTransaction);
+  [can_run_script]
+  void removeAttributeOrEquivalent(in Element element,
+                                   in AString sourceAttrName,
+                                   in boolean aSuppressTransaction);
+
+  /** edit flags for this editor.  May be set at any time. */
+  [setter_can_run_script] attribute unsigned long flags;
+
+  /**
+   * the MimeType of the document
+   */
+  attribute AString contentsMIMEType;
+
+  /** Returns true if we have a document that is not marked read-only */
+  readonly attribute boolean isDocumentEditable;
+
+  /** Returns true if the current selection anchor is editable */
+  readonly attribute boolean isSelectionEditable;
+
+  /**
+   * the DOM Document this editor is associated with, refcounted.
+   */
+  readonly attribute Document document;
+
+  /** the body element, i.e. the root of the editable document.
+   */
+  readonly attribute Element rootElement;
+
+  /**
+   * the selection controller for the current presentation, refcounted.
+   */
+  readonly attribute nsISelectionController selectionController;
+
+
+  /* ------------ Selected content removal -------------- */
+
+  /**
+   * DeleteSelection removes all nodes in the current selection.
+   * @param aDir  if eNext, delete to the right (for example, the DEL key)
+   *              if ePrevious, delete to the left (for example, the BACKSPACE key)
+   * @param stripWrappers If eStrip, strip any empty inline elements left
+   *                      behind after the deletion; if eNoStrip, don't.  If in
+   *                      doubt, pass eStrip -- eNoStrip is only for if you're
+   *                      about to insert text or similar right after.
+   */
+  [can_run_script]
+  void deleteSelection(in short action, in short stripWrappers);
+
+
+  /* ------------ Document info and file methods -------------- */
+
+  /** Returns true if the document has no *meaningful* content */
+  readonly attribute boolean documentIsEmpty;
+
+  /** Returns true if the document is modifed and needs saving */
+  readonly attribute boolean documentModified;
+
+  /**
+   * Sets document's character set.  This is available only when the editor
+   * instance is an HTMLEditor since it's odd to change character set of
+   * parent document of `<input>` and `<textarea>`.
+   */
+  [setter_can_run_script]
+  attribute ACString documentCharacterSet;
+
+  /** to be used ONLY when we need to override the doc's modification
+    * state (such as when it's saved).
+    */
+  [can_run_script]
+  void resetModificationCount();
+
+  /** Gets the modification count of the document we are editing.
+    * @return the modification count of the document being edited.
+    *         Zero means unchanged.
+    */
+  long getModificationCount();
+
+  /** called each time we modify the document.
+    * Increments the modification count of the document.
+    * @param  aModCount  the number of modifications by which
+    *                    to increase or decrease the count
+    */
+  [can_run_script]
+  void incrementModificationCount(in long aModCount);
+
+  /* ------------ Transaction methods -------------- */
+
+  /** turn the undo system on or off
+    * @param aEnable  if PR_TRUE, the undo system is turned on if available
+    *                 if PR_FALSE the undo system is turned off if it
+    *                 was previously on
+    * @return         if aEnable is PR_TRUE, returns NS_OK if
+    *                 the undo system could be initialized properly
+    *                 if aEnable is PR_FALSE, returns NS_OK.
+    */
+  void enableUndo(in boolean enable);
+
+  /**
+   * Returns true when undo/redo is enabled (by default).
+   */
+  [infallible] readonly attribute boolean undoRedoEnabled;
+
+  /**
+   * Retruns true when undo/redo is enabled and there is one or more transaction
+   * in the undo stack.
+   */
+  [infallible] readonly attribute boolean canUndo;
+
+  /**
+   * Returns true when undo/redo is enabled and there is one or more transaction
+   * in the redo stack.
+   */
+  [infallible] readonly attribute boolean canRedo;
+
+  /**
+   * Clears the transactions both for undo and redo.
+   * This may fail if you call this while editor is handling something, i.e.,
+   * don't call this from a legacy mutation event listeners, then, you won't
+   * see any exceptions.
+   */
+  [binaryname(ClearUndoRedoXPCOM)]
+  void clearUndoRedo();
+
+  /**
+   * Undo the topmost transaction in the undo stack.
+   * This may throw exception when this is called while editor is handling
+   * transactions.
+   */
+  [can_run_script]
+  void undo();
+
+  /**
+   * Undo all transactions in the undo stack.
+   * This may throw exception when this is called while editor is handling
+   * transactions.
+   */
+  [can_run_script]
+  void undoAll();
+
+  /**
+   * Redo the topmost transaction in the redo stack.
+   * This may throw exception when this is called while editor is handling
+   * transactions.
+   */
+  [can_run_script]
+  void redo();
+
+  /** beginTransaction is a signal from the caller to the editor that
+    * the caller will execute multiple updates to the content tree
+    * that should be treated as a single logical operation,
+    * in the most efficient way possible.<br>
+    * All transactions executed between a call to beginTransaction and
+    * endTransaction will be undoable as an atomic action.<br>
+    * endTransaction must be called after beginTransaction.<br>
+    * Calls to beginTransaction can be nested, as long as endTransaction
+    * is called once per beginUpdate.
+    */
+  [can_run_script]
+  void beginTransaction();
+
+  /** endTransaction is a signal to the editor that the caller is
+    * finished updating the content model.<br>
+    * beginUpdate must be called before endTransaction is called.<br>
+    * Calls to beginTransaction can be nested, as long as endTransaction
+    * is called once per beginTransaction.
+    */
+  [can_run_script]
+  void endTransaction();
+
+  /**
+   * While setting the flag with this method to false,  DeleteRangeTransaction,
+   * DeleteTextTransaction, InsertNodeTransaction, InsertTextTransaction and
+   * SplitNodeTransaction won't change Selection after modifying the DOM tree.
+   * Note that calling this with false does not guarantee that Selection won't
+   * be changed because other transaction may ignore this flag, editor itself
+   * may change selection, and current selection may become invalid after
+   * changing the DOM tree, etc.
+   * After calling this method with true, the caller should guarantee that
+   * Selection should be positioned where user expects.
+   *
+   * @param should    false if you don't want above transactions to modify
+   *                  Selection automatically after modifying the DOM tree.
+   *                  Note that calling this with false does not guarantee
+   *                  that Selection is never changed.
+   */
+  void setShouldTxnSetSelection(in boolean should);
+
+  /* ------------ Inline Spell Checking methods -------------- */
+
+  /** Returns the inline spell checker associated with this object. The spell
+    * checker is lazily created, so this function may create the object for
+    * you during this call.
+    * @param  autoCreate  If true, this will create a spell checker object
+    *                     if one does not exist yet for this editor. If false
+    *                     and the object has not been created, this function
+    *                     WILL RETURN NULL.
+    */
+  nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate);
+
+  /** Called when the user manually overrides the spellchecking state for this
+    * editor.
+    * @param  enable  The new state of spellchecking in this editor, as
+    *                 requested by the user.
+    */
+  void setSpellcheckUserOverride(in boolean enable);
+
+  /* ------------ Clipboard methods -------------- */
+
+  /** cut the currently selected text, putting it into the OS clipboard
+    * What if no text is selected?
+    * What about mixed selections?
+    * What are the clipboard formats?
+    */
+  [can_run_script]
+  void cut();
+
+  /**
+   * canCut() returns true if selected content is allowed to be copied to the
+   * clipboard and to be removed.
+   * Note that this always returns true if the editor is in a non-chrome
+   * HTML/XHTML document.
+   * FYI: Current user in script is only BlueGriffon.
+   */
+  [can_run_script]
+  boolean canCut();
+
+  /** copy the currently selected text, putting it into the OS clipboard
+    * What if no text is selected?
+    * What about mixed selections?
+    * What are the clipboard formats?
+    */
+  [can_run_script]
+  void copy();
+
+  /**
+   * canCopy() returns true if selected content is allowed to be copied to
+   * the clipboard.
+   * Note that this always returns true if the editor is in a non-chrome
+   * HTML/XHTML document.
+   * FYI: Current user in script is only BlueGriffon.
+   */
+  [can_run_script]
+  boolean canCopy();
+
+  /** paste the text in the OS clipboard at the cursor position, replacing
+    * the selected text (if any)
+    */
+  [can_run_script]
+  void paste(in long aClipboardType);
+
+  /** Paste the text in |aTransferable| at the cursor position, replacing the
+    * selected text (if any).
+    */
+  [can_run_script]
+  void pasteTransferable(in nsITransferable aTransferable);
+
+  /** Can we paste? True if the doc is modifiable, and we have
+    * pasteable data in the clipboard.
+    */
+  boolean canPaste(in long aClipboardType);
+
+  /* ------------ Selection methods -------------- */
+
+  /** sets the document selection to the entire contents of the document */
+  [can_run_script]
+  void selectAll();
+
+  /**
+   * Collapses selection at start of the document.  If it's an HTML editor,
+   * collapses selection at start of current editing host (<body> element if
+   * it's in designMode) instead.  If there is a non-editable node before any
+   * editable text nodes or inline elements which can have text nodes as their
+   * children, collapses selection at start of the editing host.  If there is
+   * an editable text node which is not collapsed, collapses selection at
+   * start of the text node.  If there is an editable inline element which
+   * cannot have text nodes as its child, collapses selection at before the
+   * element node.  Otherwise, collapses selection at start of the editing
+   * host.
+   */
+  [can_run_script]
+  void beginningOfDocument();
+
+  /**
+   * Sets the selection to the end of the last leaf child/descendant or the root
+   * element.
+   */
+  [can_run_script]
+  void endOfDocument();
+
+  /* ------------ Node manipulation methods -------------- */
+
+  /**
+   * setAttribute() sets the attribute of aElement.
+   * No checking is done to see if aAttribute is a legal attribute of the node,
+   * or if aValue is a legal value of aAttribute.
+   *
+   * @param aElement    the content element to operate on
+   * @param aAttribute  the string representation of the attribute to set
+   * @param aValue      the value to set aAttribute to
+   */
+  [can_run_script]
+  void setAttribute(in Element aElement, in AString attributestr,
+                    in AString attvalue);
+
+  /**
+   * removeAttribute() deletes aAttribute from the attribute list of aElement.
+   * If aAttribute is not an attribute of aElement, nothing is done.
+   *
+   * @param aElement      the content element to operate on
+   * @param aAttribute    the string representation of the attribute to get
+   */
+  [can_run_script]
+  void removeAttribute(in Element aElement,
+                       in AString aAttribute);
+
+  /**
+   * cloneAttributes() is similar to Node::cloneNode(),
+   *   it assures the attribute nodes of the destination are identical
+   *   with the source node by copying all existing attributes from the
+   *   source and deleting those not in the source.
+   *   This is used when the destination element already exists
+   *
+   * @param aDestNode     the destination element to operate on
+   * @param aSourceNode   the source element to copy attributes from
+   */
+  [can_run_script]
+  void cloneAttributes(in Element aDestElement, in Element aSourceElement);
+
+  /**
+   * insertNode inserts aNode into aParent at aPosition.
+   * No checking is done to verify the legality of the insertion.
+   * That is the responsibility of the caller.
+   * @param aNode     The DOM Node to insert.
+   * @param aParent   The node to insert the new object into
+   * @param aPosition The place in aParent to insert the new node
+   *                  0=first child, 1=second child, etc.
+   *                  any number > number of current children = last child
+   */
+  [can_run_script]
+  void insertNode(in Node node,
+                  in Node parent,
+                  in unsigned long aPosition);
+
+
+  /**
+   * deleteNode removes aChild from aParent.
+   * @param aChild    The node to delete
+   */
+  [can_run_script]
+  void deleteNode(in Node child);
+
+/* ------------ Output methods -------------- */
+
+  /**
+   * Output methods:
+   * aFormatType is a mime type, like text/plain.
+   */
+  AString outputToString(in AString formatType,
+                         in unsigned long flags);
+
+  /* ------------ Various listeners methods --------------
+   * nsIEditor holds strong references to the editor observers, action listeners
+   * and document state listeners.
+   */
+
+  /** add an EditActionListener to the editors list of listeners. */
+  void addEditActionListener(in nsIEditActionListener listener);
+
+  /** Remove an EditActionListener from the editor's list of listeners. */
+  void removeEditActionListener(in nsIEditActionListener listener);
+
+  /** Add a DocumentStateListener to the editors list of doc state listeners. */
+  void addDocumentStateListener(in nsIDocumentStateListener listener);
+
+  /** Remove a DocumentStateListener to the editors list of doc state listeners. */
+  void removeDocumentStateListener(in nsIDocumentStateListener listener);
+
+  /**
+   * forceCompositionEnd() force the composition end
+   */
+  void forceCompositionEnd();
+
+  /**
+   * whether this editor has active IME transaction
+   */
+  readonly attribute boolean composing;
+
+  /**
+   * unmask() is available only when the editor is a passwrod field.  This
+   * unmasks characters in specified by aStart and aEnd.  If there have
+   * already unmasked characters, they are masked when this is called.
+   * Note that if you calls this without non-zero `aTimeout`, you bear
+   * responsibility for masking password with calling `mask()`.  I.e.,
+   * user inputting password won't be masked automacitally.  If user types
+   * a new character and echo is enabled, unmasked range is expanded to
+   * including it.
+   *
+   * @param aStart      Optional, first index to show the character.  If you
+   *                    specify middle of a surrogate pair, this expands the
+   *                    range to include the prceding high surrogate
+   *                    automatically.
+   *                    If omitted, it means that all characters of the
+   *                    password becomes unmasked.
+   * @param aEnd        Optional, next index of last unmasked character.  If
+   *                    you specify middle of a surrogate pair, the expands
+   *                    the range to include the following low surrogate.
+   *                    If omitted or negative value, it means unmasking all
+   *                    characters after aStart.  Specifying same index
+   *                    throws an exception.
+   * @param aTimeout    Optional, specify milliseconds to hide the unmasked
+   *                    characters if you want to show them temporarily.
+   *                    If omitted or 0, it means this won't mask the characters
+   *                    automatically.
+   */
+  [can_run_script, optional_argc] void unmask(
+      [optional] in unsigned long aStart,
+      [optional] in long long aEnd,
+      [optional] in unsigned long aTimeout);
+
+  /**
+   * mask() is available only when the editor is a password field.  This masks
+   * all unmasked characters immediately.
+   */
+  [can_run_script] void mask();
+
+  /**
+   * These attributes are available only when the editor is a password field.
+   * unmaskedStart is first unmasked character index, or 0 if there is no
+   * unmasked characters.
+   * unmaskedEnd is next index of the last unmasked character.  0 means there
+   * is no unmasked characters.
+   */
+  readonly attribute unsigned long unmaskedStart;
+  readonly attribute unsigned long unmaskedEnd;
+
+  /**
+   * autoMaskingEnabled is true if unmasked range and newly inputted characters
+   * are masked automatically.  That's the default state.  If false, until
+   * `mask()` is called, unmasked range and newly inputted characters are
+   * unmasked.
+   */
+  readonly attribute boolean autoMaskingEnabled;
+
+  /**
+   * passwordMask attribute is a mask character which is used to mask password.
+   */
+  readonly attribute AString passwordMask;
+
+  /**
+    * The length of the contents in characters.
+    */
+  readonly attribute unsigned long textLength;
+
+  /** Get and set the body wrap width.
+    *
+    * Special values:
+    *    0 = wrap to window width
+    *   -1 = no wrap at all
+    */
+  attribute long wrapWidth;
+
+  /** Get and set newline handling.
+   *
+   *  Values are the constants defined above.
+   */
+  attribute long newlineHandling;
+
+  /**
+   * Inserts a string at the current location,
+   * given by the selection.
+   * If the selection is not collapsed, the selection is deleted
+   * and the insertion takes place at the resulting collapsed selection.
+   *
+   * @param aString   the string to be inserted
+   */
+   [can_run_script]
+   void insertText(in AString aStringToInsert);
+
+  /**
+   * Insert a line break into the content model.
+   * The interpretation of a break is up to the implementation:
+   * it may enter a character, split a node in the tree, etc.
+   * This may be more efficient than calling InsertText with a newline.
+   */
+  [can_run_script]
+  void insertLineBreak();
+
+%{C++
+  inline bool IsHTMLEditor() const;
+  inline bool IsTextEditor() const;
+
+  /**
+   * AsEditorBase() returns a pointer to EditorBase class.
+   *
+   * In order to avoid circular dependency issues, this method is defined
+   * in mozilla/EditorBase.h.  Consumers need to #include that header.
+   */
+  inline mozilla::EditorBase* AsEditorBase();
+  inline const mozilla::EditorBase* AsEditorBase() const;
+
+  /**
+   * AsTextEditor() and GetTextEditor() return a pointer to TextEditor class.
+   * AsTextEditor() does not check the concrete class type.  So, it never
+   * returns nullptr.  GetAsTextEditor() does check the concrete class type.
+   * So, it may return nullptr.
+   *
+   * In order to avoid circular dependency issues, this method is defined
+   * in mozilla/TextEditor.h.  Consumers need to #include that header.
+   */
+  inline mozilla::TextEditor* AsTextEditor();
+  inline const mozilla::TextEditor* AsTextEditor() const;
+  inline mozilla::TextEditor* GetAsTextEditor();
+  inline const mozilla::TextEditor* GetAsTextEditor() const;
+
+  /**
+   * AsHTMLEditor() and GetHTMLEditor() return a pointer to HTMLEditor class.
+   * AsHTMLEditor() does not check the concrete class type.  So, it never
+   * returns nullptr.  GetAsHTMLEditor() does check the concrete class type.
+   * So, it may return nullptr.
+   *
+   * In order to avoid circular dependency issues, this method is defined
+   * in mozilla/HTMLEditor.h.  Consumers need to #include that header.
+   */
+  inline mozilla::HTMLEditor* AsHTMLEditor();
+  inline const mozilla::HTMLEditor* AsHTMLEditor() const;
+  inline mozilla::HTMLEditor* GetAsHTMLEditor();
+  inline const mozilla::HTMLEditor* GetAsHTMLEditor() const;
+%}
+};