diff options
Diffstat (limited to 'accessible/generic/DocAccessible.h')
| -rw-r--r-- | accessible/generic/DocAccessible.h | 718 |
1 files changed, 718 insertions, 0 deletions
diff --git a/accessible/generic/DocAccessible.h b/accessible/generic/DocAccessible.h new file mode 100644 index 000000000..4bc6f03f0 --- /dev/null +++ b/accessible/generic/DocAccessible.h @@ -0,0 +1,718 @@ +/* -*- 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 |