Added comments to some tiling related code

svn path=/trunk/KDE/kdebase/workspace/; revision=1124486

kcmkwin/kwinoptions/windows.cpp

@@ -669,6 +669,10 @@ KAdvancedConfig::KAdvancedConfig (bool _standAlone, KConfig *_config, const KCom
     tilBoxLay->addWidget( tilingRaiseLabel, 2, 0 );
 
     tilingRaiseCombo = new KComboBox( tilBox );
+    // when a floating window is activated, all other floating
+    // windows are also brought to the front, above the tiled windows
+    // when a tiled window is focused, all floating windows go to the back.
+    // NOTE: If the user has explicitly set a client to "keep above others", that will be respected.
     tilingRaiseCombo->addItem( i18nc( "Window Raising Policy", "Raise/Lower all floating windows" ) );
     tilingRaiseCombo->addItem( i18nc( "Window Raising Policy", "Raise/Lower current window only") );
     tilingRaiseCombo->addItem( i18nc( "Window Raising Policy", "Floating windows are always on top" ) );

tiling.cpp

@@ -226,10 +226,8 @@ void Workspace::notifyWindowDesktopChanged( Client *c, int old_desktop )
         }
     }
 
-// TODO: make this configurable
 /*
- * If a floating window was activated, raise all floating windows.
- * If a tiled window was activated, lower all floating windows.
+ * Implements the 3 raising modes in Window Behaviour -> Advanced
  */
 void Workspace::notifyWindowActivated( Client *c )
     {

tilinglayout.cpp

@@ -60,6 +60,7 @@ Tile* TilingLayout::findTile( Client *c ) const
 
 void TilingLayout::clientMinimizeToggled( Client *c )
     {
+    // just rearrange since that will check for state
     Tile *t = findTile( c );
     if( t )
         arrange( layoutArea( t ) );
@@ -81,6 +82,7 @@ void TilingLayout::clientResized( Client *c, const QRect &moveResizeGeom, const
     commit();
     }
 
+// tries to swap the tile with the one in the new position right now
 void TilingLayout::clientMoved( Client *c, const QRect &moveResizeGeom, const QRect &orig )
     {
     if( moveResizeGeom == orig )

tilinglayout.h

@@ -39,6 +39,10 @@ class TilingLayout
         TilingLayout( Workspace *w );
         virtual ~TilingLayout();
         
+        /**
+         * Reimplement this to decide how the client(s) should
+         * be resized.
+         */
         virtual void clientResized( Client *c, const QRect &moveResizeGeom, const QRect &orig );
         void clientMoved( Client *c, const QRect &moveResizeGeom, const QRect &orig );
         void clientMinimizeToggled( Client *c );
@@ -56,14 +60,33 @@ class TilingLayout
         void swapTiles( Tile *a, Tile *b );
         void reconfigureTiling();
 
+        /**
+         * All tiling layouts do not allow the user to manually
+         * resize clients. This method will be called when the user
+         * attempts a resize. Return any valid position to allow
+         * resizing in that direction. currentMode will be the direction
+         * of resize attempted by the user. You do not have to return the same value.
+         * If you do not want to allow resizing at all, or you do not
+         * want to allow resizing for this client, then return KDecorationDefines::PositionCenter.
+         */
         virtual KDecorationDefines::Position resizeMode( Client *c, KDecorationDefines::Position currentMode ) const;
 
         const QList<Tile *>& tiles() const;
         Tile* findTile( Client *c ) const;
 
     protected:
+        /**
+         * Get a pointer to the Workspace.
+         */
         Workspace * workspace() const;
+        /**
+         * Get a area in which the Tile can be placed.
+         */
         const QRect layoutArea( Tile *t ) const;
+        /**
+         * Hooks called after a tile is added to
+         * layout and before it is removed.
+         */
         // currently only required by floating layout
         virtual void postAddTile( Tile *t );
         virtual void preRemoveTile( Tile *t );

tilinglayoutfactory.h

@@ -27,6 +27,14 @@ namespace KWin
 class Workspace;
 class TilingLayout;
 class Tile;
+
+/**
+ * The tiling layout factory is used to create tiling layouts.
+ * To add a new layout, include the appropriate header in tilinglayoutfactory.cpp
+ * and use the ADD_LAYOUT macro to create a case entry.
+ * Also insert your layout in the Layouts enumeration. Do NOT
+ * change the position of FirstLayout and LastLayout
+ */
 class TilingLayoutFactory
     {
     public:

useractions.cpp

@@ -698,6 +698,7 @@ void Workspace::performWindowOperation( Client* c, Options::WindowOperation op )
     if ( !c )
         return;
 
+    // Allows us to float a window when it is maximized, if it is tiled.
     if( tilingEnabled()
         && (    op == Options::MaximizeOp
              || op == Options::HMaximizeOp

workspace.cpp

@@ -1422,6 +1422,9 @@ bool Workspace::setCurrentDesktop( int new_desktop )
         // Now propagate the change, after hiding, before showing
         rootInfo->setCurrentDesktop( currentDesktop() );
 
+        // if the client is moved to another desktop, that desktop may
+        // not have an existing layout. In addition this tiling layout
+        // will require rearrangement, so notify about desktop changes.
         if( movingClient && !movingClient->isOnDesktop( new_desktop ))
             {
             int old_desktop = movingClient->desktop();

workspace.h

@@ -178,7 +178,14 @@ class Workspace : public QObject, public KDecorationDefines
         void setTilingEnabled( bool tiling );
         bool tileable( Client *c );
         void createTile( Client *c );
+        // updates geometry of tiles on all desktops,
+        // this rearranges the tiles.
         void updateAllTiles();
+
+        // The notification funtions are called from 
+        // various points in existing code so that
+        // tiling can take any action if required.
+        // They are defined in tiling.cpp
         void notifyWindowResize( Client *c, const QRect &moveResizeGeom, const QRect &orig );
         void notifyWindowMove( Client *c, const QRect &moveResizeGeom, const QRect &orig );
         void notifyWindowResizeDone( Client *c, const QRect &moveResizeGeom, const QRect &orig, bool canceled );
@@ -308,6 +315,10 @@ class Workspace : public QObject, public KDecorationDefines
         bool desktopLayoutDynamicity_;
 
         bool tilingEnabled_;
+        // Each tilingLayout is for one virtual desktop.
+        // The length is always one more than the number of
+        // virtual desktops so that we can quickly index them
+        // without having to remember to subtract one.
         QVector<TilingLayout *> tilingLayouts;
 
         //-------------------------------------------------
@@ -679,15 +690,19 @@ class Workspace : public QObject, public KDecorationDefines
         void suspendCompositing();
         void suspendCompositing( bool suspend );
 
+        // user actions, usually bound to shortcuts
+        // and also provided through the D-BUS interface.
         void slotToggleTiling();
         void slotToggleFloating();
         void slotNextTileLayout();
         void slotPreviousTileLayout();
 
+        // Changes the focused client
         void slotLeft();
         void slotRight();
         void slotTop();
         void slotBottom();
+        // swaps active and adjacent client.
         void slotMoveLeft();
         void slotMoveRight();
         void slotMoveTop();
@@ -844,6 +859,8 @@ class Workspace : public QObject, public KDecorationDefines
         static NET::WindowType txtToWindowType( const char* txt );
         static bool sessionInfoWindowTypeMatch( Client* c, SessionInfo* info );
 
+        // try to get a decent tile, either the one with
+        // focus or the one below the mouse.
         Tile* getNiceTile() const;
         void removeTile( Client *c );
         // int, and not Tile::Direction because