/* -*- 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/. */ #ifndef mozilla_a11y_DocAccessible_h__ #define mozilla_a11y_DocAccessible_h__ #include "nsIAccessiblePivot.h" #include "HyperTextAccessibleWrap.h" #include "AccEvent.h" #include "nsAutoPtr.h" #include "nsClassHashtable.h" #include "nsDataHashtable.h" #include "nsIDocument.h" #include "nsIDocumentObserver.h" #include "nsIEditor.h" #include "nsIObserver.h" #include "nsIScrollPositionListener.h" #include "nsITimer.h" #include "nsIWeakReference.h" class nsAccessiblePivot; const uint32_t kDefaultCacheLength = 128; namespace mozilla { namespace a11y { class DocManager; class NotificationController; class DocAccessibleChild; class RelatedAccIterator; template<class Class, class ... Args> class TNotification; class DocAccessible : public HyperTextAccessibleWrap, public nsIDocumentObserver, public nsIObserver, public nsIScrollPositionListener, public nsSupportsWeakReference, public nsIAccessiblePivotObserver { NS_DECL_ISUPPORTS_INHERITED NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(DocAccessible, Accessible) NS_DECL_NSIOBSERVER NS_DECL_NSIACCESSIBLEPIVOTOBSERVER public: DocAccessible(nsIDocument* aDocument, nsIPresShell* aPresShell); // nsIScrollPositionListener virtual void ScrollPositionWillChange(nscoord aX, nscoord aY) override {} virtual void ScrollPositionDidChange(nscoord aX, nscoord aY) override; // nsIDocumentObserver NS_DECL_NSIDOCUMENTOBSERVER // Accessible virtual void Init(); virtual void Shutdown() override; virtual nsIFrame* GetFrame() const override; virtual nsINode* GetNode() const override { return mDocumentNode; } nsIDocument* DocumentNode() const { return mDocumentNode; } virtual mozilla::a11y::ENameValueFlag Name(nsString& aName) override; virtual void Description(nsString& aDescription) override; virtual Accessible* FocusedChild() override; virtual mozilla::a11y::role NativeRole() override; virtual uint64_t NativeState() override; virtual uint64_t NativeInteractiveState() const override; virtual bool NativelyUnavailable() const override; virtual void ApplyARIAState(uint64_t* aState) const override; virtual already_AddRefed<nsIPersistentProperties> Attributes() override; virtual void TakeFocus() override; #ifdef A11Y_LOG virtual nsresult HandleAccEvent(AccEvent* aEvent) override; #endif virtual nsRect RelativeBounds(nsIFrame** aRelativeFrame) const override; // HyperTextAccessible virtual already_AddRefed<nsIEditor> GetEditor() const override; // DocAccessible /** * Return document URL. */ void URL(nsAString& aURL) const; /** * Return DOM document title. */ void Title(nsString& aTitle) const { mDocumentNode->GetTitle(aTitle); } /** * Return DOM document mime type. */ void MimeType(nsAString& aType) const { mDocumentNode->GetContentType(aType); } /** * Return DOM document type. */ void DocType(nsAString& aType) const; /** * Return virtual cursor associated with the document. */ nsIAccessiblePivot* VirtualCursor(); /** * Return presentation shell for this document accessible. */ nsIPresShell* PresShell() const { return mPresShell; } /** * Return the presentation shell's context. */ nsPresContext* PresContext() const { return mPresShell->GetPresContext(); } /** * Return true if associated DOM document was loaded and isn't unloading. */ bool IsContentLoaded() const { // eDOMLoaded flag check is used for error pages as workaround to make this // method return correct result since error pages do not receive 'pageshow' // event and as consequence nsIDocument::IsShowing() returns false. return mDocumentNode && mDocumentNode->IsVisible() && (mDocumentNode->IsShowing() || HasLoadState(eDOMLoaded)); } /** * Document load states. */ enum LoadState { // initial tree construction is pending eTreeConstructionPending = 0, // initial tree construction done eTreeConstructed = 1, // DOM document is loaded. eDOMLoaded = 1 << 1, // document is ready eReady = eTreeConstructed | eDOMLoaded, // document and all its subdocuments are ready eCompletelyLoaded = eReady | 1 << 2 }; /** * Return true if the document has given document state. */ bool HasLoadState(LoadState aState) const { return (mLoadState & static_cast<uint32_t>(aState)) == static_cast<uint32_t>(aState); } /** * Return a native window handler or pointer depending on platform. */ virtual void* GetNativeWindow() const; /** * Return the parent document. */ DocAccessible* ParentDocument() const { return mParent ? mParent->Document() : nullptr; } /** * Return the child document count. */ uint32_t ChildDocumentCount() const { return mChildDocuments.Length(); } /** * Return the child document at the given index. */ DocAccessible* GetChildDocumentAt(uint32_t aIndex) const { return mChildDocuments.SafeElementAt(aIndex, nullptr); } /** * Fire accessible event asynchronously. */ void FireDelayedEvent(AccEvent* aEvent); void FireDelayedEvent(uint32_t aEventType, Accessible* aTarget); void FireEventsOnInsertion(Accessible* aContainer); /** * Fire value change event on the given accessible if applicable. */ void MaybeNotifyOfValueChange(Accessible* aAccessible); /** * Get/set the anchor jump. */ Accessible* AnchorJump() { return GetAccessibleOrContainer(mAnchorJumpElm); } void SetAnchorJump(nsIContent* aTargetNode) { mAnchorJumpElm = aTargetNode; } /** * Bind the child document to the tree. */ void BindChildDocument(DocAccessible* aDocument); /** * Process the generic notification. * * @note The caller must guarantee that the given instance still exists when * notification is processed. * @see NotificationController::HandleNotification */ template<class Class, class Arg> void HandleNotification(Class* aInstance, typename TNotification<Class, Arg>::Callback aMethod, Arg* aArg); /** * Return the cached accessible by the given DOM node if it's in subtree of * this document accessible or the document accessible itself, otherwise null. * * @return the accessible object */ Accessible* GetAccessible(nsINode* aNode) const { return aNode == mDocumentNode ? const_cast<DocAccessible*>(this) : mNodeToAccessibleMap.Get(aNode); } /** * Return an accessible for the given node even if the node is not in * document's node map cache (like HTML area element). * * XXX: it should be really merged with GetAccessible(). */ Accessible* GetAccessibleEvenIfNotInMap(nsINode* aNode) const; Accessible* GetAccessibleEvenIfNotInMapOrContainer(nsINode* aNode) const; /** * Return whether the given DOM node has an accessible or not. */ bool HasAccessible(nsINode* aNode) const { return GetAccessible(aNode); } /** * Return the cached accessible by the given unique ID within this document. * * @note the unique ID matches with the uniqueID() of Accessible * * @param aUniqueID [in] the unique ID used to cache the node. */ Accessible* GetAccessibleByUniqueID(void* aUniqueID) { return UniqueID() == aUniqueID ? this : mAccessibleCache.GetWeak(aUniqueID); } /** * Return the cached accessible by the given unique ID looking through * this and nested documents. */ Accessible* GetAccessibleByUniqueIDInSubtree(void* aUniqueID); /** * Return an accessible for the given DOM node or container accessible if * the node is not accessible. */ Accessible* GetAccessibleOrContainer(nsINode* aNode) const; /** * Return a container accessible for the given DOM node. */ Accessible* GetContainerAccessible(nsINode* aNode) const { return aNode ? GetAccessibleOrContainer(aNode->GetParentNode()) : nullptr; } /** * Return an accessible for the given node if any, or an immediate accessible * container for it. */ Accessible* AccessibleOrTrueContainer(nsINode* aNode) const; /** * Return an accessible for the given node or its first accessible descendant. */ Accessible* GetAccessibleOrDescendant(nsINode* aNode) const; /** * Returns aria-owns seized child at the given index. */ Accessible* ARIAOwnedAt(Accessible* aParent, uint32_t aIndex) const { nsTArray<RefPtr<Accessible> >* children = mARIAOwnsHash.Get(aParent); if (children) { return children->SafeElementAt(aIndex); } return nullptr; } uint32_t ARIAOwnedCount(Accessible* aParent) const { nsTArray<RefPtr<Accessible> >* children = mARIAOwnsHash.Get(aParent); return children ? children->Length() : 0; } /** * Return true if the given ID is referred by relation attribute. * * @note Different elements may share the same ID if they are hosted inside * XBL bindings. Be careful the result of this method may be senseless * while it's called for XUL elements (where XBL is used widely). */ bool IsDependentID(const nsAString& aID) const { return mDependentIDsHash.Get(aID, nullptr); } /** * Initialize the newly created accessible and put it into document caches. * * @param aAccessible [in] created accessible * @param aRoleMapEntry [in] the role map entry role the ARIA role or nullptr * if none */ void BindToDocument(Accessible* aAccessible, const nsRoleMapEntry* aRoleMapEntry); /** * Remove from document and shutdown the given accessible. */ void UnbindFromDocument(Accessible* aAccessible); /** * Notify the document accessible that content was inserted. */ void ContentInserted(nsIContent* aContainerNode, nsIContent* aStartChildNode, nsIContent* aEndChildNode); /** * Notify the document accessible that content was removed. */ void ContentRemoved(Accessible* aContainer, nsIContent* aChildNode) { // Update the whole tree of this document accessible when the container is // null (document element is removed). UpdateTreeOnRemoval((aContainer ? aContainer : this), aChildNode); } void ContentRemoved(nsIContent* aContainerNode, nsIContent* aChildNode) { ContentRemoved(GetAccessibleOrContainer(aContainerNode), aChildNode); } /** * Updates accessible tree when rendered text is changed. */ void UpdateText(nsIContent* aTextNode); /** * Recreate an accessible, results in hide/show events pair. */ void RecreateAccessible(nsIContent* aContent); /** * Schedule ARIA owned element relocation if needed. Return true if relocation * was scheduled. */ bool RelocateARIAOwnedIfNeeded(nsIContent* aEl); /** * Return a notification controller associated with the document. */ NotificationController* Controller() const { return mNotificationController; } /** * If this document is in a content process return the object responsible for * communicating with the main process for it. */ DocAccessibleChild* IPCDoc() const { return mIPCDoc; } protected: virtual ~DocAccessible(); void LastRelease(); // DocAccessible virtual nsresult AddEventListeners(); virtual nsresult RemoveEventListeners(); /** * Marks this document as loaded or loading. */ void NotifyOfLoad(uint32_t aLoadEventType); void NotifyOfLoading(bool aIsReloading); friend class DocManager; /** * Perform initial update (create accessible tree). * Can be overridden by wrappers to prepare initialization work. */ virtual void DoInitialUpdate(); /** * Updates root element and picks up ARIA role on it if any. */ void UpdateRootElIfNeeded(); /** * Process document load notification, fire document load and state busy * events if applicable. */ void ProcessLoad(); /** * Add/remove scroll listeners, @see nsIScrollPositionListener interface. */ void AddScrollListener(); void RemoveScrollListener(); /** * Append the given document accessible to this document's child document * accessibles. */ bool AppendChildDocument(DocAccessible* aChildDocument) { return mChildDocuments.AppendElement(aChildDocument); } /** * Remove the given document accessible from this document's child document * accessibles. */ void RemoveChildDocument(DocAccessible* aChildDocument) { mChildDocuments.RemoveElement(aChildDocument); } /** * Add dependent IDs pointed by accessible element by relation attribute to * cache. If the relation attribute is missed then all relation attributes * are checked. * * @param aRelProvider [in] accessible that element has relation attribute * @param aRelAttr [in, optional] relation attribute */ void AddDependentIDsFor(Accessible* aRelProvider, nsIAtom* aRelAttr = nullptr); /** * Remove dependent IDs pointed by accessible element by relation attribute * from cache. If the relation attribute is absent then all relation * attributes are checked. * * @param aRelProvider [in] accessible that element has relation attribute * @param aRelAttr [in, optional] relation attribute */ void RemoveDependentIDsFor(Accessible* aRelProvider, nsIAtom* aRelAttr = nullptr); /** * Update or recreate an accessible depending on a changed attribute. * * @param aElement [in] the element the attribute was changed on * @param aAttribute [in] the changed attribute * @return true if an action was taken on the attribute change */ bool UpdateAccessibleOnAttrChange(mozilla::dom::Element* aElement, nsIAtom* aAttribute); /** * Fire accessible events when attribute is changed. * * @param aAccessible [in] accessible the DOM attribute is changed for * @param aNameSpaceID [in] namespace of changed attribute * @param aAttribute [in] changed attribute */ void AttributeChangedImpl(Accessible* aAccessible, int32_t aNameSpaceID, nsIAtom* aAttribute); /** * Fire accessible events when ARIA attribute is changed. * * @param aAccessible [in] accesislbe the DOM attribute is changed for * @param aAttribute [in] changed attribute */ void ARIAAttributeChanged(Accessible* aAccessible, nsIAtom* aAttribute); /** * Process ARIA active-descendant attribute change. */ void ARIAActiveDescendantChanged(Accessible* aAccessible); /** * Update the accessible tree for inserted content. */ void ProcessContentInserted(Accessible* aContainer, const nsTArray<nsCOMPtr<nsIContent> >* aInsertedContent); void ProcessContentInserted(Accessible* aContainer, nsIContent* aInsertedContent); /** * Used to notify the document to make it process the invalidation list. * * While children are cached we may encounter the case there's no accessible * for referred content by related accessible. Store these related nodes to * invalidate their containers later. */ void ProcessInvalidationList(); /** * Update the accessible tree for content removal. */ void UpdateTreeOnRemoval(Accessible* aContainer, nsIContent* aChildNode); /** * Validates all aria-owns connections and updates the tree accordingly. */ void ValidateARIAOwned(); /** * Steals or puts back accessible subtrees. */ void DoARIAOwnsRelocation(Accessible* aOwner); /** * Moves children back under their original parents. */ void PutChildrenBack(nsTArray<RefPtr<Accessible> >* aChildren, uint32_t aStartIdx); bool MoveChild(Accessible* aChild, Accessible* aNewParent, int32_t aIdxInParent); /** * Create accessible tree. * * @param aRoot [in] a root of subtree to create * @param aFocusedAcc [in, optional] a focused accessible under created * subtree if any */ void CacheChildrenInSubtree(Accessible* aRoot, Accessible** aFocusedAcc = nullptr); void CreateSubtree(Accessible* aRoot); /** * Remove accessibles in subtree from node to accessible map. */ void UncacheChildrenInSubtree(Accessible* aRoot); /** * Shutdown any cached accessible in the subtree. * * @param aAccessible [in] the root of the subrtee to invalidate accessible * child/parent refs in */ void ShutdownChildrenInSubtree(Accessible* aAccessible); /** * Return true if the document is a target of document loading events * (for example, state busy change or document reload events). * * Rules: The root chrome document accessible is never an event target * (for example, Firefox UI window). If the sub document is loaded within its * parent document then the parent document is a target only (aka events * coalescence). */ bool IsLoadEventTarget() const; /* * Set the object responsible for communicating with the main process on * behalf of this document. */ void SetIPCDoc(DocAccessibleChild* aIPCDoc) { mIPCDoc = aIPCDoc; } friend class DocAccessibleChildBase; /** * Used to fire scrolling end event after page scroll. * * @param aTimer [in] the timer object * @param aClosure [in] the document accessible where scrolling happens */ static void ScrollTimerCallback(nsITimer* aTimer, void* aClosure); protected: /** * State and property flags, kept by mDocFlags. */ enum { // Whether scroll listeners were added. eScrollInitialized = 1 << 0, // Whether the document is a tab document. eTabDocument = 1 << 1 }; /** * Cache of accessibles within this document accessible. */ AccessibleHashtable mAccessibleCache; nsDataHashtable<nsPtrHashKey<const nsINode>, Accessible*> mNodeToAccessibleMap; nsIDocument* mDocumentNode; nsCOMPtr<nsITimer> mScrollWatchTimer; uint16_t mScrollPositionChangedTicks; // Used for tracking scroll events /** * Bit mask of document load states (@see LoadState). */ uint32_t mLoadState : 3; /** * Bit mask of other states and props. */ uint32_t mDocFlags : 28; /** * Type of document load event fired after the document is loaded completely. */ uint32_t mLoadEventType; /** * Reference to anchor jump element. */ nsCOMPtr<nsIContent> mAnchorJumpElm; /** * A generic state (see items below) before the attribute value was changed. * @see AttributeWillChange and AttributeChanged notifications. */ union { // ARIA attribute value nsIAtom* mARIAAttrOldValue; // True if the accessible state bit was on bool mStateBitWasOn; }; nsTArray<RefPtr<DocAccessible> > mChildDocuments; /** * The virtual cursor of the document. */ RefPtr<nsAccessiblePivot> mVirtualCursor; /** * A storage class for pairing content with one of its relation attributes. */ class AttrRelProvider { public: AttrRelProvider(nsIAtom* aRelAttr, nsIContent* aContent) : mRelAttr(aRelAttr), mContent(aContent) { } nsIAtom* mRelAttr; nsCOMPtr<nsIContent> mContent; private: AttrRelProvider(); AttrRelProvider(const AttrRelProvider&); AttrRelProvider& operator =(const AttrRelProvider&); }; /** * The cache of IDs pointed by relation attributes. */ typedef nsTArray<nsAutoPtr<AttrRelProvider> > AttrRelProviderArray; nsClassHashtable<nsStringHashKey, AttrRelProviderArray> mDependentIDsHash; friend class RelatedAccIterator; /** * Used for our caching algorithm. We store the list of nodes that should be * invalidated. * * @see ProcessInvalidationList */ nsTArray<RefPtr<nsIContent>> mInvalidationList; /** * Holds a list of aria-owns relocations. */ nsClassHashtable<nsPtrHashKey<Accessible>, nsTArray<RefPtr<Accessible> > > mARIAOwnsHash; /** * Used to process notification from core and accessible events. */ RefPtr<NotificationController> mNotificationController; friend class EventTree; friend class NotificationController; private: nsIPresShell* mPresShell; // Exclusively owned by IPDL so don't manually delete it! DocAccessibleChild* mIPCDoc; }; inline DocAccessible* Accessible::AsDoc() { return IsDoc() ? static_cast<DocAccessible*>(this) : nullptr; } } // namespace a11y } // namespace mozilla #endif