layout/generic/nsILineIterator.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 #ifndef nsILineIterator_h___
   7 #define nsILineIterator_h___
   8
   9 #include "nscore.h"
  10 #include "nsINode.h"
  11 #include "nsRect.h"
  12 #include "mozilla/Attributes.h"
  13 #include "mozilla/Result.h"
  14 #include "mozilla/WritingModes.h"
  15
  16 class nsIFrame;
  17
  18 /**
  19  * Line iterator API.
  20  *
  21  * Lines are numbered from 0 to N, where 0 is the top line and N is
  22  * the bottom line.
  23  *
  24  * Obtain this interface from frames via nsIFrame::GetLineIterator.
  25  * This iterator belongs to the frame from which it was obtained, and should
  26  * not be deleted by the caller.
  27  * Note that any modification of the frame will invalidate the iterator!
  28  * Users must get a new iterator any time the target may have been touched.
  29  */
  30 class nsILineIterator {
  31  protected:
  32   ~nsILineIterator() = default;
  33
  34  public:
  35   /**
  36    * The number of lines in the block
  37    */
  38   virtual int32_t GetNumLines() const = 0;
  39
  40   /**
  41    * Returns whether our lines are rtl.
  42    */
  43   virtual bool IsLineIteratorFlowRTL() = 0;
  44
  45   struct LineInfo {
  46     /** The first frame on the line. */
  47     nsIFrame* mFirstFrameOnLine = nullptr;
  48     /** The numbers of frames on the line. */
  49     int32_t mNumFramesOnLine = 0;
  50     /**
  51      * The bounding box of the line (which is based on the in-flow position of
  52      * the frames on the line; if a frame was moved because of relative
  53      * positioning then its coordinates may be outside the line bounds)
  54      */
  55     nsRect mLineBounds;
  56     /** Whether the line is wrapped at the end */
  57     bool mIsWrapped = false;
  58   };
  59
  60   // Return miscellaneous information about a line.
  61   virtual mozilla::Result<LineInfo, nsresult> GetLine(int32_t aLineNumber) = 0;
  62
  63   /**
  64    * Given a frame that's a child of the block, find which line its on
  65    * and return that line index, as long as it's at least as big as
  66    * aStartLine.  Returns -1 if the frame cannot be found on lines
  67    * starting with aStartLine.
  68    */
  69   virtual int32_t FindLineContaining(nsIFrame* aFrame,
  70                                      int32_t aStartLine = 0) = 0;
  71
  72   // Given a line number and a coordinate, find the frame on the line
  73   // that is nearest to aPos along the inline axis. (The block-axis coord
  74   // of aPos is irrelevant.)
  75   // The aPosIsBeforeFirstFrame and aPosIsAfterLastFrame flags are updated
  76   // appropriately.
  77   NS_IMETHOD FindFrameAt(int32_t aLineNumber, nsPoint aPos,
  78                          nsIFrame** aFrameFound, bool* aPosIsBeforeFirstFrame,
  79                          bool* aPosIsAfterLastFrame) = 0;
  80
  81   // Check whether visual and logical order of frames within a line are
  82   // identical.
  83   //  If not, return the first and last visual frames
  84   NS_IMETHOD CheckLineOrder(int32_t aLine, bool* aIsReordered,
  85                             nsIFrame** aFirstVisual,
  86                             nsIFrame** aLastVisual) = 0;
  87 };
  88
  89 namespace mozilla {
  90
  91 // Helper struct for FindFrameAt.
  92 struct LineFrameFinder {
  93   LineFrameFinder(const nsPoint& aPos, const nsSize& aContainerSize,
  94                   WritingMode aWM, bool aIsReversed)
  95       : mPos(aWM, aPos, aContainerSize),
  96         mContainerSize(aContainerSize),
  97         mWM(aWM),
  98         mIsReversed(aIsReversed) {}
  99
 100   void Scan(nsIFrame*);
 101   void Finish(nsIFrame**, bool* aPosIsBeforeFirstFrame,
 102               bool* aPosIsAfterLastFrame);
 103
 104   const LogicalPoint mPos;
 105   const nsSize mContainerSize;
 106   const WritingMode mWM;
 107   const bool mIsReversed;
 108
 109   bool IsDone() const { return mDone; }
 110
 111  private:
 112   bool mDone = false;
 113   nsIFrame* mFirstFrame = nullptr;
 114   nsIFrame* mClosestFromStart = nullptr;
 115   nsIFrame* mClosestFromEnd = nullptr;
 116 };
 117
 118 }  // namespace mozilla
 119
 120 /**
 121  * Helper intended to be used in a scope where we're using an nsILineIterator
 122  * and want to verify that no DOM mutations (which would invalidate the
 123  * iterator) occur while we're using it.
 124  */
 125 class MOZ_STACK_CLASS AutoAssertNoDomMutations final {
 126 #ifdef MOZ_DIAGNOSTIC_ASSERT_ENABLED
 127   nsMutationGuard mGuard;
 128 #endif
 129  public:
 130   ~AutoAssertNoDomMutations() { MOZ_DIAGNOSTIC_ASSERT(!mGuard.Mutated(0)); }
 131 };
 132
 133 #endif /* nsILineIterator_h___ */