 | PixelLight 0.9.10-R1 Copyright (C) 2002-2011 by The PixelLight Team Last modified Fri Dec 23 2011 15:51:01 |  | 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-2011 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.", "") 00080 pl_method_1(SetBaseDirectory, pl_ret_type(void), const PLCore::String&, "Sets the base directory of the application. Base directory as the first parameter.", "") 00081 #endif 00082 pl_class_end 00083 00084 00085 //[-------------------------------------------------------] 00086 //[ Public functions ] 00087 //[-------------------------------------------------------] 00088 public: 00089 /** 00090 * @brief 00091 * Constructor 00092 * 00093 * @param[in] cFrontend 00094 * Frontend this application instance is running in 00095 */ 00096 PL_API ScriptApplication(PLCore::Frontend &cFrontend); 00097 00098 /** 00099 * @brief 00100 * Constructor for loading in and executing a scripted stand-alone application using just a single line of C++ code 00101 * 00102 * @param[in] cFrontend 00103 * Frontend this application instance is running in 00104 * @param[in] sScriptFilename 00105 * Filename of the script to load 00106 * 00107 * @remarks 00108 * @verbatim 00109 * Usage example: 00110 * int PLMain(const String &sExecutableFilename, const Array<String> &lstArguments) 00111 * { 00112 * return ScriptApplication("Data/Scripts/45ScriptApplication.lua").Run(sExecutableFilename, lstArguments); 00113 * } 00114 * @endverbatim 00115 */ 00116 PL_API ScriptApplication(PLCore::Frontend &cFrontend, PLCore::String sScriptFilename); 00117 00118 /** 00119 * @brief 00120 * Constructor for loading in and executing a scripted stand-alone application using just a single line of C++ code 00121 * 00122 * @param[in] cFrontend 00123 * Frontend this application instance is running in 00124 * @param[in] sScriptFilename 00125 * Filename of the script to load 00126 * @param[in] sName 00127 * Optional name of the application, if empty string a name is constructed automatically by using the filename of the script 00128 * @param[in] sTitle 00129 * Optional title of the application, if empty string a title is constructed automatically by using the filename of the script 00130 * @param[in] sAppDataSubdir 00131 * Optional subdirectory for application data files, if empty string a directory is constructed automatically by using the filename of the script 00132 * 00133 * @remarks 00134 * @verbatim 00135 * Usage example: 00136 * int PLMain(const String &sExecutableFilename, const Array<String> &lstArguments) 00137 * { 00138 * return ScriptApplication("Data/Scripts/45ScriptApplication.lua").Run(sExecutableFilename, lstArguments); 00139 * } 00140 * @endverbatim 00141 */ 00142 PL_API ScriptApplication(PLCore::Frontend &cFrontend, PLCore::String sScriptFilename, PLCore::String sName, PLCore::String sTitle, PLCore::String sAppDataSubdir); 00143 00144 /** 00145 * @brief 00146 * Destructor 00147 */ 00148 PL_API virtual ~ScriptApplication(); 00149 00150 /** 00151 * @brief 00152 * Returns the base directory of the application 00153 * 00154 * @return 00155 * The base directory of the application 00156 */ 00157 PL_API PLCore::String GetBaseDirectory() const; 00158 00159 /** 00160 * @brief 00161 * Sets the base directory of the application 00162 * 00163 * @param[in] sBaseDirectory 00164 * The base directory of the application 00165 */ 00166 PL_API void SetBaseDirectory(const PLCore::String &sBaseDirectory); 00167 00168 00169 //[-------------------------------------------------------] 00170 //[ Protected virtual PLCore::AbstractLifecycle functions ] 00171 //[-------------------------------------------------------] 00172 protected: 00173 /** 00174 * @brief 00175 * Initialization function that is called prior to OnInit() 00176 * 00177 * @return 00178 * 'true' if all went fine, else 'false' which will stop the application 00179 * 00180 * @remarks 00181 * The default implementation does the following tasks: 00182 * - Everything that EngineApplication::OnStart() does 00183 * - Load the script given to the constructor 00184 * - Call optional <OnInitFunction> script function 00185 * - Return and go on with OnInit() 00186 */ 00187 PL_API virtual bool OnStart() override; 00188 00189 /** 00190 * @brief 00191 * De-initialization function that is called after OnDeInit() 00192 * 00193 * @remarks 00194 * The default implementation does the following tasks: 00195 * - Call optional <OnDeInitFunction> script function 00196 * - Destroy the script 00197 * - Everything that EngineApplication::OnStop() does 00198 */ 00199 PL_API virtual void OnStop() override; 00200 00201 00202 //[-------------------------------------------------------] 00203 //[ Protected virtual PLCore::AbstractFrontend functions ] 00204 //[-------------------------------------------------------] 00205 protected: 00206 /** 00207 * @brief 00208 * Called to let the frontend update it's states 00209 * 00210 * @remarks 00211 * The default implementation does the following tasks: 00212 * - Everything that EngineApplication::OnUpdate() does 00213 * - Call optional <OnUpdateFunction> script function 00214 */ 00215 PL_API virtual void OnUpdate() override; 00216 00217 00218 //[-------------------------------------------------------] 00219 //[ Protected functions ] 00220 //[-------------------------------------------------------] 00221 protected: 00222 /** 00223 * @brief 00224 * Loads a script 00225 * 00226 * @param[in] sFilename 00227 * Filename of the script to load 00228 * 00229 * @return 00230 * 'true' if all went fine, else 'false' 00231 * 00232 * @note 00233 * - Calls the optional script function <OnInitFunction> 00234 */ 00235 PL_API bool LoadScript(const PLCore::String &sFilename); 00236 00237 /** 00238 * @brief 00239 * Destroys the currently used script 00240 * 00241 * @note 00242 * - Calls the optional script function <OnDeInitFunction> 00243 */ 00244 PL_API void DestroyScript(); 00245 00246 00247 //[-------------------------------------------------------] 00248 //[ Protected data ] 00249 //[-------------------------------------------------------] 00250 protected: 00251 PLCore::String m_sCurrentSceneBaseDirectory; /**< Base directory of the currently loaded scene */ 00252 PLCore::String m_sScriptFilename; /**< Filename of the used script */ 00253 PLCore::Script *m_pScript; /**< Used script instance, can be a null pointer */ 00254 00255 00256 }; 00257 00258 00259 //[-------------------------------------------------------] 00260 //[ Namespace ] 00261 //[-------------------------------------------------------] 00262 } // PLEngine 00263 00264 00265 #endif // __PLENGINE_SCRIPTAPPLICATION_H__
|