 | PixelLight 0.9.11-R1 Copyright (C) 2002-2012 by The PixelLight Team Last modified Thu Feb 23 2012 14:08:59 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: ScriptApplication.h * 00003 * 00004 * Copyright (C) 2002-2012 The PixelLight Team (http://www.pixellight.org/) 00005 * 00006 * This file is part of PixelLight. 00007 * 00008 * PixelLight is free software: you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License as published by 00010 * the Free Software Foundation, either version 3 of the License, or 00011 * (at your option) any later version. 00012 * 00013 * PixelLight is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00016 * GNU Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public License 00019 * along with PixelLight. If not, see <http://www.gnu.org/licenses/>. 00020 \*********************************************************/ 00021 00022 00023 #ifndef __PLENGINE_SCRIPTAPPLICATION_H__ 00024 #define __PLENGINE_SCRIPTAPPLICATION_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include "PLEngine/Application/EngineApplication.h" 00032 00033 00034 //[-------------------------------------------------------] 00035 //[ Forward declarations ] 00036 //[-------------------------------------------------------] 00037 namespace PLCore { 00038 class Script; 00039 } 00040 00041 00042 //[-------------------------------------------------------] 00043 //[ Namespace ] 00044 //[-------------------------------------------------------] 00045 namespace PLEngine { 00046 00047 00048 //[-------------------------------------------------------] 00049 //[ Classes ] 00050 //[-------------------------------------------------------] 00051 /** 00052 * @brief 00053 * Script application class 00054 * 00055 * @remarks 00056 * This class can load in and execute a given script out of the box. 00057 * 00058 * @note 00059 * - If a script filename was given to the constructor, the script is started within the "OnInit()"-method 00060 * - Adds the global variable "this" to the script so that it's able to access "this" RTTI class instance 00061 */ 00062 class ScriptApplication : public EngineApplication { 00063 00064 00065 //[-------------------------------------------------------] 00066 //[ RTTI interface ] 00067 //[-------------------------------------------------------] 00068 pl_class(PL_RTTI_EXPORT, ScriptApplication, "PLEngine", PLEngine::EngineApplication, "Script application class") 00069 // Attributes 00070 pl_attribute(OnInitFunction, PLCore::String, "OnInit", ReadWrite, DirectValue, "Name of the optional script function called by C++ when the application should initialize itself", "") 00071 pl_attribute(OnUpdateFunction, PLCore::String, "OnUpdate", ReadWrite, DirectValue, "Name of the optional script function called by C++ when the application should update itself", "") 00072 pl_attribute(OnDeInitFunction, PLCore::String, "OnDeInit", ReadWrite, DirectValue, "Name of the optional script function called by C++ when the application should de-initialize itself", "") 00073 #ifdef PLENGINE_EXPORTS // The following is only required when compiling PLEngine 00074 // Constructors 00075 pl_constructor_1(ParameterConstructor1, PLCore::Frontend&, "Parameter constructor. Frontend this application instance is running in as first parameter.", "") 00076 pl_constructor_2(ParameterConstructor2, PLCore::Frontend&, PLCore::String, "Parameter constructor. Frontend this application instance is running in as first parameter, parameter with the filename of the script to load as second parameter.", "") 00077 pl_constructor_5(ParameterConstructor5, PLCore::Frontend&, PLCore::String, PLCore::String, PLCore::String, PLCore::String, "Parameter constructor. Frontend this application instance is running in as first parameter, parameter with the filename of the script to load as second parameter, the following parameters name, title and subdirectory for application data files are optional and will be constructed automatically by using the filename of the script if an empty string is given", "") 00078 // Methods 00079 pl_method_0(GetBaseDirectory, pl_ret_type(PLCore::String), "Returns the base directory of the application (native path style, e.g. on Windows: 'C:\MyApplication\').", "") 00080 pl_method_1(SetBaseDirectory, pl_ret_type(void), const PLCore::String&, "Sets the base directory of the application (e.g. on Windows: 'C:\MyApplication\'). Base directory as the first parameter.", "") 00081 pl_method_0(GetScript, pl_ret_type(PLCore::Script*), "Returns the used script instance.", "") 00082 pl_method_0(GetScriptFilename, pl_ret_type(PLCore::String), "Returns the absolute filename of the used script (native path style, e.g. on Windows: 'C:\MyApplication\Main.lua').", "") 00083 pl_method_0(GetScriptDirectory, pl_ret_type(PLCore::String), "Returns the absolute directory the used script is in (native path style, e.g. on Windows: 'C:\MyApplication\' if currently the script 'C:\MyApplication\Main.lua' is used).", "") 00084 #endif 00085 pl_class_end 00086 00087 00088 //[-------------------------------------------------------] 00089 //[ Public functions ] 00090 //[-------------------------------------------------------] 00091 public: 00092 /** 00093 * @brief 00094 * Constructor 00095 * 00096 * @param[in] cFrontend 00097 * Frontend this application instance is running in 00098 */ 00099 PL_API ScriptApplication(PLCore::Frontend &cFrontend); 00100 00101 /** 00102 * @brief 00103 * Constructor for loading in and executing a scripted stand-alone application using just a single line of C++ code 00104 * 00105 * @param[in] cFrontend 00106 * Frontend this application instance is running in 00107 * @param[in] sScriptFilename 00108 * Filename of the script to load 00109 * 00110 * @remarks 00111 * @verbatim 00112 * Usage example: 00113 * int PLMain(const String &sExecutableFilename, const Array<String> &lstArguments) 00114 * { 00115 * return ScriptApplication("Data/Scripts/45ScriptApplication.lua").Run(sExecutableFilename, lstArguments); 00116 * } 00117 * @endverbatim 00118 */ 00119 PL_API ScriptApplication(PLCore::Frontend &cFrontend, PLCore::String sScriptFilename); 00120 00121 /** 00122 * @brief 00123 * Constructor for loading in and executing a scripted stand-alone application using just a single line of C++ code 00124 * 00125 * @param[in] cFrontend 00126 * Frontend this application instance is running in 00127 * @param[in] sScriptFilename 00128 * Filename of the script to load 00129 * @param[in] sName 00130 * Optional name of the application, if empty string a name is constructed automatically by using the filename of the script 00131 * @param[in] sTitle 00132 * Optional title of the application, if empty string a title is constructed automatically by using the filename of the script 00133 * @param[in] sAppDataSubdir 00134 * Optional subdirectory for application data files, if empty string a directory is constructed automatically by using the filename of the script 00135 * 00136 * @remarks 00137 * @verbatim 00138 * Usage example: 00139 * int PLMain(const String &sExecutableFilename, const Array<String> &lstArguments) 00140 * { 00141 * return ScriptApplication("Data/Scripts/45ScriptApplication.lua").Run(sExecutableFilename, lstArguments); 00142 * } 00143 * @endverbatim 00144 */ 00145 PL_API ScriptApplication(PLCore::Frontend &cFrontend, PLCore::String sScriptFilename, PLCore::String sName, PLCore::String sTitle, PLCore::String sAppDataSubdir); 00146 00147 /** 00148 * @brief 00149 * Destructor 00150 */ 00151 PL_API virtual ~ScriptApplication(); 00152 00153 /** 00154 * @brief 00155 * Returns the base directory of the application 00156 * 00157 * @return 00158 * The base directory of the application (native path style, e.g. on Windows: 'C:\MyApplication\') 00159 */ 00160 PL_API PLCore::String GetBaseDirectory() const; 00161 00162 /** 00163 * @brief 00164 * Sets the base directory of the application 00165 * 00166 * @param[in] sBaseDirectory 00167 * The base directory of the application (e.g. on Windows: 'C:\MyApplication\') 00168 */ 00169 PL_API void SetBaseDirectory(const PLCore::String &sBaseDirectory); 00170 00171 /** 00172 * @brief 00173 * Returns the used script instance 00174 * 00175 * @return 00176 * Used script instance, can be a null pointer (do not destroy the returned instance) 00177 */ 00178 PL_API PLCore::Script *GetScript() const; 00179 00180 /** 00181 * @brief 00182 * Returns the absolute filename of the used script 00183 * 00184 * @return 00185 * Absolute filename of the used script (native path style, e.g. on Windows: 'C:\MyApplication\Main.lua') 00186 */ 00187 PL_API PLCore::String GetScriptFilename() const; 00188 00189 /** 00190 * @brief 00191 * Returns the absolute directory the used script is in 00192 * 00193 * @return 00194 * The absolute directory the used script is in (native path style, e.g. on Windows: 'C:\MyApplication\' if currently the script 'C:\MyApplication\Main.lua' is used) 00195 */ 00196 PL_API PLCore::String GetScriptDirectory() const; 00197 00198 00199 //[-------------------------------------------------------] 00200 //[ Protected virtual PLCore::CoreApplication functions ] 00201 //[-------------------------------------------------------] 00202 protected: 00203 /** 00204 * @brief 00205 * Called when application should initialize itself 00206 * 00207 * @remarks 00208 * The default implementation does the following tasks: 00209 * - Everything that EngineApplication::OnInit() does 00210 * - Load the script given to the constructor 00211 * - Call optional <OnInitFunction> script function 00212 * - Return and go on with Main() 00213 */ 00214 PL_API virtual void OnInit(); 00215 00216 /** 00217 * @brief 00218 * Called when application should de-initialize itself 00219 * 00220 * @remarks 00221 * The default implementation does the following tasks: 00222 * - Call optional <OnDeInitFunction> script function 00223 * - Destroy the script 00224 * - Everything that EngineApplication::OnDeInit() does 00225 */ 00226 PL_API virtual void OnDeInit(); 00227 00228 00229 //[-------------------------------------------------------] 00230 //[ Protected virtual PLCore::AbstractFrontend functions ] 00231 //[-------------------------------------------------------] 00232 protected: 00233 /** 00234 * @brief 00235 * Called to let the frontend update it's states 00236 * 00237 * @remarks 00238 * The default implementation does the following tasks: 00239 * - Everything that EngineApplication::OnUpdate() does 00240 * - Call optional <OnUpdateFunction> script function 00241 */ 00242 PL_API virtual void OnUpdate() override; 00243 00244 00245 //[-------------------------------------------------------] 00246 //[ Protected functions ] 00247 //[-------------------------------------------------------] 00248 protected: 00249 /** 00250 * @brief 00251 * Loads a script 00252 * 00253 * @param[in] sFilename 00254 * Filename of the script to load 00255 * 00256 * @return 00257 * 'true' if all went fine, else 'false' 00258 * 00259 * @note 00260 * - Calls the optional script function <OnInitFunction> 00261 */ 00262 PL_API bool LoadScript(const PLCore::String &sFilename); 00263 00264 /** 00265 * @brief 00266 * Destroys the currently used script 00267 * 00268 * @note 00269 * - Calls the optional script function <OnDeInitFunction> 00270 */ 00271 PL_API void DestroyScript(); 00272 00273 00274 //[-------------------------------------------------------] 00275 //[ Protected data ] 00276 //[-------------------------------------------------------] 00277 protected: 00278 PLCore::String m_sInitialScriptFilename; /**< Initial filename of the script to use */ 00279 00280 00281 //[-------------------------------------------------------] 00282 //[ Private data ] 00283 //[-------------------------------------------------------] 00284 private: 00285 PLCore::String m_sCurrentSceneBaseDirectory; /**< Base directory of the currently loaded scene */ 00286 PLCore::String m_sScriptFilename; /**< Absolute filename of the used script (native path style, e.g. on Windows: 'C:\MyApplication\Main.lua') */ 00287 PLCore::Script *m_pScript; /**< Used script instance, can be a null pointer */ 00288 00289 00290 }; 00291 00292 00293 //[-------------------------------------------------------] 00294 //[ Namespace ] 00295 //[-------------------------------------------------------] 00296 } // PLEngine 00297 00298 00299 #endif // __PLENGINE_SCRIPTAPPLICATION_H__
|