CrystalSpace

Public API Reference

Main Page   Modules   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

csApplicationFramework Class Reference
[Application Framework]

Application framework class. More...

#include <csapplicationframework.h>

Inheritance diagram for csApplicationFramework:

csInitializer List of all members.

Public Methods

virtual ~csApplicationFramework ()
 Destructor.

 operator iObjectRegistry * ()
 Allow a csApplicationFramework object to be used as an iObjectRegistry*.

bool Open ()
 Open plugins and open application window.

int Main (int argc, char *argv[])
 Starts up the application framework, to be called from main().


Static Public Methods

void Quit ()
 Quit running the application.

iObjectRegistryGetObjectRegistry ()
 Returns a pointer to the object registry.

void SetApplicationName (char *name)
 Set the application's string name identifier.

const char * GetApplicationName ()
 Get the application name.

void Run ()
 Start event queue.

bool ReportError (const char *description,...)
 Display an error notification.

void ReportInfo (const char *description,...)
 Display an information notification.


Protected Methods

 csApplicationFramework ()
 Constructor.

virtual bool OnInitialize (int argc, char *argv[])=0
 Initialize the subclassed csApplicationFramework object.

virtual bool Application ()=0
 Perform application logic.

virtual void OnExit ()
 Perform any end of program processing.


Static Protected Attributes

iObjectRegistryobject_reg
 Pointer to the application's object registry.


Detailed Description

Application framework class.

Remarks:
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();
   virtual bool Application();
 };

 //--------------------------
 // Example.cpp
 // File scope

 MyApp::MyApp() : csApplicationFramework()
 {
   SetApplicationName ("my.example.app");
 }

 MyApp::OnIntialize()
 {
   // Request plugins, initialize any global non-CS data and structures
   return true;
 }
 
 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[]) 
 {
   MyApp myApp;
   return myApp.Main (argc, argv);
 }

csApplicationFramework itself is derived from csInitializer for convenience, allowing overridden members to call csInitializer methods without qualifying them with csInitializer::.

This class is not related to csApp or any other class from the deprecated CSWS library.

Definition at line 110 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.

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 295 of file csapplicationframework.h.

iObjectRegistry* csApplicationFramework::GetObjectRegistry   [inline, static]
 

Returns a pointer to the object registry.

Definition at line 253 of file csapplicationframework.h.

int csApplicationFramework::Main int    argc,
char *    argv[]
 

Starts up the application framework, to be called from main().

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 268 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 263 of file csapplicationframework.h.

void csApplicationFramework::Quit   [static]
 

Quit running the application.

Remarks:
This function will send a cscmdQuit event through the event queue. If no queue has been initialized, then it will terminate the program with an exit() call.

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 334 of file csapplicationframework.h.

References CS_REPORTER_SEVERITY_ERROR, and csReportV.

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 351 of file csapplicationframework.h.

References CS_REPORTER_SEVERITY_NOTIFY, and csReportV.

void csApplicationFramework::Run   [inline, static]
 

Start event queue.

Remarks:
This is a shorthand method of calling csDefaultRunLoop().

Definition at line 305 of file csapplicationframework.h.

References csDefaultRunLoop().

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".

Definition at line 284 of file csapplicationframework.h.


Member Data Documentation

iObjectRegistry* csApplicationFramework::object_reg [static, protected]
 

Pointer to the application's object registry.

Definition at line 208 of file csapplicationframework.h.


The documentation for this class was generated from the following file:
Generated for Crystal Space by doxygen 1.2.18