michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* vim:expandtab:shiftwidth=2:tabstop=2:
michael@0:  */
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 _nsTextEquivUtils_H_
michael@0: #define _nsTextEquivUtils_H_
michael@0: 
michael@0: #include "Accessible.h"
michael@0: #include "Role.h"
michael@0: 
michael@0: class nsIContent;
michael@0: 
michael@0: /**
michael@0:  * Text equivalent computation rules (see nsTextEquivUtils::gRoleToNameRulesMap)
michael@0:  */
michael@0: enum ETextEquivRule
michael@0: {
michael@0:   // No rule.
michael@0:   eNoNameRule = 0x00,
michael@0: 
michael@0:   // Walk into subtree only if the currently navigated accessible is not root
michael@0:   // accessible (i.e. if the accessible is part of text equivalent computation).
michael@0:   eNameFromSubtreeIfReqRule = 0x01,
michael@0: 
michael@0:   // Text equivalent computation from subtree is allowed.
michael@0:   eNameFromSubtreeRule = 0x03,
michael@0: 
michael@0:   // The accessible allows to append its value to text equivalent.
michael@0:   // XXX: This is temporary solution. Once we move accessible value of links
michael@0:   // and linkable accessibles to MSAA part we can remove this.
michael@0:   eNameFromValueRule = 0x04
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * The class provides utils methods to compute the accessible name and
michael@0:  * description.
michael@0:  */
michael@0: class nsTextEquivUtils
michael@0: {
michael@0: public:
michael@0:   typedef mozilla::a11y::Accessible Accessible;
michael@0: 
michael@0:   /**
michael@0:    * Determines if the accessible has a given name rule.
michael@0:    *
michael@0:    * @param aAccessible [in] the given accessible
michael@0:    * @param aRule       [in] a given name rule
michael@0:    * @return true if the accessible has the rule
michael@0:    */
michael@0:   static inline bool HasNameRule(Accessible* aAccessible, ETextEquivRule aRule)
michael@0:   {
michael@0:     return (GetRoleRule(aAccessible->Role()) & aRule) == aRule;
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Calculates the name from accessible subtree if allowed.
michael@0:    *
michael@0:    * @param aAccessible [in] the given accessible
michael@0:    * @param aName       [out] accessible name
michael@0:    */
michael@0:   static nsresult GetNameFromSubtree(Accessible* aAccessible,
michael@0:                                      nsAString& aName);
michael@0: 
michael@0:   /**
michael@0:    * Calculates text equivalent from the subtree. Similar to GetNameFromSubtree.
michael@0:    * However it returns not empty result for things like HTML p.
michael@0:    */
michael@0:   static void GetTextEquivFromSubtree(Accessible* aAccessible,
michael@0:                                       nsString& aTextEquiv)
michael@0:   {
michael@0:     aTextEquiv.Truncate();
michael@0: 
michael@0:     AppendFromAccessibleChildren(aAccessible, &aTextEquiv);
michael@0:     aTextEquiv.CompressWhitespace();
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Calculates text equivalent for the given accessible from its IDRefs
michael@0:    * attribute (like aria-labelledby or aria-describedby).
michael@0:    *
michael@0:    * @param aAccessible  [in] the accessible text equivalent is computed for
michael@0:    * @param aIDRefsAttr  [in] IDRefs attribute on DOM node of the accessible
michael@0:    * @param aTextEquiv   [out] result text equivalent
michael@0:    */
michael@0:   static nsresult GetTextEquivFromIDRefs(Accessible* aAccessible,
michael@0:                                          nsIAtom *aIDRefsAttr,
michael@0:                                          nsAString& aTextEquiv);
michael@0: 
michael@0:   /**
michael@0:    * Calculates the text equivalent from the given content and its subtree if
michael@0:    * allowed and appends it to the given string.
michael@0:    *
michael@0:    * @param aInitiatorAcc  [in] the accessible text equivalent is computed for
michael@0:    *                       in the end (root accessible of text equivalent
michael@0:    *                       calculation recursion)
michael@0:    * @param aContent       [in] the given content the text equivalent is
michael@0:    *                       computed from
michael@0:    * @param aString        [in, out] the string
michael@0:    */
michael@0:   static nsresult AppendTextEquivFromContent(Accessible* aInitiatorAcc,
michael@0:                                              nsIContent *aContent,
michael@0:                                              nsAString *aString);
michael@0: 
michael@0:   /**
michael@0:    * Calculates the text equivalent from the given text content (may be text
michael@0:    * node or html:br) and appends it to the given string.
michael@0:    *
michael@0:    * @param aContent       [in] the text content
michael@0:    * @param aString        [in, out] the string
michael@0:    */
michael@0:   static nsresult AppendTextEquivFromTextContent(nsIContent *aContent,
michael@0:                                                  nsAString *aString);
michael@0: 
michael@0: private:
michael@0:   /**
michael@0:    * Iterates accessible children and calculates text equivalent from each
michael@0:    * child.
michael@0:    */
michael@0:   static nsresult AppendFromAccessibleChildren(Accessible* aAccessible,
michael@0:                                                nsAString *aString);
michael@0:   
michael@0:   /**
michael@0:    * Calculates text equivalent from the given accessible and its subtree if
michael@0:    * allowed.
michael@0:    */
michael@0:   static nsresult AppendFromAccessible(Accessible* aAccessible,
michael@0:                                        nsAString *aString);
michael@0: 
michael@0:   /**
michael@0:    * Calculates text equivalent from the value of given accessible.
michael@0:    */
michael@0:   static nsresult AppendFromValue(Accessible* aAccessible,
michael@0:                                   nsAString *aString);
michael@0:   /**
michael@0:    * Iterates DOM children and calculates text equivalent from each child node.
michael@0:    */
michael@0:   static nsresult AppendFromDOMChildren(nsIContent *aContent,
michael@0:                                         nsAString *aString);
michael@0: 
michael@0:   /**
michael@0:    * Calculates text equivalent from the given DOM node and its subtree if
michael@0:    * allowed.
michael@0:    */
michael@0:   static nsresult AppendFromDOMNode(nsIContent *aContent, nsAString *aString);
michael@0: 
michael@0:   /**
michael@0:    * Concatenates strings and appends space between them. Returns true if
michael@0:    * text equivalent string was appended.
michael@0:    */
michael@0:   static bool AppendString(nsAString *aString,
michael@0:                              const nsAString& aTextEquivalent);
michael@0: 
michael@0:   /**
michael@0:    * Returns the rule (constant of ETextEquivRule) for a given role.
michael@0:    */
michael@0:   static uint32_t GetRoleRule(mozilla::a11y::roles::Role aRole);
michael@0: };
michael@0: 
michael@0: #endif