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