src/tagua.h

   1 /*
   2   Copyright (c) 2006 Paolo Capriotti <p.capriotti@sns.it>
   3             (c) 2006 Maurizio Monge <maurizio.monge@kdemail.net>
   4
   5   This program is free software; you can redistribute it and/or modify
   6   it under the terms of the GNU General Public License as published by
   7   the Free Software Foundation; either version 2 of the License, or
   8   (at your option) any later version.
   9 */
  10
  11 #ifndef LOWLEVEL_H
  12 #define LOWLEVEL_H
  13
  14 #include <map>
  15 #include <boost/shared_ptr.hpp>
  16 #include <QString>
  17 #include <QStringList>
  18 #include "point.h"
  19 #include "usermove.h"
  20 #include "index.h"
  21 #include "option.h"
  22 #include "decoratedmove.h"
  23 #include "interactiontype.h"
  24 #include "turnpolicy.h"
  25 #include "fwd.h"
  26
  27 class GraphicalAPI;
  28 class ICSAPI;
  29
  30 /**
  31   * @file tagua.h
  32   * @brief Low level abstract classes used by the interface framework.
  33   *
  34   * This file includes definitions for abstract classes used from within
  35   * the interface framework to access variant details using dynamic time
  36   * polymorphism.
  37   *
  38   * One of the big problems with this approach is what I call 'lack of
  39   * functional dependency support' for runtime polymorphism.
  40   * What is missing is the ability to override a virtual member function
  41   * in a derived class changing its signature. Or better, it is possible
  42   * to only change its return type with a covariant type, while it would
  43   * often be useful to change any of its argument types with covariant or
  44   * even controvariant types.
  45   * For controvariant types, I foresee no problems, and all type checking
  46   * can be done statically (of course the method has to be dynamically
  47   * bound) as they are now.
  48   * When using covariant types, the compiler could insert appropriate
  49   * dynamic cast's and type checks in the calling code, when there's no
  50   * way to know the exact type of an argument at compile time.
  51   *
  52   * The file @ref tagua_wrapped.h tries to address this problem doing part
  53   * of the compiler's work. One exception is that type checking code
  54   * is inserted in a method wrapper, instead of the calling place, so
  55   * even calling a method of a noncasted instance would cause some
  56   * upcast / downcast overhead; this is negligible, though, because
  57   * that scenario is rather unlikely, since wrapped classes are always
  58   * kept in variables of abstract types.
  59   */
  60
  61
  62 /**
  63   * @brief A superclass for all the piece classes.
  64   */
  65 class AbstractPiece {
  66 public:
  67   typedef boost::shared_ptr<AbstractPiece> Ptr;
  68   virtual ~AbstractPiece() { }
  69
  70   /**
  71     * Piece equality. Return false if the second pointer
  72     * is null.
  73     */
  74   virtual bool equals(const PiecePtr& other) const = 0;
  75
  76   /**
  77     * Return a unique key for the piece.
  78     * Used to store pixmaps.
  79     */
  80   virtual QString name() const = 0;
  81
  82   /**
  83     * Create a deep copy of the piece.
  84     */
  85   virtual PiecePtr clone() const = 0;
  86 };
  87
  88
  89 /**
  90   * @brief A superclass for all the move classes.
  91   *
  92   * An abstract move is simply something that can serialize
  93   * itself either as SAN notation, or as coordinate notation.
  94   */
  95 class AbstractMove {
  96 public:
  97   typedef boost::shared_ptr<AbstractMove> Ptr;
  98   virtual ~AbstractMove() { }
  99
 100   /**
 101     * Return a compact SAN representation for the move.
 102     */
 103   virtual QString SAN(const PositionPtr& ref) const = 0;
 104
 105   /**
 106     * Return a decorated representation for the move.
 107     */
 108   virtual DecoratedMove toDecoratedMove(const PositionPtr& ref) const = 0;
 109
 110   /**
 111     * Return the move in coordinate notation.
 112     */
 113   virtual QString toString(const PositionPtr& ref) const = 0;
 114
 115   /**
 116     * Convert the move to a normal user move. Used to
 117     * perform move highlighting.
 118     */
 119   virtual NormalUserMove toUserMove() const = 0;
 120
 121   /**
 122     * Checks if the two moves are equal.
 123     */
 124   virtual bool equals(const MovePtr& other) const = 0;
 125
 126 };
 127
 128 /**
 129   * @brief Superclass for pools
 130   *
 131   * A general interface for pools.
 132   */
 133 class AbstractPool {
 134 public:
 135   typedef boost::shared_ptr<AbstractPool> Ptr;
 136   virtual ~AbstractPool() {}
 137
 138   /**
 139     * \return the number of items in the pool
 140     */
 141   virtual int size() = 0;
 142
 143   /**
 144     * Inserts a piece in the pool, preferably at the position \a pref_index.
 145     * But the pool can be unpredictable and the piece can be placed at an arbitrary position.
 146     * \return the position at which the item was placed.
 147     */
 148   virtual int insert(int pref_index, const PiecePtr& piece) = 0;
 149
 150   /**
 151     * Gets the piece at the position \a index in the pool.
 152     */
 153   virtual PiecePtr get(int index) = 0;
 154
 155   /**
 156     * Removes the piece at the position \a index in the pool.
 157     * \return the removed piece.
 158     */
 159   virtual PiecePtr take(int index) = 0;
 160 };
 161
 162
 163
 164 /**
 165   * @brief A superclass for all the position classes.
 166   *
 167   * A general interface for positions. It is used from within
 168   * the graphical framework to validate external input wrt
 169   * the played variant.
 170   */
 171 class AbstractPosition {
 172 public:
 173   typedef boost::shared_ptr<AbstractPosition> Ptr;
 174   typedef boost::shared_ptr<AbstractPool> PoolPtr;
 175   virtual ~AbstractPosition() { }
 176
 177   /**
 178     * Return board size in logical units. This could be
 179     * static if C++ permitted virtual static functions.
 180     */
 181   virtual Point size() const = 0;
 182
 183   /**
 184     * Returns the text to be used for the border surrounding this position in a board
 185     */
 186   virtual QStringList borderCoords() const = 0;
 187
 188   /**
 189     * Create the starting piece setup.
 190     */
 191   virtual void setup() = 0;
 192
 193   /**
 194     * Retrieve the piece on square @a p.
 195     * Return a null pointer if that square is empty.
 196     */
 197   virtual PiecePtr get(const Point& p) const = 0;
 198
 199   /**
 200     * Set a piece on the board.
 201     */
 202   virtual void set(const Point& p, const PiecePtr& piece) = 0;
 203
 204   /**
 205     * \return an interface to modify the pool of the board relative to \a player
 206     */
 207   virtual PoolPtr pool(int player) = 0;
 208
 209   /**
 210     * Set a position pool, copying it from a given position.
 211     */
 212   virtual void copyPoolFrom(const PositionPtr& pos) = 0;
 213
 214   /**
 215     * \return 1 if the piece can be moved, -1 if could be moved in the future (premove), or else 0.
 216     */
 217   virtual InteractionType movable(const TurnPolicy::Collection& test, const Point& p) const = 0;
 218
 219   /**
 220     * \return 1 if this pool can be dropped, -1 if could be dropped in the future (premove), or else 0.
 221     */
 222   virtual InteractionType droppable(const TurnPolicy::Collection& test, int) const = 0;
 223
 224   /**
 225     * \return an id corresponding to the player
 226     * who is in turn.
 227     */
 228   virtual int turn() const = 0;
 229
 230   /**
 231     * Sets the player on move
 232     */
 233   virtual void setTurn(int) = 0;
 234
 235   /**
 236     * \return the player that just moved
 237     */
 238   virtual int previousTurn() const = 0;
 239
 240   /**
 241     * Switch to the next player.
 242     */
 243   virtual void switchTurn() = 0;
 244
 245   /**
 246     * Check move legality. Set move fields as needed.
 247     * Return whether the move is legal.
 248     * This function should return immediately if \a m
 249     * has already been tested.
 250     */
 251   virtual bool testMove(const MovePtr& m) const = 0;
 252
 253   /**
 254     * Execute move \a m. Assume that \a m is legal and tested.
 255     */
 256   virtual void move(const MovePtr& m) = 0;
 257
 258   /**
 259     * Create a deep copy of the position.
 260     */
 261   virtual PositionPtr clone() const = 0;
 262
 263   /**
 264     * Make the position equal to the given one.
 265     */
 266   virtual void copyFrom(const PositionPtr&) = 0;
 267
 268   /**
 269     * Tests if two positions are equal.
 270     */
 271   virtual bool equals(const PositionPtr& p) const = 0;
 272
 273   /**
 274     * Return a move from an algebraic notation, or a null pointer.
 275     */
 276   virtual MovePtr getMove(const QString&) const = 0;
 277
 278   /**
 279     * Return a string representing the current state of the position.
 280     */
 281   virtual QString state() const = 0;
 282
 283   /**
 284     * Return a FEN representation for the position, assuming
 285     * @a halfmove as halfmove clock and @a fullmove as full move
 286     * number.
 287     */
 288   virtual QString fen(int halfmove, int fullmove) const = 0;
 289
 290   /**
 291     * A piece somehow representing or related to the move
 292     * which has to be drawn by the interface.
 293     * Examples:
 294     * * for one click moves, the piece that would
 295     *    appear on the square.
 296     * * for promotions in chesslike variants, the promoted
 297     *   piece.
 298     * @note Return a null pointer if the move has no valid
 299     *       piece hint defined.
 300     */
 301   virtual PiecePtr moveHint(const MovePtr&) const = 0;
 302
 303   /**
 304     * Variant introspection
 305     */
 306   virtual QString variant() const = 0;
 307
 308   /**
 309     * For debugging
 310     */
 311   virtual void dump() const = 0;
 312 };
 313
 314 class AnimationGroup;
 315
 316 /**
 317   * @brief An abstract superclass for all animator classes.
 318   *
 319   * An animator is a class which is given a difference between
 320   * a graphical and a logical position, and schedules an animation
 321   * which graphically does an update.
 322   * If the difference is due to a move, the animator tries to
 323   * create a smooth animation which could possibly work for many
 324   * chess-like variants, and then fills in the gaps with a direct
 325   * update.
 326   */
 327 class AbstractAnimator {
 328 public:
 329   typedef boost::shared_ptr<AbstractAnimator> Ptr;
 330   virtual ~AbstractAnimator() { }
 331
 332   /**
 333     * Sync the graphical position with the given position.
 334     */
 335   virtual AnimationPtr warp(const PositionPtr&) = 0;
 336
 337   /**
 338     * Animate forward syncing to the given position.
 339     */
 340   virtual AnimationPtr forward(const PositionPtr&, const MovePtr&) = 0;
 341
 342   /**
 343     * Animate back syncing to the given position.
 344     */
 345   virtual AnimationPtr back(const PositionPtr&, const MovePtr&) = 0;
 346 };
 347
 348
 349 class VariantInfo {
 350 public:
 351   virtual ~VariantInfo() { }
 352   virtual PositionPtr createPosition() = 0;
 353   virtual PositionPtr createCustomPosition(const OptList& l) = 0;
 354   virtual PositionPtr createPositionFromFEN(const QString& fen) = 0;
 355   virtual void forallPieces(class PieceFunction&) = 0;
 356   virtual int moveListLayout() const = 0;
 357   virtual AnimatorPtr createAnimator(GraphicalAPI* graphical_api) = 0;
 358   virtual MovePtr createNormalMove(const NormalUserMove&) = 0;
 359   virtual MovePtr createDropMove(const DropUserMove&) = 0;
 360   virtual MovePtr getVerboseMove(int turn, const class VerboseNotation&) const = 0;
 361
 362   /**
 363     * \return if moves are done by just clicking
 364     */
 365   virtual bool simpleMoves() = 0;
 366
 367   /**
 368     * \return the name of the variant
 369     */
 370   virtual QString name() const = 0;
 371
 372   /**
 373     * \return the name of the theme proxy variant, ie the variant whose theme can be used
 374     * for the current one (for instance crazyhouse can use chess themes).
 375     */
 376   virtual QString themeProxy() const = 0;
 377
 378   /**
 379     * \return the (subvariant) options that can be specified for position creation, such as board size, etc
 380     */
 381   virtual OptList positionOptions() const = 0;
 382
 383   /**
 384     * \return The ICS API for this variant, or a null pointer, if the variant does not support
 385     *         ICS (in that case a Dummy variant will be used).
 386     */
 387   virtual ICSAPIPtr icsAPI() const = 0;
 388 };
 389
 390 #endif // LOWLEVEL_H