layout/base/nsCaret.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=2 sw=2 et tw=78: */
   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 "nsCoord.h"
  14 #include "nsISelectionListener.h"
  15 #include "nsIWeakReferenceUtils.h"
  16 #include "CaretAssociationHint.h"
  17 #include "nsPoint.h"
  18 #include "nsRect.h"
  19
  20 class nsDisplayListBuilder;
  21 class nsFrameSelection;
  22 class nsIContent;
  23 class nsIDOMNode;
  24 class nsIFrame;
  25 class nsINode;
  26 class nsIPresShell;
  27 class nsITimer;
  28
  29 namespace mozilla {
  30 namespace dom {
  31 class Selection;
  32 }
  33 namespace gfx {
  34 class DrawTarget;
  35 }
  36 }
  37
  38 //-----------------------------------------------------------------------------
  39 class nsCaret MOZ_FINAL : public nsISelectionListener
  40 {
  41     typedef mozilla::gfx::DrawTarget DrawTarget;
  42
  43   public:
  44     nsCaret();
  45
  46   protected:
  47     virtual ~nsCaret();
  48
  49   public:
  50     NS_DECL_ISUPPORTS
  51
  52     typedef mozilla::CaretAssociationHint CaretAssociationHint;
  53
  54     nsresult Init(nsIPresShell *inPresShell);
  55     void Terminate();
  56
  57     void SetSelection(nsISelection *aDOMSel);
  58     nsISelection* GetSelection();
  59
  60     /**
  61      * Sets whether the caret should only be visible in nodes that are not
  62      * user-modify: read-only, or whether it should be visible in all nodes.
  63      *
  64      * @param aIgnoreUserModify true to have the cursor visible in all nodes,
  65      *                          false to have it visible in all nodes except
  66      *                          those with user-modify: read-only
  67      */
  68     void SetIgnoreUserModify(bool aIgnoreUserModify);
  69     /** SetVisible will set the visibility of the caret
  70      *  @param inMakeVisible true to show the caret, false to hide it
  71      */
  72     void SetVisible(bool intMakeVisible);
  73     /** IsVisible will get the visibility of the caret.
  74      *  This returns false if the caret is hidden because it was set
  75      *  to not be visible, or because the selection is not collapsed, or
  76      *  because an open popup is hiding the caret.
  77      *  It does not take account of blinking or the caret being hidden
  78      *  because we're in non-editable/disabled content.
  79      */
  80     bool IsVisible();
  81     /** SetCaretReadOnly set the appearance of the caret
  82      *  @param inMakeReadonly true to show the caret in a 'read only' state,
  83      *         false to show the caret in normal, editing state
  84      */
  85     void SetCaretReadOnly(bool inMakeReadonly);
  86     /**
  87      * @param aVisibility true if the caret should be visible even when the
  88      * selection is not collapsed.
  89      */
  90     void SetVisibilityDuringSelection(bool aVisibility);
  91
  92     /**
  93      * Set the caret's position explicitly to the specified node and offset
  94      * instead of tracking its selection.
  95      * Passing null for aNode would set the caret to track its selection again.
  96      **/
  97     void SetCaretPosition(nsIDOMNode* aNode, int32_t aOffset);
  98
  99     /**
 100      * Schedule a repaint for the frame where the caret would appear.
 101      * Does not check visibility etc.
 102      */
 103     void SchedulePaint();
 104
 105     /**
 106      * Returns a frame to paint in, and the bounds of the painted caret
 107      * relative to that frame.
 108      * The rectangle includes bidi decorations.
 109      * Returns null if the caret should not be drawn (including if it's blinked
 110      * off).
 111      */
 112     nsIFrame* GetPaintGeometry(nsRect* aRect);
 113     /**
 114      * A simple wrapper around GetGeometry. Does not take any caret state into
 115      * account other than the current selection.
 116      */
 117     nsIFrame* GetGeometry(nsRect* aRect)
 118     {
 119       return GetGeometry(GetSelection(), aRect);
 120     }
 121
 122     /** PaintCaret
 123      *  Actually paint the caret onto the given rendering context.
 124      */
 125     void PaintCaret(nsDisplayListBuilder *aBuilder,
 126                     DrawTarget& aDrawTarget,
 127                     nsIFrame *aForFrame,
 128                     const nsPoint &aOffset);
 129
 130     //nsISelectionListener interface
 131     NS_DECL_NSISELECTIONLISTENER
 132
 133     /**
 134      * Gets the position and size of the caret that would be drawn for
 135      * the focus node/offset of aSelection (assuming it would be drawn,
 136      * i.e., disregarding blink status). The geometry is stored in aRect,
 137      * and we return the frame aRect is relative to.
 138      * Only looks at the focus node of aSelection, so you can call it even if
 139      * aSelection is not collapsed.
 140      * This rect does not include any extra decorations for bidi.
 141      * @param aRect must be non-null
 142      */
 143     static nsIFrame* GetGeometry(nsISelection* aSelection,
 144                                  nsRect* aRect);
 145     static nsresult GetCaretFrameForNodeOffset(nsFrameSelection* aFrameSelection,
 146                                                nsIContent* aContentNode,
 147                                                int32_t aOffset,
 148                                                CaretAssociationHint aFrameHint,
 149                                                uint8_t aBidiLevel,
 150                                                nsIFrame** aReturnFrame,
 151                                                int32_t* aReturnOffset);
 152     static nsRect GetGeometryForFrame(nsIFrame* aFrame,
 153                                       int32_t   aFrameOffset,
 154                                       nscoord*  aBidiIndicatorSize);
 155
 156     size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf) const;
 157
 158 protected:
 159     static void   CaretBlinkCallback(nsITimer *aTimer, void *aClosure);
 160
 161     void          CheckSelectionLanguageChange();
 162
 163     void          ResetBlinking();
 164     void          StopBlinking();
 165
 166     mozilla::dom::Selection* GetSelectionInternal();
 167
 168     struct Metrics {
 169       nscoord mBidiIndicatorSize; // width and height of bidi indicator
 170       nscoord mCaretWidth;        // full caret width including bidi indicator
 171     };
 172     static Metrics ComputeMetrics(nsIFrame* aFrame, int32_t aOffset,
 173                                   nscoord aCaretHeight);
 174
 175     void          ComputeCaretRects(nsIFrame* aFrame, int32_t aFrameOffset,
 176                                     nsRect* aCaretRect, nsRect* aHookRect);
 177
 178     // Returns true if we should not draw the caret because of XUL menu popups.
 179     // The caret should be hidden if:
 180     // 1. An open popup contains the caret, but a menu popup exists before the
 181     //    caret-owning popup in the popup list (i.e. a menu is in front of the
 182     //    popup with the caret). If the menu itself contains the caret we don't
 183     //    hide it.
 184     // 2. A menu popup is open, but there is no caret present in any popup.
 185     // 3. The caret selection is empty.
 186     bool IsMenuPopupHidingCaret();
 187
 188     nsWeakPtr             mPresShell;
 189     nsWeakPtr             mDomSelectionWeak;
 190
 191     nsCOMPtr<nsITimer>    mBlinkTimer;
 192
 193     /**
 194      * The content to draw the caret at. If null, we use mDomSelectionWeak's
 195      * focus node instead.
 196      */
 197     nsCOMPtr<nsINode>     mOverrideContent;
 198     /**
 199      * The character offset to draw the caret at.
 200      * Ignored if mOverrideContent is null.
 201      */
 202     int32_t               mOverrideOffset;
 203
 204     /**
 205      * mIsBlinkOn is true when we're in a blink cycle where the caret is on.
 206      */
 207     bool                  mIsBlinkOn;
 208     /**
 209      * mIsVisible is true when SetVisible was last called with 'true'.
 210      */
 211     bool                  mVisible;
 212     /**
 213      * mReadOnly is true when the caret is set to "read only" mode (i.e.,
 214      * it doesn't blink).
 215      */
 216     bool                  mReadOnly;
 217     /**
 218      * mShowDuringSelection is true when the caret should be shown even when
 219      * the selection is not collapsed.
 220      */
 221     bool                  mShowDuringSelection;
 222     /**
 223      * mIgnoreUserModify is true when the caret should be shown even when
 224      * it's in non-user-modifiable content.
 225      */
 226     bool                  mIgnoreUserModify;
 227 };
 228
 229 #endif //nsCaret_h__