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 #define NS_OK_NO_ARIA_VALUE \
  70 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_GENERAL, 0x21)
  71
  72 // Saves a data member -- if child count equals this value we haven't
  73 // cached children or child count yet
  74 enum { eChildCountUninitialized = -1 };
  75
  76 class nsAccessibleDOMStringList : public nsIDOMDOMStringList
  77 {
  78 public:
  79   nsAccessibleDOMStringList();
  80   virtual ~nsAccessibleDOMStringList();
  81
  82   NS_DECL_ISUPPORTS
  83   NS_DECL_NSIDOMDOMSTRINGLIST
  84
  85   PRBool Add(const nsAString& aName) {
  86     return mNames.AppendString(aName);
  87   }
  88
  89 private:
  90   nsStringArray mNames;
  91 };
  92
  93
  94 #define NS_ACCESSIBLE_IMPL_CID                          \
  95 {  /* 4E36C7A8-9203-4ef9-B619-271DDF6BB839 */           \
  96   0x4e36c7a8,                                           \
  97   0x9203,                                               \
  98   0x4ef9,                                               \
  99   { 0xb6, 0x19, 0x27, 0x1d, 0xdf, 0x6b, 0xb8, 0x39 }    \
 100 }
 101
 102 class nsAccessible : public nsAccessNodeWrap,
 103                      public nsIAccessible,
 104                      public nsPIAccessible,
 105                      public nsIAccessibleHyperLink,
 106                      public nsIAccessibleSelectable,
 107                      public nsIAccessibleValue
 108 {
 109 public:
 110   nsAccessible(nsIDOMNode* aNode, nsIWeakReference* aShell);
 111   virtual ~nsAccessible();
 112
 113   NS_DECL_ISUPPORTS_INHERITED
 114   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(nsAccessible, nsAccessNode)
 115
 116   NS_DECL_NSIACCESSIBLE
 117   NS_DECL_NSPIACCESSIBLE
 118   NS_DECL_NSIACCESSIBLEHYPERLINK
 119   NS_DECL_NSIACCESSIBLESELECTABLE
 120   NS_DECL_NSIACCESSIBLEVALUE
 121   NS_DECLARE_STATIC_IID_ACCESSOR(NS_ACCESSIBLE_IMPL_CID)
 122
 123   //////////////////////////////////////////////////////////////////////////////
 124   // nsAccessNode
 125
 126   virtual nsresult Shutdown();
 127
 128   //////////////////////////////////////////////////////////////////////////////
 129   // Public methods
 130
 131   /**
 132    * Returns the accessible name specified by ARIA.
 133    */
 134   nsresult GetARIAName(nsAString& aName);
 135
 136   /**
 137    * Returns the accessible name provided by native markup. It doesn't take
 138    * into account ARIA stuffs used to specify the name.
 139    */
 140   virtual nsresult GetNameInternal(nsAString& aName);
 141
 142   /**
 143    * Return the state of accessible that doesn't take into account ARIA states.
 144    * Use nsIAccessible::state to get all states for accessible. If
 145    * second argument is omitted then second bit field of accessible state won't
 146    * be calculated.
 147    */
 148   virtual nsresult GetStateInternal(PRUint32 *aState, PRUint32 *aExtraState);
 149
 150   /**
 151    * Returns attributes for accessible without explicitly setted ARIA
 152    * attributes.
 153    */
 154   virtual nsresult GetAttributesInternal(nsIPersistentProperties *aAttributes);
 155
 156   //////////////////////////////////////////////////////////////////////////////
 157   // Helper methods
 158
 159   already_AddRefed<nsIAccessible> GetParent() {
 160     nsIAccessible *parent = nsnull;
 161     GetParent(&parent);
 162     return parent;
 163   }
 164
 165 protected:
 166   PRBool MappedAttrState(nsIContent *aContent, PRUint32 *aStateInOut, nsStateMapEntry *aStateMapEntry);
 167   virtual nsIFrame* GetBoundsFrame();
 168   virtual void GetBoundsRect(nsRect& aRect, nsIFrame** aRelativeFrame);
 169   PRBool IsVisible(PRBool *aIsOffscreen);
 170
 171   // Relation helpers
 172
 173   /**
 174    * For a given ARIA relation, such as labelledby or describedby, get the collated text
 175    * for the subtree that's pointed to.
 176    *
 177    * @param aIDProperty  The ARIA relationship property to get the text for
 178    * @param aName        Where to put the text
 179    * @return error or success code
 180    */
 181   nsresult GetTextFromRelationID(nsIAtom *aIDProperty, nsString &aName);
 182
 183   //////////////////////////////////////////////////////////////////////////////
 184   // Name helpers.
 185
 186   /**
 187    * Compute the name of HTML node.
 188    */
 189   nsresult GetHTMLName(nsAString& aName);
 190
 191   /**
 192    * Compute the name for XUL node.
 193    */
 194   nsresult GetXULName(nsAString& aName);
 195
 196   // For accessibles that are not lists of choices, the name of the subtree should be the
 197   // sum of names in the subtree
 198   nsresult AppendFlatStringFromSubtree(nsIContent *aContent, nsAString *aFlatString);
 199   nsresult AppendNameFromAccessibleFor(nsIContent *aContent, nsAString *aFlatString,
 200                                        PRBool aFromValue = PR_FALSE);
 201   nsresult AppendFlatStringFromContentNode(nsIContent *aContent, nsAString *aFlatString);
 202   nsresult AppendStringWithSpaces(nsAString *aFlatString, const nsAString& textEquivalent);
 203
 204   // helper method to verify frames
 205   static nsresult GetFullKeyName(const nsAString& aModifierName, const nsAString& aKeyName, nsAString& aStringOut);
 206   static nsresult GetTranslatedString(const nsAString& aKey, nsAString& aStringOut);
 207
 208   /**
 209    * Walk into subtree and calculate the string which is used as the accessible
 210    * name or description.
 211    *
 212    * @param aContent      [in] traversed content
 213    * @param aFlatString   [in, out] result string
 214    * @param aIsRootHidden [in] specifies whether root content (we started to
 215    *                      traverse from) is hidden, in this case the result
 216    *                      string is calculated from hidden children
 217    *                      (this is used when hidden root content is explicitly
 218    *                      specified as label or description by author)
 219    */
 220   nsresult AppendFlatStringFromSubtreeRecurse(nsIContent *aContent,
 221                                               nsAString *aFlatString,
 222                                               PRBool aIsRootHidden);
 223
 224   // Helpers for dealing with children
 225   virtual void CacheChildren();
 226
 227   // nsCOMPtr<>& is useful here, because getter_AddRefs() nulls the comptr's value, and NextChild
 228   // depends on the passed-in comptr being null or already set to a child (finding the next sibling).
 229   nsIAccessible *NextChild(nsCOMPtr<nsIAccessible>& aAccessible);
 230
 231   already_AddRefed<nsIAccessible> GetNextWithState(nsIAccessible *aStart, PRUint32 matchState);
 232
 233   /**
 234    * Return an accessible for the given DOM node, or if that node isn't accessible, return the
 235    * accessible for the next DOM node which has one (based on forward depth first search)
 236    * @param aStartNode, the DOM node to start from
 237    * @param aRequireLeaf, only accept leaf accessible nodes
 238    * @return the resulting accessible
 239    */
 240   already_AddRefed<nsIAccessible> GetFirstAvailableAccessible(nsIDOMNode *aStartNode, PRBool aRequireLeaf = PR_FALSE);
 241
 242   // Hyperlink helpers
 243   virtual nsresult GetLinkOffset(PRInt32* aStartOffset, PRInt32* aEndOffset);
 244
 245   // For accessibles that have actions
 246   static void DoCommandCallback(nsITimer *aTimer, void *aClosure);
 247   nsresult DoCommand(nsIContent *aContent = nsnull);
 248
 249   // Check the visibility across both parent content and chrome
 250   PRBool CheckVisibilityInParentChain(nsIDocument* aDocument, nsIView* aView);
 251
 252   /**
 253    *  Get the container node for an atomic region, defined by aria-atomic="true"
 254    *  @return the container node
 255    */
 256   nsIDOMNode* GetAtomicRegion();
 257
 258   /**
 259    * Get numeric value of the given ARIA attribute.
 260    *
 261    * @param aAriaProperty - the ARIA property we're using
 262    * @param aValue - value of the attribute
 263    *
 264    * @return - NS_OK_NO_ARIA_VALUE if there is no setted ARIA attribute
 265    */
 266   nsresult GetAttrValue(nsIAtom *aAriaProperty, double *aValue);
 267
 268   /**
 269    * Return the action rule based on ARIA enum constants EActionRule
 270    * (see nsARIAMap.h). Used by GetNumActions() and GetActionName().
 271    *
 272    * @param aStates  [in] states of the accessible
 273    */
 274   PRUint32 GetActionRule(PRUint32 aStates);
 275
 276   /**
 277    * Fires platform accessible event. It's notification method only. It does
 278    * change nothing on Gecko side. Mostly you should use
 279    * nsIAccessible::FireAccessibleEvent excepting special cases like we have
 280    * in xul:tree accessible to lie to AT. Must be overridden in wrap classes.
 281    *
 282    * @param aEvent  the accessible event to fire.
 283    */
 284   virtual nsresult FirePlatformEvent(nsIAccessibleEvent *aEvent) = 0;
 285
 286   // Data Members
 287   nsCOMPtr<nsIAccessible> mParent;
 288   nsCOMPtr<nsIAccessible> mFirstChild;
 289   nsCOMPtr<nsIAccessible> mNextSibling;
 290
 291   nsRoleMapEntry *mRoleMapEntry; // Non-null indicates author-supplied role; possibly state & value as well
 292   PRInt32 mAccChildCount;
 293 };
 294
 295 NS_DEFINE_STATIC_IID_ACCESSOR(nsAccessible,
 296                               NS_ACCESSIBLE_IMPL_CID)
 297
 298 #endif
 299