Add documentation to the major signals and slots. Remove the obsolete fourth...

Add documentation to the major signals and slots. Remove the obsolete fourth parameter from the paintCell() signal and slot.

svn path=/branches/work/kgoldrunner-qgv/; revision=1297000

src/kgrcanvas.cpp

@@ -418,29 +418,16 @@ int KGrCanvas::tileNumber (KGrTheme::TileType type, int x, int y)
     }
 }
 
-void KGrCanvas::paintCell (const int i, const int j, const char type, const int offset)
+void KGrCanvas::paintCell (const int i, const int j, const char type)
 {
     KGrTheme::TileType tileType = tileForType (type);
+
     // In KGrGame, the top-left visible cell is [1,1]: in KGrPlayfield [0,0].
     int x = i - 1, y = j - 1;
-    switch (offset) {
-    case 1: tileType = KGrTheme::BrickAnimation1Tile; break;
-    case 2: tileType = KGrTheme::BrickAnimation2Tile; break;
-    case 3: tileType = KGrTheme::BrickAnimation3Tile; break;
-    case 4: tileType = KGrTheme::BrickAnimation4Tile; break;
-    case 5: tileType = KGrTheme::BrickAnimation5Tile; break;
-    case 6: tileType = KGrTheme::BrickAnimation6Tile; break;
-    case 7: tileType = KGrTheme::BrickAnimation7Tile; break;
-    case 8: tileType = KGrTheme::BrickAnimation8Tile; break;
-    case 9: tileType = KGrTheme::BrickAnimation9Tile; break;
-    case 0:
-    default:
-	break;
-    }
-
-    tileNo [x][y] = tileType;			// Save the tile-number for repaint.
+    tileNo [x][y] = tileType;		// Save the tile-number for repaint.
 
-    playfield->setTile (x, y, tileNumber (tileType, x, y));	// Paint with required pixmap.
+    // Paint with required pixmap.
+    playfield->setTile (x, y, tileNumber (tileType, x, y));
 }
 
 void KGrCanvas::setBaseScale()
@@ -617,7 +604,7 @@ int KGrCanvas::makeSprite (const char type, int i, int j)
         sprite->stackUnder (sprites->at (heroId));
 
         // Erase the brick-image so that animations are visible in all themes.
-        paintCell (i, j, FREE, 0);
+        paintCell (i, j, FREE);
         break;
     default:
         break;
@@ -728,7 +715,7 @@ void KGrCanvas::deleteSprite (const int spriteId)
 
     if (brick) {
         // Dug-brick sprite erased: restore the tile that was at that location.
-        paintCell ((loc.x()/bgw) + 1, (loc.y()/bgh) + 1, BRICK, 0);
+        paintCell ((loc.x()/bgw) + 1, (loc.y()/bgh) + 1, BRICK);
     }
 }
 

src/kgrcanvas.h

@@ -88,8 +88,7 @@ public slots:
     void getMousePos       (int & i, int & j);
     void setMousePos       (const int, const int);
     void animate           (bool missed);
-    void paintCell         (const int i, const int j, const char type,
-                            const int offset = 0);
+    void paintCell         (const int i, const int j, const char type);
 
     int  makeSprite        (const char type, int i, int j);
     void startAnimation    (const int id, const bool repeating,

src/kgrlevelplayer.cpp

@@ -151,8 +151,8 @@ void KGrLevelPlayer::init (KGrCanvas * view,
     grid->calculateAccess    (rules->runThruHole());
 
     // Connect to code that paints grid cells and start-positions of sprites.
-    connect (this, SIGNAL (paintCell(int,int,char,int)),
-             view, SLOT   (paintCell(int,int,char,int)));
+    connect (this, SIGNAL (paintCell(int,int,char)),
+             view, SLOT   (paintCell(int,int,char)));
     connect (this, SIGNAL (makeSprite(char,int,int)),
              view, SLOT   (makeSprite(char,int,int)));
 
@@ -181,18 +181,18 @@ void KGrLevelPlayer::init (KGrCanvas * view,
 
             // If the hero is here, leave the tile empty.
             if (type == HERO) {
-                emit paintCell (i, j, FREE, 0);
+                emit paintCell (i, j, FREE);
             }
 
             // If an enemy is here, count him and leave the tile empty.
             else if (type == ENEMY) {
                 enemyCount++;
-                emit paintCell (i, j, FREE, 0);
+                emit paintCell (i, j, FREE);
             }
 
             // Or, just paint this tile.
             else {
-                emit paintCell (i, j, type, 0);
+                emit paintCell (i, j, type);
             }
         }
     }

src/kgrlevelplayer.h

@@ -320,19 +320,76 @@ signals:
     void endLevel       (const int result);
     void getMousePos    (int & i, int & j);
     void setMousePos    (const int i, const int j);
+
+    /**
+     * Requests the view to update animated sprites. Each sprite moves as
+     * decided by the parameters of its last startAnimation() signal.
+     *
+     * @param missed       If true, moves and frame changes occur normally, but
+     *                     they are not displayed on the screen. This is to
+     *                     allow the graphics to catch up if Qt has missed one
+     *                     or more time signals.
+     */
     void animation      (bool missed);
-    void paintCell      (int i, int j, char tileType, int diggingStage = 0);
+
+    /**
+     * Requests the view to display a particular type of tile at a particular
+     * cell, or make it empty and show the background (tileType = FREE). Used
+     * when loading level-layouts.
+     *
+     * @param i            The column-number of the cell to paint.
+     * @param i            The row-number of the cell to paint.
+     * @param tileType     The type of tile to paint (gold, brick, ladder, etc).
+     */
+    void paintCell      (int i, int j, char tileType);
+
     int  makeSprite     (char spriteType, int i, int j);
+
+    /**
+     * Requests the view to display an animation of a dug brick at a
+     * particular cell, cancelling and superseding any current animation.
+     *
+     * @param spriteId     The ID of the sprite (dug brick).
+     * @param repeating    If true, repeat the animation (false for dug brick).
+     * @param i            The column-number of the cell to dig.
+     * @param j            The row-number of the cell to dig.
+     * @param time         The time in which to traverse one cell.
+     * @param dirn         The direction of motion, always STAND.
+     * @param type         The type of animation (open or close the brick).
+     */
     void startAnimation (const int spriteId, const bool repeating,
                          const int i, const int j, const int time,
                          const Direction dirn, const AnimationType type);
+
     void deleteSprite   (const int spriteId);
     void gotGold        (const int  spriteId, const int i, const int j,
                          const bool hasGold, const bool lost);
     void interruptDemo  ();
 
 private slots:
+    /**
+     * This slot powers the whole game. KGrLevelPlayer connects it to KGrTimer's
+     * tick() signal. In this slot, KGrLevelPlayer EITHER plays back a recorded
+     * tick OR checks the mouse/trackpad/keyboard for user-input, then processes
+     * dug bricks, moves the hero, moves the enemies and finally emits the
+     * animation() signal, which causes the view to update the screen.
+     *
+     * @param missed       If true, the QTimer has missed one or more ticks, due
+     *                     to overheads elsewhere in Qt or the O/S. The game
+     *                     catches up on the missed signal(s) and the graphics
+     *                     view avoids painting any sprites until the catchup
+     *                     is complete, thus saving further overheads. The
+     *                     sprites may "jump" a little when this happens, but
+     *                     at least the game stays on-time in wall-clock time.
+     * @param pScaledTime  The number of milliseconds per tick. Usually this is
+     *                     tickTime (= 20 msec), but it is less when the game is
+     *                     slowed down or more when it is speeded up. If the
+     *                     scaled time is 10 (beginner speed), the game will
+     *                     take 2 ticks of 20 msec (i.e. 40 msec) to do what it
+     *                     normally does in 20 msec.
+     */
     void tick           (bool missed, int scaledTime);
+
     void doDig          (int button);	// Dig using mouse-buttons.
 
 private:

src/kgrtimer.h

@@ -36,6 +36,24 @@ public:
                          { scaledTime = (pScale * tickTime) + 0.5; }
 
 signals:
+    /**
+     * This signal powers the whole game. KGrLevelPlayer connects it to its
+     * tick() slot.
+     *
+     * @param missed       If true, the QTimer has missed one or more ticks, due
+     *                     to overheads elsewhere in Qt or the O/S. The game
+     *                     catches up on the missed signal(s) and the graphics
+     *                     view avoids painting any sprites until the catchup
+     *                     is complete, thus saving further overheads. The
+     *                     sprites may "jump" a little when this happens, but
+     *                     at least the game stays on-time in wall-clock time.
+     * @param pScaledTime  The number of milliseconds per tick. Usually this is
+     *                     tickTime (= 20 msec), but it is less when the game is
+     *                     slowed down or more when it is speeded up. If the
+     *                     scaled time is 10 (beginner speed), the game will
+     *                     take 2 ticks of 20 msec (i.e. 40 msec) to do what it
+     *                     normally does in 20 msec.
+     */
     void tick (bool missed, int pScaledTime);
 
 private slots: