csApplicationFramework Class Reference
[Application Framework]
Application framework class.
More...
#include <cstool/csapplicationframework.h>
Inheritance diagram for csApplicationFramework:
![Inheritance graph](classcsApplicationFramework__inherit__graph.png)
Public Member Functions | |
bool | DoRestart () |
Query whether the application is to be restarted instead of exited. | |
int | Main (int argc, char *argv[]) |
Starts up the application framework, to be called from main(). | |
bool | Open () |
Open plugins and open application window. | |
operator iObjectRegistry * () | |
Allow a csApplicationFramework object to be used as an iObjectRegistry*. | |
void | Restart () |
Restart application. | |
virtual | ~csApplicationFramework () |
Destructor. | |
Static Public Member Functions | |
static const char * | GetApplicationName () |
Get the application name. | |
static iObjectRegistry * | GetObjectRegistry () |
Returns a pointer to the object registry. | |
static void | Quit () |
Quit running the application. | |
static bool | ReportError (const char *description,...) |
Display an error notification. | |
static void | ReportInfo (const char *description,...) |
Display an information notification. | |
static void | ReportWarning (const char *description,...) |
Display a warning notification. | |
static void | Run () |
Start event queue. | |
static void | SetApplicationName (char *name) |
Set the application's string name identifier. | |
Protected Member Functions | |
virtual bool | Application ()=0 |
Perform application logic. | |
csApplicationFramework () | |
Constructor. | |
virtual void | OnCommandLineHelp () |
Print out command line help. | |
virtual void | OnExit () |
Perform any end of program processing. | |
virtual bool | OnInitialize (int argc, char *argv[])=0 |
Initialize the subclassed csApplicationFramework object. | |
Static Protected Member Functions | |
static bool | SetupConfigManager (iObjectRegistry *object_reg, const char *configName) |
Setup the config manager. | |
Static Protected Attributes | |
static iObjectRegistry * | object_reg |
Pointer to the application's object registry. |
Detailed Description
Application framework class.This class provides a handy object-oriented wrapper around the Crystal Space initialization and start-up functions. It encapsulates a callback paradigm which provides methods such as OnInitialize() and OnExit() which you can override to customize the framework's behavior. You should also consider using csBaseEventHandler (csutil/csbaseeventh.h), which provides the same sort of object-oriented wrapper for the Crystal Space event mechanism; providing methods such as OnMouseClick(), OnKeyboard(), OnBroadcast(), etc.
In order to properly use this class, you must derive your own class from it, providing a constructor and implementation for the OnInitialize() and Application() methods. You may only have one csApplicationFramework derived object in existence at any time (and generally, you will only have one such object in your application). In your source code create a global instance of the overridden object, as follows:
//-------------------------- // Example.h class MyApp : public csApplicationFramework { public: MyApp(); virtual bool OnInitialize(int argc, char* argv[]); virtual bool Application(); }; //-------------------------- // Example.cpp // File scope MyApp::MyApp() : csApplicationFramework() { SetApplicationName ("my.example.app"); } bool MyApp::OnInitialize(int argc, char* argv[]) { // Request plugins, initialize any global non-CS data and structures return true; } bool MyApp::Application() { // Perform initialization of CS data and structures, set event handler, // load world, etc. if (!Open()) return false; Run(); return true; } //-------------------------- // main.cpp CS_IMPLEMENT_APPLICATION int main (int argc, char* argv[]) { return csApplicationRunner<MyApp>::Run (argc, argv); }
csApplicationFramework itself is derived from csInitializer for convenience, allowing overridden members to call csInitializer methods without qualifying them with csInitializer::
.
Definition at line 104 of file csapplicationframework.h.
Constructor & Destructor Documentation
csApplicationFramework::csApplicationFramework | ( | ) | [protected] |
Constructor.
- Remarks:
- The csApplicationFramework constructor initializes framework application variables. You must call this constructor from your derived class' constructor.
- This constructor is protected to force the derived class to provide its own constructor.
virtual csApplicationFramework::~csApplicationFramework | ( | ) | [virtual] |
Destructor.
Member Function Documentation
virtual bool csApplicationFramework::Application | ( | ) | [protected, pure virtual] |
Perform application logic.
- Remarks:
- You must override this method in the derived class. It will be called after the OnInitialize() method is called and the framework has checked the commandline for the help argument.
- This method is where the user application should perform all of its main program logic, including initializing any Crystal Space variables and states, starting the event queue loop, etc.
bool csApplicationFramework::DoRestart | ( | ) |
Query whether the application is to be restarted instead of exited.
static const char* csApplicationFramework::GetApplicationName | ( | ) | [inline, static] |
Get the application name.
- Remarks:
- This string is passed to the reporter to indicate message origins from within the derived user application class. It should be set in the derived class' constructor via SetApplicationName ().
Definition at line 317 of file csapplicationframework.h.
References csInitializer::GetDefaultAppID().
static iObjectRegistry* csApplicationFramework::GetObjectRegistry | ( | ) | [inline, static] |
int csApplicationFramework::Main | ( | int | argc, | |
char * | argv[] | |||
) |
Starts up the application framework, to be called from main().
- Remarks:
- It is possible that upon return of this method the application did not quite but rather only requested a restart. Hence, a loop should be used that checks the return value of DoRestart() and, if requested, recreates the application object and runs Main() again. The csApplicationRunner<> is a convenient way to implement this.
virtual void csApplicationFramework::OnCommandLineHelp | ( | ) | [protected, virtual] |
Print out command line help.
This method is called in the event of the user requesting command line help via the '-help' argument. If the application supports command line options, it should override this method to print out a list of the supported options.
virtual void csApplicationFramework::OnExit | ( | ) | [protected, virtual] |
Perform any end of program processing.
- Remarks:
- This method is called after the crystal space engine has been shut down, just before the framework is about to end the program. Unlike the other overridables of this class, you need not bother overriding this method. In general, this is provided to allow end of program debugging support.
virtual bool csApplicationFramework::OnInitialize | ( | int | argc, | |
char * | argv[] | |||
) | [protected, pure virtual] |
Initialize the subclassed csApplicationFramework object.
- Parameters:
-
argc number of arguments passed on the command line. argv[] list of arguments passed on the command line.
- Returns:
- true if the initialization was successful, otherwise false.
- Remarks:
- You must override this function in the derived class. It will be called after the framework has performed all necessary framework initialization.
- This method is where the user application should load any plug-ins via RequestPlugins() and initialize any global application variables or class members. Do not attempt to set or initialize any other Crystal Space structures or objects in this method.
bool csApplicationFramework::Open | ( | ) | [inline] |
Open plugins and open application window.
Definition at line 289 of file csapplicationframework.h.
References csInitializer::OpenApplication().
csApplicationFramework::operator iObjectRegistry * | ( | ) | [inline] |
Allow a csApplicationFramework object to be used as an iObjectRegistry*.
- Remarks:
- Using this implicit cast operator is a shorthand for calling GetObjectRegistry(), and allows the developer to use his derived csApplicationFramework object as a parameter to any function (and some macros) which require an iObjectRegistry reference.
Definition at line 284 of file csapplicationframework.h.
static void csApplicationFramework::Quit | ( | ) | [static] |
Quit running the application.
- Remarks:
- This function will send a csevQuit event through the event queue. If no queue has been initialized, then it will terminate the program with an exit() call.
static bool csApplicationFramework::ReportError | ( | const char * | description, | |
... | ||||
) | [inline, static] |
Display an error notification.
- Remarks:
- The error displayed with this function will be identified with the application string name identifier set with SetApplicationName().
Definition at line 366 of file csapplicationframework.h.
References CS_REPORTER_SEVERITY_ERROR, and csReportV.
static void csApplicationFramework::ReportInfo | ( | const char * | description, | |
... | ||||
) | [inline, static] |
Display an information notification.
- Remarks:
- The info displayed with this function will be identified with the application string name identifier set with SetApplicationName().
Definition at line 401 of file csapplicationframework.h.
References CS_REPORTER_SEVERITY_NOTIFY, and csReportV.
static void csApplicationFramework::ReportWarning | ( | const char * | description, | |
... | ||||
) | [inline, static] |
Display a warning notification.
- Remarks:
- The warning displayed with this function will be identified with the application string name identifier set with SetApplicationName().
Definition at line 384 of file csapplicationframework.h.
References CS_REPORTER_SEVERITY_WARNING, and csReportV.
void csApplicationFramework::Restart | ( | ) |
static void csApplicationFramework::Run | ( | ) | [inline, static] |
Start event queue.
- Remarks:
- This is a shorthand method of calling csDefaultRunLoop().
Definition at line 328 of file csapplicationframework.h.
References csDefaultRunLoop().
static void csApplicationFramework::SetApplicationName | ( | char * | name | ) | [inline, static] |
Set the application's string name identifier.
- Remarks:
- This string is used by DisplayError() and DisplayInfo() to identify the source of a message as generated by the user application (as opposed to one generated by code within the framework library or other code with the Crystal Space libraries and plugins).
Generally, you will call this function once in the constructor for your derived csApplicationFramework class, but it is safe to call it any number of times.
The string should be in the form "vendor.application-name". Spaces should be avoided.
Definition at line 306 of file csapplicationframework.h.
static bool csApplicationFramework::SetupConfigManager | ( | iObjectRegistry * | object_reg, | |
const char * | configName | |||
) | [inline, static, protected] |
Setup the config manager.
This does exactly the same as csInitializer::SetupConfigManager(), with the difference that the ApplicationID parameter defaults to the value returned by GetApplicationName().
Definition at line 263 of file csapplicationframework.h.
References csInitializer::SetupConfigManager().
Member Data Documentation
iObjectRegistry* csApplicationFramework::object_reg [static, protected] |
Pointer to the application's object registry.
Definition at line 207 of file csapplicationframework.h.
The documentation for this class was generated from the following file:
- cstool/csapplicationframework.h
Generated for Crystal Space by doxygen 1.4.7