gecko-dev/editor/nsIEditor.idl
Masayuki Nakano 5f6299d456 Bug 1764895 - part 3: Get rid of nsIEditor.setShouldTxnSetSelection r=m_kato DONTBUILD
It allows multiple edit action preserves `Selection` when updating the DOM tree.
However, most callers do not use `finally` to reset the state, and this makes
edit action handling complicated in some edge cases.  Therefore, let's stop
supporting this feature.  If Thunderbird requires the feature, the developers
should request additional param for preserving `Selection` like the preceding
patch.

Depends on D196004

Differential Revision: https://phabricator.services.mozilla.com/D196005
2023-12-14 00:41:20 +00:00

676 lines
25 KiB
Plaintext

/* -*- 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. This is currently used only with plaintext email composer.
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();
/* ------------ 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 and this operation is
* undoable.
* No checking is done to verify the legality of the insertion.
* That is the responsibility of the caller.
* TODO: Move this method to nsIHTMLEditor, TextEditor does not allow chrome
* script to customize its anonymous subtree.
*
* @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.
* If larger than number of children of aParent,
* this will append aNode into aParent.
* @param aPreseveSelection The default value is false. If set to true,
* the insert node handler does not update
* Selection.
* FYI: If somebody handles `beforeinput` event or
* `input` event caused by this and it does
* something undoable, selection may be changed by
* that.
*/
[optional_argc, can_run_script]
void insertNode(in Node node,
in Node parent,
in unsigned long aPosition,
[optional] in boolean aPreserveSelection);
/**
* deleteNode removes aChild from aParent and this operation is undobable.
* TODO: Move this method to nsIHTMLEditor, TextEditor does not allow chrome
* script to customize its anonymous subtree.
*
* @param aChild The node to delete
* @param aPreseveSelection The default value is false. If set to true,
* the insert node handler does not update
* Selection.
* FYI: If somebody handles `beforeinput` event or
* `input` event caused by this and it does
* something undoable, selection may be changed by
* that.
*/
[optional_argc, can_run_script]
void deleteNode(in Node child, [optional] in boolean aPreserveSelection);
/* ------------ 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 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;
%}
};