trunk/Src/DasherCore/DasherNode.h

   1 // DasherNode.h
   2 //
   3 // Copyright (c) 2007 David Ward
   4 //
   5 // This file is part of Dasher.
   6 //
   7 // Dasher is free software; you can redistribute it and/or modify
   8 // it under the terms of the GNU General Public License as published by
   9 // the Free Software Foundation; either version 2 of the License, or
  10 // (at your option) any later version.
  11 //
  12 // Dasher is distributed in the hope that it will be useful,
  13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 // GNU General Public License for more details.
  16 //
  17 // You should have received a copy of the GNU General Public License
  18 // along with Dasher; if not, write to the Free Software
  19 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  20
  21 #ifndef __DasherNode_h__
  22 #define __DasherNode_h__
  23
  24 #include "../Common/Common.h"
  25 #include "../Common/NoClones.h"
  26 #include "DasherTypes.h"
  27 #include "LanguageModelling/LanguageModel.h"
  28 #include "NodeManager.h"
  29 #include "Alphabet/GroupInfo.h"
  30
  31 #include <deque>
  32 #include <iostream>
  33
  34 // Node flag constants
  35 #define NF_COMMITTED 1
  36 #define NF_ACTIVE 2
  37 #define NF_ALIVE 4
  38 #define NF_SEEN 8
  39 #define NF_CONVERTED 16
  40 #define NF_GAME 32
  41 #define NF_ALLCHILDREN 64
  42 #define NF_SUBNODE 128
  43 #define NF_SUPER 256
  44
  45 namespace Dasher {
  46   class CDasherNode;
  47   class CDasherModel;
  48 }
  49
  50 /// \ingroup Model
  51 /// @{
  52
  53 /// @brief A node in the Dasher model
  54 ///
  55 /// The Dasher node represents a box drawn on the display. This class
  56 /// contains the information required to render the node, as well as
  57 /// navigation within the model (parents and children
  58 /// etc.). Additional information is stored in m_pUserData, which is
  59 /// interpreted by the node manager associated with this class. Any
  60 /// logic specific to a particular node manager should be stored here.
  61 ///
  62 /// @todo Encapsulate presentation data in a structure?
  63 /// @todo Check that all methods respect the pseudochild attribute
  64 class Dasher::CDasherNode:private NoClones {
  65  public:
  66
  67   /// Display attributes of this node, used for rendering.
  68   struct SDisplayInfo {
  69     int iColour;
  70     bool bShove;
  71     bool bVisible;
  72     std::string strDisplayText;
  73   };
  74
  75   /// Container type for storing children. Note that it's worth
  76   /// optimising this as lookup happens a lot
  77   typedef std::deque<CDasherNode*> ChildMap;
  78
  79   /// @brief Constructor
  80   ///
  81   /// @param pParent Parent of the new node
  82   /// @param iLbnd Lower bound of node within parent
  83   /// @param iHbnd Upper bound of node within parent
  84   /// @param pDisplayInfo Struct containing information on how to display the node
  85   ///
  86   inline CDasherNode(CDasherNode *pParent, int iLbnd, int iHbnd, SDisplayInfo *pDisplayInfo);
  87
  88   /// @brief Destructor
  89   ///
  90   ~CDasherNode();
  91
  92   void Trace() const;           // diagnostic
  93
  94   /// Return display information for this node
  95   inline const SDisplayInfo *GetDisplayInfo() const;
  96
  97   /// @name Routines for manipulating node status
  98   /// @{
  99
 100   /// @brief Set a node flag
 101   ///
 102   /// Set various flags corresponding to the state of the node. The following flags are defined:
 103   ///
 104   /// NF_COMMITTED - Node is 'above' the root, so corresponding symbol
 105   /// has been added to text box, language model trained etc
 106   ///
 107   /// NF_ACTIVE - Node is a decendent of the root node (TODO: Isnt this everything?)
 108   ///
 109   /// NF_ALIVE - Node is large enough to be displayed
 110   ///
 111   /// NF_SEEN - Node has already been output
 112   ///
 113   /// NF_CONVERTED - Node has been converted (eg Japanese mode)
 114   ///
 115   /// NF_GAME - Node is on the path in game mode
 116   ///
 117   /// NF_ALLCHILDREN - Node has all children (TODO: obsolete?)
 118   ///
 119   /// NF_SUBNODE - Node should be considered an integral subnode of parents (eg groups)
 120   ///
 121   /// NF_SUPER - Node covers entire visible area
 122   ///
 123   /// @param iFlag The flag to set
 124   /// @param bValue The new value of the flag
 125   ///
 126   void SetFlag(int iFlag, bool bValue);
 127
 128   /// @brief Get the value of a flag for this node
 129   ///
 130   /// @param iFlag The flag to get
 131   ///
 132   /// @return The current value of the flag
 133   ///
 134   inline bool GetFlag(int iFlag) const;
 135
 136   /// @brief Recursively mark nodes as converted
 137   ///
 138   /// Ensure that this node is marked as being converted, together with
 139   /// all of its ancestors (assuming that unconverted nodes are
 140   /// 'contiguous' at the brances of the tree).
 141   ///
 142   /// @todo replace with a generic 'recursive set flag'?
 143   ///
 144   void ConvertWithAncestors();
 145
 146   /// @}
 147
 148   /// @name Routines relating to the size of the node
 149   /// @{
 150
 151   // Lower and higher bounds, and the range
 152
 153   /// @brief Get the lower bound of a node
 154   ///
 155   /// @return The lower bound
 156   ///
 157   inline int Lbnd() const;
 158
 159   /// @brief Get the upper bound of a node
 160   ///
 161   /// @return The upper bound
 162   ///
 163   inline int Hbnd() const;
 164
 165   /// @brief Get the range of a node (upper - lower bound)
 166   ///
 167   /// @return The range
 168   ///
 169   /// @todo Should this be here (trivial arithmethic of existing methods)
 170   ///
 171   inline int Range() const;
 172
 173   /// @brief Reset the range of a node
 174   ///
 175   /// @param iLower New lower bound
 176   /// @param iUpper New upper bound
 177   ///
 178   inline void SetRange(int iLower, int iUpper);
 179
 180   /// @brief Get the probability of a node
 181   ///
 182   /// @param iNormalization Normalisation constant
 183   ///
 184   /// @return The probability
 185   ///
 186   /// @todo Possibly a bit simplistic to make a full member
 187   /// @todo Inline
 188   ///
 189   double GetProb(int iNormalization);
 190
 191   /// @brief Get the size of the most probable child
 192   ///
 193   /// @return The size
 194   ///
 195   int MostProbableChild();
 196   /// @}
 197
 198   /// @name Routines for manipulating relatives
 199   /// @{
 200
 201   inline ChildMap & Children();
 202   inline const ChildMap & GetChildren() const;
 203   inline unsigned int ChildCount() const;
 204   inline CDasherNode *Parent() const;
 205   void SetParent(CDasherNode *pNewParent);
 206   bool NodeIsParent(CDasherNode * oldnode) const;
 207   // TODO: Should this be here?
 208   CDasherNode *const Get_node_under(int, myint y1, myint y2, myint smousex, myint smousey);   // find node under given co-ords
 209
 210   /// @brief Orphan a child of this node
 211   ///
 212   /// Deletes all other children, and the node itself
 213   ///
 214   /// @param pChild The child to keep
 215   ///
 216   void OrphanChild(CDasherNode * pChild);
 217
 218   /// @brief Delete the nephews of a given child
 219   ///
 220   /// @param pChild The child to keep
 221   ///
 222   void DeleteNephews(CDasherNode *pChild);
 223
 224   /// @brief Delete the children of this node
 225   ///
 226   ///
 227   void Delete_children();
 228   /// @}
 229
 230   /// \todo Make private, read only access?
 231   CNodeManager *m_pNodeManager;
 232
 233   /// Pointer for the node manager to do with as it sees fit.
 234   /// Remember to make sure that the node manager deletes anything it
 235   /// puts here before the node is destroyed.
 236   ///
 237   /// Please put everything in here which isn't required to simply
 238   /// render the node - basically the only exceptions should be the
 239   /// node size, colour and display text.
 240   /// \todo Make private, read only access?
 241   void *m_pUserData;
 242
 243  private:
 244   SDisplayInfo *m_pDisplayInfo;
 245
 246   int m_iLbnd;
 247   int m_iHbnd;   // the cumulative lower and upper bound prob relative to parent
 248
 249   int m_iRefCount;              // reference count if ancestor of (or equal to) root node
 250
 251   ChildMap m_mChildren;         // pointer to array of children
 252   CDasherNode *m_pParent;       // pointer to parent
 253
 254   // Binary flags representing the state of the node
 255   int m_iFlags;
 256 };
 257 /// @}
 258
 259 /////////////////////////////////////////////////////////////////////////////
 260 // Inline functions
 261 /////////////////////////////////////////////////////////////////////////////
 262
 263 using namespace Dasher;
 264 using namespace Opts;
 265 #include "DasherModel.h"
 266
 267 inline CDasherNode::CDasherNode(CDasherNode *pParent, int iLbnd, int iHbnd, SDisplayInfo *pDisplayInfo) {
 268   // TODO: Check that these are disabled for debug builds, and that we're not shipping such a build
 269   DASHER_ASSERT(iHbnd >= iLbnd);
 270   DASHER_ASSERT(pDisplayInfo != NULL);
 271
 272   m_pParent = pParent;
 273   m_iLbnd = iLbnd;
 274   m_iHbnd = iHbnd;
 275   m_pDisplayInfo = pDisplayInfo;
 276
 277   // Default flags (make a definition somewhere, pass flags to constructor)
 278   m_iFlags = NF_ACTIVE | NF_ALIVE;
 279
 280   m_iRefCount = 0;
 281 }
 282
 283 inline const CDasherNode::SDisplayInfo *CDasherNode::GetDisplayInfo() const {
 284   return m_pDisplayInfo;
 285 }
 286
 287 inline int CDasherNode::Lbnd() const {
 288   return m_iLbnd;
 289 }
 290
 291 inline int CDasherNode::Hbnd() const {
 292   return m_iHbnd;
 293 }
 294
 295 inline int CDasherNode::Range() const {
 296   return m_iHbnd - m_iLbnd;
 297 }
 298
 299 inline CDasherNode::ChildMap &CDasherNode::Children() {
 300   return m_mChildren;
 301 }
 302
 303 inline const CDasherNode::ChildMap &CDasherNode::GetChildren() const {
 304   return m_mChildren;
 305 }
 306
 307 inline unsigned int CDasherNode::ChildCount() const {
 308   return m_mChildren.size();
 309 }
 310
 311 inline bool CDasherNode::GetFlag(int iFlag) const {
 312   return (m_iFlags & iFlag);
 313 }
 314
 315 inline CDasherNode *CDasherNode::Parent() const {
 316   return m_pParent;
 317 }
 318
 319 inline void CDasherNode::SetRange(int iLower, int iUpper) {
 320   m_iLbnd = iLower;
 321   m_iHbnd = iUpper;
 322 }
 323
 324
 325 #endif /* #ifndef __DasherNode_h__ */