src/DESIGN

   1 KBoard is written in C++ using QT and KDE libraries. Its source code is highly modular, and aims at providing a flexible API for later extensions and generalizations.
   2
   3 == Controllers ==
   4
   5 Different behaviours are handled with different subclasses of the abstract base class '''<code>Controller</code>'''.
   6 A concrete <code>Controller</code> subclass is instanciated every time the chessboard needs to be reset due to a new game event, or a new examination, and the like.
   7
   8 A <code>Controller</code> subclass has the following responsibilities:
   9 * setup the view with an appropriate <code>Rules</code> instance;
  10 * create a graphical info for the chosen variant;
  11 * override <code>handleStyle12</code> and <code>handleMoveList</code>, to define its behaviour in response to server events;
  12 * override <code>back</code>, <code>forward</code> and similar events, to define its behaviour in response to user events.
  13
  14 == <code>ChessBoardWidget</code> ==
  15
  16 <code>ChessBoardWidget</code> is the main KBoard graphical component. It is a widget containing a canvas containing <code>PieceSprite</code>s.
  17
  18 Its status is represented by two instance variables:
  19
  20 * <code>position</code>, of type <code>const ChessPosition*</code>,
  21 * <code>sprites</code>, of type <code>Grid&lt;PieceSprite*&gt;</code>.
  22
  23 The first is the ''logical'' position of the ChessBoard, while the seconds represents sprite locations inside the canvas. They get syncronized either directly (''warping''), or with ''animations'' (using an <code>Animator</code>).
  24
  25 A direct syncronization is obtained calling the <code>updatePosition</code> method:
  26
  27   void updatePosition(const ChessPosition* pos)
  28 * stop animations
  29 * change sprites to reflect <code>pos</code>. Don't update unchanged sprites.
  30
  31   AnimationGroup* forward(const ChessMove& move, ChessPosition* dest)
  32 * create an animation group
  33 * fill animation group using an animator
  34 * activate animation group ?
  35
  36 === How a controller handles style12 events ===
  37
  38 ==== If <code>style12.index == game->last() + 1</code> ====
  39
  40 * retrieve the move from <code>style12.san</code>
  41 * get a real <code>ChessMove</code> instance using <code>ChessPosition::getMove</code>
  42 ** if unsuccessful, try <code>style12.lastMove</code>
  43 * test move against current position
  44 * compute <code>newPosition</code>
  45 * get an animation group using <code>ChessBoardWidget::forward</code>
  46 * compare <code>newPosition</code> with <code>style12.position</code>
  47 ** add captures and anti-captures to the animation group according to <code>style12.position</code>
  48
  49 ==== If <code>style12.index == game->last()</code> ====
  50
  51 When the controller receives such an event, it should be able to add captures and anticaptures to the ''current animation group'', which unfortunately is not guaranteed to exist anymore.
  52 What happens when a user makes a move? <code>ChessBoardWidget</code> computes an approximation for the resulting position and calls forward, activating the corresponding animation group and updating <code>position</code>. Several things can happen
  53 # the animation ends before any style12 events: in this case, the view can be simply updated with <code>updatePosition</code> when needed
  54 # while animating, a style12 event referring to the newly created position arrives: see [[updating while animating]].
  55 # while animating, an invalid move event arrives: all animations shall be stopped, while current animation shall be aborted and moving pieces shall be animated back to their original squares with double speed.
  56
  57 To distinguish between these alternatives, <code>ChessBoardWidget</code> shall keep a reference to the [[ChessBoardWidget current animation|current animation]].