Bug 1463327 - part 4: Add comments to explain which kind of methods should be public methods r?m_kato
MozReview-Commit-ID: 6l8ZiMWEYCI
--- a/editor/libeditor/EditorBase.h
+++ b/editor/libeditor/EditorBase.h
@@ -193,16 +193,26 @@ enum class SplitAtEdges
* delegate the actual commands to the editor independent of the XPFE
* implementation.
*/
class EditorBase : public nsIEditor
, public nsISelectionListener
, public nsSupportsWeakReference
{
public:
+ /****************************************************************************
+ * NOTE: DO NOT MAKE YOUR NEW METHODS PUBLIC IF they are called by other
+ * classes under libeditor except EditorEventListener and
+ * HTMLEditorEventListener because each public method which may fire
+ * eEditorInput event will need to instantiate new stack class for
+ * managing input type value of eEditorInput and cache some objects
+ * for smarter handling. In other words, when you add new root
+ * method to edit the DOM tree, you can make your new method public.
+ ****************************************************************************/
+
typedef dom::Element Element;
typedef dom::Selection Selection;
typedef dom::Text Text;
NS_DECL_CYCLE_COLLECTING_ISUPPORTS
NS_DECL_CYCLE_COLLECTION_CLASS_AMBIGUOUS(EditorBase, nsIEditor)
// nsIEditor methods
@@ -655,16 +665,25 @@ public:
/** Resyncs spellchecking state (enabled/disabled). This should be called
* when anything that affects spellchecking state changes, such as the
* spellcheck attribute value.
*/
void SyncRealTimeSpell();
protected: // May be called by friends.
+ /****************************************************************************
+ * Some classes like TextEditRules, HTMLEditRules, WSRunObject which are
+ * part of handling edit actions are allowed to call the following protected
+ * methods. However, those methods won't prepare caches of some objects
+ * which are necessary for them. So, if you want some following methods
+ * to do that for you, you need to create a wrapper method in public scope
+ * and call it.
+ ****************************************************************************/
+
/**
* InsertTextWithTransaction() inserts aStringToInsert to aPointToInsert or
* better insertion point around it. If aPointToInsert isn't in a text node,
* this method looks for the nearest point in a text node with
* FindBetterInsertionPoint(). If there is no text node, this creates
* new text node and put aStringToInsert to it.
*
* @param aDocument The document of this editor.
--- a/editor/libeditor/HTMLEditor.h
+++ b/editor/libeditor/HTMLEditor.h
@@ -69,16 +69,26 @@ class HTMLEditor final : public TextEdit
, public nsIHTMLAbsPosEditor
, public nsITableEditor
, public nsIHTMLInlineTableEditor
, public nsIEditorStyleSheets
, public nsICSSLoaderObserver
, public nsStubMutationObserver
{
public:
+ /****************************************************************************
+ * NOTE: DO NOT MAKE YOUR NEW METHODS PUBLIC IF they are called by other
+ * classes under libeditor except EditorEventListener and
+ * HTMLEditorEventListener because each public method which may fire
+ * eEditorInput event will need to instantiate new stack class for
+ * managing input type value of eEditorInput and cache some objects
+ * for smarter handling. In other words, when you add new root
+ * method to edit the DOM tree, you can make your new method public.
+ ****************************************************************************/
+
NS_DECL_ISUPPORTS_INHERITED
NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(HTMLEditor, TextEditor)
// nsStubMutationObserver overrides
NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED
NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED
NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED
@@ -273,16 +283,25 @@ public:
* @param aUIAnonymousElement [IN] the inline table editing UI element
*/
nsresult DoInlineTableEditingAction(const Element& aUIAnonymousElement);
already_AddRefed<Element>
GetElementOrParentByTagName(const nsAString& aTagName, nsINode* aNode);
protected: // May be called by friends.
+ /****************************************************************************
+ * Some classes like TextEditRules, HTMLEditRules, WSRunObject which are
+ * part of handling edit actions are allowed to call the following protected
+ * methods. However, those methods won't prepare caches of some objects
+ * which are necessary for them. So, if you want some following methods
+ * to do that for you, you need to create a wrapper method in public scope
+ * and call it.
+ ****************************************************************************/
+
/**
* DeleteSelectionWithTransaction() removes selected content or content
* around caret with transactions.
*
* @param aDirection How much range should be removed.
* @param aStripWrappers Whether the parent blocks should be removed
* when they become empty.
*/
--- a/editor/libeditor/TextEditor.h
+++ b/editor/libeditor/TextEditor.h
@@ -34,16 +34,26 @@ class Selection;
* The text editor implementation.
* Use to edit text document represented as a DOM tree.
*/
class TextEditor : public EditorBase
, public nsIPlaintextEditor
, public nsIEditorMailSupport
{
public:
+ /****************************************************************************
+ * NOTE: DO NOT MAKE YOUR NEW METHODS PUBLIC IF they are called by other
+ * classes under libeditor except EditorEventListener and
+ * HTMLEditorEventListener because each public method which may fire
+ * eEditorInput event will need to instantiate new stack class for
+ * managing input type value of eEditorInput and cache some objects
+ * for smarter handling. In other words, when you add new root
+ * method to edit the DOM tree, you can make your new method public.
+ ****************************************************************************/
+
NS_DECL_ISUPPORTS_INHERITED
NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(TextEditor, EditorBase)
TextEditor();
// nsIPlaintextEditor methods
NS_DECL_NSIPLAINTEXTEDITOR
@@ -158,16 +168,25 @@ public:
/**
* OnCompositionEnd() is called when editor receives an eCompositionChange
* event and it's followed by eCompositionEnd event and after
* OnCompositionChange() is called.
*/
void OnCompositionEnd(WidgetCompositionEvent& aCompositionEndEvent);
protected: // May be called by friends.
+ /****************************************************************************
+ * Some classes like TextEditRules, HTMLEditRules, WSRunObject which are
+ * part of handling edit actions are allowed to call the following protected
+ * methods. However, those methods won't prepare caches of some objects
+ * which are necessary for them. So, if you want some following methods
+ * to do that for you, you need to create a wrapper method in public scope
+ * and call it.
+ ****************************************************************************/
+
// Overrides of EditorBase
virtual nsresult RemoveAttributeOrEquivalent(
Element* aElement,
nsAtom* aAttribute,
bool aSuppressTransaction) override;
virtual nsresult SetAttributeOrEquivalent(Element* aElement,
nsAtom* aAttribute,
const nsAString& aValue,