Src/DasherCore/DasherInterfaceBase.h

   1 // DasherInterfaceBase.h
   2 //
   3 // Copyright (c) 2002 Iain Murray
   4
   5 #ifndef __DasherInterfaceBase_h__
   6 #define __DasherInterfaceBase_h__
   7
   8 ///
   9 /// \mainpage
  10 ///
  11 /// This is the Dasher source code documentation. Please try to keep
  12 /// it up to date!
  13 ///
  14
  15 // TODO - there is a list of things to be configurable in my notes
  16 // Check that everything that is not self-contained within the GUI is covered.
  17
  18 #include "../Common/NoClones.h"
  19 #include "../Common/ModuleSettings.h"
  20 #include "Alphabet/Alphabet.h"
  21 #include "Alphabet/AlphIO.h"
  22 #include "ColourIO.h"
  23 #include "ModuleManager.h"
  24 #include "ActionButton.h"
  25
  26 #include "AutoSpeedControl.h"
  27
  28 #include "InputFilter.h"
  29
  30 namespace Dasher {
  31   class CDasherScreen;
  32   class CDasherView;
  33   class CDasherInput;
  34   class CDasherModel;
  35   class CEventHandler;
  36   class CEvent;
  37 }
  38
  39 class Dasher::CDasherScreen;
  40 class Dasher::CDasherView;
  41 class Dasher::CDasherInput;
  42 class Dasher::CDasherModel;
  43 class Dasher::CEventHandler;
  44 class Dasher::CEvent;
  45 class CSettingsStore;
  46 class CUserLogBase;
  47 class CDasherButtons;
  48 class CNodeCreationManager;
  49
  50 #include <map>
  51 #include <algorithm>
  52
  53 namespace Dasher {
  54   class CDasherInterfaceBase;
  55 }
  56
  57 /// \defgroup Core Core Dasher classes
  58 /// @{
  59
  60 /// The central class in the core of Dasher. Ties together the rest of
  61 /// the platform independent stuff and provides a single interface for
  62 /// the UI to use.
  63 class Dasher::CDasherInterfaceBase:private NoClones
  64 {
  65 public:
  66   CDasherInterfaceBase();
  67   virtual ~ CDasherInterfaceBase();
  68
  69   /// @name Access to internal member classes
  70   /// Access various classes contained within the interface. These
  71   /// should be considered dangerous and use minimised. Eventually to
  72   /// be replaced by properly encapsulated equivalents.
  73   /// @{
  74
  75   ///
  76   /// Return a pointer to the current EventHandler (the one
  77   /// which the CSettingsStore is using to notify parameter
  78   /// changes)
  79   ///
  80
  81   virtual CEventHandler *GetEventHandler() {
  82     return m_pEventHandler;
  83   };
  84
  85   ///
  86   /// \deprecated In situ alphabet editing is no longer supported
  87   /// \todo Document this
  88   ///
  89
  90   const CAlphIO::AlphInfo & GetInfo(const std::string & AlphID);
  91
  92   /// \todo Document this
  93
  94   void SetInfo(const CAlphIO::AlphInfo & NewInfo);
  95
  96   /// \todo Document this
  97
  98   void DeleteAlphabet(const std::string & AlphID);
  99
 100   /// Get a pointer to the current alphabet object
 101
 102   CAlphabet *GetAlphabet() {
 103     return m_Alphabet;
 104   }
 105
 106   /// Gets a pointer to the object doing user logging
 107
 108   CUserLogBase* GetUserLogPtr();
 109
 110   // @}
 111
 112   ///
 113   /// @name Parameter manipulation
 114   /// Members for manipulating the parameters of the core Dasher object.
 115   ///
 116
 117   //@{
 118
 119   ///
 120   /// Set a boolean parameter.
 121   /// \param iParameter The parameter to set.
 122   /// \param bValue The new value.
 123   ///
 124
 125   void SetBoolParameter(int iParameter, bool bValue);
 126
 127   ///
 128   /// Set a long integer parameter.
 129   /// \param iParameter The parameter to set.
 130   /// \param lValue The new value.
 131   ///
 132
 133   void SetLongParameter(int iParameter, long lValue);
 134
 135   ///
 136   /// Set a string parameter.
 137   /// \param iParameter The parameter to set.
 138   /// \param sValue The new value.
 139   ///
 140
 141   void SetStringParameter(int iParameter, const std::string & sValue);
 142
 143   /// Get a boolean parameter
 144   /// \param iParameter The parameter to get.
 145   /// \retval The current value.
 146
 147   bool GetBoolParameter(int iParameter);
 148
 149   /// Get a long integer parameter
 150   /// \param iParameter The parameter to get.
 151   /// \retval The current value.
 152
 153   long GetLongParameter(int iParameter);
 154
 155   /// Get a string parameter
 156   /// \param iParameter The parameter to get.
 157   /// \retval The current value.
 158
 159   std::string GetStringParameter(int iParameter);
 160
 161   ///
 162   /// Reset a parameter to the default value
 163   ///
 164
 165   void ResetParameter(int iParmater);
 166
 167   /// \todo Document this
 168
 169   void GetFontSizes(std::vector < int >*FontSizes) const;
 170
 171   ///
 172   /// Obtain the permitted values for a string parameter - used to
 173   /// geneate preferences dialogues etc.
 174   ///
 175
 176   void GetPermittedValues(int iParameter, std::vector<std::string> &vList);
 177
 178   ///
 179   /// Get a list of settings which apply to a particular module
 180   ///
 181
 182   bool GetModuleSettings(const std::string &strName, SModuleSettings **pSettings, int *iCount);
 183
 184
 185   //@}
 186
 187   /// Forward events to listeners in the SettingsUI and Editbox.
 188   /// \param pEvent The event to forward.
 189   /// \todo Should be protected.
 190
 191   virtual void ExternalEventHandler(Dasher::CEvent * pEvent) {};
 192
 193   /// Interface level event handler. For example, responsible for
 194   /// restarting the Dasher model whenever parameter changes make it
 195   /// invalid.
 196   /// \param pEvent The event.
 197   /// \todo Should be protected.
 198
 199   void InterfaceEventHandler(Dasher::CEvent * pEvent);
 200
 201
 202   void PreSetNotify(int iParameter, const std::string &sValue);
 203
 204
 205   /// Draw a new Dasher frame, regardless of whether we're paused etc.
 206   /// \param iTime Current time in ms.
 207   /// \todo See comments in cpp file for some functionality which needs to be re-implemented
 208
 209   void NewFrame(unsigned long iTime, bool bForceRedraw);
 210
 211
 212   /// @name Starting and stopping
 213   /// Methods used to instruct dynamic motion of Dasher to start or stop
 214   /// @{
 215
 216   /// Resets the Dasher model. Doesn't actually unpause Dasher.
 217   /// \deprecated Use InvalidateContext() instead
 218
 219   //  void Start();
 220
 221   /// Pause Dasher
 222   /// \todo Parameters are ignored (?) - remove from definition.
 223
 224   void PauseAt(int MouseX, int MouseY); // are required to make
 225
 226   /// Halt Dasher. This simply freezes Dasher but does not emit a stop event, so does not result in speech etc.
 227
 228   void Halt();
 229
 230   /// Unpause Dasher
 231   /// \param Time Time in ms, used to keep a constant frame rate
 232
 233   void Unpause(unsigned long Time);     // Dasher run at the
 234
 235   /// @}
 236
 237
 238   // App Interface
 239   // -----------------------------------------------------
 240
 241   // std::map<int, std::string>& GetAlphabets(); // map<key, value> int is a UID string can change. Store UID in preferences. Display string to user.
 242   // std::vector<std::string>& GetAlphabets();
 243   // std::vector<std::string>& GetLangModels();
 244   // std::vector<std::string>& GetViews();
 245
 246   /// Supply a new CDasherScreen object to do the rendering.
 247   /// \param NewScreen Pointer to the new CDasherScreen.
 248
 249   void ChangeScreen(CDasherScreen * NewScreen); // We may change the widgets Dasher uses
 250
 251   /// Train Dasher from a file
 252   /// \param Filename File to load.
 253
 254   int TrainFile(std::string Filename, int iTotalBytes, int iOffset); // all training data must be in UTF-8.
 255
 256   /// Set the context in which Dasher makes predictions
 257   /// \param strNewContext The new context (UTF-8)
 258
 259   void SetContext(std::string strNewContext);
 260
 261   /// New control mechanisms:
 262
 263   void SetBuffer(int iOffset);
 264
 265   void UnsetBuffer();
 266
 267   void SetOffset(int iOffset);
 268
 269   /// @name Status reporting
 270   /// Get information about the runtime status of Dasher which might
 271   /// be of interest for debugging purposes etc.
 272   /// @{
 273
 274   /// Get the current rate of text entry.
 275   /// \retval The rate in characters per minute.
 276   /// TODO: Check that this is still used
 277
 278   double GetCurCPM();
 279
 280   /// Get current refresh rate.
 281   /// \retval The rate in frames per second
 282   /// TODO: Check that this is still used
 283
 284   double GetCurFPS();
 285
 286   /// Get the total number of nats (base-e bits) entered.
 287   /// \retval The current total
 288   /// \todo Obsolete since new logging code?
 289
 290   double GetNats() const;
 291
 292   /// Reset the count of nats entered.
 293   /// \todo Obsolete since new logging code?
 294
 295   void ResetNats();
 296
 297   double GetFramerate();
 298
 299   int GetRenderCount();
 300
 301   /// @}
 302
 303   /// @name Control hierarchy and action buttons
 304   /// Manipulate the hierarchy of commands presented in control mode etc
 305   /// @{
 306
 307   void RegisterNode( int iID, const std::string &strLabel, int iColour );
 308
 309   void ConnectNode(int iChild, int iParent, int iAfter);
 310
 311   void DisconnectNode(int iChild, int iParent);
 312
 313   void ExecuteCommand(const std::string &strName);
 314
 315   void AddActionButton(const std::string &strName);
 316
 317   /// @}
 318
 319   /// @name User input
 320   /// Deals with forwarding user input to the core
 321   /// @{
 322
 323   void KeyDown(int iTime, int iId);
 324
 325   void KeyUp(int iTime, int iId);
 326
 327   void HandleClickUp(int iTime, int iX, int iY);
 328
 329   void HandleClickDown(int iTime, int iX, int iY);
 330
 331   /// @}
 332
 333   // Module management functions
 334   void RegisterFactory(CModuleFactory *pFactory);
 335
 336   void StartShutdown();
 337
 338   void AddGameModeString(const std::string &strText) {
 339     m_deGameModeStrings.push_back(strText);
 340     PauseAt(0,0);
 341     //    CreateDasherModel();
 342     CreateNCManager();
 343     //    Start();
 344   };
 345
 346   void ScheduleRedraw() {
 347     m_bRedrawScheduled = true;
 348   };
 349
 350   void CheckRedraw();
 351
 352   std::string GetContext(int iStart, int iLength);
 353
 354
 355 protected:
 356
 357   /// @name Startup
 358   /// Interaction with the derived class during core startup
 359   /// @{
 360
 361   ///
 362   /// Allocate resources, create alphabets etc. This is a separate
 363   /// routine to the constructor to give us a chance to set up
 364   /// parameters before things are created.
 365   ///
 366
 367   void Realize();
 368
 369   ///
 370   /// Notify the core that the UI has been realised. At this point drawing etc. is expected to work
 371   ///
 372
 373   void OnUIRealised();
 374
 375   /// @}
 376
 377   enum ETransition {
 378     TR_MODEL_INIT = 0,
 379     TR_UI_INIT,
 380     TR_LOCK,
 381     TR_UNLOCK,
 382     TR_SHUTDOWN,
 383     TR_NUM
 384   };
 385
 386   enum EState {
 387     ST_START = 0,
 388     ST_MODEL,
 389     ST_UI,
 390     ST_NORMAL,
 391     ST_LOCKED,
 392     ST_SHUTDOWN,
 393     ST_NUM,
 394     ST_FORBIDDEN,
 395     ST_DELAY
 396   };
 397
 398   /// @name State machine functions
 399   /// ...
 400   /// @{
 401
 402   void ChangeState(ETransition iTransition);
 403
 404   /// @}
 405
 406   CDasherModule *GetModule(long long int iID);
 407   CDasherModule *GetModuleByName(const std::string &strName);
 408
 409   CEventHandler *m_pEventHandler;
 410   CSettingsStore *m_pSettingsStore;
 411
 412  private:
 413
 414   /// @name Platform dependent utility functions
 415   /// These functions provide various platform dependent functions
 416   /// required by the core. A derived class is created for each
 417   /// supported platform which implements these.
 418   // @{
 419
 420   ///
 421   /// Initialise the SP_SYSTEM_LOC and SP_USER_LOC paths - the exact
 422   /// method of doing this will be OS dependent
 423   ///
 424
 425   virtual void SetupPaths() = 0;
 426
 427   ///
 428   /// Produce a list of filenames for alphabet files
 429   ///
 430
 431   virtual void ScanAlphabetFiles(std::vector<std::string> &vFileList) = 0;
 432
 433   ///
 434   /// Produce a list of filenames for colour files
 435   ///
 436
 437   virtual void ScanColourFiles(std::vector<std::string> &vFileList) = 0;
 438
 439   ///
 440   /// Set up the platform dependent UI for the widget (not the wider
 441   /// app). Note that the constructor of the derived class will
 442   /// probably want to return details of what was created - this will
 443   /// have to happen separately, but we'll need to be careful with the
 444   /// semantics.
 445   ///
 446
 447   virtual void SetupUI() = 0;
 448
 449   ///
 450   /// Create any module factories which are specific to the platform
 451   /// (eg input device drivers)
 452   ///
 453
 454   virtual void CreateLocalFactories() = 0;
 455
 456   ///
 457   /// Create settings store object, which will be platform dependent
 458   /// TODO: Can this not be done just by selecting which settings
 459   /// store implementation to instantiate?
 460   ///
 461
 462   virtual void CreateSettingsStore() = 0;
 463
 464   ///
 465   /// Obtain the size in bytes of a file - the way to do this is
 466   /// dependent on the OS (TODO: Check this - any posix on Windows?)
 467   ///
 468
 469   virtual int GetFileSize(const std::string &strFileName) = 0;
 470
 471   ///
 472   /// Start the callback timer
 473   ///
 474
 475   virtual void StartTimer() = 0;
 476
 477   ///
 478   /// Shutdown the callback timer (permenantly - this is called once
 479   /// Dasher is committed to closing).
 480   ///
 481
 482   virtual void ShutdownTimer() = 0;
 483
 484   ///
 485   /// Append text to the trainign file - used to store state between
 486   /// sessions
 487   /// @todo Pass file path to the fuction rather than having implementations work it out themselves
 488   ///
 489
 490   virtual void WriteTrainFile(const std::string &strNewText) {
 491   };
 492
 493   /// @}
 494
 495
 496   /// Provide a new CDasherInput input device object.
 497
 498   void CreateInput();
 499
 500   void CreateFactories();
 501   void CreateInputFilter();
 502
 503   void CreateModel(int iOffset);
 504   void CreateNCManager();
 505
 506   void ChangeAlphabet();
 507   void ChangeColours();
 508   void ChangeView();
 509   void Redraw(bool bRedrawNodes);
 510   void SetupActionButtons();
 511   void DestroyActionButtons();
 512   void PositionActionButtons();
 513   bool DrawActionButtons();
 514
 515   void LeaveState(EState iState);
 516   void EnterState(EState iState);
 517
 518   void WriteTrainFileFull();
 519   void WriteTrainFilePartial();
 520
 521
 522   /// @name Lock Management
 523   /// Functions for locking/unlocking the core. Note that the lock
 524   /// flags parameter is currently ignored, but will be used to give
 525   /// finer granularity
 526   /// @{
 527
 528   ///
 529   /// Add a lock
 530   ///
 531
 532   void AddLock(int iLockFlags);
 533
 534   ///
 535   /// Release an existing lock. Note that these functions have minimal
 536   /// error checking at the moment, so be careful.
 537   ///
 538
 539   void ReleaseLock(int iLockFlags);
 540
 541   /// @}
 542
 543   std::deque<std::string> m_deGameModeStrings;
 544
 545   std::vector<CActionButton *> m_vLeftButtons;
 546   std::vector<CActionButton *> m_vRightButtons;
 547
 548
 549   /// @name Child components
 550   /// Various objects which are 'owned' by the core.
 551   /// @{
 552   CAlphabet *m_Alphabet;
 553   CDasherModel *m_pDasherModel;
 554   CDasherScreen *m_DasherScreen;
 555   CDasherView *m_pDasherView;
 556   CDasherInput *m_pInput;
 557   CAlphIO *m_AlphIO;
 558   CColourIO *m_ColourIO;
 559   CNodeCreationManager *m_pNCManager;
 560   CUserLogBase *m_pUserLog;
 561   CInputFilter* m_pInputFilter;
 562   CModuleManager m_oModuleManager;
 563   /// @}
 564
 565   std::string strTrainfileBuffer;
 566   std::string strCurrentContext;
 567
 568   std::string m_strContext;
 569
 570   /// @name State variables
 571   /// Represent the current overall state of the core
 572   /// @{
 573   bool m_bGlobalLock; // The big lock
 574   bool m_bRedrawScheduled;
 575   int m_iLockCount;
 576   EState m_iCurrentState;
 577   bool m_bOldVisible;
 578   /// @}
 579
 580   bool m_bLastChanged;
 581 };
 582 /// @}
 583
 584 #endif /* #ifndef __DasherInterfaceBase_h__ */