layout/generic/nsSplittableFrame.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 /*
   8  * base class for rendering objects that can be split across lines,
   9  * columns, or pages
  10  */
  11
  12 #ifndef nsSplittableFrame_h___
  13 #define nsSplittableFrame_h___
  14
  15 #include "mozilla/Attributes.h"
  16 #include "nsIFrame.h"
  17
  18 // Derived class that allows splitting
  19 class nsSplittableFrame : public nsIFrame {
  20  public:
  21   NS_DECL_ABSTRACT_FRAME(nsSplittableFrame)
  22   NS_DECL_QUERYFRAME_TARGET(nsSplittableFrame)
  23   NS_DECL_QUERYFRAME
  24
  25   void Init(nsIContent* aContent, nsContainerFrame* aParent,
  26             nsIFrame* aPrevInFlow) override;
  27
  28   void Destroy(DestroyContext&) override;
  29
  30   /*
  31    * Frame continuations can be either fluid or non-fluid.
  32    *
  33    * Fluid continuations ("in-flows") are the result of line breaking,
  34    * column breaking, or page breaking.
  35    *
  36    * Non-fluid continuations can be the result of BiDi frame splitting,
  37    * column-span splitting, or <col span="N"> where N > 1.
  38    *
  39    * A "flow" is a chain of fluid continuations.
  40    *
  41    * For more information, see
  42    * https://firefox-source-docs.mozilla.org/layout/LayoutOverview.html#fragmentation
  43    */
  44
  45   // Get the previous/next continuation, regardless of its type (fluid or
  46   // non-fluid).
  47   nsIFrame* GetPrevContinuation() const final;
  48   nsIFrame* GetNextContinuation() const final;
  49
  50   // Set a previous non-fluid continuation.
  51   //
  52   // WARNING: this method updates caches for next-continuations, so it has O(n)
  53   // time complexity over the length of next-continuations in the chain.
  54   void SetPrevContinuation(nsIFrame*) final;
  55
  56   // Set a next non-fluid continuation.
  57   void SetNextContinuation(nsIFrame*) final;
  58
  59   // Get the first/last continuation for this frame.
  60   nsIFrame* FirstContinuation() const final;
  61   nsIFrame* LastContinuation() const final;
  62
  63 #ifdef DEBUG
  64   // Can aFrame2 be reached from aFrame1 by following prev/next continuations?
  65   static bool IsInPrevContinuationChain(nsIFrame* aFrame1, nsIFrame* aFrame2);
  66   static bool IsInNextContinuationChain(nsIFrame* aFrame1, nsIFrame* aFrame2);
  67 #endif
  68
  69   // Get the previous/next continuation, only if it is fluid (an "in-flow").
  70   nsIFrame* GetPrevInFlow() const final;
  71   nsIFrame* GetNextInFlow() const final;
  72
  73   // Set a previous fluid continuation.
  74   //
  75   // WARNING: this method updates caches for next-continuations, so it has O(n)
  76   // time complexity over the length of next-continuations in the chain.
  77   void SetPrevInFlow(nsIFrame*) final;
  78
  79   // Set a next fluid continuation.
  80   void SetNextInFlow(nsIFrame*) final;
  81
  82   // Get the first/last frame in the current flow.
  83   nsIFrame* FirstInFlow() const final;
  84   nsIFrame* LastInFlow() const final;
  85
  86   // Remove the frame from the flow. Connects the frame's prev-in-flow and its
  87   // next-in-flow. This should only be called during frame destruction, e.g. in
  88   // frame's Destroy() method.
  89   static void RemoveFromFlow(nsIFrame* aFrame);
  90
  91  protected:
  92   nsSplittableFrame(ComputedStyle* aStyle, nsPresContext* aPresContext,
  93                     ClassID aID)
  94       : nsIFrame(aStyle, aPresContext, aID) {}
  95
  96   // Return the first-continuation for this frame if this frame is the
  97   // first-continuation in the chain or if it has a cached first-continuation.
  98   // Otherwise, return nullptr.
  99   nsIFrame* GetFirstContinuationIfCached() const;
 100
 101   // Return the first-in-flow for this frame if this frame is the first-in-flow
 102   // in the chain or if it has a cached first-in-flow. Otherwise, return
 103   // nullptr.
 104   nsIFrame* GetFirstInFlowIfCached() const;
 105
 106   // Update the first-continuation and first-in-flow cache for this frame and
 107   // the next-continuations in the chain.
 108   //
 109   // Note: this function assumes that the first-continuation and first-in-flow
 110   // caches are already up-to-date on this frame's
 111   // prev-continuation/prev-in-flow frame (if there is such a frame).
 112   void UpdateFirstContinuationAndFirstInFlowCache();
 113
 114   /**
 115    * Return the sum of the block-axis content size of our previous
 116    * continuations.
 117    *
 118    * Classes that call this are _required_ to call this at least once for each
 119    * reflow (unless you're the first continuation, in which case you can skip
 120    * it, because as an optimization we don't cache it there).
 121    *
 122    * This guarantees that the internal cache works, by refreshing it. Calling it
 123    * multiple times in the same reflow is wasteful, but not an error.
 124    */
 125   nscoord CalcAndCacheConsumedBSize();
 126
 127   /**
 128    * This static wrapper over CalcAndCacheConsumedBSize() is intended for a
 129    * specific scenario where an nsSplittableFrame's subclass needs to access
 130    * another subclass' consumed block-size. For ordinary use cases,
 131    * CalcAndCacheConsumedBSize() should be called.
 132    *
 133    * This has the same requirements as CalcAndCacheConsumedBSize(). In
 134    * particular, classes that call this are _required_ to call this at least
 135    * once for each reflow.
 136    */
 137   static nscoord ConsumedBSize(nsSplittableFrame* aFrame) {
 138     return aFrame->CalcAndCacheConsumedBSize();
 139   }
 140
 141   /**
 142    * Retrieve the effective computed block size of this frame, which is the
 143    * computed block size, minus the block size consumed by any previous
 144    * continuations.
 145    */
 146   nscoord GetEffectiveComputedBSize(const ReflowInput& aReflowInput,
 147                                     nscoord aConsumed) const;
 148
 149   /**
 150    * @see nsIFrame::GetLogicalSkipSides()
 151    */
 152   LogicalSides GetLogicalSkipSides() const override {
 153     return GetBlockLevelLogicalSkipSides(true);
 154   }
 155
 156   LogicalSides GetBlockLevelLogicalSkipSides(bool aAfterReflow) const;
 157
 158   /**
 159    * A version of GetLogicalSkipSides() that is intended to be used inside
 160    * Reflow before it's known if |this| frame will be COMPLETE or not.
 161    * It returns a result that assumes this fragment is the last and thus
 162    * should apply the block-end border/padding etc (except for "true" overflow
 163    * containers which always skip block sides).  You're then expected to
 164    * recalculate the block-end side (as needed) when you know |this| frame's
 165    * reflow status is INCOMPLETE.
 166    * This method is intended for frames that break in the block axis.
 167    */
 168   LogicalSides PreReflowBlockLevelLogicalSkipSides() const {
 169     return GetBlockLevelLogicalSkipSides(false);
 170   };
 171
 172   nsIFrame* mPrevContinuation = nullptr;
 173   nsIFrame* mNextContinuation = nullptr;
 174 };
 175
 176 #endif /* nsSplittableFrame_h___ */