Src/DasherCore/ConversionManager.h

   1 // ConversionManager.h
   2 //
   3 // Copyright (c) 2007 The Dasher Team
   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 __conversion_manager_h__
  22 #define __conversion_manager_h__
  23
  24 #include "DasherTypes.h"
  25 #include "LanguageModelling/LanguageModel.h" // Urgh - we really shouldn't need to know about language models here
  26 #include "DasherNode.h"
  27 #include "SCENode.h"
  28 #include "NodeManager.h"
  29 #include "Alphabet/AlphInfo.h"
  30 #include "SettingsStore.h"
  31
  32 // TODO: Conversion manager needs to deal with offsets and contexts - Will: See Phil for an explanation.
  33
  34 class CNodeCreationManager;
  35
  36 namespace Dasher {
  37   class CDasherInterfaceBase;
  38   /// \ingroup Model
  39   /// @{
  40
  41   /// This class manages nodes in conversion subtrees, typically used
  42   /// for languages where complex characters are entered through a
  43   /// composition process, for example Japanese and Chinese.
  44   ///
  45   /// A new CConversionManager is created for each subtree, and
  46   /// therefore represents the conversion of a single phrase. The
  47   /// phrase to be converted is read by recursing through the parent
  48   /// tree. An instance of CConversionHelper is shared by several
  49   /// CConversionManagers, and performs the language dependent aspects
  50   /// of conversion. Specifically construction of the candidate
  51   /// lattice and assignment of weights.
  52   ///
  53   /// The general policy is to delay computation as far as possible,
  54   /// to avoid unnecessary computational load. The candidate lattice
  55   /// is therefore built at the first call to PopulateChildren, and
  56   /// weights are only assigned when the appropriate node has its
  57   /// child list populated.
  58   ///
  59   /// See CConversionHelper for details of the language specific
  60   /// aspects of conversion, and CNodeManager for details of the node
  61   /// management process.
  62   ///
  63   class CConversionManager : protected CSettingsUser, public CNodeManager {
  64     friend class CConvertingAlphMgr;
  65   protected:  class CConvNode; //fwd decl
  66   public:
  67     CConversionManager(CSettingsUser *pCreateFrom, CDasherInterfaceBase *pInterface, CNodeCreationManager *pNCManager, const CAlphInfo *pAlphabet, CLanguageModel *pLanguageModel);
  68
  69     ///
  70     /// Get a new root node owned by this manager
  71     ///
  72
  73     virtual CConvNode *GetRoot(int iOffset, CLanguageModel::Context newCtx);
  74
  75     ///Tells us to use the specified screen to create node labels.
  76     /// (note we cache the screen and create labels lazily)
  77     void ChangeScreen(CDasherScreen *pScreen);
  78
  79   protected:
  80
  81     class CConvNode : public CDasherNode {
  82     public:
  83       CConversionManager *mgr() const {return m_pMgr;}
  84       CConvNode(int iOffset, int iColour, CDasherScreen::Label *pLabel, CConversionManager *pMgr);
  85     ///
  86     /// Provide children for the supplied node
  87     ///
  88
  89     virtual void PopulateChildren();
  90     virtual int ExpectedNumChildren();
  91       virtual void SetFlag(int iFlag, bool bValue);
  92
  93     ~CConvNode();
  94
  95     ///Attempts to fill vContextSymbols with the context that would exist _after_ this node has been entered
  96     void GetContext(CDasherInterfaceBase *pInterface, const CAlphabetMap *pAlphabetMap, std::vector<symbol> &vContextSymbols, int iOffset, int iLength);
  97
  98     ///
  99     /// Called whenever a node belonging to this manager first
 100     /// moves under the crosshair
 101     ///
 102
 103     virtual void Output();
 104
 105     ///
 106     /// Called when a node is left backwards
 107     ///
 108
 109     virtual void Undo();
 110
 111     protected:
 112       CConversionManager *m_pMgr;
 113     public: //to ConversionManager and subclasses only, of course...
 114
 115     //TODO: REVISE
 116       symbol iSymbol;
 117       //     int iPhase;
 118       CLanguageModel::Context iContext;
 119       SCENode * pSCENode;
 120       bool bisRoot; // True for root conversion nodes
 121       //int iGameOffset;
 122     };
 123
 124     virtual CConvNode *makeNode(int iOffset, int iColour, CDasherScreen::Label *pLabel);
 125
 126     CDasherInterfaceBase *m_pInterface;
 127         CNodeCreationManager *m_pNCManager;
 128         const CAlphInfo *m_pAlphabet;
 129
 130     ///Utility method for subclasses, lazily makes+caches node labels
 131     /// \return a node label displaying the specified string
 132     CDasherScreen::Label *GetLabel(const char *pszConversion);
 133
 134     /// Convert a given string to a lattice of candidates. Sizes for
 135         /// candidates aren't assigned at this point. The input string
 136         /// should be UTF-8 encoded.
 137         ///
 138         /// @param strSource UTF-8 encoded input string.
 139         /// @param pRoot Used to return the root of the conversion lattice.
 140         /// @param childCount Unsure - document this.
 141         /// @param CMid A unique identifier for the conversion helper 'context'.
 142         ///
 143         /// @return True if conversion succeeded, false otherwise
 144         virtual bool Convert(const std::string &strSource, SCENode ** pRoot) = 0;
 145
 146         /// Assign sizes to the children of a given conversion node. This
 147         /// happens when the conversion manager populates the children of
 148         /// the Dasher node so as to avoid unnecessary computation.
 149         ///
 150         /// @param pStart The parent of the nodes to be sized.
 151         /// @param context Unsure - document this, shouldn't be in general class (include userdata pointer).
 152         /// @param normalization Normalisation constant for the child sizes (TODO: check that this is a sensible value, ie the same as Dasher normalisation).
 153         /// @param uniform Unsure - document this.
 154         ///
 155     virtual void AssignSizes(const std::vector<SCENode *> &vChildren, Dasher::CLanguageModel::Context context, long normalization, int uniform)=0;
 156
 157         /// Assign colours to the children of a given conversion node.
 158         /// This function needs a rethink.
 159         ///
 160         /// @param parentClr
 161         /// @param pNode
 162         /// @param childIndex
 163         ///
 164         /// @return
 165         ///
 166         virtual int AssignColour(int parentClr, SCENode * pNode, int childIndex) {
 167       int which = -1;
 168
 169       for (int i=0; i<2; i++)
 170         for(int j=0; j<3; j++)
 171           if (parentClr == colourStore[i][j])
 172             which = i;
 173
 174       if(which == -1)
 175         return colourStore[0][childIndex%3];
 176       else if(which == 0)
 177         return colourStore[1][childIndex%3];
 178       else
 179         return colourStore[0][childIndex%3];
 180         };
 181
 182     ///
 183     /// Calculate sizes for each of the children - default
 184     /// implementation assigns decending probabilities in a power law
 185     /// fashion (so assumes ordering), but specific subclasses are
 186     /// free to implement their own behaviour. The only restriction is
 187     /// that sizes should be positive and sum to the appropriate
 188     /// normalisation constant
 189     ///
 190
 191     virtual void AssignChildSizes(const std::vector<SCENode *> &vChildren, CLanguageModel::Context context);
 192
 193     ///
 194     /// Build the conversion tree (lattice) for the given string -
 195     /// evaluated late to prevent unnecessary conversions when the
 196     /// children of the root node are never instantiated
 197     ///
 198
 199     virtual void BuildTree(CConvNode *pRoot);
 200
 201   private:
 202
 203     std::map<std::string, CDasherScreen::Label *> m_vLabels;
 204     CDasherScreen *m_pScreen;
 205
 206     ///
 207     /// Dump tree to provided stream (debug)
 208     ///
 209
 210     void RecursiveDumpTree(std::ostream &out, SCENode *pCurrent, unsigned int iDepth);
 211
 212     CLanguageModel *m_pLanguageModel;
 213
 214     CLanguageModel::Context m_iLearnContext;
 215
 216         int colourStore[2][3];
 217
 218   };
 219   /// @}
 220 }
 221
 222 #endif