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