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