layout/base/nsCaret.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 /* the caret is the text cursor used, e.g., when editing */
   8
   9 #ifndef nsCaret_h__
  10 #define nsCaret_h__
  11
  12 #include "mozilla/MemoryReporting.h"
  13 #include "mozilla/SelectionMovementUtils.h"
  14 #include "nsCoord.h"
  15 #include "nsIFrame.h"
  16 #include "nsISelectionListener.h"
  17 #include "nsIWeakReferenceUtils.h"
  18 #include "nsPoint.h"
  19 #include "nsRect.h"
  20
  21 class nsFrameSelection;
  22 class nsIContent;
  23 class nsIFrame;
  24 class nsINode;
  25 class nsITimer;
  26
  27 namespace mozilla {
  28 class PresShell;
  29 enum class CaretAssociationHint;
  30 namespace gfx {
  31 class DrawTarget;
  32 }  // namespace gfx
  33 }  // namespace mozilla
  34
  35 //-----------------------------------------------------------------------------
  36 class nsCaret final : public nsISelectionListener {
  37   typedef mozilla::gfx::DrawTarget DrawTarget;
  38
  39  public:
  40   nsCaret();
  41
  42  protected:
  43   virtual ~nsCaret();
  44
  45  public:
  46   NS_DECL_ISUPPORTS
  47
  48   using CaretAssociationHint = mozilla::CaretAssociationHint;
  49
  50   nsresult Init(mozilla::PresShell*);
  51   void Terminate();
  52
  53   void SetSelection(mozilla::dom::Selection*);
  54   mozilla::dom::Selection* GetSelection();
  55
  56   /**
  57    * Sets whether the caret should only be visible in nodes that are not
  58    * user-modify: read-only, or whether it should be visible in all nodes.
  59    *
  60    * @param aIgnoreUserModify true to have the cursor visible in all nodes,
  61    *                          false to have it visible in all nodes except
  62    *                          those with user-modify: read-only
  63    */
  64   void SetIgnoreUserModify(bool aIgnoreUserModify);
  65   /** SetVisible will set the visibility of the caret
  66    *  @param inMakeVisible true to show the caret, false to hide it
  67    */
  68   void SetVisible(bool aVisible);
  69   /** IsVisible will get the visibility of the caret.
  70    *  This returns false if the caret is hidden because it was set
  71    *  to not be visible, or because the selection is not collapsed, or
  72    *  because an open popup is hiding the caret.
  73    *  It does not take account of blinking or the caret being hidden
  74    *  because we're in non-editable/disabled content.
  75    */
  76   bool IsVisible();
  77
  78   /**
  79    * AddForceHide() increases mHideCount and hide the caret even if
  80    * SetVisible(true) has been or will be called.  This is useful when the
  81    * caller wants to hide caret temporarily and it needs to cancel later.
  82    * Especially, in the latter case, it's too difficult to decide if the
  83    * caret should be actually visible or not because caret visible state
  84    * is set from a lot of event handlers.  So, it's very stateful.
  85    */
  86   void AddForceHide();
  87   /**
  88    * RemoveForceHide() decreases mHideCount if it's over 0.
  89    * If the value becomes 0, this may show the caret if SetVisible(true)
  90    * has been called.
  91    */
  92   void RemoveForceHide();
  93   /** SetCaretReadOnly set the appearance of the caret
  94    *  @param inMakeReadonly true to show the caret in a 'read only' state,
  95    *         false to show the caret in normal, editing state
  96    */
  97   void SetCaretReadOnly(bool aReadOnly);
  98   /**
  99    * @param aVisibility true if the caret should be visible even when the
 100    * selection is not collapsed.
 101    */
 102   void SetVisibilityDuringSelection(bool aVisibility);
 103
 104   /**
 105    * Set the caret's position explicitly to the specified node and offset
 106    * instead of tracking its selection.
 107    * Passing null for aNode would set the caret to track its selection again.
 108    **/
 109   void SetCaretPosition(nsINode* aNode, int32_t aOffset);
 110
 111   /**
 112    * Schedule a repaint for the frame where the caret would appear.
 113    * Does not check visibility etc.
 114    */
 115   void SchedulePaint();
 116
 117   /**
 118    * Returns a frame to paint in, and the bounds of the painted caret
 119    * relative to that frame.
 120    * The rectangle includes bidi decorations.
 121    * Returns null if the caret should not be drawn (including if it's blinked
 122    * off).
 123    */
 124   nsIFrame* GetPaintGeometry(nsRect* aRect);
 125   /**
 126    * Same as the overload above, but returns the caret and hook rects
 127    * separately, and also computes the color if requested.
 128    */
 129   nsIFrame* GetPaintGeometry(nsRect* aCaretRect, nsRect* aHookRect,
 130                              nscolor* aCaretColor = nullptr);
 131   /**
 132    * A simple wrapper around GetGeometry. Does not take any caret state into
 133    * account other than the current selection.
 134    */
 135   nsIFrame* GetGeometry(nsRect* aRect) {
 136     return GetGeometry(GetSelection(), aRect);
 137   }
 138
 139   /** PaintCaret
 140    *  Actually paint the caret onto the given rendering context.
 141    */
 142   void PaintCaret(DrawTarget& aDrawTarget, nsIFrame* aForFrame,
 143                   const nsPoint& aOffset);
 144
 145   // nsISelectionListener interface
 146   NS_DECL_NSISELECTIONLISTENER
 147
 148   /** The current caret position. */
 149   struct CaretPosition {
 150     nsCOMPtr<nsINode> mContent;
 151     int32_t mOffset = 0;
 152     CaretAssociationHint mHint{0};
 153     mozilla::intl::BidiEmbeddingLevel mBidiLevel;
 154
 155     bool operator==(const CaretPosition& aOther) const {
 156       return mContent == aOther.mContent && mOffset == aOther.mOffset &&
 157              mHint == aOther.mHint && mBidiLevel == aOther.mBidiLevel;
 158     }
 159     explicit operator bool() const { return !!mContent; }
 160   };
 161
 162   static CaretPosition CaretPositionFor(const mozilla::dom::Selection*);
 163
 164   /**
 165    * Gets the position and size of the caret that would be drawn for
 166    * the focus node/offset of aSelection (assuming it would be drawn,
 167    * i.e., disregarding blink status). The geometry is stored in aRect,
 168    * and we return the frame aRect is relative to.
 169    * Only looks at the focus node of aSelection, so you can call it even if
 170    * aSelection is not collapsed.
 171    * This rect does not include any extra decorations for bidi.
 172    * @param aRect must be non-null
 173    */
 174   static nsIFrame* GetGeometry(const mozilla::dom::Selection* aSelection,
 175                                nsRect* aRect);
 176
 177   static nsRect GetGeometryForFrame(nsIFrame* aFrame, int32_t aFrameOffset,
 178                                     nscoord* aBidiIndicatorSize);
 179
 180   // Get the frame and frame offset based on aPosition.
 181   static mozilla::CaretFrameData GetFrameAndOffset(
 182       const CaretPosition& aPosition);
 183
 184   size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf) const;
 185
 186  protected:
 187   static void CaretBlinkCallback(nsITimer* aTimer, void* aClosure);
 188
 189   void CheckSelectionLanguageChange();
 190
 191   void ResetBlinking();
 192   void StopBlinking();
 193
 194   struct Metrics {
 195     nscoord mBidiIndicatorSize;  // width and height of bidi indicator
 196     nscoord mCaretWidth;         // full caret width including bidi indicator
 197   };
 198   static Metrics ComputeMetrics(nsIFrame* aFrame, int32_t aOffset,
 199                                 nscoord aCaretHeight);
 200   void ComputeCaretRects(nsIFrame* aFrame, int32_t aFrameOffset,
 201                          nsRect* aCaretRect, nsRect* aHookRect);
 202
 203   // Returns true if we should not draw the caret because of XUL menu popups.
 204   // The caret should be hidden if:
 205   // 1. An open popup contains the caret, but a menu popup exists before the
 206   //    caret-owning popup in the popup list (i.e. a menu is in front of the
 207   //    popup with the caret). If the menu itself contains the caret we don't
 208   //    hide it.
 209   // 2. A menu popup is open, but there is no caret present in any popup.
 210   // 3. The caret selection is empty.
 211   bool IsMenuPopupHidingCaret();
 212
 213   // If we're tracking the selection, this updates the caret position and
 214   // invalidates paint as needed.
 215   void UpdateCaretPositionFromSelectionIfNeeded();
 216
 217   nsWeakPtr mPresShell;
 218   mozilla::WeakPtr<mozilla::dom::Selection> mDomSelectionWeak;
 219
 220   nsCOMPtr<nsITimer> mBlinkTimer;
 221
 222   CaretPosition mCaretPosition;
 223
 224   /**
 225    * mBlinkCount is used to control the number of times to blink the caret
 226    * before stopping the blink. This is reset each time we reset the
 227    * blinking.
 228    */
 229   int32_t mBlinkCount = -1;
 230   /**
 231    * mBlinkRate is the rate of the caret blinking the last time we read it.
 232    * It is used as a way to optimize whether we need to reset the blinking
 233    * timer. 0 or a negative value means no blinking.
 234    */
 235   int32_t mBlinkRate = 0;
 236   /**
 237    * mHideCount is not 0, it means that somebody doesn't want the caret
 238    * to be visible.  See AddForceHide() and RemoveForceHide().
 239    */
 240   uint32_t mHideCount = 0;
 241
 242   /**
 243    * mIsBlinkOn is true when we're in a blink cycle where the caret is on.
 244    */
 245   bool mIsBlinkOn = false;
 246   /**
 247    * mIsVisible is true when SetVisible was last called with 'true'.
 248    */
 249   bool mVisible = false;
 250   /**
 251    * mReadOnly is true when the caret is set to "read only" mode (i.e.,
 252    * it doesn't blink).
 253    */
 254   bool mReadOnly = false;
 255   /**
 256    * mShowDuringSelection is true when the caret should be shown even when
 257    * the selection is not collapsed.
 258    */
 259   bool mShowDuringSelection = false;
 260   /**
 261    * mIgnoreUserModify is true when the caret should be shown even when
 262    * it's in non-user-modifiable content.
 263    */
 264   bool mIgnoreUserModify = true;
 265
 266   /**
 267    * If the caret position is fixed, it's been overridden externally and it
 268    * will not track the selection.
 269    */
 270   bool mFixedCaretPosition = false;
 271 };
 272
 273 #endif  // nsCaret_h__