doc/elements.md

   1 # Architecture
   2
   3 ## Layout
   4
   5 A layout is a plugin with a method `layout` taking a rectangle and a hash of
   6 elements (board, clocks, pools...), and calling `set_geometry` on each of those
   7 objects, disposing them inside the given rectangle.
   8
   9 ## Board
  10
  11 The `Board` is the main game area, where pieces are shown and moved. A board is
  12 a rectangular element, divided in equally sized squares, in numbers dictated by
  13 `@game.size`.
  14
  15 The `Board` class includes `PointConverter`, which converts *logical*
  16 coordinates to actual coordinates on the canvas (called *real*).
  17 To do so, the *flipped* state of the board is taken into consideration.
  18
  19 `Board` is a `Qt::GraphicsItemGroup`, containing pieces (and other subelements,
  20 like the background and square highlighting) as items, stored in the `@items`
  21 hash.
  22
  23 When the board is resized, the `set_geometry` method is called by the parent
  24 `Layout` object, and all its items are recreated. This happens inside the
  25 `reload_item` method, which selects how to recreate items based on their key.
  26 Read/write access to items is provided by the `ItemBag` module.
  27
  28 ## Pool
  29
  30 `Pool` is a part of the gaming area where captured pieces are shown in games
  31 like Shogi and Crazyhouse. It is very similar in structure to `Board`, with
  32 which it shares some of the included modules.
  33
  34 Items are stored in an array instead of a hash. Since `ItemBag` only works with
  35 hashes of items, `Pool` uses a helper class `ExtraItemContainer` which mixes
  36 `ItemBag` in and provides support for redrawing square highlighting items.
  37
  38 Most of the logic for moving pieces around in the pool is provided by the
  39 `PoolAnimator` class. The main method of this class is `warp`, which takes a
  40 pool object (a set-like object containing pieces), compares it with the current
  41 state of the parent `Pool` object, and returns an animation that adds, removes,
  42 and/or moves pieces around, so that they match.
  43
  44
  45