accessible/src/base/nsAccessible.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   John Gaunt (jgaunt@netscape.com)
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #ifndef _nsAccessible_H_
  40 #define _nsAccessible_H_
  41
  42 #include "nsAccessNodeWrap.h"
  43
  44 #include "nsIAccessible.h"
  45 #include "nsPIAccessible.h"
  46 #include "nsIAccessibleHyperLink.h"
  47 #include "nsIAccessibleSelectable.h"
  48 #include "nsIAccessibleValue.h"
  49 #include "nsIAccessibleRole.h"
  50 #include "nsIAccessibleStates.h"
  51 #include "nsAccessibleRelationWrap.h"
  52 #include "nsIAccessibleEvent.h"
  53
  54 #include "nsIDOMNodeList.h"
  55 #include "nsINameSpaceManager.h"
  56 #include "nsWeakReference.h"
  57 #include "nsString.h"
  58 #include "nsIDOMDOMStringList.h"
  59 #include "nsARIAMap.h"
  60
  61 struct nsRect;
  62 class nsIContent;
  63 class nsIFrame;
  64 class nsIPresShell;
  65 class nsIDOMNode;
  66 class nsIAtom;
  67 class nsIView;
  68
  69 // see nsAccessible::GetAttrValue
  70 #define NS_OK_NO_ARIA_VALUE \
  71 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_GENERAL, 0x21)
  72
  73 // see nsAccessible::GetNameInternal
  74 #define NS_OK_EMPTY_NAME \
  75 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_GENERAL, 0x23)
  76
  77 // Saves a data member -- if child count equals this value we haven't
  78 // cached children or child count yet
  79 enum { eChildCountUninitialized = -1 };
  80
  81 class nsAccessibleDOMStringList : public nsIDOMDOMStringList
  82 {
  83 public:
  84   nsAccessibleDOMStringList();
  85   virtual ~nsAccessibleDOMStringList();
  86
  87   NS_DECL_ISUPPORTS
  88   NS_DECL_NSIDOMDOMSTRINGLIST
  89
  90   PRBool Add(const nsAString& aName) {
  91     return mNames.AppendString(aName);
  92   }
  93
  94 private:
  95   nsStringArray mNames;
  96 };
  97
  98
  99 #define NS_ACCESSIBLE_IMPL_CID                          \
 100 {  /* 4E36C7A8-9203-4ef9-B619-271DDF6BB839 */           \
 101   0x4e36c7a8,                                           \
 102   0x9203,                                               \
 103   0x4ef9,                                               \
 104   { 0xb6, 0x19, 0x27, 0x1d, 0xdf, 0x6b, 0xb8, 0x39 }    \
 105 }
 106
 107 class nsAccessible : public nsAccessNodeWrap,
 108                      public nsIAccessible,
 109                      public nsPIAccessible,
 110                      public nsIAccessibleHyperLink,
 111                      public nsIAccessibleSelectable,
 112                      public nsIAccessibleValue
 113 {
 114 public:
 115   nsAccessible(nsIDOMNode* aNode, nsIWeakReference* aShell);
 116   virtual ~nsAccessible();
 117
 118   NS_DECL_ISUPPORTS_INHERITED
 119   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(nsAccessible, nsAccessNode)
 120
 121   NS_DECL_NSIACCESSIBLE
 122   NS_DECL_NSPIACCESSIBLE
 123   NS_DECL_NSIACCESSIBLEHYPERLINK
 124   NS_DECL_NSIACCESSIBLESELECTABLE
 125   NS_DECL_NSIACCESSIBLEVALUE
 126   NS_DECLARE_STATIC_IID_ACCESSOR(NS_ACCESSIBLE_IMPL_CID)
 127
 128   //////////////////////////////////////////////////////////////////////////////
 129   // nsAccessNode
 130
 131   virtual nsresult Shutdown();
 132
 133   //////////////////////////////////////////////////////////////////////////////
 134   // Public methods
 135
 136   /**
 137    * Returns the accessible name specified by ARIA.
 138    */
 139   nsresult GetARIAName(nsAString& aName);
 140
 141   /**
 142    * Returns the accessible name provided by native markup. It doesn't take
 143    * into account ARIA markup used to specify the name.
 144    *
 145    * @param  aName             [out] the accessible name
 146    *
 147    * @return NS_OK_EMPTY_NAME  points empty name was specified by native markup
 148    *                           explicitly (see nsIAccessible::name attribute for
 149    *                           details)
 150    */
 151   virtual nsresult GetNameInternal(nsAString& aName);
 152
 153   /**
 154    * Return the state of accessible that doesn't take into account ARIA states.
 155    * Use nsIAccessible::state to get all states for accessible. If
 156    * second argument is omitted then second bit field of accessible state won't
 157    * be calculated.
 158    */
 159   virtual nsresult GetStateInternal(PRUint32 *aState, PRUint32 *aExtraState);
 160
 161   /**
 162    * Returns attributes for accessible without explicitly setted ARIA
 163    * attributes.
 164    */
 165   virtual nsresult GetAttributesInternal(nsIPersistentProperties *aAttributes);
 166
 167   //////////////////////////////////////////////////////////////////////////////
 168   // Helper methods
 169
 170   already_AddRefed<nsIAccessible> GetParent() {
 171     nsIAccessible *parent = nsnull;
 172     GetParent(&parent);
 173     return parent;
 174   }
 175
 176 protected:
 177   PRBool MappedAttrState(nsIContent *aContent, PRUint32 *aStateInOut, nsStateMapEntry *aStateMapEntry);
 178   virtual nsIFrame* GetBoundsFrame();
 179   virtual void GetBoundsRect(nsRect& aRect, nsIFrame** aRelativeFrame);
 180   PRBool IsVisible(PRBool *aIsOffscreen);
 181
 182   // Relation helpers
 183
 184   /**
 185    * For a given ARIA relation, such as labelledby or describedby, get the collated text
 186    * for the subtree that's pointed to.
 187    *
 188    * @param aIDProperty  The ARIA relationship property to get the text for
 189    * @param aName        Where to put the text
 190    * @return error or success code
 191    */
 192   nsresult GetTextFromRelationID(nsIAtom *aIDProperty, nsString &aName);
 193
 194   //////////////////////////////////////////////////////////////////////////////
 195   // Name helpers.
 196
 197   /**
 198    * Compute the name of HTML node.
 199    */
 200   nsresult GetHTMLName(nsAString& aName);
 201
 202   /**
 203    * Compute the name for XUL node.
 204    */
 205   nsresult GetXULName(nsAString& aName);
 206
 207   // For accessibles that are not lists of choices, the name of the subtree should be the
 208   // sum of names in the subtree
 209   nsresult AppendFlatStringFromSubtree(nsIContent *aContent, nsAString *aFlatString);
 210   nsresult AppendNameFromAccessibleFor(nsIContent *aContent, nsAString *aFlatString,
 211                                        PRBool aFromValue = PR_FALSE);
 212   nsresult AppendFlatStringFromContentNode(nsIContent *aContent, nsAString *aFlatString);
 213   nsresult AppendStringWithSpaces(nsAString *aFlatString, const nsAString& textEquivalent);
 214
 215   // helper method to verify frames
 216   static nsresult GetFullKeyName(const nsAString& aModifierName, const nsAString& aKeyName, nsAString& aStringOut);
 217   static nsresult GetTranslatedString(const nsAString& aKey, nsAString& aStringOut);
 218
 219   /**
 220    * Walk into subtree and calculate the string which is used as the accessible
 221    * name or description.
 222    *
 223    * @param aContent      [in] traversed content
 224    * @param aFlatString   [in, out] result string
 225    * @param aIsRootHidden [in] specifies whether root content (we started to
 226    *                      traverse from) is hidden, in this case the result
 227    *                      string is calculated from hidden children
 228    *                      (this is used when hidden root content is explicitly
 229    *                      specified as label or description by author)
 230    */
 231   nsresult AppendFlatStringFromSubtreeRecurse(nsIContent *aContent,
 232                                               nsAString *aFlatString,
 233                                               PRBool aIsRootHidden);
 234
 235   // Helpers for dealing with children
 236   virtual void CacheChildren();
 237
 238   // nsCOMPtr<>& is useful here, because getter_AddRefs() nulls the comptr's value, and NextChild
 239   // depends on the passed-in comptr being null or already set to a child (finding the next sibling).
 240   nsIAccessible *NextChild(nsCOMPtr<nsIAccessible>& aAccessible);
 241
 242   already_AddRefed<nsIAccessible> GetNextWithState(nsIAccessible *aStart, PRUint32 matchState);
 243
 244   /**
 245    * Return an accessible for the given DOM node, or if that node isn't accessible, return the
 246    * accessible for the next DOM node which has one (based on forward depth first search)
 247    * @param aStartNode, the DOM node to start from
 248    * @param aRequireLeaf, only accept leaf accessible nodes
 249    * @return the resulting accessible
 250    */
 251   already_AddRefed<nsIAccessible> GetFirstAvailableAccessible(nsIDOMNode *aStartNode, PRBool aRequireLeaf = PR_FALSE);
 252
 253   // Hyperlink helpers
 254   virtual nsresult GetLinkOffset(PRInt32* aStartOffset, PRInt32* aEndOffset);
 255
 256   // For accessibles that have actions
 257   static void DoCommandCallback(nsITimer *aTimer, void *aClosure);
 258   nsresult DoCommand(nsIContent *aContent = nsnull);
 259
 260   // Check the visibility across both parent content and chrome
 261   PRBool CheckVisibilityInParentChain(nsIDocument* aDocument, nsIView* aView);
 262
 263   /**
 264    *  Get the container node for an atomic region, defined by aria-atomic="true"
 265    *  @return the container node
 266    */
 267   nsIDOMNode* GetAtomicRegion();
 268
 269   /**
 270    * Get numeric value of the given ARIA attribute.
 271    *
 272    * @param aAriaProperty - the ARIA property we're using
 273    * @param aValue - value of the attribute
 274    *
 275    * @return - NS_OK_NO_ARIA_VALUE if there is no setted ARIA attribute
 276    */
 277   nsresult GetAttrValue(nsIAtom *aAriaProperty, double *aValue);
 278
 279   /**
 280    * Return the action rule based on ARIA enum constants EActionRule
 281    * (see nsARIAMap.h). Used by GetNumActions() and GetActionName().
 282    *
 283    * @param aStates  [in] states of the accessible
 284    */
 285   PRUint32 GetActionRule(PRUint32 aStates);
 286
 287   /**
 288    * Fires platform accessible event. It's notification method only. It does
 289    * change nothing on Gecko side. Mostly you should use
 290    * nsIAccessible::FireAccessibleEvent excepting special cases like we have
 291    * in xul:tree accessible to lie to AT. Must be overridden in wrap classes.
 292    *
 293    * @param aEvent  the accessible event to fire.
 294    */
 295   virtual nsresult FirePlatformEvent(nsIAccessibleEvent *aEvent) = 0;
 296
 297   // Data Members
 298   nsCOMPtr<nsIAccessible> mParent;
 299   nsCOMPtr<nsIAccessible> mFirstChild;
 300   nsCOMPtr<nsIAccessible> mNextSibling;
 301
 302   nsRoleMapEntry *mRoleMapEntry; // Non-null indicates author-supplied role; possibly state & value as well
 303   PRInt32 mAccChildCount;
 304 };
 305
 306 NS_DEFINE_STATIC_IID_ACCESSOR(nsAccessible,
 307                               NS_ACCESSIBLE_IMPL_CID)
 308
 309 #endif
 310