layout/generic/nsPlaceholderFrame.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  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 /*
  39  * rendering object for the point that anchors out-of-flow rendering
  40  * objects such as floats and absolutely positioned elements
  41  */
  42
  43 /*
  44  * Destruction of a placeholder and its out-of-flow must observe the
  45  * following constraints:
  46  *
  47  * - The mapping from the out-of-flow to the placeholder must be
  48  *   removed from the frame manager before the placeholder is destroyed.
  49  * - The mapping from the out-of-flow to the placeholder must be
  50  *   removed from the frame manager before the out-of-flow is destroyed.
  51  * - The placeholder must be removed from the frame tree, or have the
  52  *   mapping from it to its out-of-flow cleared, before the out-of-flow
  53  *   is destroyed (so that the placeholder will not point to a destroyed
  54  *   frame while it's in the frame tree).
  55  *
  56  * Therefore the safe order of teardown is to:
  57  *
  58  * 1)  Unregister the placeholder from the frame manager.
  59  * 2)  Destroy the placeholder
  60  * 3)  Destroy the out of flow
  61  *
  62  * In certain cases it may be possible to replace step (2) with:
  63  *
  64  * 2') Null out the mOutOfFlowFrame pointer in the placeholder
  65  *
  66  * and add
  67  *
  68  * 4) Destroy the placeholder
  69  *
  70  * but this is somewhat dangerous, since lots of code assumes that
  71  * placeholders point to something useful.
  72  */
  73
  74 #ifndef nsPlaceholderFrame_h___
  75 #define nsPlaceholderFrame_h___
  76
  77 #include "nsSplittableFrame.h"
  78 #include "nsGkAtoms.h"
  79
  80 nsIFrame* NS_NewPlaceholderFrame(nsIPresShell* aPresShell, nsStyleContext* aContext);
  81
  82 /**
  83  * Implementation of a frame that's used as a placeholder for a frame that
  84  * has been moved out of the flow
  85  */
  86 class nsPlaceholderFrame : public nsSplittableFrame {
  87 public:
  88   /**
  89    * Create a new placeholder frame
  90    */
  91   friend nsIFrame* NS_NewPlaceholderFrame(nsIPresShell* aPresShell, nsStyleContext* aContext);
  92   nsPlaceholderFrame(nsStyleContext* aContext) : nsSplittableFrame(aContext) {}
  93   virtual ~nsPlaceholderFrame();
  94
  95   // Get/Set the associated out of flow frame
  96   nsIFrame*  GetOutOfFlowFrame() const {return mOutOfFlowFrame;}
  97   void       SetOutOfFlowFrame(nsIFrame* aFrame) {mOutOfFlowFrame = aFrame;}
  98
  99   // nsIHTMLReflow overrides
 100   // We need to override GetMinWidth and GetPrefWidth because XUL uses
 101   // placeholders not within lines.
 102   virtual nscoord GetMinWidth(nsIRenderingContext *aRenderingContext);
 103   virtual nscoord GetPrefWidth(nsIRenderingContext *aRenderingContext);
 104   virtual void AddInlineMinWidth(nsIRenderingContext *aRenderingContext,
 105                                  InlineMinWidthData *aData);
 106   virtual void AddInlinePrefWidth(nsIRenderingContext *aRenderingContext,
 107                                   InlinePrefWidthData *aData);
 108   NS_IMETHOD Reflow(nsPresContext* aPresContext,
 109                     nsHTMLReflowMetrics& aDesiredSize,
 110                     const nsHTMLReflowState& aReflowState,
 111                     nsReflowStatus& aStatus);
 112
 113   virtual void Destroy();
 114   virtual nsSplittableType GetSplittableType() const;
 115
 116   // nsIFrame overrides
 117 #if defined(DEBUG) || (defined(MOZ_REFLOW_PERF_DSP) && defined(MOZ_REFLOW_PERF))
 118   NS_IMETHOD BuildDisplayList(nsDisplayListBuilder*   aBuilder,
 119                               const nsRect&           aDirtyRect,
 120                               const nsDisplayListSet& aLists);
 121 #endif // DEBUG || (MOZ_REFLOW_PERF_DSP && MOZ_REFLOW_PERF)
 122
 123 #ifdef DEBUG
 124   NS_IMETHOD List(FILE* out, PRInt32 aIndent) const;
 125 #endif // DEBUG
 126
 127   /**
 128    * Get the "type" of the frame
 129    *
 130    * @see nsGkAtoms::placeholderFrame
 131    */
 132   virtual nsIAtom* GetType() const;
 133
 134 #ifdef DEBUG
 135   NS_IMETHOD GetFrameName(nsAString& aResult) const;
 136 #endif
 137
 138   virtual PRBool IsEmpty() { return PR_TRUE; }
 139   virtual PRBool IsSelfEmpty() { return PR_TRUE; }
 140
 141   virtual PRBool CanContinueTextRun() const;
 142
 143 #ifdef ACCESSIBILITY
 144   NS_IMETHOD  GetAccessible(nsIAccessible** aAccessible)
 145   {
 146     nsIFrame *realFrame = GetRealFrameForPlaceholder(this);
 147     return realFrame ? realFrame->GetAccessible(aAccessible) :
 148                        nsSplittableFrame::GetAccessible(aAccessible);
 149   }
 150 #endif
 151
 152   NS_IMETHOD GetParentStyleContextFrame(nsPresContext* aPresContext,
 153                                         nsIFrame**      aProviderFrame,
 154                                         PRBool*         aIsChild);
 155   /**
 156    * @return the out-of-flow for aFrame if aFrame is a placeholder; otherwise
 157    * aFrame
 158    */
 159   static nsIFrame* GetRealFrameFor(nsIFrame* aFrame) {
 160     NS_PRECONDITION(aFrame, "Must have a frame to work with");
 161     if (aFrame->GetType() == nsGkAtoms::placeholderFrame) {
 162       return GetRealFrameForPlaceholder(aFrame);
 163     }
 164     return aFrame;
 165   }
 166
 167   /**
 168    * @return the out-of-flow for aFrame, which is known to be a placeholder
 169    */
 170   static nsIFrame* GetRealFrameForPlaceholder(nsIFrame* aFrame) {
 171     NS_PRECONDITION(aFrame->GetType() == nsGkAtoms::placeholderFrame,
 172                     "Must have placeholder frame as input");
 173     nsIFrame* outOfFlow =
 174       static_cast<nsPlaceholderFrame*>(aFrame)->GetOutOfFlowFrame();
 175     NS_ASSERTION(outOfFlow, "Null out-of-flow for placeholder?");
 176     return outOfFlow;
 177   }
 178
 179 protected:
 180   nsIFrame* mOutOfFlowFrame;
 181 };
 182
 183 #endif /* nsPlaceholderFrame_h___ */