michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef _Accessible_H_
michael@0: #define _Accessible_H_
michael@0: 
michael@0: #include "mozilla/a11y/AccTypes.h"
michael@0: #include "mozilla/a11y/RelationType.h"
michael@0: #include "mozilla/a11y/Role.h"
michael@0: #include "mozilla/a11y/States.h"
michael@0: 
michael@0: #include "nsIAccessible.h"
michael@0: #include "nsIAccessibleHyperLink.h"
michael@0: #include "nsIAccessibleStates.h"
michael@0: #include "xpcAccessibleSelectable.h"
michael@0: #include "xpcAccessibleValue.h"
michael@0: 
michael@0: #include "nsIContent.h"
michael@0: #include "nsString.h"
michael@0: #include "nsTArray.h"
michael@0: #include "nsRefPtrHashtable.h"
michael@0: 
michael@0: struct nsRoleMapEntry;
michael@0: 
michael@0: struct nsRect;
michael@0: class nsIFrame;
michael@0: class nsIAtom;
michael@0: class nsView;
michael@0: 
michael@0: namespace mozilla {
michael@0: namespace a11y {
michael@0: 
michael@0: class Accessible;
michael@0: class AccEvent;
michael@0: class AccGroupInfo;
michael@0: class DocAccessible;
michael@0: class EmbeddedObjCollector;
michael@0: class HTMLImageMapAccessible;
michael@0: class HTMLLIAccessible;
michael@0: class HyperTextAccessible;
michael@0: class ImageAccessible;
michael@0: class KeyBinding;
michael@0: class Relation;
michael@0: class RootAccessible;
michael@0: class TableAccessible;
michael@0: class TableCellAccessible;
michael@0: class TextLeafAccessible;
michael@0: class XULLabelAccessible;
michael@0: class XULTreeAccessible;
michael@0: 
michael@0: /**
michael@0:  * Name type flags.
michael@0:  */
michael@0: enum ENameValueFlag {
michael@0:   /**
michael@0:    * Name either
michael@0:    *  a) present (not empty): !name.IsEmpty()
michael@0:    *  b) no name (was missed): name.IsVoid()
michael@0:    */
michael@0:  eNameOK,
michael@0: 
michael@0:  /**
michael@0:   * Name was left empty by the author on purpose:
michael@0:   * name.IsEmpty() && !name.IsVoid().
michael@0:   */
michael@0:  eNoNameOnPurpose,
michael@0: 
michael@0:  /**
michael@0:   * Name was computed from the subtree.
michael@0:   */
michael@0:  eNameFromSubtree,
michael@0: 
michael@0:  /**
michael@0:   * Tooltip was used as a name.
michael@0:   */
michael@0:  eNameFromTooltip
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * Group position (level, position in set and set size).
michael@0:  */
michael@0: struct GroupPos
michael@0: {
michael@0:   GroupPos() : level(0), posInSet(0), setSize(0) { }
michael@0: 
michael@0:   int32_t level;
michael@0:   int32_t posInSet;
michael@0:   int32_t setSize;
michael@0: };
michael@0: 
michael@0: typedef nsRefPtrHashtable<nsPtrHashKey<const void>, Accessible>
michael@0:   AccessibleHashtable;
michael@0: 
michael@0: 
michael@0: #define NS_ACCESSIBLE_IMPL_IID                          \
michael@0: {  /* 133c8bf4-4913-4355-bd50-426bd1d6e1ad */           \
michael@0:   0x133c8bf4,                                           \
michael@0:   0x4913,                                               \
michael@0:   0x4355,                                               \
michael@0:   { 0xbd, 0x50, 0x42, 0x6b, 0xd1, 0xd6, 0xe1, 0xad }    \
michael@0: }
michael@0: 
michael@0: class Accessible : public nsIAccessible,
michael@0:                    public nsIAccessibleHyperLink,
michael@0:                    public xpcAccessibleSelectable,
michael@0:                    public xpcAccessibleValue
michael@0: {
michael@0: public:
michael@0:   Accessible(nsIContent* aContent, DocAccessible* aDoc);
michael@0:   virtual ~Accessible();
michael@0: 
michael@0:   NS_DECL_CYCLE_COLLECTING_ISUPPORTS
michael@0:   NS_DECL_CYCLE_COLLECTION_CLASS_AMBIGUOUS(Accessible, nsIAccessible)
michael@0: 
michael@0:   NS_DECL_NSIACCESSIBLE
michael@0:   NS_DECL_NSIACCESSIBLEHYPERLINK
michael@0:   NS_DECLARE_STATIC_IID_ACCESSOR(NS_ACCESSIBLE_IMPL_IID)
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Public methods
michael@0: 
michael@0:   /**
michael@0:    * Return the document accessible for this accessible.
michael@0:    */
michael@0:   DocAccessible* Document() const { return mDoc; }
michael@0: 
michael@0:   /**
michael@0:    * Return the root document accessible for this accessible.
michael@0:    */
michael@0:   a11y::RootAccessible* RootAccessible() const;
michael@0: 
michael@0:   /**
michael@0:    * Return frame for this accessible.
michael@0:    */
michael@0:   virtual nsIFrame* GetFrame() const;
michael@0: 
michael@0:   /**
michael@0:    * Return DOM node associated with the accessible.
michael@0:    */
michael@0:   virtual nsINode* GetNode() const;
michael@0:   inline already_AddRefed<nsIDOMNode> DOMNode() const
michael@0:   {
michael@0:     nsCOMPtr<nsIDOMNode> DOMNode = do_QueryInterface(GetNode());
michael@0:     return DOMNode.forget();
michael@0:   }
michael@0:   nsIContent* GetContent() const { return mContent; }
michael@0: 
michael@0:   /**
michael@0:    * Return node type information of DOM node associated with the accessible.
michael@0:    */
michael@0:   bool IsContent() const
michael@0:     { return GetNode() && GetNode()->IsNodeOfType(nsINode::eCONTENT); }
michael@0: 
michael@0:   /**
michael@0:    * Return the unique identifier of the accessible.
michael@0:    */
michael@0:   void* UniqueID() { return static_cast<void*>(this); }
michael@0: 
michael@0:   /**
michael@0:    * Return language associated with the accessible.
michael@0:    */
michael@0:   void Language(nsAString& aLocale);
michael@0: 
michael@0:   /**
michael@0:    * Get the description of this accessible.
michael@0:    */
michael@0:   virtual void Description(nsString& aDescription);
michael@0: 
michael@0:   /**
michael@0:    * Get the value of this accessible.
michael@0:    */
michael@0:   virtual void Value(nsString& aValue);
michael@0: 
michael@0:   /**
michael@0:    * Get the name of this accessible.
michael@0:    *
michael@0:    * Note: aName.IsVoid() when name was left empty by the author on purpose.
michael@0:    * aName.IsEmpty() when the author missed name, AT can try to repair a name.
michael@0:    */
michael@0:   virtual ENameValueFlag Name(nsString& aName);
michael@0: 
michael@0:   /**
michael@0:    * Maps ARIA state attributes to state of accessible. Note the given state
michael@0:    * argument should hold states for accessible before you pass it into this
michael@0:    * method.
michael@0:    *
michael@0:    * @param  [in/out] where to fill the states into.
michael@0:    */
michael@0:   virtual void ApplyARIAState(uint64_t* aState) const;
michael@0: 
michael@0:   /**
michael@0:    * Return enumerated accessible role (see constants in Role.h).
michael@0:    */
michael@0:   mozilla::a11y::role Role();
michael@0: 
michael@0:   /**
michael@0:    * Return true if ARIA role is specified on the element.
michael@0:    */
michael@0:   bool HasARIARole() const { return mRoleMapEntry; }
michael@0:   bool IsARIARole(nsIAtom* aARIARole) const;
michael@0: 
michael@0:   /**
michael@0:    * Retrun ARIA role map if any.
michael@0:    */
michael@0:   nsRoleMapEntry* ARIARoleMap() const { return mRoleMapEntry; }
michael@0: 
michael@0:   /**
michael@0:    * Return accessible role specified by ARIA (see constants in
michael@0:    * roles).
michael@0:    */
michael@0:   mozilla::a11y::role ARIARole();
michael@0: 
michael@0:   /**
michael@0:    * Returns enumerated accessible role from native markup (see constants in
michael@0:    * Role.h). Doesn't take into account ARIA roles.
michael@0:    */
michael@0:   virtual mozilla::a11y::role NativeRole();
michael@0: 
michael@0:   /**
michael@0:    * Return all states of accessible (including ARIA states).
michael@0:    */
michael@0:   virtual uint64_t State();
michael@0: 
michael@0:   /**
michael@0:    * Return interactive states present on the accessible
michael@0:    * (@see NativeInteractiveState).
michael@0:    */
michael@0:   uint64_t InteractiveState() const
michael@0:   {
michael@0:     uint64_t state = NativeInteractiveState();
michael@0:     ApplyARIAState(&state);
michael@0:     return state;
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return link states present on the accessible.
michael@0:    */
michael@0:   uint64_t LinkState() const
michael@0:   {
michael@0:     uint64_t state = NativeLinkState();
michael@0:     ApplyARIAState(&state);
michael@0:     return state;
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return if accessible is unavailable.
michael@0:    */
michael@0:   bool Unavailable() const
michael@0:   {
michael@0:     uint64_t state = NativelyUnavailable() ? states::UNAVAILABLE : 0;
michael@0:     ApplyARIAState(&state);
michael@0:     return state & states::UNAVAILABLE;
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return the states of accessible, not taking into account ARIA states.
michael@0:    * Use State() to get complete set of states.
michael@0:    */
michael@0:   virtual uint64_t NativeState();
michael@0: 
michael@0:   /**
michael@0:    * Return native interactice state (unavailable, focusable or selectable).
michael@0:    */
michael@0:   virtual uint64_t NativeInteractiveState() const;
michael@0: 
michael@0:   /**
michael@0:    * Return native link states present on the accessible.
michael@0:    */
michael@0:   virtual uint64_t NativeLinkState() const;
michael@0: 
michael@0:   /**
michael@0:    * Return bit set of invisible and offscreen states.
michael@0:    */
michael@0:   uint64_t VisibilityState();
michael@0: 
michael@0:   /**
michael@0:    * Return true if native unavailable state present.
michael@0:    */
michael@0:   virtual bool NativelyUnavailable() const;
michael@0: 
michael@0:   /**
michael@0:    * Return object attributes for the accessible.
michael@0:    */
michael@0:   virtual already_AddRefed<nsIPersistentProperties> Attributes();
michael@0: 
michael@0:   /**
michael@0:    * Return group position (level, position in set and set size).
michael@0:    */
michael@0:   virtual mozilla::a11y::GroupPos GroupPosition();
michael@0: 
michael@0:   /**
michael@0:    * Used by ChildAtPoint() method to get direct or deepest child at point.
michael@0:    */
michael@0:   enum EWhichChildAtPoint {
michael@0:     eDirectChild,
michael@0:     eDeepestChild
michael@0:   };
michael@0: 
michael@0:   /**
michael@0:    * Return direct or deepest child at the given point.
michael@0:    *
michael@0:    * @param  aX           [in] x coordinate relative screen
michael@0:    * @param  aY           [in] y coordinate relative screen
michael@0:    * @param  aWhichChild  [in] flag points if deepest or direct child
michael@0:    *                        should be returned
michael@0:    */
michael@0:   virtual Accessible* ChildAtPoint(int32_t aX, int32_t aY,
michael@0:                                    EWhichChildAtPoint aWhichChild);
michael@0: 
michael@0:   /**
michael@0:    * Return the focused child if any.
michael@0:    */
michael@0:   virtual Accessible* FocusedChild();
michael@0: 
michael@0:   /**
michael@0:    * Return calculated group level based on accessible hierarchy.
michael@0:    */
michael@0:   virtual int32_t GetLevelInternal();
michael@0: 
michael@0:   /**
michael@0:    * Calculate position in group and group size ('posinset' and 'setsize') based
michael@0:    * on accessible hierarchy.
michael@0:    *
michael@0:    * @param  aPosInSet  [out] accessible position in the group
michael@0:    * @param  aSetSize   [out] the group size
michael@0:    */
michael@0:   virtual void GetPositionAndSizeInternal(int32_t *aPosInSet,
michael@0:                                           int32_t *aSetSize);
michael@0: 
michael@0:   /**
michael@0:    * Get the relation of the given type.
michael@0:    */
michael@0:   virtual Relation RelationByType(RelationType aType);
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Initializing methods
michael@0: 
michael@0:   /**
michael@0:    * Shutdown this accessible object.
michael@0:    */
michael@0:   virtual void Shutdown();
michael@0: 
michael@0:   /**
michael@0:    * Set the ARIA role map entry for a new accessible.
michael@0:    */
michael@0:   void SetRoleMapEntry(nsRoleMapEntry* aRoleMapEntry)
michael@0:     { mRoleMapEntry = aRoleMapEntry; }
michael@0: 
michael@0:   /**
michael@0:    * Update the children cache.
michael@0:    */
michael@0:   inline bool UpdateChildren()
michael@0:   {
michael@0:     InvalidateChildren();
michael@0:     return EnsureChildren();
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Cache children if necessary. Return true if the accessible is defunct.
michael@0:    */
michael@0:   bool EnsureChildren();
michael@0: 
michael@0:   /**
michael@0:    * Set the child count to -1 (unknown) and null out cached child pointers.
michael@0:    * Should be called when accessible tree is changed because document has
michael@0:    * transformed. Note, if accessible cares about its parent relation chain
michael@0:    * itself should override this method to do nothing.
michael@0:    */
michael@0:   virtual void InvalidateChildren();
michael@0: 
michael@0:   /**
michael@0:    * Append/insert/remove a child. Return true if operation was successful.
michael@0:    */
michael@0:   bool AppendChild(Accessible* aChild)
michael@0:     { return InsertChildAt(mChildren.Length(), aChild); }
michael@0:   virtual bool InsertChildAt(uint32_t aIndex, Accessible* aChild);
michael@0:   virtual bool RemoveChild(Accessible* aChild);
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Accessible tree traverse methods
michael@0: 
michael@0:   /**
michael@0:    * Return parent accessible.
michael@0:    */
michael@0:   Accessible* Parent() const { return mParent; }
michael@0: 
michael@0:   /**
michael@0:    * Return child accessible at the given index.
michael@0:    */
michael@0:   virtual Accessible* GetChildAt(uint32_t aIndex) const;
michael@0: 
michael@0:   /**
michael@0:    * Return child accessible count.
michael@0:    */
michael@0:   virtual uint32_t ChildCount() const;
michael@0: 
michael@0:   /**
michael@0:    * Return index of the given child accessible.
michael@0:    */
michael@0:   int32_t GetIndexOf(const Accessible* aChild) const
michael@0:     { return (aChild->mParent != this) ? -1 : aChild->IndexInParent(); }
michael@0: 
michael@0:   /**
michael@0:    * Return index in parent accessible.
michael@0:    */
michael@0:   virtual int32_t IndexInParent() const;
michael@0: 
michael@0:   /**
michael@0:    * Return true if accessible has children;
michael@0:    */
michael@0:   bool HasChildren() { return !!GetChildAt(0); }
michael@0: 
michael@0:   /**
michael@0:    * Return first/last/next/previous sibling of the accessible.
michael@0:    */
michael@0:   inline Accessible* NextSibling() const
michael@0:     {  return GetSiblingAtOffset(1); }
michael@0:   inline Accessible* PrevSibling() const
michael@0:     { return GetSiblingAtOffset(-1); }
michael@0:   inline Accessible* FirstChild()
michael@0:     { return GetChildAt(0); }
michael@0:   inline Accessible* LastChild()
michael@0:   {
michael@0:     uint32_t childCount = ChildCount();
michael@0:     return childCount != 0 ? GetChildAt(childCount - 1) : nullptr;
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return embedded accessible children count.
michael@0:    */
michael@0:   uint32_t EmbeddedChildCount();
michael@0: 
michael@0:   /**
michael@0:    * Return embedded accessible child at the given index.
michael@0:    */
michael@0:   Accessible* GetEmbeddedChildAt(uint32_t aIndex);
michael@0: 
michael@0:   /**
michael@0:    * Return index of the given embedded accessible child.
michael@0:    */
michael@0:   int32_t GetIndexOfEmbeddedChild(Accessible* aChild);
michael@0: 
michael@0:   /**
michael@0:    * Return number of content children/content child at index. The content
michael@0:    * child is created from markup in contrast to it's never constructed by its
michael@0:    * parent accessible (like treeitem accessibles for XUL trees).
michael@0:    */
michael@0:   uint32_t ContentChildCount() const { return mChildren.Length(); }
michael@0:   Accessible* ContentChildAt(uint32_t aIndex) const
michael@0:     { return mChildren.ElementAt(aIndex); }
michael@0: 
michael@0:   /**
michael@0:    * Return true if children were initialized.
michael@0:    */
michael@0:   inline bool AreChildrenCached() const
michael@0:     { return !IsChildrenFlag(eChildrenUninitialized); }
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible is attached to tree.
michael@0:    */
michael@0:   bool IsBoundToParent() const { return !!mParent; }
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Miscellaneous methods
michael@0: 
michael@0:   /**
michael@0:    * Handle accessible event, i.e. process it, notifies observers and fires
michael@0:    * platform specific event.
michael@0:    */
michael@0:   virtual nsresult HandleAccEvent(AccEvent* aAccEvent);
michael@0: 
michael@0:   /**
michael@0:    * Return true if this accessible allows accessible children from anonymous subtree.
michael@0:    */
michael@0:   virtual bool CanHaveAnonChildren();
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible is an acceptable child.
michael@0:    */
michael@0:   virtual bool IsAcceptableChild(Accessible* aPossibleChild) const { return true; }
michael@0: 
michael@0:   /**
michael@0:    * Returns text of accessible if accessible has text role otherwise empty
michael@0:    * string.
michael@0:    *
michael@0:    * @param aText         [in] returned text of the accessible
michael@0:    * @param aStartOffset  [in, optional] start offset inside of the accessible,
michael@0:    *                        if missed entire text is appended
michael@0:    * @param aLength       [in, optional] required length of text, if missed
michael@0:    *                        then text form start offset till the end is appended
michael@0:    */
michael@0:   virtual void AppendTextTo(nsAString& aText, uint32_t aStartOffset = 0,
michael@0:                             uint32_t aLength = UINT32_MAX);
michael@0: 
michael@0:   /**
michael@0:    * Assert if child not in parent's cache if the cache was initialized at this
michael@0:    * point.
michael@0:    */
michael@0:   void TestChildCache(Accessible* aCachedChild) const;
michael@0: 
michael@0:   /**
michael@0:    * Return boundaries rect relative the bounding frame.
michael@0:    */
michael@0:   virtual void GetBoundsRect(nsRect& aRect, nsIFrame** aRelativeFrame);
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Downcasting and types
michael@0: 
michael@0:   inline bool IsAbbreviation() const
michael@0:   {
michael@0:     return mContent->IsHTML() &&
michael@0:       (mContent->Tag() == nsGkAtoms::abbr || mContent->Tag() == nsGkAtoms::acronym);
michael@0:   }
michael@0: 
michael@0:   bool IsApplication() const { return mType == eApplicationType; }
michael@0: 
michael@0:   bool IsAutoComplete() const { return HasGenericType(eAutoComplete); }
michael@0: 
michael@0:   bool IsAutoCompletePopup() const
michael@0:     { return HasGenericType(eAutoCompletePopup); }
michael@0: 
michael@0:   bool IsButton() const { return HasGenericType(eButton); }
michael@0: 
michael@0:   bool IsCombobox() const { return HasGenericType(eCombobox); }
michael@0: 
michael@0:   bool IsDoc() const { return HasGenericType(eDocument); }
michael@0:   DocAccessible* AsDoc();
michael@0: 
michael@0:   bool IsHyperText() const { return HasGenericType(eHyperText); }
michael@0:   HyperTextAccessible* AsHyperText();
michael@0: 
michael@0:   bool IsHTMLBr() const { return mType == eHTMLBRType; }
michael@0:   bool IsHTMLFileInput() const { return mType == eHTMLFileInputType; }
michael@0: 
michael@0:   bool IsHTMLListItem() const { return mType == eHTMLLiType; }
michael@0:   HTMLLIAccessible* AsHTMLListItem();
michael@0: 
michael@0:   bool IsHTMLOptGroup() const { return mType == eHTMLOptGroupType; }
michael@0: 
michael@0:   bool IsHTMLTable() const { return mType == eHTMLTableType; }
michael@0:   bool IsHTMLTableRow() const { return mType == eHTMLTableRowType; }
michael@0: 
michael@0:   bool IsImage() const { return mType == eImageType; }
michael@0:   ImageAccessible* AsImage();
michael@0: 
michael@0:   bool IsImageMap() const { return mType == eImageMapType; }
michael@0:   HTMLImageMapAccessible* AsImageMap();
michael@0: 
michael@0:   bool IsList() const { return HasGenericType(eList); }
michael@0: 
michael@0:   bool IsListControl() const { return HasGenericType(eListControl); }
michael@0: 
michael@0:   bool IsMenuButton() const { return HasGenericType(eMenuButton); }
michael@0: 
michael@0:   bool IsMenuPopup() const { return mType == eMenuPopupType; }
michael@0: 
michael@0:   bool IsProgress() const { return mType == eProgressType; }
michael@0: 
michael@0:   bool IsRoot() const { return mType == eRootType; }
michael@0:   a11y::RootAccessible* AsRoot();
michael@0: 
michael@0:   bool IsSelect() const { return HasGenericType(eSelect); }
michael@0: 
michael@0:   bool IsTable() const { return HasGenericType(eTable); }
michael@0:   virtual TableAccessible* AsTable() { return nullptr; }
michael@0: 
michael@0:   bool IsTableCell() const { return HasGenericType(eTableCell); }
michael@0:   virtual TableCellAccessible* AsTableCell() { return nullptr; }
michael@0:   const TableCellAccessible* AsTableCell() const
michael@0:     { return const_cast<Accessible*>(this)->AsTableCell(); }
michael@0: 
michael@0:   bool IsTableRow() const { return HasGenericType(eTableRow); }
michael@0: 
michael@0:   bool IsTextField() const { return mType == eHTMLTextFieldType; }
michael@0: 
michael@0:   bool IsTextLeaf() const { return mType == eTextLeafType; }
michael@0:   TextLeafAccessible* AsTextLeaf();
michael@0: 
michael@0:   bool IsXULLabel() const { return mType == eXULLabelType; }
michael@0:   XULLabelAccessible* AsXULLabel();
michael@0: 
michael@0:   bool IsXULListItem() const { return mType == eXULListItemType; }
michael@0: 
michael@0:   bool IsXULTabpanels() const { return mType == eXULTabpanelsType; }
michael@0: 
michael@0:   bool IsXULTree() const { return mType == eXULTreeType; }
michael@0:   XULTreeAccessible* AsXULTree();
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible belongs to the given accessible type.
michael@0:    */
michael@0:   bool HasGenericType(AccGenericType aType) const;
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // ActionAccessible
michael@0: 
michael@0:   /**
michael@0:    * Return the number of actions that can be performed on this accessible.
michael@0:    */
michael@0:   virtual uint8_t ActionCount();
michael@0: 
michael@0:   /**
michael@0:    * Return access key, such as Alt+D.
michael@0:    */
michael@0:   virtual KeyBinding AccessKey() const;
michael@0: 
michael@0:   /**
michael@0:    * Return global keyboard shortcut for default action, such as Ctrl+O for
michael@0:    * Open file menuitem.
michael@0:    */
michael@0:   virtual KeyBinding KeyboardShortcut() const;
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // HyperLinkAccessible
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible is hyper link accessible.
michael@0:    */
michael@0:   virtual bool IsLink();
michael@0: 
michael@0:   /**
michael@0:    * Return the start offset of the link within the parent accessible.
michael@0:    */
michael@0:   virtual uint32_t StartOffset();
michael@0: 
michael@0:   /**
michael@0:    * Return the end offset of the link within the parent accessible.
michael@0:    */
michael@0:   virtual uint32_t EndOffset();
michael@0: 
michael@0:   /**
michael@0:    * Return true if the link is valid (e. g. points to a valid URL).
michael@0:    */
michael@0:   inline bool IsLinkValid()
michael@0:   {
michael@0:     NS_PRECONDITION(IsLink(), "IsLinkValid is called on not hyper link!");
michael@0: 
michael@0:     // XXX In order to implement this we would need to follow every link
michael@0:     // Perhaps we can get information about invalid links from the cache
michael@0:     // In the mean time authors can use role="link" aria-invalid="true"
michael@0:     // to force it for links they internally know to be invalid
michael@0:     return (0 == (State() & mozilla::a11y::states::INVALID));
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return the number of anchors within the link.
michael@0:    */
michael@0:   virtual uint32_t AnchorCount();
michael@0: 
michael@0:   /**
michael@0:    * Returns an anchor accessible at the given index.
michael@0:    */
michael@0:   virtual Accessible* AnchorAt(uint32_t aAnchorIndex);
michael@0: 
michael@0:   /**
michael@0:    * Returns an anchor URI at the given index.
michael@0:    */
michael@0:   virtual already_AddRefed<nsIURI> AnchorURIAt(uint32_t aAnchorIndex);
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // SelectAccessible
michael@0: 
michael@0:   /**
michael@0:    * Return an array of selected items.
michael@0:    */
michael@0:   virtual already_AddRefed<nsIArray> SelectedItems();
michael@0: 
michael@0:   /**
michael@0:    * Return the number of selected items.
michael@0:    */
michael@0:   virtual uint32_t SelectedItemCount();
michael@0: 
michael@0:   /**
michael@0:    * Return selected item at the given index.
michael@0:    */
michael@0:   virtual Accessible* GetSelectedItem(uint32_t aIndex);
michael@0: 
michael@0:   /**
michael@0:    * Determine if item at the given index is selected.
michael@0:    */
michael@0:   virtual bool IsItemSelected(uint32_t aIndex);
michael@0: 
michael@0:   /**
michael@0:    * Add item at the given index the selection. Return true if success.
michael@0:    */
michael@0:   virtual bool AddItemToSelection(uint32_t aIndex);
michael@0: 
michael@0:   /**
michael@0:    * Remove item at the given index from the selection. Return if success.
michael@0:    */
michael@0:   virtual bool RemoveItemFromSelection(uint32_t aIndex);
michael@0: 
michael@0:   /**
michael@0:    * Select all items. Return true if success.
michael@0:    */
michael@0:   virtual bool SelectAll();
michael@0: 
michael@0:   /**
michael@0:    * Unselect all items. Return true if success.
michael@0:    */
michael@0:   virtual bool UnselectAll();
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Value (numeric value interface)
michael@0: 
michael@0:   virtual double MaxValue() const;
michael@0:   virtual double MinValue() const;
michael@0:   virtual double CurValue() const;
michael@0:   virtual double Step() const;
michael@0:   virtual bool SetCurValue(double aValue);
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Widgets
michael@0: 
michael@0:   /**
michael@0:    * Return true if accessible is a widget, i.e. control or accessible that
michael@0:    * manages its items. Note, being a widget the accessible may be a part of
michael@0:    * composite widget.
michael@0:    */
michael@0:   virtual bool IsWidget() const;
michael@0: 
michael@0:   /**
michael@0:    * Return true if the widget is active, i.e. has a focus within it.
michael@0:    */
michael@0:   virtual bool IsActiveWidget() const;
michael@0: 
michael@0:   /**
michael@0:    * Return true if the widget has items and items are operable by user and
michael@0:    * can be activated.
michael@0:    */
michael@0:   virtual bool AreItemsOperable() const;
michael@0: 
michael@0:   /**
michael@0:    * Return the current item of the widget, i.e. an item that has or will have
michael@0:    * keyboard focus when widget gets active.
michael@0:    */
michael@0:   virtual Accessible* CurrentItem();
michael@0: 
michael@0:   /**
michael@0:    * Set the current item of the widget.
michael@0:    */
michael@0:   virtual void SetCurrentItem(Accessible* aItem);
michael@0: 
michael@0:   /**
michael@0:    * Return container widget this accessible belongs to.
michael@0:    */
michael@0:   virtual Accessible* ContainerWidget() const;
michael@0: 
michael@0:   /**
michael@0:    * Return the localized string for the given key.
michael@0:    */
michael@0:   static void TranslateString(const nsString& aKey, nsAString& aStringOut);
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible is defunct.
michael@0:    */
michael@0:   bool IsDefunct() const { return mStateFlags & eIsDefunct; }
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible is no longer in the document.
michael@0:    */
michael@0:   bool IsInDocument() const { return !(mStateFlags & eIsNotInDocument); }
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible should be contained by document node map.
michael@0:    */
michael@0:   bool IsNodeMapEntry() const
michael@0:     { return HasOwnContent() && !(mStateFlags & eNotNodeMapEntry); }
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible's group info needs to be updated.
michael@0:    */
michael@0:   inline bool HasDirtyGroupInfo() const { return mStateFlags & eGroupInfoDirty; }
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible has associated DOM content.
michael@0:    */
michael@0:   bool HasOwnContent() const
michael@0:     { return mContent && !(mStateFlags & eSharedNode); }
michael@0: 
michael@0:   /**
michael@0:   * Return true if the accessible has a numeric value.
michael@0:   */
michael@0:   bool HasNumericValue() const;
michael@0: 
michael@0:   /**
michael@0:    * Return true if the accessible state change is processed by handling proper
michael@0:    * DOM UI event, if otherwise then false. For example, HTMLCheckboxAccessible
michael@0:    * process nsIDocumentObserver::ContentStateChanged instead
michael@0:    * 'CheckboxStateChange' event.
michael@0:    */
michael@0:   bool NeedsDOMUIEvent() const
michael@0:     { return !(mStateFlags & eIgnoreDOMUIEvent); }
michael@0: 
michael@0:   /**
michael@0:    * Return true if this accessible has a parent whose name depends on this
michael@0:    * accessible.
michael@0:    */
michael@0:   bool HasNameDependentParent() const
michael@0:     { return mContextFlags & eHasNameDependentParent; }
michael@0: 
michael@0: protected:
michael@0: 
michael@0:   /**
michael@0:    * Return the accessible name provided by native markup. It doesn't take
michael@0:    * into account ARIA markup used to specify the name.
michael@0:    */
michael@0:   virtual mozilla::a11y::ENameValueFlag NativeName(nsString& aName);
michael@0: 
michael@0:   /**
michael@0:    * Return object attributes provided by native markup. It doesn't take into
michael@0:    * account ARIA.
michael@0:    */
michael@0:   virtual already_AddRefed<nsIPersistentProperties> NativeAttributes();
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Initializing, cache and tree traverse methods
michael@0: 
michael@0:   /**
michael@0:    * Destroy the object.
michael@0:    */
michael@0:   void LastRelease();
michael@0: 
michael@0:   /**
michael@0:    * Cache accessible children.
michael@0:    */
michael@0:   virtual void CacheChildren();
michael@0: 
michael@0:   /**
michael@0:    * Set accessible parent and index in parent.
michael@0:    */
michael@0:   virtual void BindToParent(Accessible* aParent, uint32_t aIndexInParent);
michael@0:   virtual void UnbindFromParent();
michael@0: 
michael@0:   /**
michael@0:    * Return sibling accessible at the given offset.
michael@0:    */
michael@0:   virtual Accessible* GetSiblingAtOffset(int32_t aOffset,
michael@0:                                          nsresult *aError = nullptr) const;
michael@0: 
michael@0:   /**
michael@0:    * Flags used to describe the state and type of children.
michael@0:    */
michael@0:   enum ChildrenFlags {
michael@0:     eChildrenUninitialized = 0, // children aren't initialized
michael@0:     eMixedChildren = 1 << 0, // text leaf children are presented
michael@0:     eEmbeddedChildren = 1 << 1, // all children are embedded objects
michael@0: 
michael@0:     eLastChildrenFlag = eEmbeddedChildren
michael@0:   };
michael@0: 
michael@0:   /**
michael@0:    * Return true if the children flag is set.
michael@0:    */
michael@0:   bool IsChildrenFlag(ChildrenFlags aFlag) const
michael@0:     { return static_cast<ChildrenFlags>(mChildrenFlags) == aFlag; }
michael@0: 
michael@0:   /**
michael@0:    * Set children flag.
michael@0:    */
michael@0:   void SetChildrenFlag(ChildrenFlags aFlag) { mChildrenFlags = aFlag; }
michael@0: 
michael@0:   /**
michael@0:    * Flags used to describe the state of this accessible.
michael@0:    * @note keep these flags in sync with ChildrenFlags
michael@0:    */
michael@0:   enum StateFlags {
michael@0:     eIsDefunct = 1 << 0, // accessible is defunct
michael@0:     eIsNotInDocument = 1 << 1, // accessible is not in document
michael@0:     eSharedNode = 1 << 2, // accessible shares DOM node from another accessible
michael@0:     eNotNodeMapEntry = 1 << 3, // accessible shouldn't be in document node map
michael@0:     eHasNumericValue = 1 << 4, // accessible has a numeric value
michael@0:     eGroupInfoDirty = 1 << 5, // accessible needs to update group info
michael@0:     eIgnoreDOMUIEvent = 1 << 6, // don't process DOM UI events for a11y events
michael@0: 
michael@0:     eLastStateFlag = eIgnoreDOMUIEvent
michael@0:   };
michael@0: 
michael@0:   /**
michael@0:    * Flags used for contextual information about the accessible.
michael@0:    */
michael@0:   enum ContextFlags {
michael@0:     eHasNameDependentParent = 1 << 0, // Parent's name depends on this accessible.
michael@0: 
michael@0:     eLastContextFlag = eHasNameDependentParent
michael@0:   };
michael@0: 
michael@0: protected:
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Miscellaneous helpers
michael@0: 
michael@0:   /**
michael@0:    * Return ARIA role (helper method).
michael@0:    */
michael@0:   mozilla::a11y::role ARIATransformRole(mozilla::a11y::role aRole);
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Name helpers
michael@0: 
michael@0:   /**
michael@0:    * Returns the accessible name specified by ARIA.
michael@0:    */
michael@0:   void ARIAName(nsString& aName);
michael@0: 
michael@0:   /**
michael@0:    * Return the name for XUL element.
michael@0:    */
michael@0:   static void XULElmName(DocAccessible* aDocument,
michael@0:                          nsIContent* aElm, nsString& aName);
michael@0: 
michael@0:   // helper method to verify frames
michael@0:   static nsresult GetFullKeyName(const nsAString& aModifierName, const nsAString& aKeyName, nsAString& aStringOut);
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Action helpers
michael@0: 
michael@0:   /**
michael@0:    * Prepares click action that will be invoked in timeout.
michael@0:    *
michael@0:    * @note  DoCommand() prepares an action in timeout because when action
michael@0:    *  command opens a modal dialog/window, it won't return until the
michael@0:    *  dialog/window is closed. If executing action command directly in
michael@0:    *  nsIAccessible::DoAction() method, it will block AT tools (e.g. GOK) that
michael@0:    *  invoke action of mozilla accessibles direclty (see bug 277888 for details).
michael@0:    *
michael@0:    * @param  aContent      [in, optional] element to click
michael@0:    * @param  aActionIndex  [in, optional] index of accessible action
michael@0:    */
michael@0:   void DoCommand(nsIContent *aContent = nullptr, uint32_t aActionIndex = 0);
michael@0: 
michael@0:   /**
michael@0:    * Dispatch click event.
michael@0:    */
michael@0:   virtual void DispatchClickEvent(nsIContent *aContent, uint32_t aActionIndex);
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // Helpers
michael@0: 
michael@0:   /**
michael@0:    *  Get the container node for an atomic region, defined by aria-atomic="true"
michael@0:    *  @return the container node
michael@0:    */
michael@0:   nsIContent* GetAtomicRegion() const;
michael@0: 
michael@0:   /**
michael@0:    * Return numeric value of the given ARIA attribute, NaN if not applicable.
michael@0:    *
michael@0:    * @param aARIAProperty  [in] the ARIA property we're using
michael@0:    * @return  a numeric value
michael@0:    */
michael@0:   double AttrNumericValue(nsIAtom* aARIAAttr) const;
michael@0: 
michael@0:   /**
michael@0:    * Return the action rule based on ARIA enum constants EActionRule
michael@0:    * (see ARIAMap.h). Used by ActionCount() and GetActionName().
michael@0:    */
michael@0:   uint32_t GetActionRule();
michael@0: 
michael@0:   /**
michael@0:    * Return group info.
michael@0:    */
michael@0:   AccGroupInfo* GetGroupInfo();
michael@0: 
michael@0:   /**
michael@0:    * Set dirty state of the accessible's group info.
michael@0:    */
michael@0:   inline void SetDirtyGroupInfo(bool aIsDirty)
michael@0:   {
michael@0:     if (aIsDirty)
michael@0:       mStateFlags |= eGroupInfoDirty;
michael@0:     else
michael@0:       mStateFlags &= ~eGroupInfoDirty;
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Flag all children group info as needing to be updated.
michael@0:    */
michael@0:   void InvalidateChildrenGroupInfo();
michael@0: 
michael@0:   // Data Members
michael@0:   nsCOMPtr<nsIContent> mContent;
michael@0:   DocAccessible* mDoc;
michael@0: 
michael@0:   nsRefPtr<Accessible> mParent;
michael@0:   nsTArray<nsRefPtr<Accessible> > mChildren;
michael@0:   int32_t mIndexInParent;
michael@0: 
michael@0:   static const uint8_t kChildrenFlagsBits = 2;
michael@0:   static const uint8_t kStateFlagsBits = 7;
michael@0:   static const uint8_t kContextFlagsBits = 1;
michael@0:   static const uint8_t kTypeBits = 6;
michael@0:   static const uint8_t kGenericTypesBits = 13;
michael@0: 
michael@0:   /**
michael@0:    * Keep in sync with ChildrenFlags, StateFlags, ContextFlags, and AccTypes.
michael@0:    */
michael@0:   uint32_t mChildrenFlags : kChildrenFlagsBits;
michael@0:   uint32_t mStateFlags : kStateFlagsBits;
michael@0:   uint32_t mContextFlags : kContextFlagsBits;
michael@0:   uint32_t mType : kTypeBits;
michael@0:   uint32_t mGenericTypes : kGenericTypesBits;
michael@0: 
michael@0:   void StaticAsserts() const;
michael@0: 
michael@0:   friend class DocAccessible;
michael@0: 
michael@0:   nsAutoPtr<mozilla::a11y::EmbeddedObjCollector> mEmbeddedObjCollector;
michael@0:   int32_t mIndexOfEmbeddedChild;
michael@0:   friend class EmbeddedObjCollector;
michael@0: 
michael@0:   nsAutoPtr<AccGroupInfo> mGroupInfo;
michael@0:   friend class AccGroupInfo;
michael@0: 
michael@0:   /**
michael@0:    * Non-null indicates author-supplied role; possibly state & value as well
michael@0:    */
michael@0:   nsRoleMapEntry* mRoleMapEntry;
michael@0: 
michael@0: private:
michael@0:   Accessible() MOZ_DELETE;
michael@0:   Accessible(const Accessible&) MOZ_DELETE;
michael@0:   Accessible& operator =(const Accessible&) MOZ_DELETE;
michael@0: 
michael@0: };
michael@0: 
michael@0: NS_DEFINE_STATIC_IID_ACCESSOR(Accessible,
michael@0:                               NS_ACCESSIBLE_IMPL_IID)
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Represent key binding associated with accessible (such as access key and
michael@0:  * global keyboard shortcuts).
michael@0:  */
michael@0: class KeyBinding
michael@0: {
michael@0: public:
michael@0:   /**
michael@0:    * Modifier mask values.
michael@0:    */
michael@0:   static const uint32_t kShift = 1;
michael@0:   static const uint32_t kControl = 2;
michael@0:   static const uint32_t kAlt = 4;
michael@0:   static const uint32_t kMeta = 8;
michael@0:   static const uint32_t kOS = 16;
michael@0: 
michael@0:   KeyBinding() : mKey(0), mModifierMask(0) {}
michael@0:   KeyBinding(uint32_t aKey, uint32_t aModifierMask) :
michael@0:     mKey(aKey), mModifierMask(aModifierMask) {}
michael@0: 
michael@0:   inline bool IsEmpty() const { return !mKey; }
michael@0:   inline uint32_t Key() const { return mKey; }
michael@0:   inline uint32_t ModifierMask() const { return mModifierMask; }
michael@0: 
michael@0:   enum Format {
michael@0:     ePlatformFormat,
michael@0:     eAtkFormat
michael@0:   };
michael@0: 
michael@0:   /**
michael@0:    * Return formatted string for this key binding depending on the given format.
michael@0:    */
michael@0:   inline void ToString(nsAString& aValue,
michael@0:                        Format aFormat = ePlatformFormat) const
michael@0:   {
michael@0:     aValue.Truncate();
michael@0:     AppendToString(aValue, aFormat);
michael@0:   }
michael@0:   inline void AppendToString(nsAString& aValue,
michael@0:                              Format aFormat = ePlatformFormat) const
michael@0:   {
michael@0:     if (mKey) {
michael@0:       if (aFormat == ePlatformFormat)
michael@0:         ToPlatformFormat(aValue);
michael@0:       else
michael@0:         ToAtkFormat(aValue);
michael@0:     }
michael@0:   }
michael@0: 
michael@0: private:
michael@0:   void ToPlatformFormat(nsAString& aValue) const;
michael@0:   void ToAtkFormat(nsAString& aValue) const;
michael@0: 
michael@0:   uint32_t mKey;
michael@0:   uint32_t mModifierMask;
michael@0: };
michael@0: 
michael@0: } // namespace a11y
michael@0: } // namespace mozilla
michael@0: 
michael@0: #endif