layout/generic/nsFrame.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Pierre Phaneuf <pp@ludusdesign.com>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 /* base class of all rendering objects */
  40
  41 #ifndef nsFrame_h___
  42 #define nsFrame_h___
  43
  44 #include "nsBox.h"
  45 #include "nsRect.h"
  46 #include "nsString.h"
  47 #include "prlog.h"
  48
  49 #include "nsIPresShell.h"
  50 #include "nsFrameSelection.h"
  51 #include "nsHTMLReflowState.h"
  52 #include "nsHTMLReflowMetrics.h"
  53
  54 /**
  55  * nsFrame logging constants. We redefine the nspr
  56  * PRLogModuleInfo.level field to be a bitfield.  Each bit controls a
  57  * specific type of logging. Each logging operation has associated
  58  * inline methods defined below.
  59  */
  60 #define NS_FRAME_TRACE_CALLS        0x1
  61 #define NS_FRAME_TRACE_PUSH_PULL    0x2
  62 #define NS_FRAME_TRACE_CHILD_REFLOW 0x4
  63 #define NS_FRAME_TRACE_NEW_FRAMES   0x8
  64
  65 #define NS_FRAME_LOG_TEST(_lm,_bit) (PRIntn((_lm)->level) & (_bit))
  66
  67 #ifdef NS_DEBUG
  68 #define NS_FRAME_LOG(_bit,_args)                                \
  69   PR_BEGIN_MACRO                                                \
  70     if (NS_FRAME_LOG_TEST(nsFrame::GetLogModuleInfo(),_bit)) {  \
  71       PR_LogPrint _args;                                        \
  72     }                                                           \
  73   PR_END_MACRO
  74 #else
  75 #define NS_FRAME_LOG(_bit,_args)
  76 #endif
  77
  78 // XXX Need to rework this so that logging is free when it's off
  79 #ifdef NS_DEBUG
  80 #define NS_FRAME_TRACE_IN(_method) Trace(_method, PR_TRUE)
  81
  82 #define NS_FRAME_TRACE_OUT(_method) Trace(_method, PR_FALSE)
  83
  84 // XXX remove me
  85 #define NS_FRAME_TRACE_MSG(_bit,_args)                          \
  86   PR_BEGIN_MACRO                                                \
  87     if (NS_FRAME_LOG_TEST(nsFrame::GetLogModuleInfo(),_bit)) {  \
  88       TraceMsg _args;                                           \
  89     }                                                           \
  90   PR_END_MACRO
  91
  92 #define NS_FRAME_TRACE(_bit,_args)                              \
  93   PR_BEGIN_MACRO                                                \
  94     if (NS_FRAME_LOG_TEST(nsFrame::GetLogModuleInfo(),_bit)) {  \
  95       TraceMsg _args;                                           \
  96     }                                                           \
  97   PR_END_MACRO
  98
  99 #define NS_FRAME_TRACE_REFLOW_IN(_method) Trace(_method, PR_TRUE)
 100
 101 #define NS_FRAME_TRACE_REFLOW_OUT(_method, _status) \
 102   Trace(_method, PR_FALSE, _status)
 103
 104 #else
 105 #define NS_FRAME_TRACE(_bits,_args)
 106 #define NS_FRAME_TRACE_IN(_method)
 107 #define NS_FRAME_TRACE_OUT(_method)
 108 #define NS_FRAME_TRACE_MSG(_bits,_args)
 109 #define NS_FRAME_TRACE_REFLOW_IN(_method)
 110 #define NS_FRAME_TRACE_REFLOW_OUT(_method, _status)
 111 #endif
 112
 113 // Frame allocation boilerplate macros.  Every subclass of nsFrame
 114 // must define its own operator new and GetAllocatedSize.  If they do
 115 // not, the per-frame recycler lists in nsPresArena will not work
 116 // correctly, with potentially catastrophic consequences (not enough
 117 // memory is allocated for a frame object).
 118
 119 #define NS_DECL_FRAMEARENA_HELPERS                                \
 120   NS_MUST_OVERRIDE void* operator new(size_t, nsIPresShell*);     \
 121   virtual NS_MUST_OVERRIDE nsQueryFrame::FrameIID GetFrameId();
 122
 123 #define NS_IMPL_FRAMEARENA_HELPERS(class)                         \
 124   void* class::operator new(size_t sz, nsIPresShell* aShell)      \
 125   { return aShell->AllocateFrame(nsQueryFrame::class##_id, sz); } \
 126   nsQueryFrame::FrameIID class::GetFrameId()                      \
 127   { return nsQueryFrame::class##_id; }
 128
 129 //----------------------------------------------------------------------
 130
 131 struct nsBoxLayoutMetrics;
 132
 133 /**
 134  * Implementation of a simple frame that's not splittable and has no
 135  * child frames.
 136  *
 137  * Sets the NS_FRAME_SYNCHRONIZE_FRAME_AND_VIEW bit, so the default
 138  * behavior is to keep the frame and view position and size in sync.
 139  */
 140 class nsFrame : public nsBox
 141 {
 142 public:
 143   /**
 144    * Create a new "empty" frame that maps a given piece of content into a
 145    * 0,0 area.
 146    */
 147   friend nsIFrame* NS_NewEmptyFrame(nsIPresShell* aShell,
 148                                     nsStyleContext* aContext);
 149
 150 private:
 151   // Left undefined; nsFrame objects are never allocated from the heap.
 152   void* operator new(size_t sz) CPP_THROW_NEW;
 153
 154 protected:
 155   // Overridden to prevent the global delete from being called, since
 156   // the memory came out of an arena instead of the heap.
 157   //
 158   // Ideally this would be private and undefined, like the normal
 159   // operator new.  Unfortunately, the C++ standard requires an
 160   // overridden operator delete to be accessible to any subclass that
 161   // defines a virtual destructor, so we can only make it protected;
 162   // worse, some C++ compilers will synthesize calls to this function
 163   // from the "deleting destructors" that they emit in case of
 164   // delete-expressions, so it can't even be undefined.
 165   void operator delete(void* aPtr, size_t sz);
 166
 167 public:
 168
 169   // nsQueryFrame
 170   NS_DECL_QUERYFRAME
 171   NS_DECL_FRAMEARENA_HELPERS
 172
 173   // nsIFrame
 174   NS_IMETHOD  Init(nsIContent*      aContent,
 175                    nsIFrame*        aParent,
 176                    nsIFrame*        asPrevInFlow);
 177   NS_IMETHOD  SetInitialChildList(nsIAtom*           aListName,
 178                                   nsFrameList&       aChildList);
 179   NS_IMETHOD  AppendFrames(nsIAtom*        aListName,
 180                            nsFrameList&    aFrameList);
 181   NS_IMETHOD  InsertFrames(nsIAtom*        aListName,
 182                            nsIFrame*       aPrevFrame,
 183                            nsFrameList&    aFrameList);
 184   NS_IMETHOD  RemoveFrame(nsIAtom*        aListName,
 185                           nsIFrame*       aOldFrame);
 186   virtual void DestroyFrom(nsIFrame* aDestructRoot);
 187   virtual nsStyleContext* GetAdditionalStyleContext(PRInt32 aIndex) const;
 188   virtual void SetAdditionalStyleContext(PRInt32 aIndex,
 189                                          nsStyleContext* aStyleContext);
 190   NS_IMETHOD  SetParent(const nsIFrame* aParent);
 191   virtual nscoord GetBaseline() const;
 192   virtual nsIAtom* GetAdditionalChildListName(PRInt32 aIndex) const;
 193   virtual nsFrameList GetChildList(nsIAtom* aListName) const;
 194   NS_IMETHOD  HandleEvent(nsPresContext* aPresContext,
 195                           nsGUIEvent*     aEvent,
 196                           nsEventStatus*  aEventStatus);
 197   NS_IMETHOD  GetContentForEvent(nsPresContext* aPresContext,
 198                                  nsEvent* aEvent,
 199                                  nsIContent** aContent);
 200   NS_IMETHOD  GetCursor(const nsPoint&    aPoint,
 201                         nsIFrame::Cursor& aCursor);
 202
 203   NS_IMETHOD  GetPointFromOffset(PRInt32                inOffset,
 204                                  nsPoint*               outPoint);
 205
 206   NS_IMETHOD  GetChildFrameContainingOffset(PRInt32     inContentOffset,
 207                                  PRBool                 inHint,
 208                                  PRInt32*               outFrameContentOffset,
 209                                  nsIFrame*              *outChildFrame);
 210
 211   static nsresult  GetNextPrevLineFromeBlockFrame(nsPresContext* aPresContext,
 212                                         nsPeekOffsetStruct *aPos,
 213                                         nsIFrame *aBlockFrame,
 214                                         PRInt32 aLineStart,
 215                                         PRInt8 aOutSideLimit
 216                                         );
 217
 218   NS_IMETHOD  CharacterDataChanged(CharacterDataChangeInfo* aInfo);
 219   NS_IMETHOD  AttributeChanged(PRInt32         aNameSpaceID,
 220                                nsIAtom*        aAttribute,
 221                                PRInt32         aModType);
 222   virtual nsSplittableType GetSplittableType() const;
 223   virtual nsIFrame* GetPrevContinuation() const;
 224   NS_IMETHOD  SetPrevContinuation(nsIFrame*);
 225   virtual nsIFrame* GetNextContinuation() const;
 226   NS_IMETHOD  SetNextContinuation(nsIFrame*);
 227   virtual nsIFrame* GetPrevInFlowVirtual() const;
 228   NS_IMETHOD  SetPrevInFlow(nsIFrame*);
 229   virtual nsIFrame* GetNextInFlowVirtual() const;
 230   NS_IMETHOD  SetNextInFlow(nsIFrame*);
 231   NS_IMETHOD  GetOffsetFromView(nsPoint& aOffset, nsIView** aView) const;
 232   virtual nsIAtom* GetType() const;
 233   virtual PRBool IsContainingBlock() const;
 234
 235   NS_IMETHOD  GetSelected(PRBool *aSelected) const;
 236   NS_IMETHOD  IsSelectable(PRBool* aIsSelectable, PRUint8* aSelectStyle) const;
 237
 238   NS_IMETHOD  GetSelectionController(nsPresContext *aPresContext, nsISelectionController **aSelCon);
 239
 240   virtual PRBool PeekOffsetNoAmount(PRBool aForward, PRInt32* aOffset);
 241   virtual PRBool PeekOffsetCharacter(PRBool aForward, PRInt32* aOffset);
 242   virtual PRBool PeekOffsetWord(PRBool aForward, PRBool aWordSelectEatSpace, PRBool aIsKeyboardSelect,
 243                                 PRInt32* aOffset, PeekWordState *aState);
 244   /**
 245    * Check whether we should break at a boundary between punctuation and
 246    * non-punctuation. Only call it at a punctuation boundary
 247    * (i.e. exactly one of the previous and next characters are punctuation).
 248    * @param aForward true if we're moving forward in content order
 249    * @param aPunctAfter true if the next character is punctuation
 250    * @param aWhitespaceAfter true if the next character is whitespace
 251    */
 252   PRBool BreakWordBetweenPunctuation(const PeekWordState* aState,
 253                                      PRBool aForward,
 254                                      PRBool aPunctAfter, PRBool aWhitespaceAfter,
 255                                      PRBool aIsKeyboardSelect);
 256
 257   NS_IMETHOD  CheckVisibility(nsPresContext* aContext, PRInt32 aStartIndex, PRInt32 aEndIndex, PRBool aRecurse, PRBool *aFinished, PRBool *_retval);
 258
 259   NS_IMETHOD  GetOffsets(PRInt32 &aStart, PRInt32 &aEnd) const;
 260   virtual void ChildIsDirty(nsIFrame* aChild);
 261
 262 #ifdef ACCESSIBILITY
 263   virtual already_AddRefed<nsAccessible> CreateAccessible();
 264 #endif
 265
 266   NS_IMETHOD GetParentStyleContextFrame(nsPresContext* aPresContext,
 267                                         nsIFrame**      aProviderFrame,
 268                                         PRBool*         aIsChild);
 269
 270   virtual PRBool IsEmpty();
 271   virtual PRBool IsSelfEmpty();
 272
 273   virtual void MarkIntrinsicWidthsDirty();
 274   virtual nscoord GetMinWidth(nsIRenderingContext *aRenderingContext);
 275   virtual nscoord GetPrefWidth(nsIRenderingContext *aRenderingContext);
 276   virtual void AddInlineMinWidth(nsIRenderingContext *aRenderingContext,
 277                                  InlineMinWidthData *aData);
 278   virtual void AddInlinePrefWidth(nsIRenderingContext *aRenderingContext,
 279                                   InlinePrefWidthData *aData);
 280   virtual IntrinsicWidthOffsetData
 281     IntrinsicWidthOffsets(nsIRenderingContext* aRenderingContext);
 282   virtual IntrinsicSize GetIntrinsicSize();
 283   virtual nsSize GetIntrinsicRatio();
 284
 285   virtual nsSize ComputeSize(nsIRenderingContext *aRenderingContext,
 286                              nsSize aCBSize, nscoord aAvailableWidth,
 287                              nsSize aMargin, nsSize aBorder, nsSize aPadding,
 288                              PRBool aShrinkWrap);
 289
 290   // Compute tight bounds assuming this frame honours its border, background
 291   // and outline, its children's tight bounds, and nothing else.
 292   nsRect ComputeSimpleTightBounds(gfxContext* aContext) const;
 293
 294   /**
 295    * A helper, used by |nsFrame::ComputeSize| (for frames that need to
 296    * override only this part of ComputeSize), that computes the size
 297    * that should be returned when 'width', 'height', and
 298    * min/max-width/height are all 'auto' or equivalent.
 299    *
 300    * In general, frames that can accept any computed width/height should
 301    * override only ComputeAutoSize, and frames that cannot do so need to
 302    * override ComputeSize to enforce their width/height invariants.
 303    *
 304    * Implementations may optimize by returning a garbage width if
 305    * GetStylePosition()->mWidth.GetUnit() != eStyleUnit_Auto, and
 306    * likewise for height, since in such cases the result is guaranteed
 307    * to be unused.
 308    */
 309   virtual nsSize ComputeAutoSize(nsIRenderingContext *aRenderingContext,
 310                                  nsSize aCBSize, nscoord aAvailableWidth,
 311                                  nsSize aMargin, nsSize aBorder,
 312                                  nsSize aPadding, PRBool aShrinkWrap);
 313
 314   /**
 315    * Utility function for ComputeAutoSize implementations.  Return
 316    * max(GetMinWidth(), min(aWidthInCB, GetPrefWidth()))
 317    */
 318   nscoord ShrinkWidthToFit(nsIRenderingContext *aRenderingContext,
 319                            nscoord aWidthInCB);
 320
 321   NS_IMETHOD  WillReflow(nsPresContext* aPresContext);
 322   NS_IMETHOD  Reflow(nsPresContext*          aPresContext,
 323                      nsHTMLReflowMetrics&     aDesiredSize,
 324                      const nsHTMLReflowState& aReflowState,
 325                      nsReflowStatus&          aStatus);
 326   NS_IMETHOD  DidReflow(nsPresContext*           aPresContext,
 327                         const nsHTMLReflowState*  aReflowState,
 328                         nsDidReflowStatus         aStatus);
 329   virtual PRBool CanContinueTextRun() const;
 330
 331   // Selection Methods
 332   // XXX Doc me... (in nsIFrame.h puhleeze)
 333   // XXX If these are selection specific, then the name should imply selection
 334   // rather than generic event processing, e.g., SelectionHandlePress...
 335   NS_IMETHOD HandlePress(nsPresContext* aPresContext,
 336                          nsGUIEvent *    aEvent,
 337                          nsEventStatus*  aEventStatus);
 338
 339   NS_IMETHOD HandleMultiplePress(nsPresContext* aPresContext,
 340                          nsGUIEvent *    aEvent,
 341                          nsEventStatus*  aEventStatus,
 342                          PRBool          aControlHeld);
 343
 344   NS_IMETHOD HandleDrag(nsPresContext* aPresContext,
 345                         nsGUIEvent *    aEvent,
 346                         nsEventStatus*  aEventStatus);
 347
 348   NS_IMETHOD HandleRelease(nsPresContext* aPresContext,
 349                            nsGUIEvent *    aEvent,
 350                            nsEventStatus*  aEventStatus);
 351
 352   NS_IMETHOD PeekBackwardAndForward(nsSelectionAmount aAmountBack,
 353                                     nsSelectionAmount aAmountForward,
 354                                     PRInt32 aStartPos,
 355                                     nsPresContext* aPresContext,
 356                                     PRBool aJumpLines,
 357                                     PRBool aMultipleSelection);
 358
 359
 360   // Helper for GetContentAndOffsetsFromPoint; calculation of content offsets
 361   // in this function assumes there is no child frame that can be targeted.
 362   virtual ContentOffsets CalcContentOffsetsFromFramePoint(nsPoint aPoint);
 363
 364   // Box layout methods
 365   virtual nsSize GetPrefSize(nsBoxLayoutState& aBoxLayoutState);
 366   virtual nsSize GetMinSize(nsBoxLayoutState& aBoxLayoutState);
 367   virtual nsSize GetMaxSize(nsBoxLayoutState& aBoxLayoutState);
 368   virtual nscoord GetFlex(nsBoxLayoutState& aBoxLayoutState);
 369   virtual nscoord GetBoxAscent(nsBoxLayoutState& aBoxLayoutState);
 370
 371   // We compute and store the HTML content's overflow area. So don't
 372   // try to compute it in the box code.
 373   virtual PRBool ComputesOwnOverflowArea() { return PR_TRUE; }
 374
 375   //--------------------------------------------------
 376   // Additional methods
 377
 378   /**
 379    * Helper method to invalidate portions of a standard container frame if the
 380    * desired size indicates that the size has changed (specifically border,
 381    * background and outline).
 382    * We assume that the difference between the old frame area and the new
 383    * frame area is invalidated by some other means.
 384    * @param aDesiredSize the new size of the frame
 385    */
 386   void CheckInvalidateSizeChange(nsHTMLReflowMetrics&     aNewDesiredSize);
 387
 388   // Helper function that tests if the frame tree is too deep; if it
 389   // is it marks the frame as "unflowable" and zeros out the metrics
 390   // and returns PR_TRUE. Otherwise, the frame is unmarked
 391   // "unflowable" and the metrics are not touched and PR_FALSE is
 392   // returned.
 393   PRBool IsFrameTreeTooDeep(const nsHTMLReflowState& aReflowState,
 394                             nsHTMLReflowMetrics& aMetrics);
 395
 396   // Do the work for getting the parent style context frame so that
 397   // other frame's |GetParentStyleContextFrame| methods can call this
 398   // method on *another* frame.  (This function handles out-of-flow
 399   // frames by using the frame manager's placeholder map and it also
 400   // handles block-within-inline and generated content wrappers.)
 401   nsresult DoGetParentStyleContextFrame(nsPresContext* aPresContext,
 402                                         nsIFrame**      aProviderFrame,
 403                                         PRBool*         aIsChild);
 404
 405   // incorporate the child overflow area into the parent overflow area
 406   // if the child does not have a overflow use the child area
 407   void ConsiderChildOverflow(nsRect&   aOverflowArea,
 408                              nsIFrame* aChildFrame);
 409
 410   virtual const void* GetStyleDataExternal(nsStyleStructID aSID) const;
 411
 412
 413 #ifdef NS_DEBUG
 414   /**
 415    * Tracing method that writes a method enter/exit routine to the
 416    * nspr log using the nsIFrame log module. The tracing is only
 417    * done when the NS_FRAME_TRACE_CALLS bit is set in the log module's
 418    * level field.
 419    */
 420   void Trace(const char* aMethod, PRBool aEnter);
 421   void Trace(const char* aMethod, PRBool aEnter, nsReflowStatus aStatus);
 422   void TraceMsg(const char* fmt, ...);
 423
 424   // Helper function that verifies that each frame in the list has the
 425   // NS_FRAME_IS_DIRTY bit set
 426   static void VerifyDirtyBitSet(const nsFrameList& aFrameList);
 427
 428   // Helper function to return the index in parent of the frame's content
 429   // object. Returns -1 on error or if the frame doesn't have a content object
 430   static PRInt32 ContentIndexInContainer(const nsIFrame* aFrame);
 431
 432   static void IndentBy(FILE* out, PRInt32 aIndent) {
 433     while (--aIndent >= 0) fputs("  ", out);
 434   }
 435
 436   void ListTag(FILE* out) const {
 437     ListTag(out, this);
 438   }
 439
 440   static void ListTag(FILE* out, const nsIFrame* aFrame) {
 441     nsAutoString tmp;
 442     aFrame->GetFrameName(tmp);
 443     fputs(NS_LossyConvertUTF16toASCII(tmp).get(), out);
 444     fprintf(out, "@%p", static_cast<const void*>(aFrame));
 445   }
 446
 447   static void XMLQuote(nsString& aString);
 448
 449   /**
 450    * Dump out the "base classes" regression data. This should dump
 451    * out the interior data, not the "frame" XML container. And it
 452    * should call the base classes same named method before doing
 453    * anything specific in a derived class. This means that derived
 454    * classes need not override DumpRegressionData unless they need
 455    * some custom behavior that requires changing how the outer "frame"
 456    * XML container is dumped.
 457    */
 458   virtual void DumpBaseRegressionData(nsPresContext* aPresContext, FILE* out, PRInt32 aIndent);
 459
 460   nsresult MakeFrameName(const nsAString& aKind, nsAString& aResult) const;
 461
 462   // Display Reflow Debugging
 463   static void* DisplayReflowEnter(nsPresContext*          aPresContext,
 464                                   nsIFrame*                aFrame,
 465                                   const nsHTMLReflowState& aReflowState);
 466   static void* DisplayLayoutEnter(nsIFrame* aFrame);
 467   static void* DisplayIntrinsicWidthEnter(nsIFrame* aFrame,
 468                                           const char* aType);
 469   static void* DisplayIntrinsicSizeEnter(nsIFrame* aFrame,
 470                                          const char* aType);
 471   static void  DisplayReflowExit(nsPresContext*      aPresContext,
 472                                  nsIFrame*            aFrame,
 473                                  nsHTMLReflowMetrics& aMetrics,
 474                                  PRUint32             aStatus,
 475                                  void*                aFrameTreeNode);
 476   static void  DisplayLayoutExit(nsIFrame* aFrame,
 477                                  void* aFrameTreeNode);
 478   static void  DisplayIntrinsicWidthExit(nsIFrame* aFrame,
 479                                          const char* aType,
 480                                          nscoord aResult,
 481                                          void* aFrameTreeNode);
 482   static void  DisplayIntrinsicSizeExit(nsIFrame* aFrame,
 483                                         const char* aType,
 484                                         nsSize aResult,
 485                                         void* aFrameTreeNode);
 486
 487   static void DisplayReflowStartup();
 488   static void DisplayReflowShutdown();
 489 #endif
 490
 491   static void ShutdownLayerActivityTimer();
 492
 493   /**
 494    * Adds display item for standard CSS background if necessary.
 495    * Does not check IsVisibleForPainting.
 496    * @param aForceBackground draw the background even if the frame
 497    * background style appears to have no background --- this is useful
 498    * for frames that might receive a propagated background via
 499    * nsCSSRendering::FindBackground
 500    */
 501   nsresult DisplayBackgroundUnconditional(nsDisplayListBuilder*   aBuilder,
 502                                           const nsDisplayListSet& aLists,
 503                                           PRBool aForceBackground = PR_FALSE);
 504   /**
 505    * Adds display items for standard CSS borders, background and outline for
 506    * for this frame, as necessary. Checks IsVisibleForPainting and won't
 507    * display anything if the frame is not visible.
 508    * @param aForceBackground draw the background even if the frame
 509    * background style appears to have no background --- this is useful
 510    * for frames that might receive a propagated background via
 511    * nsCSSRendering::FindBackground
 512    */
 513   nsresult DisplayBorderBackgroundOutline(nsDisplayListBuilder*   aBuilder,
 514                                           const nsDisplayListSet& aLists,
 515                                           PRBool aForceBackground = PR_FALSE);
 516   /**
 517    * Add a display item for the CSS outline. Does not check visibility.
 518    */
 519   nsresult DisplayOutlineUnconditional(nsDisplayListBuilder*   aBuilder,
 520                                        const nsDisplayListSet& aLists);
 521   /**
 522    * Add a display item for the CSS outline, after calling
 523    * IsVisibleForPainting to confirm we are visible.
 524    */
 525   nsresult DisplayOutline(nsDisplayListBuilder*   aBuilder,
 526                           const nsDisplayListSet& aLists);
 527
 528   /**
 529    * Adjust the given parent frame to the right style context parent frame for
 530    * the child, given the pseudo-type of the prospective child.  This handles
 531    * things like walking out of table pseudos and so forth.
 532    *
 533    * @param aProspectiveParent what GetParent() on the child returns.
 534    *                           Must not be null.
 535    * @param aChildPseudo the child's pseudo type, if any.
 536    */
 537   static nsIFrame*
 538   CorrectStyleParentFrame(nsIFrame* aProspectiveParent, nsIAtom* aChildPseudo);
 539
 540 protected:
 541   // Protected constructor and destructor
 542   nsFrame(nsStyleContext* aContext);
 543   virtual ~nsFrame();
 544
 545   /**
 546    * To be called by |BuildDisplayLists| of this class or derived classes to add
 547    * a translucent overlay if this frame's content is selected.
 548    * @param aContentType an nsISelectionDisplay DISPLAY_ constant identifying
 549    * which kind of content this is for
 550    */
 551   nsresult DisplaySelectionOverlay(nsDisplayListBuilder* aBuilder,
 552       const nsDisplayListSet& aLists, PRUint16 aContentType = nsISelectionDisplay::DISPLAY_FRAMES);
 553
 554   PRInt16 DisplaySelection(nsPresContext* aPresContext, PRBool isOkToTurnOn = PR_FALSE);
 555
 556   // Style post processing hook
 557   virtual void DidSetStyleContext(nsStyleContext* aOldStyleContext);
 558
 559 public:
 560   //given a frame five me the first/last leaf available
 561   //XXX Robert O'Callahan wants to move these elsewhere
 562   static void GetLastLeaf(nsPresContext* aPresContext, nsIFrame **aFrame);
 563   static void GetFirstLeaf(nsPresContext* aPresContext, nsIFrame **aFrame);
 564
 565   // Return the line number of the aFrame, and (optionally) the containing block
 566   // frame.
 567   // If aScrollLock is true, don't break outside scrollframes when looking for a
 568   // containing block frame.
 569   static PRInt32 GetLineNumber(nsIFrame *aFrame,
 570                                PRBool aLockScroll,
 571                                nsIFrame** aContainingBlock = nsnull);
 572
 573 protected:
 574
 575   // Test if we are selecting a table object:
 576   //  Most table/cell selection requires that Ctrl (Cmd on Mac) key is down
 577   //   during a mouse click or drag. Exception is using Shift+click when
 578   //   already in "table/cell selection mode" to extend a block selection
 579   //  Get the parent content node and offset of the frame
 580   //   of the enclosing cell or table (if not inside a cell)
 581   //  aTarget tells us what table element to select (currently only cell and table supported)
 582   //  (enums for this are defined in nsIFrame.h)
 583   NS_IMETHOD GetDataForTableSelection(const nsFrameSelection *aFrameSelection,
 584                                       nsIPresShell *aPresShell, nsMouseEvent *aMouseEvent,
 585                                       nsIContent **aParentContent, PRInt32 *aContentOffset,
 586                                       PRInt32 *aTarget);
 587
 588   // Fills aCursor with the appropriate information from ui
 589   static void FillCursorInformationFromStyle(const nsStyleUserInterface* ui,
 590                                              nsIFrame::Cursor& aCursor);
 591   NS_IMETHOD DoLayout(nsBoxLayoutState& aBoxLayoutState);
 592
 593 #ifdef DEBUG_LAYOUT
 594   virtual void GetBoxName(nsAutoString& aName);
 595 #endif
 596
 597   void InitBoxMetrics(PRBool aClear);
 598   nsBoxLayoutMetrics* BoxMetrics() const;
 599
 600   // Fire DOM event. If no aContent argument use frame's mContent.
 601   void FireDOMEvent(const nsAString& aDOMEventName, nsIContent *aContent = nsnull);
 602
 603 private:
 604   nsresult BoxReflow(nsBoxLayoutState& aState,
 605                      nsPresContext*    aPresContext,
 606                      nsHTMLReflowMetrics&     aDesiredSize,
 607                      nsIRenderingContext* aRenderingContext,
 608                      nscoord aX,
 609                      nscoord aY,
 610                      nscoord aWidth,
 611                      nscoord aHeight,
 612                      PRBool aMoveFrame = PR_TRUE);
 613
 614   NS_IMETHODIMP RefreshSizeCache(nsBoxLayoutState& aState);
 615
 616   virtual nsILineIterator* GetLineIterator();
 617
 618 #ifdef NS_DEBUG
 619 public:
 620   // Formerly the nsIFrameDebug interface
 621
 622   NS_IMETHOD  List(FILE* out, PRInt32 aIndent) const;
 623   /**
 624    * lists the frames beginning from the root frame
 625    * - calls root frame's List(...)
 626    */
 627   static void RootFrameList(nsPresContext* aPresContext,
 628                             FILE* out, PRInt32 aIndent);
 629
 630   static void DumpFrameTree(nsIFrame* aFrame);
 631
 632   /**
 633    * Get a printable from of the name of the frame type.
 634    * XXX This should be eliminated and we use GetType() instead...
 635    */
 636   NS_IMETHOD  GetFrameName(nsAString& aResult) const;
 637   /**
 638    * Return the state bits that are relevant to regression tests (that
 639    * is, those bits which indicate a real difference when they differ
 640    */
 641   NS_IMETHOD_(nsFrameState)  GetDebugStateBits() const;
 642   /**
 643    * Called to dump out regression data that describes the layout
 644    * of the frame and its children, and so on. The format of the
 645    * data is dictated to be XML (using a specific DTD); the
 646    * specific kind of data dumped is up to the frame itself, with
 647    * the caveat that some base types are defined.
 648    * For more information, see XXX.
 649    */
 650   NS_IMETHOD  DumpRegressionData(nsPresContext* aPresContext,
 651                                  FILE* out, PRInt32 aIndent);
 652
 653   /**
 654    * See if style tree verification is enabled. To enable style tree
 655    * verification add "styleverifytree:1" to your NSPR_LOG_MODULES
 656    * environment variable (any non-zero debug level will work). Or,
 657    * call SetVerifyStyleTreeEnable with PR_TRUE.
 658    */
 659   static PRBool GetVerifyStyleTreeEnable();
 660
 661   /**
 662    * Set the verify-style-tree enable flag.
 663    */
 664   static void SetVerifyStyleTreeEnable(PRBool aEnabled);
 665
 666   /**
 667    * The frame class and related classes share an nspr log module
 668    * for logging frame activity.
 669    *
 670    * Note: the log module is created during library initialization which
 671    * means that you cannot perform logging before then.
 672    */
 673   static PRLogModuleInfo* GetLogModuleInfo();
 674
 675   // Show frame borders when rendering
 676   static void ShowFrameBorders(PRBool aEnable);
 677   static PRBool GetShowFrameBorders();
 678
 679   // Show frame border of event target
 680   static void ShowEventTargetFrameBorder(PRBool aEnable);
 681   static PRBool GetShowEventTargetFrameBorder();
 682
 683   static void PrintDisplayList(nsDisplayListBuilder* aBuilder,
 684                                const nsDisplayList& aList);
 685
 686 #endif
 687 };
 688
 689 // Start Display Reflow Debugging
 690 #ifdef DEBUG
 691
 692   struct DR_cookie {
 693     DR_cookie(nsPresContext*          aPresContext,
 694               nsIFrame*                aFrame,
 695               const nsHTMLReflowState& aReflowState,
 696               nsHTMLReflowMetrics&     aMetrics,
 697               nsReflowStatus&          aStatus);
 698     ~DR_cookie();
 699     void Change() const;
 700
 701     nsPresContext*          mPresContext;
 702     nsIFrame*                mFrame;
 703     const nsHTMLReflowState& mReflowState;
 704     nsHTMLReflowMetrics&     mMetrics;
 705     nsReflowStatus&          mStatus;
 706     void*                    mValue;
 707   };
 708
 709   struct DR_layout_cookie {
 710     DR_layout_cookie(nsIFrame* aFrame);
 711     ~DR_layout_cookie();
 712
 713     nsIFrame* mFrame;
 714     void* mValue;
 715   };
 716
 717   struct DR_intrinsic_width_cookie {
 718     DR_intrinsic_width_cookie(nsIFrame* aFrame, const char* aType,
 719                               nscoord& aResult);
 720     ~DR_intrinsic_width_cookie();
 721
 722     nsIFrame* mFrame;
 723     const char* mType;
 724     nscoord& mResult;
 725     void* mValue;
 726   };
 727
 728   struct DR_intrinsic_size_cookie {
 729     DR_intrinsic_size_cookie(nsIFrame* aFrame, const char* aType,
 730                              nsSize& aResult);
 731     ~DR_intrinsic_size_cookie();
 732
 733     nsIFrame* mFrame;
 734     const char* mType;
 735     nsSize& mResult;
 736     void* mValue;
 737   };
 738
 739   struct DR_init_constraints_cookie {
 740     DR_init_constraints_cookie(nsIFrame* aFrame, nsHTMLReflowState* aState,
 741                                nscoord aCBWidth, nscoord aCBHeight,
 742                                const nsMargin* aBorder,
 743                                const nsMargin* aPadding);
 744     ~DR_init_constraints_cookie();
 745
 746     nsIFrame* mFrame;
 747     nsHTMLReflowState* mState;
 748     void* mValue;
 749   };
 750
 751   struct DR_init_offsets_cookie {
 752     DR_init_offsets_cookie(nsIFrame* aFrame, nsCSSOffsetState* aState,
 753                            nscoord aCBWidth, const nsMargin* aBorder,
 754                            const nsMargin* aPadding);
 755     ~DR_init_offsets_cookie();
 756
 757     nsIFrame* mFrame;
 758     nsCSSOffsetState* mState;
 759     void* mValue;
 760   };
 761
 762   struct DR_init_type_cookie {
 763     DR_init_type_cookie(nsIFrame* aFrame, nsHTMLReflowState* aState);
 764     ~DR_init_type_cookie();
 765
 766     nsIFrame* mFrame;
 767     nsHTMLReflowState* mState;
 768     void* mValue;
 769   };
 770
 771 #define DISPLAY_REFLOW(dr_pres_context, dr_frame, dr_rf_state, dr_rf_metrics, dr_rf_status) \
 772   DR_cookie dr_cookie(dr_pres_context, dr_frame, dr_rf_state, dr_rf_metrics, dr_rf_status);
 773 #define DISPLAY_REFLOW_CHANGE() \
 774   dr_cookie.Change();
 775 #define DISPLAY_LAYOUT(dr_frame) \
 776   DR_layout_cookie dr_cookie(dr_frame);
 777 #define DISPLAY_MIN_WIDTH(dr_frame, dr_result) \
 778   DR_intrinsic_width_cookie dr_cookie(dr_frame, "Min", dr_result)
 779 #define DISPLAY_PREF_WIDTH(dr_frame, dr_result) \
 780   DR_intrinsic_width_cookie dr_cookie(dr_frame, "Pref", dr_result)
 781 #define DISPLAY_PREF_SIZE(dr_frame, dr_result) \
 782   DR_intrinsic_size_cookie dr_cookie(dr_frame, "Pref", dr_result)
 783 #define DISPLAY_MIN_SIZE(dr_frame, dr_result) \
 784   DR_intrinsic_size_cookie dr_cookie(dr_frame, "Min", dr_result)
 785 #define DISPLAY_MAX_SIZE(dr_frame, dr_result) \
 786   DR_intrinsic_size_cookie dr_cookie(dr_frame, "Max", dr_result)
 787 #define DISPLAY_INIT_CONSTRAINTS(dr_frame, dr_state, dr_cbw, dr_cbh,       \
 788                                  dr_bdr, dr_pad)                           \
 789   DR_init_constraints_cookie dr_cookie(dr_frame, dr_state, dr_cbw, dr_cbh, \
 790                                        dr_bdr, dr_pad)
 791 #define DISPLAY_INIT_OFFSETS(dr_frame, dr_state, dr_cbw, dr_bdr, dr_pad)  \
 792   DR_init_offsets_cookie dr_cookie(dr_frame, dr_state, dr_cbw, dr_bdr, dr_pad)
 793 #define DISPLAY_INIT_TYPE(dr_frame, dr_result) \
 794   DR_init_type_cookie dr_cookie(dr_frame, dr_result)
 795
 796 #else
 797
 798 #define DISPLAY_REFLOW(dr_pres_context, dr_frame, dr_rf_state, dr_rf_metrics, dr_rf_status)
 799 #define DISPLAY_REFLOW_CHANGE()
 800 #define DISPLAY_LAYOUT(dr_frame) PR_BEGIN_MACRO PR_END_MACRO
 801 #define DISPLAY_MIN_WIDTH(dr_frame, dr_result) PR_BEGIN_MACRO PR_END_MACRO
 802 #define DISPLAY_PREF_WIDTH(dr_frame, dr_result) PR_BEGIN_MACRO PR_END_MACRO
 803 #define DISPLAY_PREF_SIZE(dr_frame, dr_result) PR_BEGIN_MACRO PR_END_MACRO
 804 #define DISPLAY_MIN_SIZE(dr_frame, dr_result) PR_BEGIN_MACRO PR_END_MACRO
 805 #define DISPLAY_MAX_SIZE(dr_frame, dr_result) PR_BEGIN_MACRO PR_END_MACRO
 806 #define DISPLAY_INIT_CONSTRAINTS(dr_frame, dr_state, dr_cbw, dr_cbh,       \
 807                                  dr_bdr, dr_pad)                           \
 808   PR_BEGIN_MACRO PR_END_MACRO
 809 #define DISPLAY_INIT_OFFSETS(dr_frame, dr_state, dr_cbw, dr_bdr, dr_pad)  \
 810   PR_BEGIN_MACRO PR_END_MACRO
 811 #define DISPLAY_INIT_TYPE(dr_frame, dr_result) PR_BEGIN_MACRO PR_END_MACRO
 812
 813 #endif
 814 // End Display Reflow Debugging
 815
 816 // similar to NS_ENSURE_TRUE but with no return value
 817 #define ENSURE_TRUE(x)                                        \
 818   PR_BEGIN_MACRO                                              \
 819     if (!(x)) {                                               \
 820        NS_WARNING("ENSURE_TRUE(" #x ") failed");              \
 821        return;                                                \
 822     }                                                         \
 823   PR_END_MACRO
 824 #endif /* nsFrame_h___ */