|
|
00001 //--------------------------------------------------------------------------- 00002 /// \file CATApp.h 00003 /// \brief Application parent class - derive from this for each app made. 00004 /// \ingroup CATGUI 00005 /// 00006 /// Copyright (c) 2007-2008 by Michael Ellison. 00007 /// See COPYING.txt for the \ref gaslicense License (MIT License). 00008 /// 00009 // $Author: mikeellison $ 00010 // $Date: 2008-01-31 06:29:47 -0600 (Thu, 31 Jan 2008) $ 00011 // $Revision: $ 00012 // $NoKeywords: $ 00013 // 00014 //--------------------------------------------------------------------------- 00015 #ifndef CATApp_H_ 00016 #define CATApp_H_ 00017 00018 #include "CATTypes.h" 00019 #include "CATString.h" 00020 #include "CATResult.h" 00021 #include "CATStringTableCore.h" 00022 #include "CATMutex.h" 00023 #include "CATSkin.h" 00024 00025 class CATPrefs; 00026 class CATWaitDlg; 00027 class CATFileSystem; 00028 class CATGuiFactory; 00029 00030 /// CATRunMode defines the type of app the code is running as. 00031 /// It allows classes to perform differently in different environments 00032 /// without having to #ifdef stuff. 00033 /// 00034 /// Use CATApp::GetRunMode() to retrieve the current run mode. 00035 enum CATRunMode 00036 { 00037 /// Basic console app 00038 CAT_CONSOLE, 00039 /// Windowed GUI app 00040 CAT_GUI, 00041 /// VST plug-in environment 00042 CAT_VST 00043 }; 00044 00045 /// \class CATApp 00046 /// \brief Application parent class - derive from this for each app made. 00047 /// \ingroup CATGUI 00048 /// 00049 /// CATApp is an attempt at virtualizing enough of the idea of an application 00050 /// that we don't have to rewrite our entrypoint code each time or #ifdef 00051 /// code depending on whether we're in a VST, a console app, or whatever. 00052 /// 00053 class CATApp 00054 { 00055 public: 00056 /// App construct - requires you to specify a runmode in the 00057 /// constructor. 00058 /// 00059 /// \param instance - instance of app (HINSTANCE for windows, does mac have equiv?) 00060 /// \param runMode - current runmode. See CATRunMode 00061 /// \param appName - application name 00062 /// 00063 CATApp( CATINSTANCE instance, 00064 CATRunMode runMode, 00065 const CATString& appName); 00066 00067 virtual ~CATApp(); 00068 00069 /// GetBaseDir() retrieves the base directory for the application. 00070 /// 00071 /// This should generally be the directory the .exe is in. 00072 /// \return CATString - base directory path 00073 virtual CATString GetBaseDir(); 00074 00075 /// GetDataDir() retrieves the directory misc. data (like the prefs) 00076 /// are in. 00077 /// 00078 /// This should generally be BaseDir + "Data/" 00079 /// \return CATString - skin directory path 00080 virtual CATString GetDataDir(); 00081 00082 /// GetSkinDir() retrieves the directory skins are located in. 00083 /// 00084 /// This should generally be BaseDir + "Skin/" 00085 /// \return CATString - skin directory path 00086 virtual CATString GetSkinDir(); 00087 00088 /// GetSkinDir() retrieves the directory the help files are located in. 00089 /// 00090 /// This should generally be BaseDir + "Help/" 00091 /// \return CATString - help directory path 00092 virtual CATString GetHelpDir(); 00093 00094 /// InitWaitDlg() initializes the wait dialog for use. Call 00095 /// before retrieving the wait dialog. Generally initialized 00096 /// in OnStart() from derived classes. 00097 virtual CATResult InitWaitDlg( CATInt32 bmpId, 00098 CATRect& textRect, 00099 CATInt32 progressOnId = 0, 00100 CATInt32 progressOffId = 0, 00101 CATInt32 progressLeft = 0, 00102 CATInt32 progressTop = 0); 00103 00104 /// GetWaitDlg() retrieves a pointer to the app's wait dialog. 00105 /// WARNING: this may be null. Call InitWaitDlg() to create the 00106 /// wait dialog first. 00107 virtual CATWaitDlg* GetWaitDlg(); 00108 00109 virtual void SetWaitString( const CATString& waitStr); 00110 00111 virtual void SetWaitProgress( CATFloat32 progress ); 00112 00113 virtual void SetWaitStatus( const CATString& waitStr, 00114 CATFloat32 progress); 00115 00116 /// GetAppFileSystem() retrieves a file system object for the 00117 /// app's base directory. 00118 /// 00119 /// \return CATFileSystem* - pointer to app file system. 00120 /// Don't delete this - only one per app... 00121 CATFileSystem* GetAppFileSystem(); 00122 00123 /// GetGlobalFileSystem() retrieves a file system object for 00124 /// the system. 00125 /// 00126 /// \return CATFileSystem* - pointer to global file system. 00127 /// Don't delete this - only one per app... 00128 CATFileSystem* GetGlobalFileSystem(); 00129 00130 /// GetRunMode() returns the run mode as defined in CATRunMode. 00131 /// 00132 /// \return CATRunMode - current run mode of the application 00133 CATRunMode GetRunMode(); 00134 00135 00136 //--------------------------------------------------------------------- 00137 // Overrideables 00138 //--------------------------------------------------------------------- 00139 /// Run() begins the app. 00140 /// 00141 /// You should load a stringtable first via SetLanguage(). 00142 /// Run() does not return until the app is exiting. It calls 00143 /// the overrideables for OnStart(), OnEnd(), and MainLoop() 00144 /// however so your derived class gets control. 00145 /// 00146 /// \return CATResult - final result for application 00147 virtual CATResult Run(); 00148 00149 //--------------------------------------------------------------------- 00150 /// Display an error box for a given return value. 00151 /// 00152 /// Since these may be classes or integers, it needs 00153 /// to account for both and dump as much information 00154 /// as possible. 00155 /// \param resultCode - result code to display info from 00156 virtual void DisplayError( const CATResult& resultCode, 00157 CATWindow* wnd = 0); 00158 00159 /// Display an message box with the specified string 00160 /// 00161 /// \param message - string to display 00162 virtual void DisplayMessage(const CATString& message, 00163 CATWindow* wnd = 0); 00164 00165 /// CATPROMPTTYPE defines the types of prompts that are available 00166 /// from DisplayPrompt 00167 enum CATPROMPTTYPE 00168 { 00169 CATPROMPT_YESNO, 00170 CATPROMPT_OKCANCEL, 00171 CATPROMPT_OK, 00172 CATPROMPT_YESNOCANCEL 00173 }; 00174 00175 /// DisplayPrompt() displays a message and retrieves a response 00176 /// from the user. 00177 /// 00178 /// The user is prompted with a message, and the response from the 00179 /// prompt is returned. 00180 /// 00181 /// \param message - message to send to user 00182 /// \param prompt - type of prompt to use (see CATPROMPTTYPE) 00183 /// \param wnd - parent window of display box (GUI only) 00184 /// \return CATResult - CAT_STAT_PROMPT_[YES|NO|OK|CANCEL] 00185 virtual CATResult DisplayPrompt( const CATString& message, 00186 CATPROMPTTYPE prompt, 00187 CATWindow* wnd = 0); 00188 00189 00190 00191 /// OpenFileDialog() displays an open file dialog and returns the 00192 /// selected file path, if any. 00193 /// 00194 /// \param title - title string 00195 /// \param filetypeList - list of file type / extension pairs. std::map<filename, filemask>, 00196 /// e.g. std::map.Insert("Session files","*.drum_sess") 00197 /// \param returnPath - ref to string to fill with received file path, if any. 00198 /// when called, this is also used as the default file name. 00199 /// \param parentWnd - parent window ofof dialog 00200 virtual CATResult OpenFileDialog( const CATString& title, 00201 std::vector<CATString>& filetypeList, 00202 CATString& returnPath, 00203 CATWindow* parentWnd = 0); 00204 00205 /// SaveFileDialog() displays a save file dialog and returns the 00206 /// selected file path, if any. 00207 /// 00208 /// \param title - title string 00209 /// \param filetypeList - list of file type / extension pairs. std::map<filename, filemask>, 00210 /// e.g. std::map.Insert("Session files","*.drum_sess") 00211 /// \param returnPath - ref to string to fill with received file path, if any. 00212 /// when called, this is also used as the default file name. 00213 /// \param parentWnd - parent window 00214 /// \param promptOverwrite - if true, prompts if the file already exists... 00215 /// \param fileExtension - default file extension to add to file name 00216 /// 00217 virtual CATResult SaveFileDialog( const CATString& title, 00218 std::vector<CATString>& filetypeList, 00219 CATString& returnPath, 00220 CATWindow* parentWnd = 0, 00221 bool promptOverwrite = true, 00222 const CATString& fileExtension = ""); 00223 00224 00225 /// GetString() retrieves the string for the current language (set in SetLanguage) 00226 /// associated with the stringId. 00227 /// 00228 /// SetLanguage() should be called before calling GetString(). 00229 /// GetString() is threadsafe, and may be called from any thread in the application. 00230 /// 00231 /// \param stringId - ID for the string - these will be defined in the 00232 /// CATResult_* files. 00233 /// \return CATString - requested string, fallback string, or an empty string 00234 /// if none was found. 00235 /// \sa SetLanguage() 00236 CATString GetString(CATUInt32 stringId); 00237 00238 /// GetAppName() retrieves the application name 00239 /// 00240 /// \return CATString - name of application 00241 CATString GetAppName(); 00242 00243 /// GetAppName() retrieves the full path of the application. 00244 /// 00245 /// \return CATString - path to application 00246 CATString GetAppExePath(); 00247 00248 /// GetPrefs() retrieves a pointer to the preferences object for the app. 00249 /// 00250 /// Do NOT delete this. It is owned by the app. 00251 /// \return CATPrefs - application preferences 00252 /// \sa CATPrefs 00253 CATPrefs* GetPrefs(); 00254 00255 /// GetTempPrefs() retrieves a pointer to the runtime prefs. 00256 /// 00257 /// Do NOT delete this. It is owned by the app. 00258 /// \return CATPrefs - application preferences 00259 /// \sa CATPrefs 00260 CATPrefs* GetTempPrefs(); 00261 00262 /// GetInstance() retrieves the application instance. 00263 /// For windows, this is your HINSTANCE handle. 00264 /// \return CATINSTANCE - instance of application 00265 CATINSTANCE GetInstance(); 00266 00267 /// LoadSkin() loads a skin 00268 /// WARNING: this is not really tested for loading more than 00269 /// one yet per run. 00270 /// \param skinPath - path to skin to load 00271 /// \return CATResult - CAT_SUCCESS on success. 00272 CATResult LoadSkin(const CATString& skinPath); 00273 CATGuiFactory* GetGUIFactory() {return fGUIFactory;} 00274 00275 /// GetSkin() retrieves a ptr to the base skin object. 00276 /// Do NOT delete it. 00277 /// \return CATSkin* - pointer to the current skin 00278 CATSkin* GetSkin(); 00279 00280 //--------------------------------------------------------------------- 00281 // You should override the following functions in your application. 00282 //--------------------------------------------------------------------- 00283 00284 /// OnStart() is called before the primary event loop is started. This would 00285 /// be a good place to load your skin and perform other initialization functions. 00286 /// \return CAT_SUCCESS on success. 00287 virtual CATResult OnStart(); 00288 00289 /// OnEnd() is called after the main loop finishes, with the result code of 00290 /// the loop. 00291 /// 00292 virtual CATResult OnEnd(const CATResult& result); 00293 00294 /// OnEvent() is called as events are received that need to be processed by the application. 00295 virtual CATResult OnEvent(const CATEvent& event, CATInt32& retVal); 00296 00297 /// OnCommand() is called each time a command is received by the application. 00298 /// 00299 /// Most often, commands will come up from the Skin from controls. Each time 00300 /// a button is clicked or a knob turned, for example. 00301 /// 00302 /// The commands are a class, primarily containing a command string that the 00303 /// application should check to see if it supports. If so, the command should 00304 /// be performed. 00305 /// 00306 /// \param command - the command to execute 00307 /// \param ctrl - the control that sent the command, or 0 00308 /// \param wnd - the window of the control, or 0 00309 /// \param skin - the skin the command came from, or 0 00310 virtual void OnCommand( CATCommand& command, 00311 CATControl* ctrl, 00312 CATWindow* wnd, 00313 CATSkin* skin); 00314 00315 /// MainLoop() is the message pump. You'll generally want to do things like 00316 /// a GetMessage() / DispatchMEssage() loop in here. 00317 virtual CATResult MainLoop(); 00318 00319 /// ExitApp() requests an immediate exit 00320 virtual void ExitApp(); 00321 00322 /// IsExiting() returns true if the application is in the process of exiting. 00323 virtual bool IsExiting(); 00324 00325 /// OnHelp() is called when the user requests help. 00326 virtual void OnHelp(); 00327 00328 virtual CATString GetVersionString(); 00329 00330 00331 /// Resource image request functions - these allow us to reuse a single 00332 /// image w/o wasting more space... 00333 CATResult AddResourceImage( const CATString& path, CATImage* image); 00334 CATResult GetResourceImage( const CATString& path, CATImage*& image); 00335 CATResult FlushResourceCache(); 00336 00337 virtual void OSOnAppCreate(); 00338 //--------------------------------------------------------------------- 00339 // Global objects 00340 //--------------------------------------------------------------------- 00341 00342 protected: 00343 static void SkinLoadCB( CATFloat32 progress, const CATString& status, void* userParam); 00344 00345 bool fExiting; // Flag for inherited classes to check in their main loop 00346 // to see if we're exiting. 00347 00348 CATPrefs* fPrefs; // Global preferences 00349 CATPrefs* fTempPrefs; // Runtime preferences 00350 00351 CATMutex fAppLock; // Thread lock for app object 00352 // to serialize access 00353 CATStringTableCore fStringTable; // Application string table 00354 CATRunMode fRunMode; // Current run mode 00355 00356 CATFileSystem* fGlobalFileSystem; // Global file system for app framework. 00357 00358 CATString fBaseDir; // Base directory for app 00359 CATString fDataDir; // Base data directory 00360 00361 CATString fHelpDir; // Help directory 00362 00363 CATString fProgramPath; // Full path of program 00364 CATString fAppName; // friendly application name 00365 CATINSTANCE fAppInstance; // Application instance 00366 00367 CATString fSkinDir; // Base skin directory 00368 CATGuiFactory* fGUIFactory; // Factory for GUI (overrideable) 00369 CATSkin* fSkin; // Application's skin 00370 CATWaitDlg* fWaitDlg; 00371 00372 std::map<CATString, CATImage*> fImageCache; // Image cache 00373 }; 00374 00375 extern CATApp* gApp; 00376 00377 #endif // CATApp_H_
1.5.4