dom/base/DirectionalityUtils.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef DirectionalityUtils_h___
   8 #define DirectionalityUtils_h___
   9
  10 #include "nscore.h"
  11 #include "nsStringFwd.h"
  12
  13 class nsIContent;
  14 class nsINode;
  15 class nsAttrValue;
  16 class nsTextNode;
  17
  18 namespace mozilla::dom {
  19 class Element;
  20 class HTMLSlotElement;
  21 struct UnbindContext;
  22 }  // namespace mozilla::dom
  23
  24 namespace mozilla {
  25
  26 enum class Directionality : uint8_t { Unset, Rtl, Ltr, Auto };
  27
  28 /**
  29  * Various methods for returning the directionality of a string using the
  30  * first-strong algorithm defined in http://unicode.org/reports/tr9/#P2
  31  *
  32  * @param[out] aFirstStrong the offset to the first character in the string with
  33  *             strong directionality, or UINT32_MAX if there is none (in which
  34  *             case the return value is Directionality::Unset).
  35  * @return the directionality of the string, or Unset if not available.
  36  */
  37 Directionality GetDirectionFromText(const char16_t* aText,
  38                                     const uint32_t aLength,
  39                                     uint32_t* aFirstStrong = nullptr);
  40
  41 /**
  42  * Set the directionality of an element according to the algorithm defined at
  43  * https://html.spec.whatwg.org/#the-directionality, not including elements with
  44  * auto direction.
  45  *
  46  * @return the directionality that the element was set to
  47  */
  48 Directionality RecomputeDirectionality(mozilla::dom::Element* aElement,
  49                                        bool aNotify = true);
  50
  51 /**
  52  * Conceptually https://html.spec.whatwg.org/#parent-directionality, but a bit
  53  * different in how we deal with shadow DOM.
  54  *
  55  * FIXME(bug 1857719): Update directionality to the latest version of the spec.
  56  */
  57 Directionality GetParentDirectionality(const mozilla::dom::Element* aElement);
  58
  59 /**
  60  * Set the directionality of any descendants of a node that do not themselves
  61  * have a dir attribute.
  62  * For performance reasons we walk down the descendant tree in the rare case
  63  * of setting the dir attribute, rather than walking up the ancestor tree in
  64  * the much more common case of getting the element's directionality.
  65  */
  66 void SetDirectionalityOnDescendants(mozilla::dom::Element* aElement,
  67                                     Directionality aDir, bool aNotify = true);
  68
  69 /**
  70  * Walk the descendants of a node in tree order and, for any text node
  71  * descendant that determines the directionality of some element and is not a
  72  * descendant of another descendant of the original node with dir=auto,
  73  * redetermine that element's directionality
  74  */
  75 void WalkDescendantsResetAutoDirection(mozilla::dom::Element* aElement);
  76
  77 /**
  78  * In case a slot element was added or removed it may change the directionality
  79  * of ancestors or assigned nodes.
  80  *
  81  * aAllAssignedNodesChanged forces the computation of the state for all of the
  82  * assigned descendants.
  83  */
  84 void SlotStateChanged(dom::HTMLSlotElement* aSlot,
  85                       bool aAllAssignedNodesChanged = true);
  86
  87 /**
  88  * When only a single node in a slot is reassigned we can save some work
  89  * compared to the above.
  90  */
  91 void SlotAssignedNodeChanged(dom::HTMLSlotElement* aSlot,
  92                              nsIContent& aAssignedNode);
  93
  94 /**
  95  * After setting dir=auto on an element, walk its descendants in tree order.
  96  * If the node doesn't have the NODE_ANCESTOR_HAS_DIR_AUTO flag, set the
  97  * NODE_ANCESTOR_HAS_DIR_AUTO flag on all of its descendants.
  98  * Resolve the directionality of the element by the "downward propagation
  99  * algorithm" (defined in section 3 in the comments at the beginning of
 100  * DirectionalityUtils.cpp)
 101  */
 102 void WalkDescendantsSetDirAuto(mozilla::dom::Element* aElement,
 103                                bool aNotify = true);
 104
 105 /**
 106  * After unsetting dir=auto on an element, walk its descendants in tree order,
 107  * skipping any that have dir=auto themselves, and unset the
 108  * NODE_ANCESTOR_HAS_DIR_AUTO flag
 109  */
 110 void WalkDescendantsClearAncestorDirAuto(nsIContent* aContent);
 111
 112 /**
 113  * When the contents of a text node are about to change, retrieve the current
 114  * directionality of the text
 115  *
 116  * @return whether the text node affects the directionality of any element
 117  */
 118 bool TextNodeWillChangeDirection(nsTextNode* aTextNode, Directionality* aOldDir,
 119                                  uint32_t aOffset);
 120
 121 /**
 122  * After the contents of a text node have changed, change the directionality
 123  * of any elements whose directionality is determined by that node
 124  */
 125 void TextNodeChangedDirection(nsTextNode* aTextNode, Directionality aOldDir,
 126                               bool aNotify);
 127
 128 /**
 129  * When a text node is appended to an element, find any ancestors with dir=auto
 130  * whose directionality will be determined by the text node
 131  */
 132 void SetDirectionFromNewTextNode(nsTextNode* aTextNode);
 133
 134 /**
 135  * When a text node is removed from a document, find any ancestors whose
 136  * directionality it determined and redetermine their directionality
 137  */
 138 void ResetDirectionSetByTextNode(nsTextNode*, dom::UnbindContext&);
 139
 140 /**
 141  * Set the directionality of an element according to the directionality of the
 142  * text in aValue
 143  */
 144 void SetDirectionalityFromValue(mozilla::dom::Element* aElement,
 145                                 const nsAString& aValue, bool aNotify);
 146
 147 /**
 148  * Called when setting the dir attribute on an element, immediately after
 149  * AfterSetAttr. This is instead of using BeforeSetAttr or AfterSetAttr, because
 150  * in AfterSetAttr we don't know the old value, so we can't identify all cases
 151  * where we need to walk up or down the document tree and reset the direction;
 152  * and in BeforeSetAttr we can't do the walk because this element hasn't had the
 153  * value set yet so the results will be wrong.
 154  */
 155 void OnSetDirAttr(mozilla::dom::Element* aElement, const nsAttrValue* aNewValue,
 156                   bool hadValidDir, bool hadDirAuto, bool aNotify);
 157
 158 /**
 159  * Called when binding a new element to the tree, to set the
 160  * NodeAncestorHasDirAuto flag and set the direction of the element and its
 161  * ancestors if necessary
 162  */
 163 void SetDirOnBind(mozilla::dom::Element* aElement, nsIContent* aParent);
 164
 165 /**
 166  * Called when unbinding an element from the tree, to recompute the
 167  * directionality of the element if it doesn't have autodirection, and to
 168  * clean up any entries in nsTextDirectionalityMap that refer to it.
 169  */
 170 void ResetDir(mozilla::dom::Element* aElement);
 171 }  // end namespace mozilla
 172
 173 #endif /* DirectionalityUtils_h___ */