/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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/. */
#ifndef mozilla_TextComposition_h
#define mozilla_TextComposition_h
#include "nsCOMPtr.h"
#include "nsINode.h"
#include "nsIWidget.h"
#include "nsTArray.h"
#include "nsThreadUtils.h"
#include "nsPresContext.h"
#include "mozilla/AlreadyAddRefed.h"
#include "mozilla/Assertions.h"
#include "mozilla/Attributes.h"
#include "mozilla/EventForwards.h"
#include "mozilla/RangeBoundary.h"
#include "mozilla/TextRange.h"
#include "mozilla/dom/BrowserParent.h"
#include "mozilla/dom/Text.h"
class nsRange;
struct CharacterDataChangeInfo;
namespace mozilla {
class EditorBase;
class EventDispatchingCallback;
class IMEStateManager;
/**
* TextComposition represents a text composition. This class stores the
* composition event target and its presContext. At dispatching the event via
* this class, the instances use the stored event target.
*/
class TextComposition final {
friend class IMEStateManager;
NS_INLINE_DECL_REFCOUNTING(TextComposition)
public:
typedef dom::BrowserParent BrowserParent;
typedef dom::Text Text;
static bool IsHandlingSelectionEvent() {
return sHandlingSelectionEvent; }
TextComposition(nsPresContext* aPresContext, nsINode* aNode,
BrowserParent* aBrowserParent,
WidgetCompositionEvent* aCompositionEvent);
TextComposition() =
delete;
TextComposition(
const TextComposition& aOther) =
delete;
bool Destroyed()
const {
return !mPresContext; }
nsPresContext* GetPresContext()
const {
return mPresContext; }
nsINode* GetEventTargetNode()
const {
return mNode; }
// The text node which includes composition string.
Text* GetContainerTextNode()
const {
return mContainerTextNode; }
// The latest CompositionEvent.data value except compositionstart event.
// This value is modified at dispatching compositionupdate.
const nsString& LastData()
const {
return mLastData; }
// Returns commit string if it'll be commited as-is.
nsString CommitStringIfCommittedAsIs()
const;
// The composition string which is already handled by the focused editor.
// I.e., this value must be same as the composition string on the focused
// editor. This value is modified at a call of
// EditorDidHandleCompositionChangeEvent().
// Note that mString and mLastData are different between dispatcing
// compositionupdate and compositionchange event handled by focused editor.
const nsString& String()
const {
return mString; }
// The latest clauses range of the composition string.
// During compositionupdate event, GetRanges() returns old ranges.
// So if getting on compositionupdate, Use GetLastRange instead of GetRange().
TextRangeArray* GetLastRanges()
const {
return mLastRanges; }
// Returns the clauses and/or caret range of the composition string.
// This is modified at a call of EditorWillHandleCompositionChangeEvent().
// This may return null if there is no clauses and caret.
// XXX We should return |const TextRangeArray*| here, but it causes compile
// error due to inaccessible Release() method.
TextRangeArray* GetRanges()
const {
return mRanges; }
// Returns the widget which is proper to call NotifyIME().
already_AddRefed<nsIWidget> GetWidget()
const {
if (!mPresContext) {
return nullptr;
}
return do_AddRef(mPresContext->GetRootWidget());
}
// Returns the tab parent which has this composition in its remote process.
BrowserParent* GetBrowserParent()
const {
return mBrowserParent; }
// Returns true if the composition is started with synthesized event which
// came from nsDOMWindowUtils.
bool IsSynthesizedForTests()
const {
return mIsSynthesizedForTests; }
// Returns the composition ID. It must be 0 if the composition is synthesized
// in a content process. Otherwise, returns 1 or larger value.
uint32_t Id()
const {
return mCompositionId; }
const widget::NativeIMEContext& GetNativeIMEContext()
const {
return mNativeContext;
}
/**
* This is called when IMEStateManager stops managing the instance.
*/
void Destroy();
/**
* Request to commit (or cancel) the composition to IME. This method should
* be called only by IMEStateManager::NotifyIME().
*/
nsresult RequestToCommit(nsIWidget* aWidget,
bool aDiscard);
/**
* IsRequestingCommitOrCancelComposition() returns true if the instance is
* requesting widget to commit or cancel composition.
*/
bool IsRequestingCommitOrCancelComposition()
const {
return mIsRequestingCancel || mIsRequestingCommit;
}
/**
* Send a notification to IME. It depends on the IME or platform spec what
* will occur (or not occur).
*/
nsresult NotifyIME(widget::IMEMessage aMessage);
/**
* the offset of first composition string
*/
uint32_t NativeOffsetOfStartComposition()
const {
return mCompositionStartOffset;
}
/**
* the offset of first selected clause or start of composition
*/
uint32_t NativeOffsetOfTargetClause()
const {
return mCompositionStartOffset + mTargetClauseOffsetInComposition;
}
/**
* Return current composition start and end point in the DOM tree.
* Note that one of or both of those result container may be different
* from GetContainerTextNode() if the DOM tree was modified by the web
* app. If there is no composition string the DOM tree, these return
* unset range boundaries.
*/
RawRangeBoundary FirstIMESelectionStartRef()
const;
RawRangeBoundary LastIMESelectionEndRef()
const;
/**
* The offset of composition string in the text node. If composition string
* hasn't been inserted in any text node yet, this returns UINT32_MAX.
*/
uint32_t XPOffsetInTextNode()
const {
return mCompositionStartOffsetInTextNode;
}
/**
* The length of composition string in the text node. If composition string
* hasn't been inserted in any text node yet, this returns 0.
*/
uint32_t XPLengthInTextNode()
const {
return mCompositionLengthInTextNode == UINT32_MAX
? 0
: mCompositionLengthInTextNode;
}
/**
* The end offset of composition string in the text node. If composition
* string hasn't been inserted in any text node yet, this returns UINT32_MAX.
*/
uint32_t XPEndOffsetInTextNode()
const {
if (mCompositionStartOffsetInTextNode == UINT32_MAX ||
mCompositionLengthInTextNode == UINT32_MAX) {
return UINT32_MAX;
}
return mCompositionStartOffsetInTextNode + mCompositionLengthInTextNode;
}
/**
* Returns true if there is non-empty composition string and it's not fixed.
* Otherwise, false.
*/
bool IsComposing()
const {
return mIsComposing; }
/**
* If we're requesting IME to commit or cancel composition, or we've already
* requested it, or we've already known this composition has been ended in
* IME, we don't need to request commit nor cancel composition anymore and
* shouldn't do so if we're in content process for not committing/canceling
* "current" composition in native IME. So, when this returns true,
* RequestIMEToCommit() does nothing.
*/
[[nodiscard]]
bool CanRequsetIMEToCommitOrCancelComposition()
const {
return !mIsRequestingCommit && !mIsRequestingCancel &&
!mRequestedToCommitOrCancel && !mHasReceivedCommitEvent;
}
/**
* Returns true if editor has started or already ended handling an event which
* is modifying the composition string and/or IME selections.
*/
[[nodiscard]]
bool EditorHasHandledLatestChange()
const {
return EditorIsHandlingLatestChange() ||
(mLastRanges == mRanges && mLastData == mString);
}
/**
* Returns true while editor is handling an event which is modifying the
* composition string and/or IME selections.
*/
[[nodiscard]]
bool EditorIsHandlingLatestChange()
const {
return mEditorIsHandlingEvent;
}
/**
* IsMovingToNewTextNode() returns true if editor detects the text node
* has been removed and still not insert the composition string into
* new text node.
*/
bool IsMovingToNewTextNode()
const {
return !mContainerTextNode && mCompositionLengthInTextNode &&
mCompositionLengthInTextNode != UINT32_MAX;
}
/**
* StartHandlingComposition() and EndHandlingComposition() are called by
* editor when it holds a TextComposition instance and release it.
*/
void StartHandlingComposition(EditorBase* aEditorBase);
void EndHandlingComposition(EditorBase* aEditorBase);
/**
* OnEditorDestroyed() is called when the editor is destroyed but there is
* active composition.
*/
void OnEditorDestroyed();
/**
* CompositionChangeEventHandlingMarker class should be created at starting
* to handle text event in focused editor. This calls
* EditorWillHandleCompositionChangeEvent() and
* EditorDidHandleCompositionChangeEvent() automatically.
*/
class MOZ_STACK_CLASS CompositionChangeEventHandlingMarker {
public:
CompositionChangeEventHandlingMarker(
TextComposition* aComposition,
const WidgetCompositionEvent* aCompositionChangeEvent)
: mComposition(aComposition) {
mComposition->EditorWillHandleCompositionChangeEvent(
aCompositionChangeEvent);
}
~CompositionChangeEventHandlingMarker() {
mComposition->EditorDidHandleCompositionChangeEvent();
}
private:
RefPtr<TextComposition> mComposition;
CompositionChangeEventHandlingMarker();
CompositionChangeEventHandlingMarker(
const CompositionChangeEventHandlingMarker& aOther);
};
/**
* OnUpdateCompositionInEditor() is called when editor updates composition
* string in the DOM tree.
*
* @param aStringToInsert The string to insert the text node actually.
* This may be different from the data of
* dispatching composition event because it may
* be replaced with different character for
* passwords, or truncated due to maxlength.
* @param aTextNode The text node which includes composition string.
* @param aOffset The offset of composition string in aTextNode.
*/
void OnUpdateCompositionInEditor(
const nsAString& aStringToInsert,
Text& aTextNode, uint32_t aOffset) {
mContainerTextNode = &aTextNode;
mCompositionStartOffsetInTextNode = aOffset;
NS_WARNING_ASSERTION(mCompositionStartOffsetInTextNode != UINT32_MAX,
"The text node is really too long.");
mCompositionLengthInTextNode = aStringToInsert.Length();
NS_WARNING_ASSERTION(mCompositionLengthInTextNode != UINT32_MAX,
"The string to insert is really too long.");
}
/**
* OnTextNodeRemoved() is called when focused editor is reframed and
* mContainerTextNode may be (or have been) replaced with different text
* node, or just removes the text node due to empty.
*/
void OnTextNodeRemoved() {
mContainerTextNode = nullptr;
// Don't reset mCompositionStartOffsetInTextNode nor
// mCompositionLengthInTextNode because editor needs them to restore
// composition in new text node.
}
/**
* OnCharacterDataChanged() is called when IMEContentObserver receives
* character data change notifications.
*/
void OnCharacterDataChanged(Text& aText,
const CharacterDataChangeInfo& aInfo);
private:
// Private destructor, to discourage deletion outside of Release():
~TextComposition() {
// WARNING: mPresContext may be destroying, so, be careful if you touch it.
}
// sHandlingSelectionEvent is true while TextComposition sends a selection
// event to ContentEventHandler.
static bool sHandlingSelectionEvent;
// This class holds nsPresContext weak. This instance shouldn't block
// destroying it. When the presContext is being destroyed, it's notified to
// IMEStateManager::OnDestroyPresContext(), and then, it destroy
// this instance.
nsPresContext* mPresContext;
RefPtr<nsINode> mNode;
RefPtr<BrowserParent> mBrowserParent;
// The text node which includes the composition string.
RefPtr<Text> mContainerTextNode;
// This is the clause and caret range information which is managed by
// the focused editor. This may be null if there is no clauses or caret.
RefPtr<TextRangeArray> mRanges;
// Same as mRange, but mRange will have old ranges before editor starts
// handling the latest eCompositionChange. Therefore, this stores the latest
// ranges which is introduced by the latest eCompositionChange. So this may
// be useful during dispatching eCompositionUpdate or eCompositionChange.
RefPtr<TextRangeArray> mLastRanges;
// mNativeContext stores a opaque pointer. This works as the "ID" for this
// composition. Don't access the instance, it may not be available.
widget::NativeIMEContext mNativeContext;
// mEditorBaseWeak is a weak reference to the focused editor handling
// composition.
nsWeakPtr mEditorBaseWeak;
// mLastData stores the data attribute of the latest composition event (except
// the compositionstart event).
nsString mLastData;
// mString stores the composition text which has been handled by the focused
// editor.
nsString mString;
// Composition ID of this composition. If this is in a parent process,
// this is 1 or larger. If the composition is created for managing a
// composition synthesized in a content process, this is 0.
const uint32_t mCompositionId = 0;
// Offset of the composition string from start of the editor
uint32_t mCompositionStartOffset;
// Offset of the selected clause of the composition string from
// mCompositionStartOffset
uint32_t mTargetClauseOffsetInComposition;
// Offset of the composition string in mContainerTextNode.
// NOTE: This is NOT valid in the main process if focused editor is in a
// remote process.
uint32_t mCompositionStartOffsetInTextNode;
// Length of the composition string in mContainerTextNode. If this instance
// has already dispatched eCompositionCommit(AsIs) and
// EditorDidHandleCompositionChangeEvent() has already been called,
// this may be different from length of mString because committed string
// may be truncated by maxlength attribute of <input> or <textarea>.
// NOTE: This is NOT valid in the main process if focused editor is in a
// remote process.
uint32_t mCompositionLengthInTextNode;
// See the comment for IsSynthesizedForTests().
bool mIsSynthesizedForTests;
// See the comment for IsComposing().
bool mIsComposing;
// mEditorIsHandlingEvent is true while editor is modifying the composition
// string.
bool mEditorIsHandlingEvent =
false;
// mIsRequestingCommit or mIsRequestingCancel is true *only* while we're
// requesting commit or canceling the composition. In other words, while
// one of these values is true, we're handling the request.
bool mIsRequestingCommit;
bool mIsRequestingCancel;
// mRequestedToCommitOrCancel is true *after* we requested IME to commit or
// cancel the composition. In other words, we already requested of IME that
// it commits or cancels current composition.
// NOTE: Before this is set to true, both mIsRequestingCommit and
// mIsRequestingCancel are set to false.
bool mRequestedToCommitOrCancel;
// Set to true if the instance dispatches an eCompositionChange event.
bool mHasDispatchedDOMTextEvent;
// Before this dispatches commit event into the tree, this is set to true.
// So, this means if native IME already commits the composition.
bool mHasReceivedCommitEvent;
// mWasNativeCompositionEndEventDiscarded is true if this composition was
// requested commit or cancel itself but native compositionend event is
// discarded by PresShell due to not safe to dispatch events.
bool mWasNativeCompositionEndEventDiscarded;
// Allow control characters appear in composition string.
// When this is false, control characters except
// CHARACTER TABULATION (horizontal tab) are removed from
// both composition string and data attribute of compositionupdate
// and compositionend events.
bool mAllowControlCharacters;
// mWasCompositionStringEmpty is true if the composition string was empty
// when DispatchCompositionEvent() is called.
bool mWasCompositionStringEmpty;
/**
* GetEditorBase() returns EditorBase pointer of mEditorBaseWeak.
*/
already_AddRefed<EditorBase> GetEditorBase()
const;
/**
* HasEditor() returns true if mEditorBaseWeak holds EditorBase instance
* which is alive. Otherwise, false.
*/
bool HasEditor()
const;
/**
* EditorWillHandleCompositionChangeEvent() must be called before the focused
* editor handles the compositionchange event.
*/
void EditorWillHandleCompositionChangeEvent(
const WidgetCompositionEvent* aCompositionChangeEvent);
/**
* EditorDidHandleCompositionChangeEvent() must be called after the focused
* editor handles a compositionchange event.
*/
void EditorDidHandleCompositionChangeEvent();
/**
* IsValidStateForComposition() returns true if it's safe to dispatch an event
* to the DOM tree. Otherwise, false.
* WARNING: This doesn't check script blocker state. It should be checked
* before dispatching the first event.
*/
bool IsValidStateForComposition(nsIWidget* aWidget)
const;
/**
* DispatchCompositionEvent() dispatches the aCompositionEvent to the mContent
* synchronously. The caller must ensure that it's safe to dispatch the event.
*/
MOZ_CAN_RUN_SCRIPT
void DispatchCompositionEvent(
WidgetCompositionEvent* aCompositionEvent, nsEventStatus* aStatus,
EventDispatchingCallback* aCallBack,
bool aIsSynthesized);
/**
* Simply calling EventDispatcher::Dispatch() with plugin event.
* If dispatching event has no orginal clone, aOriginalEvent can be null.
*/
MOZ_CAN_RUN_SCRIPT
void DispatchEvent(
WidgetCompositionEvent* aDispatchEvent, nsEventStatus* aStatus,
EventDispatchingCallback* aCallback,
const WidgetCompositionEvent* aOriginalEvent = nullptr);
/**
* HandleSelectionEvent() sends the selection event to ContentEventHandler
* or dispatches it to the focused child process.
*/
MOZ_CAN_RUN_SCRIPT
void HandleSelectionEvent(WidgetSelectionEvent* aSelectionEvent) {
RefPtr<nsPresContext> presContext(mPresContext);
RefPtr<BrowserParent> browserParent(mBrowserParent);
HandleSelectionEvent(presContext, browserParent, aSelectionEvent);
}
MOZ_CAN_RUN_SCRIPT
static void HandleSelectionEvent(nsPresContext* aPresContext,
BrowserParent* aBrowserParent,
WidgetSelectionEvent* aSelectionEvent);
/**
* MaybeDispatchCompositionUpdate() may dispatch a compositionupdate event
* if aCompositionEvent changes composition string.
* @return Returns false if dispatching the compositionupdate event caused
* destroying this composition.
*/
MOZ_CAN_RUN_SCRIPT
bool MaybeDispatchCompositionUpdate(
const WidgetCompositionEvent* aCompositionEvent);
/**
* CloneAndDispatchAs() dispatches a composition event which is
* duplicateed from aCompositionEvent and set the aMessage.
*
* @return Returns BaseEventFlags which is the result of dispatched event.
*/
MOZ_CAN_RUN_SCRIPT BaseEventFlags
CloneAndDispatchAs(
const WidgetCompositionEvent* aCompositionEvent,
EventMessage aMessage, nsEventStatus* aStatus = nullptr,
EventDispatchingCallback* aCallBack = nullptr);
/**
* If IME has already dispatched compositionend event but it was discarded
* by PresShell due to not safe to dispatch, this returns true.
*/
bool WasNativeCompositionEndEventDiscarded()
const {
return mWasNativeCompositionEndEventDiscarded;
}
/**
* OnCompositionEventDiscarded() is called when PresShell discards
* compositionupdate, compositionend or compositionchange event due to not
* safe to dispatch event.
*/
void OnCompositionEventDiscarded(WidgetCompositionEvent* aCompositionEvent);
/**
* OnCompositionEventDispatched() is called after a composition event is
* dispatched.
*/
MOZ_CAN_RUN_SCRIPT
void OnCompositionEventDispatched(
const WidgetCompositionEvent* aDispatchEvent);
/**
* MaybeNotifyIMEOfCompositionEventHandled() notifies IME of composition
* event handled. This should be called after dispatching a composition
* event which came from widget.
*/
void MaybeNotifyIMEOfCompositionEventHandled(
const WidgetCompositionEvent* aCompositionEvent);
/**
* GetSelectionStartOffset() returns normal selection start offset in the
* editor which has this composition.
* If it failed or lost focus, this would return 0.
*/
MOZ_CAN_RUN_SCRIPT uint32_t GetSelectionStartOffset();
/**
* OnStartOffsetUpdatedInChild() is called when composition start offset
* is updated in the child process. I.e., this is called and never called
* if the composition is in this process.
* @param aStartOffset New composition start offset with native
* linebreaks.
*/
void OnStartOffsetUpdatedInChild(uint32_t aStartOffset);
/**
* CompositionEventDispatcher dispatches the specified composition (or text)
* event.
*/
class CompositionEventDispatcher :
public Runnable {
public:
CompositionEventDispatcher(TextComposition* aTextComposition,
nsINode* aEventTarget,
EventMessage aEventMessage,
const nsAString& aData,
bool aIsSynthesizedEvent =
false);
MOZ_CAN_RUN_SCRIPT_BOUNDARY NS_IMETHOD Run() override;
private:
RefPtr<TextComposition> mTextComposition;
nsCOMPtr<nsINode> mEventTarget;
nsString mData;
EventMessage mEventMessage;
bool mIsSynthesizedEvent;
CompositionEventDispatcher()
: Runnable(
"TextComposition::CompositionEventDispatcher"),
mEventMessage(eVoidEvent),
mIsSynthesizedEvent(
false) {};
};
/**
* DispatchCompositionEventRunnable() dispatches a composition event to the
* content. Be aware, if you use this method, nsPresShellEventCB isn't used.
* That means that nsIFrame::HandleEvent() is never called.
* WARNING: The instance which is managed by IMEStateManager may be
* destroyed by this method call.
*
* @param aEventMessage Must be one of composition events.
* @param aData Used for mData value.
* @param aIsSynthesizingCommit true if this is called for synthesizing
* commit or cancel composition. Otherwise,
* false.
*/
void DispatchCompositionEventRunnable(EventMessage aEventMessage,
const nsAString& aData,
bool aIsSynthesizingCommit =
false);
};
/**
* TextCompositionArray manages the instances of TextComposition class.
* Managing with array is enough because only one composition is typically
* there. Even if user switches native IME context, it's very rare that
* second or more composition is started.
* It's assumed that this is used by IMEStateManager for storing all active
* compositions in the process. If the instance is it, each TextComposition
* in the array can be destroyed by calling some methods of itself.
*/
class TextCompositionArray final
:
public AutoTArray<RefPtr<TextComposition>, 2> {
public:
// Looking for per native IME context.
index_type IndexOf(
const widget::NativeIMEContext& aNativeIMEContext);
index_type IndexOf(nsIWidget* aWidget);
TextComposition* GetCompositionFor(nsIWidget* aWidget);
TextComposition* GetCompositionFor(
const WidgetCompositionEvent* aCompositionEvent);
// Looking for per nsPresContext
index_type IndexOf(nsPresContext* aPresContext);
index_type IndexOf(nsPresContext* aPresContext, nsINode* aNode);
TextComposition* GetCompositionFor(nsPresContext* aPresContext);
TextComposition* GetCompositionFor(nsPresContext* aPresContext,
nsINode* aNode);
TextComposition* GetCompositionInContent(nsPresContext* aPresContext,
nsIContent* aContent);
};
}
// namespace mozilla
#endif // #ifndef mozilla_TextComposition_h
