translate German comments in (and minor clean up of) sw/source/core/inc/{flowfrm,flyfrm}.hxx

sw/source/core/inc/flowfrm.hxx

@@ -25,29 +25,10 @@
  * for a copy of the LGPLv3 License.
  *
  ************************************************************************/
+
 #ifndef _FLOWFRM_HXX
 #define _FLOWFRM_HXX
 
-//Der FlowFrm gibt die Funktionalitaet fuer alle Frms vor, die fliessen und
-//die sich aufspalten koennen (wie CntntFrm oder TabFrm).
-//Teile der Funktionalitaet sind im FlowFrm implementiert, andere Teile werden
-//von den spezifischen Frms implementiert.
-//Der FlowFrm ist kein eigenstaender Frm, es kann also auch niemals eine
-//eigenstaendige Instanz vom FlowFrm existieren.
-//Der FlowFrm ist nicht einmal ein echter Frm. Die naheliegende Implementierung
-//waere ein FlowFrm der virtual vom SwFrm abgeleitet ist und direkt auf den
-//eigenen Instanzdaten arbeitet. Abgeleitete Klassen muessten sich
-//vom FlowFrm und (ueber mehrere Basisklassen weil der Klassenbaum sich direkt
-//vom SwFrm zu SwCntntFrm und zum SwLayoutFrm spaltet) virtual vom SwFrm
-//ableiten.
-//Leider entstehen dadurch - neben Problemen mit Compilern und Debuggern -
-//erhebliche zusaetzliche Kosten, die wir uns heutzutage IMHO nicht erlauben
-//koennen.
-//Ich greife deshalb auf eine andere Technik zurueck: Der FlowFrm hat eine
-//Referenz auf den SwFrm - der er genau betrachtet selbst ist - und ist mit
-//diesem befreundet. So kann der FlowFrm anstelle des this-Pointer mit der
-//Referenz auf den SwFrm arbeiten.
-
 class SwPageFrm;
 class SwRect;
 class SwBorderAttrs;
@@ -58,10 +39,32 @@ class SwObjectFormatterTxtFrm;
 
 void MakeFrms( SwDoc *, const SwNodeIndex &, const SwNodeIndex & );
 
-/// Base class for frames that are allowed at page breaks and shall continue on the next page, e.g. paragraphs, tables.
+/** Base class that provides the general functionalities for frames that are
+    allowed at page breaks (flow) and shall continue on the next page (can be
+    split), e.g. paragraphs (CntntFrm) or tables (TabFrm).
+
+    Some parts of these functionalities are implemented in FlowFrm while the
+    specific ones are done in the corresponding Frm classes. The FlowFrm has to
+    be seen as a base class. As such it is no Frm by itself and thus no direct
+    instances of FlowFrm can exist.
+
+    Actually it is not even a real Frm. The obvious implementation would be a
+    FlowFrm that is virtually inherited from SwFrm and that works with its own
+    member data. Further classes would need to inherit from FlowFrm and (via
+    multiple base classes since the class tree splits exactly at the branch
+    from SwFrm to SwCntntFrm and SwLayoutFrm) also virtually from SwFrm as
+    well. Unfortunately, this leads - besides problems with compilers and
+    debugging programs - to high additional costs, that we IMHO are not able to
+    afford nowadays.
+
+    Hence, we use another technique: A FlowFrm keeps a reference to a SwFrm
+    - which it is actually itself - and they are friends. As a result, the
+    FlowFrm can work with the reference to the SwFrm instead of working with
+    its own this-pointer.
+ */
 class SwFlowFrm
 {
-    //PrepareMake darf Locken/Unlocken (Robustheit)
+    // PrepareMake is allowed to lock/unlock (robustness)
     friend inline void PrepareLock  ( SwFlowFrm * );
     friend inline void PrepareUnlock( SwFlowFrm * );
     friend inline void TableSplitRecalcLock( SwFlowFrm * );
@@ -69,7 +72,7 @@ class SwFlowFrm
     // #i44049#
     friend class SwObjectFormatterTxtFrm;
 
-    //TblSel darf das Follow-Bit zuruecksetzen.
+    // TblSel is allowed to reset the follow-bit
     friend inline void UnsetFollow( SwFlowFrm *pFlow );
 
     friend void MakeFrms( SwDoc *, const SwNodeIndex &, const SwNodeIndex & );
@@ -78,13 +81,16 @@ class SwFlowFrm
 
     SwFrm &rThis;
 
-    //Hilfsfunktionen fuer MoveSubTree()
+    // helper methods for MoveSubTree()
     static SwLayoutFrm *CutTree( SwFrm* );
     static sal_Bool   PasteTree( SwFrm *, SwLayoutFrm *, SwFrm *, SwFrm* );
 
-    //Wird fuer das Zusammenspiel von _GetPrevxxx und MoveBwd gebraucht, damit
-    //mehrere Blaetter gleichzeitig uebersprungen werden koennen.
-    //Wird auch vom MoveBwd des TabFrm ausgewertet!
+    /** indicates that a backward move was done over multiple pages
+
+        Needed for the interaction of _GetPrevxxx and MoveBwd so that multiple
+        pages can be skipped at the same time. In addition, it is evaluated by
+        the MoveBwd() method in TabFrm.
+    */
     static sal_Bool bMoveBwdJump;
 
     /** helper method to determine previous frame for calculation of the
@@ -114,25 +120,26 @@ class SwFlowFrm
                                 const SwTwips _nUpperSpaceWithoutGrid ) const;
 
 protected:
-
     SwFlowFrm *m_pFollow;
     SwFlowFrm *m_pPrecede;
 
-    sal_Bool bLockJoin  :1; //Join (und damit deleten) verboten wenn sal_True!
-    sal_Bool bUndersized:1; // wir sind kleiner als gewuenscht
-    sal_Bool bFlyLock   :1; //  Stop positioning of at-character flyframes
+    sal_Bool bLockJoin  :1; // if sal_True than joins (and thus deletes) are prohibited!
+    sal_Bool bUndersized:1; // I am smaller than needed
+    sal_Bool bFlyLock   :1; // stop positioning of at-character flyframes
 
-    //Prueft ob Vorwaertsfluss noch Sinn macht Endloswanderschaften (unterbinden)
+    // checks if forward flow makes sense to prevent infinite moves
     inline sal_Bool IsFwdMoveAllowed();
     // #i44049# - method <CalcCntnt(..)> has to check this property.
     friend void CalcCntnt( SwLayoutFrm *pLay, bool bNoColl, bool bNoCalcFollow );
-    sal_Bool IsKeepFwdMoveAllowed();    //Wie oben, Move fuer Keep.
+    sal_Bool IsKeepFwdMoveAllowed();    // like above, forward flow for Keep.
+
+    /** method to determine overlapping of an object that requests floating
 
-    //Prueft ob ein Obj das Umlauf wuenscht ueberlappt.
-    //eine Null bedeutet, kein Objekt ueberlappt,
-    // 1 heisst, Objekte, die am FlowFrm selbst verankert sind, ueberlappen
-    // 2 heisst, Objekte, die woanders verankert sind, ueberlappen
-    // 3 heistt, beiderlei verankerte Objekte ueberlappen
+        0: no overlapping
+        1: objects that are anchored at the FlowFrm overlap
+        2: objects that are anchored somewhere else overlap
+        3: both types of objects overlap
+    */
     sal_uInt8 BwdMoveNecessary( const SwPageFrm *pPage, const SwRect &rRect );
 
     void LockJoin()   { bLockJoin = sal_True;  }
@@ -140,8 +147,8 @@ protected:
 
     sal_Bool CheckMoveFwd( bool& rbMakePage, sal_Bool bKeep, sal_Bool bMovedBwd );
     sal_Bool MoveFwd( sal_Bool bMakePage, sal_Bool bPageBreak, sal_Bool bMoveAlways = sal_False );
-    virtual sal_Bool ShouldBwdMoved( SwLayoutFrm *pNewUpper, sal_Bool bHead, sal_Bool &rReformat )=0;
     sal_Bool MoveBwd( sal_Bool &rbReformat );
+    virtual sal_Bool ShouldBwdMoved( SwLayoutFrm *pNewUpper, sal_Bool bHead, sal_Bool &rReformat )=0;
 
 public:
     SwFlowFrm( SwFrm &rFrm );
@@ -158,28 +165,26 @@ public:
 
     sal_Bool IsPrevObjMove() const;
 
-    //Die Kette mit minimalen Operationen und Benachrichtigungen unter den
-    //neuen Parent Moven.
+    /** hook tree onto new parent with minimal operations and notifications */
     void MoveSubTree( SwLayoutFrm* pParent, SwFrm* pSibling = 0 );
 
     sal_Bool HasFollow() const { return m_pFollow ? sal_True : sal_False; }
     sal_Bool IsFollow() const { return 0 != m_pPrecede; }
+    sal_Bool IsAnFollow( const SwFlowFrm *pFlow ) const;
     const SwFlowFrm *GetFollow() const { return m_pFollow; }
           SwFlowFrm *GetFollow()       { return m_pFollow; }
-           sal_Bool       IsAnFollow( const SwFlowFrm *pFlow ) const;
     void SetFollow(SwFlowFrm *const pFollow);
 
     const SwFlowFrm *GetPrecede() const { return m_pPrecede; }
           SwFlowFrm *GetPrecede()       { return m_pPrecede; }
 
-
     sal_Bool IsJoinLocked() const { return bLockJoin; }
     sal_Bool IsAnyJoinLocked() const { return bLockJoin || HasLockedFollow(); }
 
     sal_Bool IsPageBreak( sal_Bool bAct ) const;
     sal_Bool IsColBreak( sal_Bool bAct ) const;
 
-    //Ist ein Keep zu beruecksichtigen (Breaks!)
+    /** method to determine if a Keep needs to be considered (Breaks!) */
     sal_Bool IsKeep( const SwAttrSet& rAttrs, bool bBreakCheck = false ) const;
 
     sal_Bool HasLockedFollow() const;
@@ -188,9 +193,10 @@ public:
 
     /** method to determine the upper space hold by the frame
 
-        #i11860# - add 3rd parameter <_bConsiderGrid> to get
-        the upper space with and without considering the page grid
-        (default value: <sal_True>)
+        #i11860#
+
+        @param _bConsiderGrid
+        optional input parameter - consider the page grid while calculating?
     */
     SwTwips CalcUpperSpace( const SwBorderAttrs *pAttrs = NULL,
                             const SwFrm* pPr = NULL,
@@ -204,8 +210,7 @@ public:
     */
     SwTwips GetUpperSpaceAmountConsideredForPrevFrmAndPageGrid() const;
 
-    /** calculation of lower space
-    */
+    /** calculation of lower space */
     SwTwips CalcLowerSpace( const SwBorderAttrs* _pAttrs = 0L ) const;
 
     /** calculation of the additional space to be considered, if flow frame
@@ -228,8 +233,8 @@ public:
     void SetFlyLock( sal_Bool bNew ){ bFlyLock = bNew; }
     sal_Bool IsFlyLock() const {    return bFlyLock; }
 
-    //casten einen Frm auf einen FlowFrm - wenns denn einer ist, sonst 0
-    //Diese Methoden muessen fuer neue Ableitungen geaendert werden!
+    // Casting of a Frm into a FlowFrm (if it is one, otherwise 0)
+    // These methods need to be customized in subclasses!
     static       SwFlowFrm *CastFlowFrm( SwFrm *pFrm );
     static const SwFlowFrm *CastFlowFrm( const SwFrm *pFrm );
 };
@@ -238,7 +243,6 @@ inline sal_Bool SwFlowFrm::IsFwdMoveAllowed()
 {
     return rThis.GetIndPrev() != 0;
 }
-
 #endif
 
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

sw/source/core/inc/flyfrm.hxx

@@ -25,6 +25,7 @@
  * for a copy of the LGPLv3 License.
  *
  ************************************************************************/
+
 #ifndef SW_FLYFRM_HXX
 #define SW_FLYFRM_HXX
 
@@ -46,27 +47,32 @@ class SwFmt;
 
 #include <anchoredobject.hxx>
 
-//Sucht ausgehend von pOldAnch einen Anker fuer Absatzgebundene Rahmen.
-//Wird beim Draggen von Absatzgebundenen Objekten zur Ankeranzeige sowie
-//fuer Ankerwechsel benoetigt.
-//implementiert in layout/flycnt.cxx
+/** search an anchor for paragraph bound frames starting from pOldAnch
+
+    needed for dragging of objects bound to a paragraph for showing an anchor
+    indicator as well as for changing the anchor.
+
+    implemented in layout/flycnt.cxx
+ */
 const SwCntntFrm *FindAnchor( const SwFrm *pOldAnch, const Point &rNew,
                               const sal_Bool bBody = sal_False );
 
-// berechnet das Rechteck, in dem das Objekt bewegt bzw. resized werden darf
+/** calculate rectangle in that the object can be moved or rather be resized */
 sal_Bool CalcClipRect( const SdrObject *pSdrObj, SwRect &rRect, sal_Bool bMove = sal_True );
 
-//allg. Basisklasse fuer alle Freifliegenden Rahmen
-// #i26791# - inherit also from <SwAnchoredFlyFrm>
+/** general base class for all free-flowing frames
+
+    #i26791# - inherit also from <SwAnchoredFlyFrm>
+*/
 class SwFlyFrm : public SwLayoutFrm, public SwAnchoredObject
 {
-    //darf Locken. Definiert in frmtool.cxx
+    // is allowed to lock, implemented in frmtool.cxx
     friend void AppendObjs   ( const SwSpzFrmFmts *, sal_uLong, SwFrm *, SwPageFrm * );
     friend void Notify( SwFlyFrm *, SwPageFrm *pOld, const SwRect &rOld,
                         const SwRect* pOldPrt );
 
-    void InitDrawObj( sal_Bool bNotify );   //Wird von den CToren gerufen.
-    void FinitDrawObj();                //Wird vom CTor gerufen.
+    void InitDrawObj( sal_Bool bNotify ); // these to methods are called in the
+    void FinitDrawObj();                  // constructors
 
     void _UpdateAttr( const SfxPoolItem*, const SfxPoolItem*, sal_uInt8 &,
                       SwAttrSetChg *pa = 0, SwAttrSetChg *pb = 0 );
@@ -77,51 +83,50 @@ class SwFlyFrm : public SwLayoutFrm, public SwAnchoredObject
     SwVirtFlyDrawObj* CreateNewRef( SwFlyDrawContact* );
 
 protected:
-
-    SwFlyFrm *pPrevLink,        // Vorgaenger/Nachfolger fuer Verkettung mit
-             *pNextLink;        // Textfluss
-
-    // #i26791# - moved to <SwAnchoredObject>
-//    Point aRelPos;   //Die Relative Position zum Master
+    // Predecessor/Successor for chaining with text flow
+    SwFlyFrm *pPrevLink, *pNextLink;
 
 private:
-    sal_Bool bLocked    :1; //Cntnt-gebundene Flys muessen derart blockiert werden
-                        //koennen, dass sie nicht Formatiert werden; :MakeAll
-                        //returnt dann sofort. Dies ist bei Seitenwechseln
-                        //waehrend der Formatierung notwendig.
-                        //Auch wahrend des RootCTors ist dies notwendig da
-                        //sonst der Anker formatiert wird obwohl die Root noch
-                        //nicht korrekt an der Shell haengt und weil sonst
-                        //initial zuviel Formatiert wuerde.
-    sal_Bool bNotifyBack:1; //sal_True wenn am Ende eines MakeAll() der Background
-                        //vom NotifyDTor benachrichtigt werden muss.
-protected:
+    // It must be possible to block Cntnt-bound flys so that they will be not
+    // formatted; in this case MakeAll() returns immediately. This is necessary
+    // for page changes during formattting. In addition, it is needed during
+    // the constructor call of the root object since otherwise the anchor will
+    // be formatted before the root is anchored correctly to a shell and
+    // because too much would be formatted as a result.
+    sal_Bool bLocked :1;
+    // sal_True if the background of NotifyDTor needs to be notified at the end
+    // of a MakeAll() call.
+    sal_Bool bNotifyBack :1;
 
-    sal_Bool bInvalid :1;   //Pos, PrtArea od. SSize wurden Invalidiert, sie werden
-                        //gleich wieder Validiert, denn sie muessen _immer_
-                        //gueltig sein. Damit in LayAction korrekt gearbeitet
-                        //werden kann muss hier festgehalten werden, dass sie
-                        //invalidiert wurden. Ausnahmen bestaetigen die Regelt!
-    sal_Bool bMinHeight:1;  //sal_True wenn die vom Attribut vorgegebene Hoehe eine
-                        //eine Minimalhoehe ist (der Frm also bei Bedarf
-                        //darueberhinaus wachsen kann).
-    sal_Bool bHeightClipped :1; //sal_True wenn der Fly nicht die Pos/Size anhand der Attrs
-    sal_Bool bWidthClipped  :1; //formatieren konnte, weil z.B. nicht genug Raum vorh.
-                            //war.
-    sal_Bool bFormatHeightOnly  :1; //Damit nach einer Anpassung der Breite
-                                //(CheckClip) nur das Format aufgerufen wird;
-                                //nicht aber die Breite anhand der Attribute
-                                //wieder bestimmt wird.
-    sal_Bool bInCnt         :1; // FLY_AS_CHAR, anchored as character
-    sal_Bool bAtCnt         :1; // FLY_AT_PARA, anchored at paragraph
-    sal_Bool bLayout        :1; // FLY_AT_PAGE, FLY_AT_FLY, at page or at frame
-    sal_Bool bAutoPosition  :1; // FLY_AT_CHAR, anchored at character
-    sal_Bool bNoShrink      :1; // temporary forbud of shrinking to avoid loops
-    sal_Bool bLockDeleteContent :1;           // If the flag is set, the content of the
-                                        // fly frame is not deleted if moved to
-                                        // invisible layer.
-
-    friend class SwNoTxtFrm; // Darf NotifyBackground rufen
+protected:
+    // Pos, PrtArea or SSize have been invalidated - they will be evaluated
+    // again immediately because they have to be valid _at all time_.
+    // The invalidation is tracked here so that LayAction knows about it and
+    // can handle it properly. Exceptions prove the rule.
+    sal_Bool bInvalid :1;
+
+    // sal_True if the proposed height of an attribute is a minimal height
+    // (this means that the frame can grow higher if needed)
+    sal_Bool bMinHeight :1;
+    // sal_True if the fly frame could not format position/size based on its
+    // attributes, e.g. because there was not enough space.
+    sal_Bool bHeightClipped :1;
+    sal_Bool bWidthClipped :1;
+    // If sal_True call only the format after adjusting the width (CheckClip);
+    // but the width will not be re-evaluated based on the attributes.
+    sal_Bool bFormatHeightOnly :1;
+
+    sal_Bool bInCnt :1;        //< FLY_AS_CHAR, anchored as character
+    sal_Bool bAtCnt :1;        //< FLY_AT_PARA, anchored at paragraph
+    sal_Bool bLayout :1;       //< FLY_AT_PAGE, FLY_AT_FLY, at page or at frame
+    sal_Bool bAutoPosition :1; //< FLY_AT_CHAR, anchored at character
+
+    sal_Bool bNoShrink :1;     //< temporary forbid shrinking to avoid loops
+    // If sal_True, the content of the fly frame will not be deleted when it
+    // is moved to an invisible layer.
+    sal_Bool bLockDeleteContent :1;
+
+    friend class SwNoTxtFrm; // is allowed to call NotifyBackground
 
     virtual void Format( const SwBorderAttrs *pAttrs = 0 );
     void MakePrtArea( const SwBorderAttrs &rAttrs );
@@ -157,7 +162,7 @@ public:
     TYPEINFO();
 
     virtual ~SwFlyFrm();
-        // erfrage vom Client Informationen
+    // get client information
     virtual sal_Bool GetInfo( SfxPoolItem& ) const;
     virtual void Paint( SwRect const&,
                         SwPrintData const*const pPrintData = NULL ) const;
@@ -230,12 +235,13 @@ public:
                      const sal_Bool _bForPaint = sal_False ) const;
 
 
-    //Auf dieser Shell painten (PreView, Print-Flag usw. rekursiv beachten)?.
+    // Paint on this shell (consider PreView, print flag, etc. recursively)?
     static sal_Bool IsPaint( SdrObject *pObj, const ViewShell *pSh );
 
     /** SwFlyFrm::IsBackgroundTransparent
 
-        determines, if background of fly frame has to be drawn transparent
+        determines if background of fly frame has to be drawn transparently
+
         definition found in /core/layout/paintfrm.cxx
 
         @return true, if background color is transparent or a existing background
@@ -245,7 +251,8 @@ public:
 
     /** SwFlyFrm::IsShadowTransparent
 
-        determine, if shadow color of fly frame has to be drawn transparent
+        determine if shadow color of fly frame has to be drawn transparently
+
         definition found in /core/layout/paintfrm.cxx
 
         @return true, if shadow color is transparent.
@@ -267,7 +274,7 @@ public:
 
     virtual const SwRect GetObjRect() const;
 
-    /** method to determine, if a format on the Writer fly frame is possible
+    /** method to determine if a format on the Writer fly frame is possible
 
         #i28701#
         refine 'IsFormatPossible'-conditions of method
@@ -288,3 +295,4 @@ public:
 #endif
 
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
+