Started to improve header comments for FL

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@13644 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

contrib/include/wx/fl/antiflickpl.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        No names yet.
+// Name:        antiflickpl.h
-// Purpose:     Contrib. demo
+// Purpose:     Double-buffering plugin class for reducing flicker
 // Author:      Aleksandras Gluchovas (@Lithuania)
 // Modified by:
 // Created:     23/10/98
@@ -18,14 +18,18 @@
 
 #include "wx/fl/controlbar.h"
 
+/*
+Implements double-buffering to reduce flicker.
+Bitmap and memory DC buffers are shared "resources" among all instances of
+antiflicker plugins within the application.
+
+Locking for multithreaded applications is  not yet implemented.
+*/
+
 class cbAntiflickerPlugin : public cbPluginBase
 {
 	DECLARE_DYNAMIC_CLASS( cbAntiflickerPlugin )
 protected:
-	// double-buffers are shared "resource" among all instances of 
-	// antiflicker plugin within the application 
-	//
-	// TODO:: locking should be implemented, for multithreaded GUIs
 
 	static wxBitmap*   mpVertBuf;
 	static wxBitmap*   mpHorizBuf;
@@ -34,15 +38,16 @@ protected:
 
 	static int mRefCount;
 
-	wxDC*  mpLRUBufDc; // last-reacently-used buffer
+	wxDC*  mpLRUBufDc; // last-recently-used buffer
-	wxRect mLRUArea;   // last-reacently-used area
+	wxRect mLRUArea;   // last-recently-used area
 
 protected:
-	// returns NULL, if sutable buffer is not present
+	// Finds a suitable buffer. Returns NULL if a suitable buffer is not present.
 	wxDC* FindSuitableBuffer( const wxRect& forArea );
+	// Allocates a suitable buffer.
 	wxDC* AllocNewBuffer( const wxRect& forArea );
-	wxDC& GetWindowDC();
 
+	wxDC& GetWindowDC();
 	wxDC& GetClientDC();
 public:
 
@@ -52,9 +57,10 @@ public:
 
 	virtual ~cbAntiflickerPlugin();
 
-	// handlers for plugin events
+	// Handler for plugin event.
-
 	void OnStartDrawInArea ( cbStartDrawInAreaEvent& event );
+
+	// Handler for plugin event.
 	void OnFinishDrawInArea( cbFinishDrawInAreaEvent& event );
 
 	DECLARE_EVENT_TABLE()

contrib/include/wx/fl/bardragpl.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        No names yet.
+// Name:        bardragpl.h
-// Purpose:     Contrib. demo
+// Purpose:     cbBarDragPlugin class
 // Author:      Aleksandras Gluchovas
 // Modified by:
 // Created:     23/09/98
@@ -30,7 +30,7 @@ protected:
 	wxScreenDC*    mpScrDc;            // created while tracking hint-rect
 	wxCursor*      mpCurCursor;
 
-	// rectnagle shows the position/dimensions of the bar, 
+	// rectangle shows the position/dimensions of the bar,
 	// if it would be docked now
 
 	wxRect         mPrevHintRect;
@@ -57,62 +57,108 @@ public: /*** public properties ***/
 
 protected:
 
-
+    // Internal implementation function.
 	void AdjustHintRect( wxPoint& mousePos );
 
+    // Internal implementation function.
 	void ClipRectInFrame( wxRect& rect );
+
+    // Internal implementation function.
 	void ClipPosInFrame( wxPoint& pos );
 
+    // Internal implementation function. Finds the pane
+    // under the specified rectangle.
 	cbDockPane* HitTestPanes( wxRect& rect );
+
+    // Internal implementation function. Finds the pane
+    // under the specified point.
 	cbDockPane* HitTestPanes( wxPoint& pos );
+
+    // Internal implementation function.
 	bool HitsPane( cbDockPane* pPane, wxRect& rect );
 
+    // Internal implementation function.
 	void CalcOnScreenDims( wxRect& rect );
 
+    // Internal implementation function.
 	int  GetDistanceToPane( cbDockPane* pPane, wxPoint& mousePos );
 
+    // Internal implementation function.
 	bool IsInOtherPane ( wxPoint& mousePos );
+
+    // Internal implementation function.
 	bool IsInClientArea( wxPoint& mousePos );
+
+    // Internal implementation function.
 	bool IsInClientArea( wxRect& rect );
 
+    // Internal implementation function.
 	void StickToPane( cbDockPane* pPane, wxPoint& mousePos );
+
+    // Internal implementation function.
 	void UnstickFromPane( cbDockPane* pPane, wxPoint& mousePos );
 
+    // Internal implementation function.
 	int GetBarWidthInPane( cbDockPane* pPane );
+
+    // Internal implementation function.
 	int GetBarHeightInPane( cbDockPane* pPane );
 
 	// on-screen hint-tracking related methods
 
+    // Internal implementation function.
+    // Start showing a visual hint while dragging.
 	void StartTracking();
 
+    // Internal implementation function.
+    // Draw the visual hint while dragging.
 	void DrawHintRect ( wxRect& rect, bool isInClientRect);
+    // Internal implementation function.
+    // Erase the visual hint while dragging.
 	void EraseHintRect( wxRect& rect, bool isInClientRect);
 
+    // Internal implementation function.
+    // Stop showing the visual hint while dragging.
 	void FinishTracking();
 
+    // Internal implementation function.
+    // Draw the hint rectangle.
 	void DoDrawHintRect( wxRect& rect, bool isInClientRect);
 
+    // Internal implementation function.
+    // Converts the given rectangle from window to screen coordinates.
 	void RectToScr( wxRect& frameRect, wxRect& scrRect );
 
+    // Internal implementation function.
+    // Show the hint; called within OnMouseMove.
 	void ShowHint( bool prevWasInClient );
 
 public:
+    // Default constructor.
 	cbBarDragPlugin(void);
 
+    // Constructor taking a parent frame, and flag. See cbPluginBase.
 	cbBarDragPlugin( wxFrameLayout* pPanel, int paneMask = wxALL_PANES );
 
+    // Destructor.
 	virtual ~cbBarDragPlugin();
 
-	// handlers for plugin events
+	// Handler for plugin event.
-
 	void OnMouseMove( cbMotionEvent& event );
+
+	// Handler for plugin event.
 	void OnLButtonUp( cbLeftUpEvent& event );
+
+	// Handler for plugin event.
 	void OnLButtonDown( cbLeftDownEvent& event );
+
+	// Handler for plugin event.
 	void OnLDblClick( cbLeftDClickEvent& event );
 
-	// handles event, which oriniates from itself
+	// Handles event, which originates from itself.
 	void OnDrawHintRect( cbDrawHintRectEvent& event );        
 
+	// Handler for plugin event.
 	void OnStartBarDragging( cbStartBarDraggingEvent& event );
 
 	DECLARE_EVENT_TABLE()

contrib/include/wx/fl/barhintspl.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        No names yet.
+// Name:        barhintspl.h
-// Purpose:     Contrib. demo
+// Purpose:     cbBarHintsPlugin class declaration
 // Author:      Aleksandras Gluchovas
 // Modified by:
 // Created:     30/11/98 (my 22th birthday :-)
@@ -20,9 +20,9 @@
 #include "wx/fl/toolwnd.h"
 
 /*
- * Intercepts bar-decoration and sizing events, draws 3d-hints
+This class intercepts bar-decoration and sizing events, and draws 3D hints
- * around fixed and flexible bars, similar to those in Microsoft DevStudio 6.x
+around fixed and flexible bars, similar to those in Microsoft DevStudio 6.x
- */
+*/
 
 class cbBarHintsPlugin : public cbPluginBase
 {
@@ -39,24 +39,33 @@ protected:
 	bool        mDepressed;
 
 protected:
-	// drawing helpers
+    // Helper function: draws a 3D box.
-
 	void Draw3DBox      ( wxDC& dc, const wxPoint& pos, bool pressed );
+
+    // Helper function: draws a close box.
 	void DrawCloseBox   ( wxDC& dc, const wxPoint& pos, bool pressed );
+
+    // Helper function: draws a collapse box.
 	void DrawCollapseBox( wxDC& dc, const wxPoint& pos, 
 						  bool atLeft, bool disabled, bool pressed );
 
+    // Helper function: draws grooves.
 	void DrawGrooves    ( wxDC& dc, const wxPoint& pos, int length );
 
+    // Helper function: draws a hint.
 	void DoDrawHint( wxDC& dc, wxRect& rect, int pos, int boxOfs, int grooveOfs, bool isFixed );
 	
+    // Helper function: gets the layout of a hint.
 	void GetHintsLayout( wxRect& rect, cbBarInfo& info, 
 						 int& boxOfs, int& grooveOfs, int& pos );
 
+    // Helper function: returns information about the hint under the given position.
 	int HitTestHints( cbBarInfo& info, const wxPoint& pos );
 
+    // Helper function.
 	void ExcludeHints( wxRect& rect, cbBarInfo& info );
 
+    // Helper function: creates close and collapse boxes.
 	void CreateBoxes();
 
 public:
@@ -69,24 +78,34 @@ public:
 	int  mXWeight;       // default: 2 (width in pixels of lines which used for drawing cross)
 
 public:
-
+    // Default constructor.
 	cbBarHintsPlugin(void);
 
+    // Constructor, taking parent frame and pane mask flag.
 	cbBarHintsPlugin( wxFrameLayout* pLayout, int paneMask = wxALL_PANES );
 
+    // Destructor.
     ~cbBarHintsPlugin();
 
+    // Set the number of grooves to be shown in the pane.
 	void SetGrooveCount( int nGrooves );
 
+    // Called to initialize this plugin.
 	void OnInitPlugin();
 
-	// handlers of plugin-events
+	// Handles a plugin event.
-
 	void OnSizeBarWindow( cbSizeBarWndEvent& event );
+
+	// Handles a plugin event.
 	void OnDrawBarDecorations( cbDrawBarDecorEvent& event );
 
+	// Handles a plugin event.
 	void OnLeftDown( cbLeftDownEvent& event );
+
+	// Handles a plugin event.
 	void OnLeftUp  ( cbLeftUpEvent&   event );
+
+	// Handles a plugin event.
 	void OnMotion  ( cbMotionEvent&   event );
 
 	DECLARE_EVENT_TABLE()

contrib/include/wx/fl/cbcustom.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        No names yet.
+// Name:        cbcustom.h
-// Purpose:     Contrib. demo
+// Purpose:     cbSimpleCustomizationPlugin class declaration
 // Author:      Aleksandras Gluchovas
 // Modified by:
 // Created:     28/10/98
@@ -18,6 +18,12 @@
 
 #include "wx/fl/controlbar.h"
 
+/*
+This class enables customization of a bar, popping up a
+menu and handling basic customization such as floating
+and horizontal/vertical alignment of the bar.
+*/
+
 class cbSimpleCustomizationPlugin : public cbPluginBase
 {
 public:
@@ -26,18 +32,19 @@ public:
 	int mCustMenuItemId;
 public:
 
+    // Default constructor.
 	cbSimpleCustomizationPlugin(void);
 
+    // Constructor, taking parent pane and a pane mask flag.
 	cbSimpleCustomizationPlugin( wxFrameLayout* pPanel, int paneMask = wxALL_PANES );
 
-	// plugin-event handlers
+	// Plugin event handler for cbCustomizeBarEvent.
-
 	void OnCustomizeBar( cbCustomizeBarEvent& event );
 
+	// Plugin event handler for cbCustomizeLayoutEvent.
 	void OnCustomizeLayout( cbCustomizeLayoutEvent& event );
 
-	// menu-event handler
+	// Menu event handler.
-
 	void OnMenuItemSelected( wxCommandEvent& event );
 
 	DECLARE_EVENT_TABLE()

contrib/include/wx/fl/controlbar.h

@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        No names yet.
+// Name:        controlbar.h
 // Purpose:     Central header file for control-bar related classes
 //
 // Author:      Aleksandras Gluchovas <mailto:alex@soften.ktu.lt>
@@ -92,13 +92,15 @@ enum CB_HITTEST_RESULT
 	CB_BAR_CONTENT_HITTED
 };
 
-// FIXME:: somehow in debug v. originall wxASSERT's are not compiled in...
+// FIXME:: somehow in debug v. original wxASSERT's are not compiled in...
 
 //#undef  wxASSERT
 //#define wxASSERT(x) if ( !(x) ) throw;
 
-// helper class, used for spying for not-handled mouse events on control-bars
+/*
-// and forwarding them to the frame layout
+Helper class, used for spying for unhandled mouse events on control bars
+and forwarding them to the frame layout.
+*/
 
 class cbBarSpy : public wxEvtHandler
 {
@@ -109,277 +111,357 @@ public:
 	wxWindow*      mpBarWnd;
 
 public:
+    // Default constructor.
+
 	cbBarSpy(void);
 
+    // Constructor, taking a parent pane.
+
 	cbBarSpy( wxFrameLayout* pPanel );
 
+    // Sets the bar window.
+
 	void SetBarWindow( wxWindow* pWnd );
 
-	// overriden
+	// Performs special event processing.
 
 	virtual bool ProcessEvent(wxEvent& event);
 };
 
-/* wxFrameLayout manages containment and docking of control bars.
+/*
- * which can be docked along top, bottom, righ, or left side of the
+wxFrameLayout manages containment and docking of control bars,
- * parent frame
+which can be docked along the top, bottom, right, or left side of the
- */
+parent frame.
+*/
 
 class wxFrameLayout : public wxEvtHandler
 {
 public:
-	wxFrameLayout(void); // used only while serializing
+    // Default constructor, used only for serialization.
+
+	wxFrameLayout();
+
+    // Constructor, taking parent window, the (MDI) client of the parent if there
+    // is one, and flag specifying whether to activate the layout.
 
 	wxFrameLayout( wxWindow* pParentFrame,
 				   wxWindow* pFrameClient = NULL,
 				   bool      activateNow  = TRUE );
 
-	// (doesn't destroy bar windows)
+	// Destructor. It does not destroy the bar windows.
+
 	virtual ~wxFrameLayout();
 
-	// (by default floating of control-bars is ON)
+	// Enables floating behaviour. By default floating of control bars is on.
+
 	virtual void EnableFloating( bool enable = TRUE );
 
-	// Can be called after some other layout has been deactivated,
+	// Activate can be called after some other layout has been deactivated,
-	// and this one must "take over" the current contents of frame window.
+	// and this one must take over the current contents of the frame window.
 	//
-	// Effectively hooks itself to the frame window, re-displays all not-hidden
+	// Effectively hooks itself to the frame window, re-displays all non-hidden
-	// bar-windows and repaints decorations
+	// bar windows and repaints the decorations.
 
 	virtual void Activate();
 
-	// unhooks itself from frame window, and hides all not-hidden windows
+	// Deactivate unhooks itself from frame window, and hides all non-hidden windows.
 	//
-	// NOTE:: two frame-layouts should not be active at the same time in the
+	// Note: two frame layouts should not be active at the same time in the
-	//        same frame window, it would cause messy overlapping of bar windows
+	// same frame window, since it would cause messy overlapping of bar windows
-	//        from both layouts
+	// from both layouts.
 
 	virtual void Deactivate();
 
-	// also hides the client window if presents
+	// Hides the bar windows, and also the client window if present.
 
 	void HideBarWindows();
 
+    // Destroys the bar windows.
+
 	virtual void DestroyBarWindows();
 
-	// passes the client window (e.g. MDI-client frame) to be controled by
+	// Passes the client window (e.g. MDI client window) to be controlled by
 	// frame layout, the size and position of which should be adjusted to be
-	// surrounded by controlbar panes, whenever frame is resized, or dimensions
+	// surrounded by controlbar panes, whenever the frame is resized or the dimensions
-	// of control panes change
+	// of control panes change.
 
 	void SetFrameClient( wxWindow* pFrameClient );
 
+    // Returns the frame client, or NULL if not present.
+
 	wxWindow* GetFrameClient();
 
+    // Returns the parent frame.
+
 	wxWindow& GetParentFrame() { return *mpFrame; }
 
-	// used by updates-managers
+	// Returns an array of panes. Used by update managers.
+
 	cbDockPane** GetPanesArray() { return mPanes; }
 
-	// see pane alignment types
+	// Returns a pane for the given alignment. See pane alignment types.
+
 	cbDockPane* GetPane( int alignment )
 
 		{ return mPanes[alignment]; }
 
-	// Adds bar information to frame-layout, appearence of layout is not refreshed
+	// Adds bar information to the frame layout. The appearance of the layout is not refreshed
-	// immediately, RefreshNow() can be called if necessary.
+	// immediately; RefreshNow() can be called if necessary.
 	//
-	// NOTES:: argument pBarWnd can by NULL, resulting bar decorations to be drawn
+	// Notes: the argument pBarWnd can by NULL, resulting in bar decorations to be drawn
-	//         around the empty rectangle (filled with default background colour).
+	// around the empty rectangle (filled with default background colour).
-	//         Argument dimInfo, can be re-used for adding any number of bars, since
+	// Argument dimInfo can be reused for adding any number of bars, since
-	//         it is not used directly, instead it's members are copied. If dimensions-
+	// it is not used directly - instead its members are copied. If the dimensions
-	//         handler is present, it's instance shared (reference counted). Dimension
+	// handler is present, its instance is shared (reference counted). The dimension
-	//         handler should always be allocated on the heap!)
+	// handler should always be allocated on the heap.
+
+    // pBarWnd is the window to be managed.
+
+    // dimInfo contains dimension information.
+
+    // alignment is a value such as FL_ALIGN_TOP.
+
+	// rowNo is the vertical position or row in the pane (if in docked state).
+
+	// columnPos is the horizontal position within the row in pixels (if in docked state).
+
+	// name is a name by which the bar can be referred in layout customization dialogs.
+
+	// If spyEvents is TRUE, input events for the bar should be "spyed" in order
+    // to forward unhandled mouse clicks to the frame layout, for example to enable
+    // easy draggablity of toolbars just by clicking on their interior regions.
+    // For widgets like text/tree control this value should be FALSE,
+	// since there's no certain way to detect  whether the event was actually handled.
+
+	// state is the initial state, such as wxCBAR_DOCKED_HORIZONTALLY,
+    // wxCBAR_FLOATING, wxCBAR_HIDDEN.
 
 	virtual void AddBar( wxWindow*        pBarWnd,
                          const cbDimInfo&       dimInfo,
 
 						 // defaults:
 						 int alignment    = FL_ALIGN_TOP,
-						 int rowNo        = 0,      // vert. position - row in the pane (if docked state)
+						 int rowNo        = 0,
-						 int columnPos    = 0,      // horiz. position in the row in pixels (if docked state)
+						 int columnPos    = 0,
-						 const wxString& name="bar",// name, by which the bar could be referred
+						 const wxString& name="bar",
-						                            // in layout customization dialogs
+						 bool spyEvents    = FALSE,
-
+						 int state        = wxCBAR_DOCKED_HORIZONTALLY
-						 bool spyEvents    = FALSE,	// if TRUE - input events for the bar should
-													// be "spyed" in order to forward not-handled
-													// mouse clicks to frame layout (e.g. to enable
-													// easy-draggablity of toolbars just by clicking
-													// on their interior regions). For widgets like
-													// text/tree control this value should be FALSE
-													// (since there's _no_ certain way to detect
-													//  whether the event was actually handled...)
-
-						 int state        = wxCBAR_DOCKED_HORIZONTALLY // e.g. wxCBAR_FLOATING
-																	   // or wxCBAR_HIDDEN
 					   );
 
-	// can be used for repositioning already existing bars. The given bar is first removed
+	// ReddockBar can be used for repositioning existing bars. The given bar is first removed
 	// from the pane it currently belongs to, and inserted into the pane, which "matches"
-	// the given recantular area. If pToPane is not NULL, bar is docked to this given pane
+	// the given rectangular area. If pToPane is not NULL, the bar is docked to this given pane.
-
+	// To dock a bar which is floating, use the wxFrameLayout::DockBar method.
-	// to dock the bar which is floated, use wxFrameLayout::DockBar(..) method
 
 	virtual bool RedockBar( cbBarInfo* pBar, const wxRect& shapeInParent,
 							cbDockPane* pToPane = NULL, bool updateNow = TRUE );
 
-	// methods for access and modification of bars in frame layout
+	// Finds the bar in the framelayout, by name.
 
 	cbBarInfo* FindBarByName( const wxString& name );
 
+	// Finds the bar in the framelayout, by window.
+
 	cbBarInfo* FindBarByWindow( const wxWindow* pWnd );
 
+    // Gets an array of bars.
+
 	BarArrayT& GetBars();
 
-	// changes bar's docking state (see possible control bar states)
+	// Changes the bar's docking state (see possible control bar states).
 
 	void SetBarState( cbBarInfo* pBar, int newStatem, bool updateNow );
 
+    // Toggles the bar between visible and hidden.
+
 	void InverseVisibility( cbBarInfo* pBar );
 
-	// reflects changes in bar information structure visually
+	// Reflects changes in bar information structure visually.
-	// (e.g. moves bar, changes it's dimension info, pane to which it is docked)
+	// For example, moves the bar, changes its dimension information,
+    // or changes the pane to which it is docked.
 
 	void ApplyBarProperties( cbBarInfo* pBar );
 
-	// removes bar from layout permanently, hides it's corresponding window if present
+	// Removes the bar from the layout permanently, and hides its corresponding window if present.
 
 	void RemoveBar( cbBarInfo* pBar );
 
-	// recalcualtes layout of panes, and all bars/rows in each pane
+	// Recalculates the layout of panes, and all bars/rows in each pane.
 
 	virtual void RecalcLayout( bool repositionBarsNow = FALSE );
 
+    // Returns the client height.
+
 	int     GetClientHeight();
+
+    // Returns the client width.
+
 	int     GetClientWidth();
+
+    // Returns the client's rectangle.
+
 	wxRect& GetClientRect()		{ return mClntWndBounds;     }
 
-	// NOTE:: in future ubdates-manager will become a normal plugin
+	// Returns a reference to the updates manager.
+    // Note: in future, the updates manager will become a normal plugin.
 
 	cbUpdatesManagerBase& GetUpdatesManager();
 
-	// destroys the previous manager if any, set the new one
+	// Destroys the previous manager if any, and sets the new one.
 
 	void SetUpdatesManager( cbUpdatesManagerBase* pUMgr );
 
-	// NOTE:: changing properties of panes, does not result immediate on-screen update
+	// Gets the pane properties for the given alignment.
 
 	virtual void GetPaneProperties( cbCommonPaneProperties& props, int alignment = FL_ALIGN_TOP );
 
+	// Sets the pane properties for the given alignment.
+    // Note: changing properties of panes does not result immediate on-screen update.
+
 	virtual void SetPaneProperties( const cbCommonPaneProperties& props,
 		                            int paneMask = wxALL_PANES );
 
-	// TODO:: margins should go into cbCommonPaneProperties in the future
+	// Sets the margins for the given panes.
+    // The margins should go into cbCommonPaneProperties in the future.
 	//
-	// NOTE:: this method should be called before any custom plugins are attached
+	// Note: this method should be called before any custom plugins are attached.
 
 	virtual void SetMargins( int top, int bottom, int left, int right,
 		                     int paneMask = wxALL_PANES );
 
+    // Sets the pane background colour.
+
 	virtual void SetPaneBackground( const wxColour& colour );
 
-	// recalculates layoute and performs on-screen update of all panes
+	// Recalculates layout and performs on-screen update of all panes.
 
 	void RefreshNow( bool recalcLayout = TRUE );
 
-	// event handlers
+	// Event handler for a size event.
 
 	void OnSize       ( wxSizeEvent&  event );
+
+	// Event handler for a left down button event.
+
 	void OnLButtonDown( wxMouseEvent& event );
+
+	// Event handler for a left doubleclick button event.
+
 	void OnLDblClick  ( wxMouseEvent& event );
+
+	// Event handler for a left button up event.
+
 	void OnLButtonUp  ( wxMouseEvent& event );
+
+	// Event handler for a right button down event.
+
 	void OnRButtonDown( wxMouseEvent& event );
+
+	// Event handler for a right button up event.
+
 	void OnRButtonUp  ( wxMouseEvent& event );
+
+	// Event handler for a mouse move event.
+
 	void OnMouseMove  ( wxMouseEvent& event );
 
-	/*** plugin-related methods ***/
+	// This function should be used instead of passing the event to the ProcessEvent method
-
+	// of the top-level plugin directly. This method checks if events are currently
-	// should be used, instead of passing the event to ProcessEvent(..) method
-	// of the top-plugin directly. This method checks if events are currently
 	// captured and ensures that plugin-event is routed correctly.
 
 	virtual void FirePluginEvent( cbPluginEvent& event );
 
-	// captures/releases user-input event's for the given plugin
+	// Captures user input events for the given plugin.
-	// Input events are: mouse movement, mouse clicks, keyboard input
+	// Input events are: mouse movement, mouse clicks, keyboard input.
 
 	virtual void CaptureEventsForPlugin ( cbPluginBase* pPlugin );
+
+	// Releases user input events for the given plugin.
+	// Input events are: mouse movement, mouse clicks, keyboard input
+
 	virtual void ReleaseEventsFromPlugin( cbPluginBase* pPlugin );
 
-	// called by plugins ( also captures/releases mouse in parent frame)
+	// Called by plugins; also captures the mouse in the parent frame.
+
 	void CaptureEventsForPane( cbDockPane* toPane );
+
+	// Called by plugins; also releases mouse in the parent frame.
+
 	void ReleaseEventsFromPane( cbDockPane* fromPane );
 
-	// returns current top-level plugin (the one which receives events first,
+	// Returns the current top-level plugin (the one that receives events first,
-	// with an exception if input-events are currently captured by some other plugin)
+	// except if input events are currently captured by some other plugin).
 
 	virtual cbPluginBase& GetTopPlugin();
 
-	// hooking custom plugins to frame layout
+	// Hooking custom plugins to frame layout.
 	//
-	// NOTE:: when hooking one plugin on top of the other -
+	// Note: when hooking one plugin on top of the other,
-	//        use SetNextHandler(..) or similar methods
+	// use SetNextHandler or similar methods
-	//		  of wxEvtHandler class to compose the chain of plugins,
+	// of wxEvtHandler class to compose the chain of plugins,
-	//        than pass the left-most handler in this chain to
+	// than pass the left-most handler in this chain to
-	//        the above methods (assuming that events are delegated
+	// the above methods (assuming that events are delegated
-	//        from left-most towards right-most handler)
+	// from left-most towards right-most handler).
 	//
-	//        NOTE2:: this secenario is very inconvenient and "low-level",
+	// This secenario is very inconvenient and "low-level",
-	//                use Add/Push/PopPlugin methods instead
+	// so use the Add/Push/PopPlugin methods instead.
 
 	virtual void SetTopPlugin( cbPluginBase* pPlugin );
 
-	// similar to wxWindow's "push/pop-event-handler" methods, execept
+	// Similar to wxWindow's "push/pop-event-handler" methods, execept
-	// that plugin is *deleted* upon "popping"
+	// that the plugin is deleted upon "popping".
 
 	virtual void PushPlugin( cbPluginBase* pPugin );
+
+	// Similar to wxWindow's "push/pop-event-handler" methods, execept
+	// that the plugin is deleted upon "popping".
+
 	virtual void PopPlugin();
 
+    // Pop all plugins.
 	virtual void PopAllPlugins();
 
-	// default plugins are : cbPaneDrawPlugin, cbRowLayoutPlugin, cbBarDragPlugin,
+	// Adds the default plugins. These are cbPaneDrawPlugin, cbRowLayoutPlugin, cbBarDragPlugin,
-	// 						 cbAntiflickerPlugin, cbSimpleCustomizePlugin
+	// cbAntiflickerPlugin, cbSimpleCustomizePlugin.
 	//
-	// this method is automatically invoked, if no plugins were found upon
+	// This method is automatically invoked if no plugins were found upon
-	// fireing of the first plugin-event, i.e. wxFrameLayout *CONFIGURES* itself
+	// firing of the first plugin-event, i.e. when wxFrameLayout configures itself.
 
 	virtual void PushDefaultPlugins();
 
-	/* "Advanced" methods for plugin-configuration	using their */
+	// An advanced methods for plugin configuration	using their
-	/* dynamic class information (e.g. CLASSINFO(pluginClass) ) */
+	// dynamic class information, for example CLASSINFO(pluginClass).
 
-	// first checks if plugin of the given class is already "hooked up",
+	// First checks if the plugin of the given class is already "hooked up".
-	// if not, adds it to the top of plugins chain
+	// If not, adds it to the top of the plugins chain.
 
 	virtual void AddPlugin( wxClassInfo* pPlInfo, int paneMask = wxALL_PANES );
 
-	// first checks if plugin of the givne class already hooked,
+	// First checks if the plugin of the given class is already hooked.
-	// if so, removes it, and then inserts it to the chain
+	// If so, removes it, and then inserts it into the chain
-	// before plugin of the class given by "pNextPlInfo"
+	// before the plugin of the class given by pNextPlInfo.
 	//
-	// NOTE:: this method is "handy" in some cases, where the order
+	// Note: this method is handy in some cases where the order
-	//        of plugin-chain could be important, e.g. one plugin overrides
+	// of the plugin-chain could be important, for example when one plugin overrides
-	//        some functionallity of the other already hooked plugin,
+	// some functionality of another already-hooked plugin,
-	//        thefore the former should be hooked before the one
+	// so that the former plugin should be hooked before the one
-	//        who's functionality is being overriden
+	// whose functionality is being overridden.
 
 	virtual void AddPluginBefore( wxClassInfo* pNextPlInfo, wxClassInfo* pPlInfo,
 								  int paneMask = wxALL_PANES );
 
-	// checks if plugin of the given class is hooked, removes
+	// Checks if the plugin of the given class is hooked, and removes
-	// it if found
+	// it if found.
-	//
-	// @param pPlInfo class information structure for the plugin
-	// @note
-	// @see wxFrameLayout::Method
-
 
 	virtual void RemovePlugin( wxClassInfo* pPlInfo );
 
-	// returns NULL, if plugin of the given class is not hooked
+	// Finds a plugin with the given class, or returns NULL if a plugin of the given
+    // class is not hooked.
 
 	virtual cbPluginBase* FindPlugin( wxClassInfo* pPlInfo );
 
+    // Returns true if there is a top plugin.
+
 	bool HasTopPlugin();
 
 	DECLARE_EVENT_TABLE()
@@ -460,62 +542,115 @@ public: /* protected really (accessed only by plugins) */
 	// refrence to custom updates manager
 	cbUpdatesManagerBase* mpUpdatesMgr;
 
-	// called to set calculated layout to window objects
+	// Called to apply the calculated layout to window objects.
+
 	void PositionClientWindow();
+
+	// Called to apply the calculated layout to window objects.
+
 	void PositionPanes();
+
+    // Creates the cursors.
+
 	void CreateCursors();
 
+    // Applies the calculated layout to a floating bar.
+
 	void RepositionFloatedBar( cbBarInfo* pBar );
+
+    // Applies the state to the window objects.
+
 	void DoSetBarState( cbBarInfo* pBar );
 
+    // The purpose of this function is unknown.
+
 	bool LocateBar( cbBarInfo* pBarInfo,
 					cbRowInfo**  ppRow,
 					cbDockPane** ppPane );
 
 
+    // Returns TRUE if the position is within the given pane.
+
 	bool HitTestPane( cbDockPane* pPane, int x, int y );
+
+    // Returns the pane for which the rectangle hit test succeeds, giving
+    // preference to the given pane if supplied.
+
 	cbDockPane* HitTestPanes( const wxRect& rect, cbDockPane* pCurPane );
 
-	// returns panes, to which the given bar belongs
+	// Returns the pane to which the given bar belongs.
 
 	cbDockPane* GetBarPane( cbBarInfo* pBar );
 
-	// delegated from "bar-spy"
+	// Delegated from "bar-spy".
 	void ForwardMouseEvent( wxMouseEvent& event,
 							cbDockPane*   pToPane,
 							int           eventType );
 
+    // Routes the mouse event to the appropriate pane.
+
 	void RouteMouseEvent( wxMouseEvent& event, int pluginEvtType );
 
+    // Shows all floated windows.
+
 	void ShowFloatedWindows( bool show );
 
+    // Unhooks the layout from the frame.
+
 	void UnhookFromFrame();
+
+    // Hooks the layout up to the frame (pushes the layout onto the
+    // frame's event handler stack).
+
 	void HookUpToFrame();
 
-	// NOTE:: reparenting of windows may NOT work on all platforms
+	// Returns TRUE if the platform allows reparenting. This may not return TRUE
-	//        (reparenting allows control-bars to be floated)
+    // for all platforms. Reparenting allows control bars to be floated.
 
 	bool CanReparent();
+
+    // Reparents pChild to have parent pNewParent.
+
 	void ReparentWindow( wxWindow* pChild, wxWindow* pNewParent );
 
+    // Returns the previous client window rectangle.
+
 	wxRect& GetPrevClientRect() { return mPrevClntWndBounds; }
 
+    // Handles paint events, calling PaintPane for each pane.
+
 	void OnPaint( wxPaintEvent& event );
+
+    // Handles background erase events. Currently does nothing.
+
 	void OnEraseBackground( wxEraseEvent& event );
+
+    // Handles focus kill events. Currently does nothing.
+
 	void OnKillFocus( wxFocusEvent& event );
+
+    // Handles focus set events. Currently does nothing.
+
 	void OnSetFocus( wxFocusEvent& event );
+
+    // Handles activation events. Currently does nothing.
+
 	void OnActivate( wxActivateEvent& event );
+
+    // Handles idle events.
+
 	void OnIdle( wxIdleEvent& event );
 
-	// factory method
+	// Returns a new cbGCUpdatesMgr object.
+
 	virtual cbUpdatesManagerBase* CreateUpdatesManager();
 };
 
-/* structure, which is present in each item of layout,
+/*
- * it used by any specific updates-manager to store
+A structure that is present in each item of layout,
- * auxilary information to be used by it's specific
+used by any particular updates-manager to store
- * updating algorithm
+auxiliary information to be used by its updating algorithm.
- */
+*/
 
 class cbUpdateMgrData : public wxObject
 {
@@ -528,23 +663,34 @@ public:
 
 	wxObject*  mpCustomData; // any custom data stored by specific updates mgr.
 
-	cbUpdateMgrData();   // is-dirty flag is set TRUE initially
+    // Default constructor. Is-dirty flag is set TRUE initially.
+
+	cbUpdateMgrData();
+
+    // Store the item state.
 
 	void StoreItemState( const wxRect& boundsInParent );
 
+    // Set the dirty flag.
+
 	void SetDirty( bool isDirty = TRUE );
 
+    // Set custom data.
+
 	void SetCustomData( wxObject* pCustomData );
 
+    // Returns the is-dirty flag.
+
 	inline bool IsDirty() { return mIsDirty; }
 };
 
-/* Abstract interface for bar-size handler classes.
+/*
- * These objects receive notifications, whenever the docking
+Abstract interface for bar-size handler classes.
- * state of the bar is changed, thus they have a possibility
+These objects receive notifications whenever the docking
- * to adjust the values in cbDimInfo::mSizes accordingly.
+state of the bar is changed, thus they provide the possibility
- * Specific handlers can be hooked to specific types of bars.
+to adjust the values in cbDimInfo::mSizes accordingly.
- */
+Specific handlers can be hooked up to specific types of bar.
+*/
 
 class cbBarDimHandlerBase : public wxObject
 {