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 nsAccUtils_h_
michael@0: #define nsAccUtils_h_
michael@0: 
michael@0: #include "mozilla/a11y/Accessible.h"
michael@0: 
michael@0: #include "nsAccessibilityService.h"
michael@0: #include "nsCoreUtils.h"
michael@0: 
michael@0: #include "nsIDocShell.h"
michael@0: #include "nsPoint.h"
michael@0: 
michael@0: namespace mozilla {
michael@0: 
michael@0: namespace dom {
michael@0: class Element;
michael@0: }
michael@0: 
michael@0: namespace a11y {
michael@0: 
michael@0: class HyperTextAccessible;
michael@0: class DocAccessible;
michael@0: 
michael@0: class nsAccUtils
michael@0: {
michael@0: public:
michael@0:   /**
michael@0:    * Returns value of attribute from the given attributes container.
michael@0:    *
michael@0:    * @param aAttributes - attributes container
michael@0:    * @param aAttrName - the name of requested attribute
michael@0:    * @param aAttrValue - value of attribute
michael@0:    */
michael@0:   static void GetAccAttr(nsIPersistentProperties *aAttributes,
michael@0:                          nsIAtom *aAttrName,
michael@0:                          nsAString& aAttrValue);
michael@0: 
michael@0:   /**
michael@0:    * Set value of attribute for the given attributes container.
michael@0:    *
michael@0:    * @param aAttributes - attributes container
michael@0:    * @param aAttrName - the name of requested attribute
michael@0:    * @param aAttrValue - new value of attribute
michael@0:    */
michael@0:   static void SetAccAttr(nsIPersistentProperties *aAttributes,
michael@0:                          nsIAtom *aAttrName,
michael@0:                          const nsAString& aAttrValue);
michael@0: 
michael@0:   /**
michael@0:    * Set group attributes ('level', 'setsize', 'posinset').
michael@0:    */
michael@0:   static void SetAccGroupAttrs(nsIPersistentProperties *aAttributes,
michael@0:                                int32_t aLevel, int32_t aSetSize,
michael@0:                                int32_t aPosInSet);
michael@0: 
michael@0:   /**
michael@0:    * Get default value of the level for the given accessible.
michael@0:    */
michael@0:   static int32_t GetDefaultLevel(Accessible* aAcc);
michael@0: 
michael@0:   /**
michael@0:    * Return ARIA level value or the default one if ARIA is missed for the
michael@0:    * given accessible.
michael@0:    */
michael@0:   static int32_t GetARIAOrDefaultLevel(Accessible* aAccessible);
michael@0: 
michael@0:   /**
michael@0:    * Compute group level for nsIDOMXULContainerItemElement node.
michael@0:    */
michael@0:   static int32_t GetLevelForXULContainerItem(nsIContent *aContent);
michael@0: 
michael@0:   /**
michael@0:    * Set container-foo live region attributes for the given node.
michael@0:    *
michael@0:    * @param aAttributes    where to store the attributes
michael@0:    * @param aStartContent  node to start from
michael@0:    * @param aTopContent    node to end at
michael@0:    */
michael@0:   static void SetLiveContainerAttributes(nsIPersistentProperties *aAttributes,
michael@0:                                          nsIContent *aStartContent,
michael@0:                                          nsIContent *aTopContent);
michael@0: 
michael@0:   /**
michael@0:    * Any ARIA property of type boolean or NMTOKEN is undefined if the ARIA
michael@0:    * property is not present, or is "" or "undefined". Do not call 
michael@0:    * this method for properties of type string, decimal, IDREF or IDREFS.
michael@0:    * 
michael@0:    * Return true if the ARIA property is defined, otherwise false
michael@0:    */
michael@0:   static bool HasDefinedARIAToken(nsIContent *aContent, nsIAtom *aAtom);
michael@0: 
michael@0:   /**
michael@0:    * Return atomic value of ARIA attribute of boolean or NMTOKEN type.
michael@0:    */
michael@0:   static nsIAtom* GetARIAToken(mozilla::dom::Element* aElement, nsIAtom* aAttr);
michael@0: 
michael@0:   /**
michael@0:    * Return document accessible for the given DOM node.
michael@0:    */
michael@0:   static DocAccessible* GetDocAccessibleFor(nsINode* aNode)
michael@0:   {
michael@0:     nsIPresShell *presShell = nsCoreUtils::GetPresShellFor(aNode);
michael@0:     return GetAccService()->GetDocAccessible(presShell);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return document accessible for the given docshell.
michael@0:    */
michael@0:   static DocAccessible* GetDocAccessibleFor(nsIDocShellTreeItem* aContainer)
michael@0:   {
michael@0:     nsCOMPtr<nsIDocShell> docShell(do_QueryInterface(aContainer));
michael@0:     return GetAccService()->GetDocAccessible(docShell->GetPresShell());
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return single or multi selectable container for the given item.
michael@0:    *
michael@0:    * @param  aAccessible  [in] the item accessible
michael@0:    * @param  aState       [in] the state of the item accessible
michael@0:    */
michael@0:   static Accessible* GetSelectableContainer(Accessible* aAccessible,
michael@0:                                             uint64_t aState);
michael@0: 
michael@0:   /**
michael@0:    * Return a text container accessible for the given node.
michael@0:    */
michael@0:   static HyperTextAccessible* GetTextContainer(nsINode* aNode);
michael@0: 
michael@0:   /**
michael@0:    * Return true if the DOM node of given accessible has aria-selected="true"
michael@0:    * attribute.
michael@0:    */
michael@0:   static bool IsARIASelected(Accessible* aAccessible);
michael@0: 
michael@0:   /**
michael@0:    * Converts the given coordinates to coordinates relative screen.
michael@0:    *
michael@0:    * @param aX               [in] the given x coord
michael@0:    * @param aY               [in] the given y coord
michael@0:    * @param aCoordinateType  [in] specifies coordinates origin (refer to
michael@0:    *                         nsIAccessibleCoordinateType)
michael@0:    * @param aAccessible      [in] the accessible if coordinates are given
michael@0:    *                         relative it.
michael@0:    * @return converted coordinates
michael@0:    */
michael@0:   static nsIntPoint ConvertToScreenCoords(int32_t aX, int32_t aY,
michael@0:                                           uint32_t aCoordinateType,
michael@0:                                           Accessible* aAccessible);
michael@0: 
michael@0:   /**
michael@0:    * Converts the given coordinates relative screen to another coordinate
michael@0:    * system.
michael@0:    *
michael@0:    * @param aX               [in, out] the given x coord
michael@0:    * @param aY               [in, out] the given y coord
michael@0:    * @param aCoordinateType  [in] specifies coordinates origin (refer to
michael@0:    *                         nsIAccessibleCoordinateType)
michael@0:    * @param aAccessible      [in] the accessible if coordinates are given
michael@0:    *                         relative it
michael@0:    */
michael@0:   static void ConvertScreenCoordsTo(int32_t* aX, int32_t* aY,
michael@0:                                     uint32_t aCoordinateType,
michael@0:                                     Accessible* aAccessible);
michael@0: 
michael@0:   /**
michael@0:    * Returns coordinates relative screen for the parent of the given accessible.
michael@0:    *
michael@0:    * @param [in] aAccessible  the accessible
michael@0:    */
michael@0:   static nsIntPoint GetScreenCoordsForParent(Accessible* aAccessible);
michael@0: 
michael@0:   /**
michael@0:    * Get the 'live' or 'container-live' object attribute value from the given
michael@0:    * ELiveAttrRule constant.
michael@0:    *
michael@0:    * @param  aRule   [in] rule constant (see ELiveAttrRule in nsAccMap.h)
michael@0:    * @param  aValue  [out] object attribute value
michael@0:    *
michael@0:    * @return         true if object attribute should be exposed
michael@0:    */
michael@0:   static bool GetLiveAttrValue(uint32_t aRule, nsAString& aValue);
michael@0: 
michael@0: #ifdef DEBUG
michael@0:   /**
michael@0:    * Detect whether the given accessible object implements nsIAccessibleText,
michael@0:    * when it is text or has text child node.
michael@0:    */
michael@0:   static bool IsTextInterfaceSupportCorrect(Accessible* aAccessible);
michael@0: #endif
michael@0: 
michael@0:   /**
michael@0:    * Return text length of the given accessible, return 0 on failure.
michael@0:    */
michael@0:   static uint32_t TextLength(Accessible* aAccessible);
michael@0: 
michael@0:   /**
michael@0:    * Return true if the given accessible is embedded object.
michael@0:    */
michael@0:   static bool IsEmbeddedObject(Accessible* aAcc)
michael@0:   {
michael@0:     uint32_t role = aAcc->Role();
michael@0:     return role != roles::TEXT_LEAF &&
michael@0:            role != roles::WHITESPACE &&
michael@0:            role != roles::STATICTEXT;
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Transform nsIAccessibleStates constants to internal state constant.
michael@0:    */
michael@0:   static inline uint64_t To64State(uint32_t aState1, uint32_t aState2)
michael@0:   {
michael@0:     return static_cast<uint64_t>(aState1) +
michael@0:         (static_cast<uint64_t>(aState2) << 31);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Transform internal state constant to nsIAccessibleStates constants.
michael@0:    */
michael@0:   static inline void To32States(uint64_t aState64,
michael@0:                                 uint32_t* aState1, uint32_t* aState2)
michael@0:   {
michael@0:     *aState1 = aState64 & 0x7fffffff;
michael@0:     if (aState2)
michael@0:       *aState2 = static_cast<uint32_t>(aState64 >> 31);
michael@0:   }
michael@0: 
michael@0:   static uint32_t To32States(uint64_t aState, bool* aIsExtra)
michael@0:   {
michael@0:     uint32_t extraState = aState >> 31;
michael@0:     *aIsExtra = !!extraState;
michael@0:     return aState | extraState;
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return true if the given accessible can't have children. Used when exposing
michael@0:    * to platform accessibility APIs, should the children be pruned off?
michael@0:    */
michael@0:   static bool MustPrune(Accessible* aAccessible);
michael@0: };
michael@0: 
michael@0: } // namespace a11y
michael@0: } // namespace mozilla
michael@0: 
michael@0: #endif