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  *
   4  * ***** BEGIN LICENSE BLOCK *****
   5  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   6  *
   7  * The contents of this file are subject to the Mozilla Public License Version
   8  * 1.1 (the "License"); you may not use this file except in compliance with
   9  * the License. You may obtain a copy of the License at
  10  * http://www.mozilla.org/MPL/
  11  *
  12  * Software distributed under the License is distributed on an "AS IS" basis,
  13  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14  * for the specific language governing rights and limitations under the
  15  * License.
  16  *
  17  * The Original Code is mozilla.org code.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1998
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 /* the caret is the text cursor used, e.g., when editing */
  41
  42 #ifndef nsCaret_h__
  43 #define nsCaret_h__
  44
  45 #include "nsCoord.h"
  46 #include "nsISelectionListener.h"
  47 #include "nsITimer.h"
  48 #include "nsWeakPtr.h"
  49 #include "nsFrameSelection.h"
  50
  51 class nsIRenderingContext;
  52 class nsDisplayListBuilder;
  53
  54 //-----------------------------------------------------------------------------
  55 class nsCaret : public nsISelectionListener
  56 {
  57   public:
  58
  59                   nsCaret();
  60     virtual       ~nsCaret();
  61
  62     enum EViewCoordinates {
  63       eTopLevelWindowCoordinates,
  64       eRenderingViewCoordinates,
  65       eClosestViewCoordinates
  66     };
  67
  68   public:
  69
  70     NS_DECL_ISUPPORTS
  71
  72     nsresult    Init(nsIPresShell *inPresShell);
  73     void    Terminate();
  74
  75     nsISelection*    GetCaretDOMSelection();
  76     nsresult    SetCaretDOMSelection(nsISelection *inDOMSel);
  77
  78     /** GetCaretVisible will get the visibility of the caret
  79      *  This function is virtual so that it can be used by nsCaretAccessible
  80      *  without linking
  81      *  @param inMakeVisible PR_TRUE it is shown, PR_FALSE it is hidden
  82      *  @return false if and only if inMakeVisible is null, otherwise true
  83      */
  84     virtual nsresult    GetCaretVisible(PRBool *outMakeVisible);
  85
  86     /** SetCaretVisible will set the visibility of the caret
  87      *  @param inMakeVisible PR_TRUE to show the caret, PR_FALSE to hide it
  88      */
  89     void    SetCaretVisible(PRBool intMakeVisible);
  90
  91     /** SetCaretReadOnly set the appearance of the caret
  92      *  @param inMakeReadonly PR_TRUE to show the caret in a 'read only' state,
  93      *      PR_FALSE to show the caret in normal, editing state
  94      */
  95     void    SetCaretReadOnly(PRBool inMakeReadonly);
  96
  97     /** GetCaretReadOnly get the appearance of the caret
  98      *  @return PR_TRUE if the caret is in 'read only' state, otherwise,
  99      *      returns PR_FALSE
 100      */
 101     PRBool GetCaretReadOnly()
 102     {
 103       return mReadOnly;
 104     }
 105
 106     /**
 107      * Gets the position and size of the caret that would be drawn for
 108      * the focus node/offset of aSelection (assuming it would be drawn,
 109      * i.e., disregarding blink status). The geometry is stored in aRect,
 110      * and we return the frame aRect is relative to.
 111      * @param aRect must be non-null
 112      * @param aBidiIndicatorSize if non-null, set to the bidi indicator size.
 113      */
 114     virtual nsIFrame* GetGeometry(nsISelection* aSelection,
 115                                   nsRect* aRect,
 116                                   nscoord* aBidiIndicatorSize = nsnull);
 117
 118     /** EraseCaret
 119      *  this will erase the caret if its drawn and reset drawn status
 120      */
 121     void    EraseCaret();
 122
 123     void    SetVisibilityDuringSelection(PRBool aVisibility);
 124
 125     /** DrawAtPosition
 126      *
 127      *  Draw the caret explicitly, at the specified node and offset.
 128      *  To avoid drawing glitches, you should call EraseCaret()
 129      *  after each call to DrawAtPosition().
 130      *
 131      *  Note: This call breaks the caret's ability to blink at all.
 132      **/
 133     nsresult    DrawAtPosition(nsIDOMNode* aNode, PRInt32 aOffset);
 134
 135     /** GetCaretFrame
 136      *  Get the current frame that the caret should be drawn in. If the caret is
 137      *  not currently visible (i.e., it is between blinks), then this will
 138      *  return null.
 139      *
 140      *  @param aOffset is result of the caret offset in the content.
 141      */
 142     nsIFrame*     GetCaretFrame(PRInt32 *aOffset = nsnull);
 143
 144     /** GetCaretRect
 145      *  Get the current caret rect. Only call this when GetCaretFrame returns
 146      *  non-null.
 147      */
 148     nsRect        GetCaretRect()
 149     {
 150       nsRect r;
 151       r.UnionRect(mCaretRect, GetHookRect());
 152       return r;
 153     }
 154
 155     /** InvalidateOutsideCaret
 156      *  Invalidate the area that the caret currently occupies if the caret is
 157      *  outside of its frame's overflow area. This is used when the content that
 158      *  the caret is currently drawn is is being deleted or reflowed.
 159      */
 160     void      InvalidateOutsideCaret();
 161
 162     /** UpdateCaretPosition
 163      *  Update the caret's current frame and rect, but don't draw yet. This is
 164      *  useful for flickerless moving of the caret (e.g., when the frame the
 165      *  caret is in reflows and is moved).
 166      */
 167     void      UpdateCaretPosition();
 168
 169     /** PaintCaret
 170      *  Actually paint the caret onto the given rendering context.
 171      */
 172     void      PaintCaret(nsDisplayListBuilder *aBuilder,
 173                          nsIRenderingContext *aCtx,
 174                          nsIFrame *aForFrame,
 175                          const nsPoint &aOffset);
 176     /**
 177      * Sets whether the caret should only be visible in nodes that are not
 178      * user-modify: read-only, or whether it should be visible in all nodes.
 179      *
 180      * @param aIgnoreUserModify PR_TRUE to have the cursor visible in all nodes,
 181      *                          PR_FALSE to have it visible in all nodes except
 182      *                          those with user-modify: read-only
 183      */
 184
 185     void SetIgnoreUserModify(PRBool aIgnoreUserModify);
 186
 187     //nsISelectionListener interface
 188     NS_DECL_NSISELECTIONLISTENER
 189
 190     static void   CaretBlinkCallback(nsITimer *aTimer, void *aClosure);
 191
 192     nsresult      GetCaretFrameForNodeOffset(nsIContent* aContentNode,
 193                                              PRInt32 aOffset,
 194                                              nsFrameSelection::HINT aFrameHint,
 195                                              PRUint8 aBidiLevel,
 196                                              nsIFrame** aReturnFrame,
 197                                              PRInt32* aReturnOffset);
 198
 199     NS_IMETHOD CheckCaretDrawingState();
 200
 201 protected:
 202
 203     void          KillTimer();
 204     nsresult      PrimeTimer();
 205
 206     void          StartBlinking();
 207     void          StopBlinking();
 208
 209     PRBool        DrawAtPositionWithHint(nsIDOMNode* aNode,
 210                                          PRInt32 aOffset,
 211                                          nsFrameSelection::HINT aFrameHint,
 212                                          PRUint8 aBidiLevel,
 213                                          PRBool aInvalidate);
 214
 215     struct Metrics {
 216       nscoord mBidiIndicatorSize; // width and height of bidi indicator
 217       nscoord mCaretWidth;        // full caret width including bidi indicator
 218     };
 219     Metrics ComputeMetrics(nsIFrame* aFrame, PRInt32 aOffset, nscoord aCaretHeight);
 220     nsresult GetGeometryForFrame(nsIFrame* aFrame,
 221                                  PRInt32   aFrameOffset,
 222                                  nsRect*   aRect,
 223                                  nscoord*  aBidiIndicatorSize);
 224
 225     // Returns true if the caret should be drawn. When |mDrawn| is true,
 226     // this returns true, so that we erase the drawn caret. If |aIgnoreDrawnState|
 227     // is true, we don't take into account whether the caret is currently
 228     // drawn or not. This can be used to determine if the caret is drawn when
 229     // it shouldn't be.
 230     PRBool        MustDrawCaret(PRBool aIgnoreDrawnState);
 231
 232     void          DrawCaret(PRBool aInvalidate);
 233     void          DrawCaretAfterBriefDelay();
 234     PRBool        UpdateCaretRects(nsIFrame* aFrame, PRInt32 aFrameOffset);
 235     static void   InvalidateRects(const nsRect &aRect, const nsRect &aHook,
 236                                   nsIFrame *aFrame);
 237     nsRect        GetHookRect()
 238     {
 239 #ifdef IBMBIDI
 240       return mHookRect;
 241 #else
 242       return nsRect();
 243 #endif
 244     }
 245     void          ToggleDrawnStatus() { mDrawn = !mDrawn; }
 246
 247     already_AddRefed<nsFrameSelection> GetFrameSelection();
 248
 249     // Returns true if we should not draw the caret because of XUL menu popups.
 250     // The caret should be hidden if:
 251     // 1. An open popup contains the caret, but a menu popup exists before the
 252     //    caret-owning popup in the popup list (i.e. a menu is in front of the
 253     //    popup with the caret). If the menu itself contains the caret we don't
 254     //    hide it.
 255     // 2. A menu popup is open, but there is no caret present in any popup.
 256     // 3. The caret selection is empty.
 257     PRBool IsMenuPopupHidingCaret();
 258
 259 protected:
 260
 261     nsWeakPtr             mPresShell;
 262     nsWeakPtr             mDomSelectionWeak;
 263
 264     nsCOMPtr<nsITimer>    mBlinkTimer;
 265
 266     // XXX these fields should go away and the values be acquired as needed,
 267     // probably by ComputeMetrics.
 268     PRUint32              mBlinkRate;         // time for one cyle (on then off), in milliseconds
 269     nscoord               mCaretWidthCSSPx;   // caret width in CSS pixels
 270     float                 mCaretAspectRatio;  // caret width/height aspect ratio
 271
 272     PRPackedBool          mVisible;           // is the caret blinking
 273
 274     PRPackedBool          mDrawn;             // Denotes when the caret is physically drawn on the screen.
 275     PRPackedBool          mPendingDraw;       // True when the last on-state draw was suppressed.
 276
 277     PRPackedBool          mReadOnly;          // it the caret in readonly state (draws differently)
 278     PRPackedBool          mShowDuringSelection; // show when text is selected
 279
 280     PRPackedBool          mIgnoreUserModify;
 281
 282 #ifdef IBMBIDI
 283     PRPackedBool          mKeyboardRTL;       // is the keyboard language right-to-left
 284     PRPackedBool          mBidiUI;            // is bidi UI turned on
 285     nsRect                mHookRect;          // directional hook on the caret
 286     PRUint8               mLastBidiLevel;     // saved bidi level of the last draw request, to use when we erase
 287 #endif
 288     nsRect                mCaretRect;         // the last caret rect, in the coodinates of the last frame.
 289
 290     nsCOMPtr<nsIContent>  mLastContent;       // store the content the caret was last requested to be drawn
 291                                               // in (by DrawAtPosition()/DrawCaret()),
 292                                               // note that this can be different than where it was
 293                                               // actually drawn (anon <BR> in text control)
 294     PRInt32               mLastContentOffset; // the offset for the last request
 295
 296     nsFrameSelection::HINT mLastHint;        // the hint associated with the last request, see also
 297                                               // mLastBidiLevel below
 298
 299 };
 300
 301 nsresult
 302 NS_NewCaret(nsCaret** aInstancePtrResult);
 303
 304 // handy stack-based class for temporarily disabling the caret
 305
 306 class StCaretHider
 307 {
 308 public:
 309                StCaretHider(nsCaret* aSelCon)
 310                : mWasVisible(PR_FALSE), mCaret(aSelCon)
 311                {
 312                  if (mCaret)
 313                  {
 314                    mCaret->GetCaretVisible(&mWasVisible);
 315                    if (mWasVisible)
 316                      mCaret->SetCaretVisible(PR_FALSE);
 317                  }
 318                }
 319
 320                ~StCaretHider()
 321                {
 322                  if (mCaret && mWasVisible)
 323                    mCaret->SetCaretVisible(PR_TRUE);
 324                  // nsCOMPtr releases mPresShell
 325                }
 326
 327 protected:
 328
 329     PRBool                  mWasVisible;
 330     nsCOMPtr<nsCaret>  mCaret;
 331 };
 332
 333 #endif //nsCaret_h__