accessible/base/nsCoreUtils.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef nsCoreUtils_h_
   7 #define nsCoreUtils_h_
   8
   9 #include "mozilla/EventForwards.h"
  10 #include "mozilla/dom/Element.h"
  11 #include "nsIAccessibleEvent.h"
  12 #include "nsIContent.h"
  13 #include "mozilla/dom/Document.h"  // for GetPresShell()
  14
  15 #include "nsPoint.h"
  16 #include "nsTArray.h"
  17
  18 class nsRange;
  19 class nsTreeColumn;
  20 class nsIFrame;
  21 class nsIDocShell;
  22 class nsIWidget;
  23
  24 namespace mozilla {
  25 class PresShell;
  26 namespace dom {
  27 class XULTreeElement;
  28 }
  29 }  // namespace mozilla
  30
  31 /**
  32  * Core utils.
  33  */
  34 class nsCoreUtils {
  35  public:
  36   typedef mozilla::PresShell PresShell;
  37   typedef mozilla::dom::Document Document;
  38
  39   /**
  40    * Return true if the given node is a label of a control.
  41    */
  42   static bool IsLabelWithControl(nsIContent* aContent);
  43
  44   /**
  45    * Return true if the given node has registered click, mousedown or mouseup
  46    * event listeners.
  47    */
  48   static bool HasClickListener(nsIContent* aContent);
  49
  50   /**
  51    * Dispatch click event to XUL tree cell.
  52    *
  53    * @param  aTree        [in] tree
  54    * @param  aRowIndex    [in] row index
  55    * @param  aColumn      [in] column object
  56    * @param  aPseudoElm   [in] pseudo element inside the cell, see
  57    *                       XULTreeElement for available values
  58    */
  59   MOZ_CAN_RUN_SCRIPT
  60   static void DispatchClickEvent(mozilla::dom::XULTreeElement* aTree,
  61                                  int32_t aRowIndex, nsTreeColumn* aColumn,
  62                                  const nsAString& aPseudoElt = EmptyString());
  63
  64   /**
  65    * Send mouse event to the given element.
  66    *
  67    * @param aMessage     [in] an event message (see EventForwards.h)
  68    * @param aX           [in] x coordinate in dev pixels
  69    * @param aY           [in] y coordinate in dev pixels
  70    * @param aContent     [in] the element
  71    * @param aFrame       [in] frame of the element
  72    * @param aPresShell   [in] the presshell for the element
  73    * @param aRootWidget  [in] the root widget of the element
  74    */
  75   MOZ_CAN_RUN_SCRIPT
  76   static void DispatchMouseEvent(mozilla::EventMessage aMessage, int32_t aX,
  77                                  int32_t aY, nsIContent* aContent,
  78                                  nsIFrame* aFrame, PresShell* aPresShell,
  79                                  nsIWidget* aRootWidget);
  80
  81   /**
  82    * Send a touch event with a single touch point to the given element.
  83    *
  84    * @param aMessage     [in] an event message (see EventForwards.h)
  85    * @param aX           [in] x coordinate in dev pixels
  86    * @param aY           [in] y coordinate in dev pixels
  87    * @param aContent     [in] the element
  88    * @param aFrame       [in] frame of the element
  89    * @param aPresShell   [in] the presshell for the element
  90    * @param aRootWidget  [in] the root widget of the element
  91    */
  92   MOZ_CAN_RUN_SCRIPT
  93   static void DispatchTouchEvent(mozilla::EventMessage aMessage, int32_t aX,
  94                                  int32_t aY, nsIContent* aContent,
  95                                  nsIFrame* aFrame, PresShell* aPresShell,
  96                                  nsIWidget* aRootWidget);
  97
  98   /**
  99    * Return an accesskey registered on the given element by
 100    * EventStateManager or 0 if there is no registered accesskey.
 101    *
 102    * @param aContent - the given element.
 103    */
 104   static uint32_t GetAccessKeyFor(nsIContent* aContent);
 105
 106   /**
 107    * Return DOM element related with the given node, i.e.
 108    * a) itself if it is DOM element
 109    * b) parent element if it is text node
 110    * c) otherwise nullptr
 111    *
 112    * @param aNode  [in] the given DOM node
 113    */
 114   static nsIContent* GetDOMElementFor(nsIContent* aContent);
 115
 116   /**
 117    * Return DOM node for the given DOM point.
 118    */
 119   static nsINode* GetDOMNodeFromDOMPoint(nsINode* aNode, uint32_t aOffset);
 120
 121   /**
 122    * Is the first passed in node an ancestor of the second?
 123    * Note: A node is not considered to be the ancestor of itself.
 124    *
 125    * @param  aPossibleAncestorNode   [in] node to test for ancestor-ness of
 126    *                                   aPossibleDescendantNode
 127    * @param  aPossibleDescendantNode [in] node to test for descendant-ness of
 128    *                                   aPossibleAncestorNode
 129    * @param  aRootNode               [in, optional] the root node that search
 130    *                                   search should be performed within
 131    * @return true                     if aPossibleAncestorNode is an ancestor of
 132    *                                   aPossibleDescendantNode
 133    */
 134   static bool IsAncestorOf(nsINode* aPossibleAncestorNode,
 135                            nsINode* aPossibleDescendantNode,
 136                            nsINode* aRootNode = nullptr);
 137
 138   /**
 139    * Helper method to scroll range into view, used for implementation of
 140    * nsIAccessibleText::scrollSubstringTo().
 141    *
 142    * @param aFrame        the frame for accessible the range belongs to.
 143    * @param aRange    the range to scroll to
 144    * @param aScrollType   the place a range should be scrolled to
 145    */
 146   static nsresult ScrollSubstringTo(nsIFrame* aFrame, nsRange* aRange,
 147                                     uint32_t aScrollType);
 148
 149   /** Helper method to scroll range into view, used for implementation of
 150    * nsIAccessibleText::scrollSubstringTo[Point]().
 151    *
 152    * @param aFrame        the frame for accessible the range belongs to.
 153    * @param aRange    the range to scroll to
 154    * @param aVertical     how to align vertically, specified in percents, and
 155    * when.
 156    * @param aHorizontal     how to align horizontally, specified in percents,
 157    * and when.
 158    */
 159   static nsresult ScrollSubstringTo(nsIFrame* aFrame, nsRange* aRange,
 160                                     mozilla::ScrollAxis aVertical,
 161                                     mozilla::ScrollAxis aHorizontal);
 162
 163   /**
 164    * Scrolls the given frame to the point, used for implememntation of
 165    * nsIAccessible::scrollToPoint and nsIAccessibleText::scrollSubstringToPoint.
 166    *
 167    * @param aScrollableFrame  the scrollable frame
 168    * @param aFrame            the frame to scroll
 169    * @param aPoint            the point scroll to
 170    */
 171   static void ScrollFrameToPoint(nsIFrame* aScrollableFrame, nsIFrame* aFrame,
 172                                  const nsIntPoint& aPoint);
 173
 174   /**
 175    * Converts scroll type constant defined in nsIAccessibleScrollType to
 176    * vertical and horizontal parameters.
 177    */
 178   static void ConvertScrollTypeToPercents(uint32_t aScrollType,
 179                                           mozilla::ScrollAxis* aVertical,
 180                                           mozilla::ScrollAxis* aHorizontal);
 181
 182   /**
 183    * Returns coordinates in device pixels relative screen for the top level
 184    * window.
 185    *
 186    * @param aNode  the DOM node hosted in the window.
 187    */
 188   static nsIntPoint GetScreenCoordsForWindow(nsINode* aNode);
 189
 190   /**
 191    * Return document shell for the given DOM node.
 192    */
 193   static already_AddRefed<nsIDocShell> GetDocShellFor(nsINode* aNode);
 194
 195   /**
 196    * Return true if the given document is root document.
 197    */
 198   static bool IsRootDocument(Document* aDocument);
 199
 200   /**
 201    * Return true if the given document is content document (not chrome).
 202    */
 203   static bool IsContentDocument(Document* aDocument);
 204
 205   /**
 206    * Return true if the given document node is for tab document accessible.
 207    */
 208   static bool IsTabDocument(Document* aDocumentNode);
 209
 210   /**
 211    * Return true if the given document is an error page.
 212    */
 213   static bool IsErrorPage(Document* aDocument);
 214
 215   /**
 216    * Return presShell for the document containing the given DOM node.
 217    */
 218   static PresShell* GetPresShellFor(nsINode* aNode) {
 219     return aNode->OwnerDoc()->GetPresShell();
 220   }
 221
 222   /**
 223    * Get the ID for an element, in some types of XML this may not be the ID
 224    * attribute
 225    * @param aContent  Node to get the ID for
 226    * @param aID       Where to put ID string
 227    * @return          true if there is an ID set for this node
 228    */
 229   static bool GetID(nsIContent* aContent, nsAString& aID);
 230
 231   /**
 232    * Convert attribute value of the given node to positive integer. If no
 233    * attribute or wrong value then false is returned.
 234    */
 235   static bool GetUIntAttr(nsIContent* aContent, nsAtom* aAttr, int32_t* aUInt);
 236
 237   /**
 238    * Returns language for the given node.
 239    *
 240    * @param aContent     [in] the given node
 241    * @param aRootContent [in] container of the given node
 242    * @param aLanguage    [out] language
 243    */
 244   static void GetLanguageFor(nsIContent* aContent, nsIContent* aRootContent,
 245                              nsAString& aLanguage);
 246
 247   /**
 248    * Return tree from any levels DOMNode under the XUL tree.
 249    */
 250   static mozilla::dom::XULTreeElement* GetTree(nsIContent* aContent);
 251
 252   /**
 253    * Return first sensible column for the given tree box object.
 254    */
 255   static already_AddRefed<nsTreeColumn> GetFirstSensibleColumn(
 256       mozilla::dom::XULTreeElement* aTree);
 257
 258   /**
 259    * Return sensible columns count for the given tree box object.
 260    */
 261   static uint32_t GetSensibleColumnCount(mozilla::dom::XULTreeElement* aTree);
 262
 263   /**
 264    * Return sensible column at the given index for the given tree box object.
 265    */
 266   static already_AddRefed<nsTreeColumn> GetSensibleColumnAt(
 267       mozilla::dom::XULTreeElement* aTree, uint32_t aIndex);
 268
 269   /**
 270    * Return next sensible column for the given column.
 271    */
 272   static already_AddRefed<nsTreeColumn> GetNextSensibleColumn(
 273       nsTreeColumn* aColumn);
 274
 275   /**
 276    * Return previous sensible column for the given column.
 277    */
 278   static already_AddRefed<nsTreeColumn> GetPreviousSensibleColumn(
 279       nsTreeColumn* aColumn);
 280
 281   /**
 282    * Return true if the given column is hidden (i.e. not sensible).
 283    */
 284   static bool IsColumnHidden(nsTreeColumn* aColumn);
 285
 286   /**
 287    * Scroll content into view.
 288    */
 289   MOZ_CAN_RUN_SCRIPT
 290   static void ScrollTo(PresShell* aPresShell, nsIContent* aContent,
 291                        uint32_t aScrollType);
 292
 293   /**
 294    * Return true if the given node is table header element.
 295    */
 296   static bool IsHTMLTableHeader(nsIContent* aContent) {
 297     return aContent->NodeInfo()->Equals(nsGkAtoms::th) ||
 298            (aContent->IsElement() && aContent->AsElement()->HasAttr(
 299                                          kNameSpaceID_None, nsGkAtoms::scope));
 300   }
 301
 302   /**
 303    * Returns true if the given string is empty or contains whitespace symbols
 304    * only. In contrast to nsWhitespaceTokenizer class it takes into account
 305    * non-breaking space (0xa0).
 306    */
 307   static bool IsWhitespaceString(const nsAString& aString);
 308
 309   /**
 310    * Returns true if the given character is whitespace symbol.
 311    */
 312   static bool IsWhitespace(char16_t aChar) {
 313     return aChar == ' ' || aChar == '\n' || aChar == '\r' || aChar == '\t' ||
 314            aChar == 0xa0;
 315   }
 316
 317   /*
 318    * Return true if there are any observers of accessible events.
 319    */
 320   static bool AccEventObserversExist();
 321
 322   /**
 323    * Notify accessible event observers of an event.
 324    */
 325   static void DispatchAccEvent(RefPtr<nsIAccessibleEvent> aEvent);
 326
 327   static bool IsDisplayContents(nsIContent* aContent);
 328 };
 329
 330 #endif