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/dom/Selection.h"
  14 #include "nsCoord.h"
  15 #include "nsISelectionListener.h"
  16 #include "nsIWeakReferenceUtils.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* aPresShell);
  50   void Terminate();
  51
  52   void SetSelection(mozilla::dom::Selection* aDOMSel);
  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   /** SetVisible will set the visibility of the caret
  65    *  @param inMakeVisible true to show the caret, false to hide it
  66    */
  67   void SetVisible(bool intMakeVisible);
  68   /** IsVisible will get the visibility of the caret.
  69    *  This returns false if the caret is hidden because it was set
  70    *  to not be visible, or because the selection is not collapsed, or
  71    *  because an open popup is hiding the caret.
  72    *  It does not take account of blinking or the caret being hidden
  73    *  because we're in non-editable/disabled content.
  74    */
  75   bool IsVisible(mozilla::dom::Selection* aSelection = nullptr) {
  76     if (!mVisible || mHideCount) {
  77       return false;
  78     }
  79
  80     if (!mShowDuringSelection) {
  81       mozilla::dom::Selection* selection;
  82       if (aSelection) {
  83         selection = aSelection;
  84       } else {
  85         selection = GetSelection();
  86       }
  87       if (!selection || !selection->IsCollapsed()) {
  88         return false;
  89       }
  90     }
  91
  92     if (IsMenuPopupHidingCaret()) {
  93       return false;
  94     }
  95
  96     return true;
  97   }
  98   /**
  99    * AddForceHide() increases mHideCount and hide the caret even if
 100    * SetVisible(true) has been or will be called.  This is useful when the
 101    * caller wants to hide caret temporarily and it needs to cancel later.
 102    * Especially, in the latter case, it's too difficult to decide if the
 103    * caret should be actually visible or not because caret visible state
 104    * is set from a lot of event handlers.  So, it's very stateful.
 105    */
 106   void AddForceHide();
 107   /**
 108    * RemoveForceHide() decreases mHideCount if it's over 0.
 109    * If the value becomes 0, this may show the caret if SetVisible(true)
 110    * has been called.
 111    */
 112   void RemoveForceHide();
 113   /** SetCaretReadOnly set the appearance of the caret
 114    *  @param inMakeReadonly true to show the caret in a 'read only' state,
 115    *         false to show the caret in normal, editing state
 116    */
 117   void SetCaretReadOnly(bool inMakeReadonly);
 118   /**
 119    * @param aVisibility true if the caret should be visible even when the
 120    * selection is not collapsed.
 121    */
 122   void SetVisibilityDuringSelection(bool aVisibility);
 123
 124   /**
 125    * Set the caret's position explicitly to the specified node and offset
 126    * instead of tracking its selection.
 127    * Passing null for aNode would set the caret to track its selection again.
 128    **/
 129   void SetCaretPosition(nsINode* aNode, int32_t aOffset);
 130
 131   /**
 132    * Schedule a repaint for the frame where the caret would appear.
 133    * Does not check visibility etc.
 134    */
 135   void SchedulePaint(mozilla::dom::Selection* aSelection = nullptr);
 136
 137   /**
 138    * Returns a frame to paint in, and the bounds of the painted caret
 139    * relative to that frame.
 140    * The rectangle includes bidi decorations.
 141    * Returns null if the caret should not be drawn (including if it's blinked
 142    * off).
 143    */
 144   nsIFrame* GetPaintGeometry(nsRect* aRect);
 145   /**
 146    * Same as the overload above, but returns the caret and hook rects
 147    * separately, and also computes the color if requested.
 148    */
 149   nsIFrame* GetPaintGeometry(nsRect* aCaretRect, nsRect* aHookRect,
 150                              nscolor* aCaretColor = nullptr);
 151   /**
 152    * A simple wrapper around GetGeometry. Does not take any caret state into
 153    * account other than the current selection.
 154    */
 155   nsIFrame* GetGeometry(nsRect* aRect) {
 156     return GetGeometry(GetSelection(), aRect);
 157   }
 158
 159   /** PaintCaret
 160    *  Actually paint the caret onto the given rendering context.
 161    */
 162   void PaintCaret(DrawTarget& aDrawTarget, nsIFrame* aForFrame,
 163                   const nsPoint& aOffset);
 164
 165   // nsISelectionListener interface
 166   NS_DECL_NSISELECTIONLISTENER
 167
 168   /**
 169    * Gets the position and size of the caret that would be drawn for
 170    * the focus node/offset of aSelection (assuming it would be drawn,
 171    * i.e., disregarding blink status). The geometry is stored in aRect,
 172    * and we return the frame aRect is relative to.
 173    * Only looks at the focus node of aSelection, so you can call it even if
 174    * aSelection is not collapsed.
 175    * This rect does not include any extra decorations for bidi.
 176    * @param aRect must be non-null
 177    */
 178   static nsIFrame* GetGeometry(const mozilla::dom::Selection* aSelection,
 179                                nsRect* aRect);
 180
 181   static nsRect GetGeometryForFrame(nsIFrame* aFrame, int32_t aFrameOffset,
 182                                     nscoord* aBidiIndicatorSize);
 183
 184   // Get the frame and frame offset based on the focus node and focus offset
 185   // of aSelection. If aOverrideNode and aOverride are provided, use them
 186   // instead.
 187   // @param aFrameOffset return the frame offset if non-null.
 188   // @param aUnadjustedFrame return the original frame that the selection is
 189   // targeting, without any adjustment for painting.
 190   // @return the frame of the focus node.
 191   static nsIFrame* GetFrameAndOffset(const mozilla::dom::Selection* aSelection,
 192                                      nsINode* aOverrideNode,
 193                                      int32_t aOverrideOffset,
 194                                      int32_t* aFrameOffset,
 195                                      nsIFrame** aUnadjustedFrame = nullptr);
 196
 197   size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf) const;
 198
 199  protected:
 200   static void CaretBlinkCallback(nsITimer* aTimer, void* aClosure);
 201
 202   void CheckSelectionLanguageChange();
 203
 204   void ResetBlinking();
 205   void StopBlinking();
 206
 207   struct Metrics {
 208     nscoord mBidiIndicatorSize;  // width and height of bidi indicator
 209     nscoord mCaretWidth;         // full caret width including bidi indicator
 210   };
 211   static Metrics ComputeMetrics(nsIFrame* aFrame, int32_t aOffset,
 212                                 nscoord aCaretHeight);
 213   void ComputeCaretRects(nsIFrame* aFrame, int32_t aFrameOffset,
 214                          nsRect* aCaretRect, nsRect* aHookRect);
 215
 216   // Returns true if we should not draw the caret because of XUL menu popups.
 217   // The caret should be hidden if:
 218   // 1. An open popup contains the caret, but a menu popup exists before the
 219   //    caret-owning popup in the popup list (i.e. a menu is in front of the
 220   //    popup with the caret). If the menu itself contains the caret we don't
 221   //    hide it.
 222   // 2. A menu popup is open, but there is no caret present in any popup.
 223   // 3. The caret selection is empty.
 224   bool IsMenuPopupHidingCaret();
 225
 226   nsWeakPtr mPresShell;
 227   mozilla::WeakPtr<mozilla::dom::Selection> mDomSelectionWeak;
 228
 229   nsCOMPtr<nsITimer> mBlinkTimer;
 230
 231   /**
 232    * The content to draw the caret at. If null, we use mDomSelectionWeak's
 233    * focus node instead.
 234    */
 235   nsCOMPtr<nsINode> mOverrideContent;
 236   /**
 237    * The character offset to draw the caret at.
 238    * Ignored if mOverrideContent is null.
 239    */
 240   int32_t mOverrideOffset;
 241   /**
 242    * mBlinkCount is used to control the number of times to blink the caret
 243    * before stopping the blink. This is reset each time we reset the
 244    * blinking.
 245    */
 246   int32_t mBlinkCount;
 247   /**
 248    * mBlinkRate is the rate of the caret blinking the last time we read it.
 249    * It is used as a way to optimize whether we need to reset the blinking
 250    * timer. 0 or a negative value means no blinking.
 251    */
 252   int32_t mBlinkRate;
 253   /**
 254    * mHideCount is not 0, it means that somebody doesn't want the caret
 255    * to be visible.  See AddForceHide() and RemoveForceHide().
 256    */
 257   uint32_t mHideCount;
 258
 259   /**
 260    * mIsBlinkOn is true when we're in a blink cycle where the caret is on.
 261    */
 262   bool mIsBlinkOn;
 263   /**
 264    * mIsVisible is true when SetVisible was last called with 'true'.
 265    */
 266   bool mVisible;
 267   /**
 268    * mReadOnly is true when the caret is set to "read only" mode (i.e.,
 269    * it doesn't blink).
 270    */
 271   bool mReadOnly;
 272   /**
 273    * mShowDuringSelection is true when the caret should be shown even when
 274    * the selection is not collapsed.
 275    */
 276   bool mShowDuringSelection;
 277   /**
 278    * mIgnoreUserModify is true when the caret should be shown even when
 279    * it's in non-user-modifiable content.
 280    */
 281   bool mIgnoreUserModify;
 282 };
 283
 284 #endif  // nsCaret_h__