src/tagua.h

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