Bug 1319672 Part 1 - Add document related to writing-mode in nsFloatManager. r=dbaron
authorTing-Yu Lin <tlin@mozilla.com>
Wed, 23 Nov 2016 18:07:56 +0800
changeset 324625 81eb4fbbb3ef691d439fce501778f3ef19d05f2f
parent 324624 9f8294cdd9bb9f672993e62543696d182ff268a8
child 324626 cb5869f00c9f6b1f6f9360e0883e958050e51502
push id24
push usermaklebus@msu.edu
push dateTue, 20 Dec 2016 03:11:33 +0000
reviewersdbaron
bugs1319672
milestone53.0a1
Bug 1319672 Part 1 - Add document related to writing-mode in nsFloatManager. r=dbaron MozReview-Commit-ID: 2Sr7UU6BQ9r
layout/generic/nsFloatManager.h
--- a/layout/generic/nsFloatManager.h
+++ b/layout/generic/nsFloatManager.h
@@ -40,16 +40,36 @@ struct nsFlowAreaRect {
                  nscoord aISize, nscoord aBSize,
                  bool aHasFloats)
     : mRect(aWritingMode, aICoord, aBCoord, aISize, aBSize)
     , mHasFloats(aHasFloats) {}
 };
 
 #define NS_FLOAT_MANAGER_CACHE_SIZE 4
 
+/**
+ * nsFloatManager is responsible for implementing CSS's rules for
+ * positioning floats. An nsFloatManager object is created during reflow for
+ * any block with NS_BLOCK_FLOAT_MGR. During reflow, the float manager for
+ * the nearest such ancestor block is found in ReflowInput::mFloatManager.
+ *
+ * According to the line-relative mappings in CSS Writing Modes spec [1],
+ * line-right and line-left are calculated with respect to the writing mode
+ * of the containing block of the floats. All the writing modes passed to
+ * nsFloatManager methods should be the containing block's writing mode.
+ *
+ * However, according to the abstract-to-physical mappings table [2], the
+ * 'direction' property of the containing block doesn't affect the
+ * interpretation of line-right and line-left. We actually implement this by
+ * passing in the writing mode of the block formatting context (BFC), i.e.
+ * the of BlockReflowInput's writing mode.
+ *
+ * [1] https://drafts.csswg.org/css-writing-modes/#line-mappings
+ * [2] https://drafts.csswg.org/css-writing-modes/#logical-to-physical
+ */
 class nsFloatManager {
 public:
   explicit nsFloatManager(nsIPresShell* aPresShell, mozilla::WritingMode aWM);
   ~nsFloatManager();
 
   void* operator new(size_t aSize) CPP_THROW_NEW;
   void operator delete(void* aPtr, size_t aSize);
 
@@ -380,16 +400,18 @@ private:
     nsRect mRect;
     // This is the reference box of css shape-outside if specified, which
     // implements the <shape-box> value in the CSS Shapes Module Level 1.
     // The coordinate setup is the same as mRect.
     mozilla::Maybe<nsRect> mShapeBoxRect;
   };
 
 #ifdef DEBUG
+  // Store the writing mode from the block frame which establishes the block
+  // formatting context (BFC) when the nsFloatManager is created.
   mozilla::WritingMode mWritingMode;
 #endif
 
   // Translation from local to global coordinate space.
   nscoord mLineLeft, mBlockStart;
   nsTArray<FloatInfo> mFloats;
   nsIntervalSet   mFloatDamage;